refactor(scripts): scinder scripts/lib/helpers.js en modules mono-responsabilité
Contexte
scripts/lib/helpers.js (653 lignes, 22 fonctions exportées) mélange 7 responsabilités distinctes, contrairement à tous ses voisins de scripts/lib/ (docs.js, frontmatter.js, yaml.js, glob.js, fs-scan.js, targets.js, args.js), tous mono-responsabilité. Relevé par l'audit qualité de la branche #13 (closed) (2026-09-08, score SRP 15/25 sur la revue d'architecture, module noté 54/100 en isolation, seul module de scripts/lib/ sans aucun test).
Le fichier assume lui-même ce scope-out en en-tête (renvoi à l'issue oxa#197 — "fine-grained splitting out of scope"), mais la MR #13 (closed) s'intitulant "décomposition", c'est le seul module resté monolithique. 26 des 27 fichiers de scripts/ en dépendent.
Découpage proposé
| Fonctions actuelles (helpers.js) | Nouveau module |
|---|---|
log, error, success, info, warning
|
scripts/lib/console.js |
resolveStepReferences, collectStepNames, removeStepReferences, extractStepDescription
|
scripts/lib/step-references.js |
checkSubmoduleExists, loadTechsRegistry, resolveInheritanceChain, loadArchRegistry
|
scripts/lib/tech-registry.js |
loadAgentManifest, walkAgentFolders, loadAllManifests
|
scripts/lib/agent-manifests.js |
buildStepSkillFile, generateClaudeStepSkills
|
scripts/lib/claude-skills.js |
scanDir, buildDocsCategoryIndex, buildPhase0Block, buildDocsInjectionBlock
|
scripts/lib/docs-index.js |
copyDirectory |
scripts/lib/fs-scan.js (fonction générique fs, rejoint son voisinage naturel) |
Objectif
-
scripts/lib/helpers.jsscindé selon le tableau ci-dessus (noms ajustables à l'implémentation) -
Chaque module créé embarque directement son propre test miroir sous tests/lib/(pas de ticket de test séparé — tests écrits en même temps que le split, au fil de l'eau) -
Couverture au minimum sur les fonctions à risque : resolveStepReferences(récursion + garde-fou de profondeur + fallback project → submodule),loadAllManifests(fusion specific override shared),generateClaudeStepSkills(création de symlinks, cas d'erreur) -
Tous les imports des 26 fichiers consommateurs mis à jour -
npm testvert (125 tests existants + nouveaux), comportement denode scripts/install-guidelines.jsinchangé sur un projet témoin (diff vide)