@artefact-ci/spec-trace 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Artefact CI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,41 @@
-# Temporary Holding Version
+# @artefact-ci/spec-trace
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Matrice scénarios → tests des specs Spec Kit, sortie de `tools/dev/spec-trace.mts` du boilerplate (`b30bb7b`) : même logique, même sortie. C'est la commande `commands.trace` de `.specify/stack.yml`.
+
+```sh
+npx @artefact-ci/spec-trace                       # toutes les features de specs/ (CI)
+npx @artefact-ci/spec-trace specs/003-order-note  # une seule, en mode strict
+npx @artefact-ci/spec-trace --base origin/dev     # avertit en plus des tests modifiés sans leur spec
+npx @artefact-ci/spec-trace --tests 'src/**/*.test.ts'  # autres fichiers de tests (répétable)
+```
+
+À lancer à la racine du dépôt (Node 24.11 ou plus récent, et git).
+
+- Chaque scénario d'acceptation actif `NNN-US<story>-AS<n>` doit être cité par au moins un test ; une spec en `Draft` y échappe, sauf si on la vise. Aucun test ne doit citer un scénario absent ou retiré.
+- Si `specs/product.yml` existe, chaque spec nomme ses exigences (`**Product Requirements**:`), et la commande affiche l'état des exigences, des epics et la couverture des parcours (`E03-J1`). Un epic peut porter une priorité (`priority: P1`, `P2`…, sur tous les epics ou sur aucun) : la commande refuse un niveau mal formé et un epic plus urgent qu'un epic dont il dépend, trie le tableau des epics par priorité et nomme le prochain epic à livrer (`Prochain epic`). Un epic retiré ne retient plus ceux qui en dépendent.
+- Code de sortie 1 quand quelque chose manque.
+
+## Fichiers de tests
+
+Ceux de `tests.globs` dans `.specify/stack.yml` ; `--tests` les remplace. Sans l'un ni l'autre : `**/*.spec.ts` et `**/*.spec.tsx`, ceux du boilerplate. Seuls les fichiers suivis par git ou nouveaux (hors `.gitignore`) sont lus.
+
+Les motifs sont des pathspecs git (`:(glob)`), pour la matrice comme pour l'avertissement de `--base` : les deux voient les mêmes fichiers, quel que soit le moteur JS.
+
+- `*` ne traverse pas un `/`, `**/` traverse zéro ou plusieurs dossiers, racine et dossiers à point (`.storybook/`) compris ;
+- les accolades sont développées par l'outil : `src/**/*.{test,spec}.ts` vaut deux motifs ;
+- un `./` en tête est ignoré ; un chemin est relatif à la racine du dépôt.
+
+Le format des ids (`NNN-US<story>-AS<n>`, `E<n>-J<n>`) est celui de la méthode : les commandes du preset et la constitution le citent, il ne se configure pas ici.
+
+Il faut Node 24.11 ou plus récent, aussi sur un projet Bun : `bunx` lance l'outil avec Node quand il est installé (shebang `node`), et n'est pas testé sous Bun.
+
+## Développer
+
+```sh
+pnpm install
+pnpm --filter @artefact-ci/spec-trace test        # node --test sur src/*.test.mts
+pnpm --filter @artefact-ci/spec-trace typecheck
+pnpm --filter @artefact-ci/spec-trace build       # dist/*.mjs, ce que publie le paquet
+```
+
+`src/core.mts` est la logique pure, `src/stack.mts` la lecture de `stack.yml` et les motifs, `src/cli.mts` les fichiers, git et l'affichage. `src/cli.test.mts` lance la CLI sur un dépôt jetable (`test/fixture/`) et compare sa sortie à celle de l'outil d'origine (`test/golden/`, produite par `tools/dev/spec-trace.mts` du boilerplate sur ce même dépôt).

package/dist/cli.mjs

@@ -0,0 +1,285 @@
+#!/usr/bin/env node
+/**
+ * Matrice scénario → tests des specs Spec Kit, à lancer à la racine du dépôt.
+ *   spec-trace                      → toutes les features de specs/ (CI)
+ *   spec-trace specs/003-order-note → une seule, en mode strict
+ *   spec-trace --base origin/dev    → avertit en plus des tests modifiés sans leur spec
+ *   spec-trace --tests 'src/**\/*.test.ts' → d'autres fichiers de tests que ceux de stack.yml
+ * Les fichiers de tests sont ceux de `tests.globs` dans .specify/stack.yml (par défaut
+ * `**\/*.spec.ts` et `**\/*.spec.tsx`).
+ * Chaque scénario d'acceptation actif `NNN-US<story>-AS<n>` doit être cité par au moins un test
+ * (`it('003-US1-AS2: …')`) ; une spec en Draft y échappe, sauf si on la vise (mode strict).
+ * Aucun test ne doit citer un scénario absent ou retiré. Code de sortie 1 sinon.
+ * Si specs/product.yml existe, chaque spec nomme les exigences qu'elle implémente
+ * (`**Product Requirements**:`), toutes présentes dans l'index ; sans argument, la commande
+ * affiche aussi l'état de chaque epic (par priorité, puis le prochain à livrer), de chaque
+ * exigence et la couverture des parcours. Un epic terminé exige un test par parcours (`E03-J1: …`).
+ */
+import { execFileSync } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { driftedFeatures, epicCells, featureIdOf, parseProductIndex, parseRequirementRefs, parseScenarios, parseStatus, traceEpics, traceFeature, traceRequirements, } from "./core.mjs";
+import { pathspecs, testGlobs } from "./stack.mjs";
+const SPECS_DIR = 'specs';
+const REQUIREMENT_INDEX = join(SPECS_DIR, 'product.yml');
+const LEGACY_INDEX = join(SPECS_DIR, 'product-requirements.json');
+const STACK_FILE = join('.specify', 'stack.yml');
+const USAGE = 'Usage : spec-trace [specs/NNN-nom…] [--base <ref git>] [--tests <motif>…]';
+function featureDirs(args) {
+    if (args.length > 0)
+        return args;
+    if (!existsSync(SPECS_DIR))
+        return [];
+    return readdirSync(SPECS_DIR, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() && existsSync(join(SPECS_DIR, entry.name, 'spec.md')))
+        .map((entry) => join(SPECS_DIR, entry.name))
+        .sort();
+}
+// Fichiers suivis et nouveaux (pas encore ajoutés), hors fichiers ignorés (node_modules, dist…).
+// Filtrés par git, comme l'avertissement de dérive : un seul moteur de motifs.
+function testFiles(globs) {
+    const output = execFileSync('git', ['ls-files', '--cached', '--others', '--exclude-standard', '--', ...pathspecs(globs)], { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+    return output
+        .split('\n')
+        .filter((path) => path !== '' && existsSync(path))
+        .map((path) => ({ path, content: readFileSync(path, 'utf8') }));
+}
+function print(featureDir, report) {
+    console.log(`\n## ${featureDir} (${report.status}) : ${report.ok ? 'OK' : 'INCOMPLET'}\n`);
+    if (report.rows.length === 0) {
+        console.log(`Aucun scénario d'acceptation trouvé dans ${join(featureDir, 'spec.md')}.`);
+    }
+    else {
+        console.log('| Scénario | Tests |');
+        console.log('| -------- | ----- |');
+        for (const row of report.rows) {
+            const tests = row.tests.length > 0 ? row.tests.join('<br>') : row.retired ? '' : '**aucun**';
+            console.log(`| ${row.id}${row.retired ? ' (retiré)' : ''} | ${tests} |`);
+        }
+    }
+    if (!report.coverageRequired && report.status === 'Draft' && report.uncovered.length > 0) {
+        console.log(`\nSpec en Draft : ${report.uncovered.length} scénario(s) encore sans test, toléré. ` +
+            'Passer le statut à Implemented quand tous sont couverts.');
+    }
+    for (const orphan of report.orphans) {
+        console.log(`\nTest orphelin : ${orphan.path} cite ${orphan.id}, absent de la spec.`);
+    }
+    for (const stale of report.retiredCited) {
+        console.log(`\nTest périmé : ${stale.path} cite ${stale.id}, scénario retiré.`);
+    }
+}
+function printRequirements(report, { hasIndex, showRows }) {
+    if (showRows) {
+        console.log(`\n## Exigences (${REQUIREMENT_INDEX}) : ${report.ok ? 'OK' : 'INCOMPLET'}\n`);
+        console.log('| Exigence | État | Specs |');
+        console.log('| -------- | ---- | ----- |');
+        for (const row of report.rows) {
+            const specs = row.specs.map((spec) => `${spec.featureDir} (${spec.status})`).join('<br>');
+            const state = row.state === 'Unspecified' ? '**non spécifiée**' : row.state;
+            console.log(`| ${row.id} ${row.title} | ${state} | ${specs} |`);
+        }
+    }
+    for (const { featureDir, id } of report.unknown) {
+        const where = hasIndex
+            ? `absente de ${REQUIREMENT_INDEX}`
+            : `et ${REQUIREMENT_INDEX} n'existe pas`;
+        console.log(`\nExigence inconnue : ${featureDir}/spec.md cite ${id}, ${where}.`);
+    }
+    for (const { featureDir, id } of report.retiredCited) {
+        console.log(`\nAvertissement : ${featureDir}/spec.md cite ${id}, exigence retirée dans ${REQUIREMENT_INDEX} ` +
+            "(retirer la spec, ou la rattacher à l'exigence qui la remplace).");
+    }
+    for (const featureDir of report.missingLine) {
+        console.log(`\nLigne **Product Requirements** absente de ${featureDir}/spec.md ` +
+            `(les exigences de ${REQUIREMENT_INDEX} qu'elle implémente, ou None).`);
+    }
+}
+function printEpics(report, { showRows }) {
+    if (showRows && report.rows.length > 0) {
+        console.log(`\n## Epics (${REQUIREMENT_INDEX}) : ${report.ok ? 'OK' : 'INCOMPLET'}\n`);
+        const prioritized = report.rows.some((row) => row.priority !== undefined);
+        console.log(`| Epic |${prioritized ? ' Priorité |' : ''} État | Avancement | Exigences | Dépend de |`);
+        console.log(`| ---- |${prioritized ? ' -------- |' : ''} ---- | ---------- | --------- | --------- |`);
+        for (const row of report.rows) {
+            const { state, progress } = epicCells(row);
+            const priority = prioritized ? ` P${row.priority} |` : '';
+            console.log(`| ${row.id} ${row.title} |${priority} ${state} | ${progress} | ${row.requirements.join(', ')} | ${row.dependsOn.join(', ')} |`);
+        }
+        const level = report.rows.find((row) => row.id === report.next[0])?.priority;
+        const allDone = report.rows.every((row) => row.state === 'Retired' || row.state === 'Implemented' || row.state === 'Shipped');
+        console.log(report.next.length === 0
+            ? `\nProchain epic : aucun, ${allDone ? 'tous sont terminés' : 'aucun prêt (dépendances)'}.`
+            : `\nProchain epic${report.next.length > 1 ? ' (au choix)' : ''} : ` +
+                `${report.next.join(', ')}${level === undefined ? '' : ` (P${level})`}.`);
+    }
+    if (showRows && report.journeys.length > 0) {
+        console.log('\n| Parcours | Tests |');
+        console.log('| -------- | ----- |');
+        for (const journey of report.journeys) {
+            const tests = journey.tests.length > 0 ? journey.tests.join('<br>') : journey.retired ? '' : '**aucun**';
+            console.log(`| ${journey.id}${journey.retired ? ' (retiré)' : ''} ${journey.title} | ${tests} |`);
+        }
+    }
+    for (const id of report.uncovered) {
+        console.log(`\nParcours sans test : ${id}, alors que son epic est terminé.`);
+    }
+    for (const orphan of report.orphans) {
+        console.log(`\nTest orphelin : ${orphan.path} cite ${orphan.id}, parcours absent de ${REQUIREMENT_INDEX}.`);
+    }
+    for (const stale of report.retiredCited) {
+        console.log(`\nTest périmé : ${stale.path} cite ${stale.id}, parcours retiré.`);
+    }
+    for (const { featureDir, epicId, waitingOn } of report.blocked) {
+        console.log(`\nAvertissement : ${featureDir} avance sur ${epicId}, qui dépend de ${waitingOn.join(', ')}, ` +
+            'pas encore terminé (Implemented).');
+    }
+}
+// Exigences citées par toutes les specs de specs/ ; une spec illisible est signalée quand on la
+// vise, et ignorée ici.
+function allRequirementRefs() {
+    return featureDirs([]).flatMap((featureDir) => {
+        const spec = readFileSync(join(featureDir, 'spec.md'), 'utf8');
+        try {
+            return [{ featureDir, status: parseStatus(spec), refs: parseRequirementRefs(spec) }];
+        }
+        catch {
+            return [];
+        }
+    });
+}
+// Tests modifiés depuis la base (commits et fichiers en cours) dont la spec n'a pas bougé.
+function warnDrift(base, globs) {
+    const git = (args) => execFileSync('git', args, { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+    const mergeBase = git(['merge-base', base, 'HEAD']).trim();
+    const diff = git(['diff', '-U0', mergeBase, '--', ...pathspecs(globs)]);
+    const changed = [
+        ...git(['diff', '--name-only', mergeBase]).split('\n'),
+        ...git(['ls-files', '--others', '--exclude-standard']).split('\n'),
+    ].filter(Boolean);
+    const drift = driftedFeatures(diff, changed);
+    if (drift.length === 0)
+        return;
+    console.log('\n## Avertissements\n');
+    for (const { featureId, paths } of drift) {
+        const message = `Des tests qui citent les scénarios ${featureId}-… ont changé, pas specs/${featureId}-*/spec.md. ` +
+            'Si le comportement a changé, mettre la spec à jour dans la même PR.';
+        console.log(`- ${message} (${paths.join(', ')})`);
+        // Annotation visible dans la PR, sans faire échouer le job.
+        if (process.env['GITHUB_ACTIONS'] === 'true') {
+            for (const path of paths)
+                console.log(`::warning file=${path}::${message}`);
+        }
+    }
+}
+const args = process.argv.slice(2);
+if (args.includes('--help') || args.includes('-h')) {
+    console.log(USAGE);
+    process.exit(0);
+}
+// Retire une option et sa valeur des arguments ; `undefined` si elle manque, `''` si sa valeur manque.
+function takeOption(name) {
+    const at = args.indexOf(name);
+    if (at < 0)
+        return undefined;
+    const value = args[at + 1];
+    const valid = value !== undefined && !value.startsWith('--');
+    args.splice(at, valid ? 2 : 1);
+    return valid ? value : '';
+}
+const base = takeOption('--base');
+if (base === '') {
+    console.error('--base attend une référence git (ex. origin/dev).');
+    process.exit(1);
+}
+const cliGlobs = [];
+for (let glob = takeOption('--tests'); glob !== undefined; glob = takeOption('--tests')) {
+    if (glob === '') {
+        console.error("--tests attend un motif de fichiers de tests (ex. 'src/**/*.test.ts').");
+        process.exit(1);
+    }
+    cliGlobs.push(glob);
+}
+const unknownOption = args.find((arg) => arg.startsWith('--'));
+if (unknownOption) {
+    console.error(`Option inconnue : ${unknownOption}\n${USAGE}`);
+    process.exit(1);
+}
+let globs;
+try {
+    globs =
+        cliGlobs.length > 0
+            ? cliGlobs
+            : testGlobs(existsSync(STACK_FILE) ? readFileSync(STACK_FILE, 'utf8') : undefined);
+    pathspecs(globs); // une accolade non fermée s'arrête ici, avant toute sortie
+}
+catch (error) {
+    console.error(`${STACK_FILE} : ${error.message}`);
+    process.exit(1);
+}
+// Viser une feature, c'est vérifier qu'elle est complète : même en Draft, tout scénario a son test.
+const strict = args.length > 0;
+const dirs = featureDirs(args);
+if (existsSync(LEGACY_INDEX)) {
+    console.error(`${LEGACY_INDEX} n'est plus lu : l'index du produit est ${REQUIREMENT_INDEX} ` +
+        '(mêmes exigences en YAML, plus les epics) : le convertir, puis supprimer l\'ancien fichier.');
+    process.exit(1);
+}
+let index;
+if (existsSync(REQUIREMENT_INDEX)) {
+    try {
+        index = parseProductIndex(readFileSync(REQUIREMENT_INDEX, 'utf8'));
+    }
+    catch (error) {
+        console.error(`${REQUIREMENT_INDEX} : ${error.message}`);
+        process.exit(1);
+    }
+}
+if (dirs.length === 0 && !index) {
+    console.log(`Aucune spec dans ${SPECS_DIR}/.`);
+    if (base)
+        warnDrift(base, globs);
+    process.exit(0);
+}
+const files = testFiles(globs);
+let ok = true;
+const requirementRefs = [];
+for (const dir of dirs) {
+    const specPath = join(dir, 'spec.md');
+    if (!existsSync(specPath)) {
+        console.error(`${specPath} introuvable.`);
+        ok = false;
+        continue;
+    }
+    const featureId = featureIdOf(dir);
+    const spec = readFileSync(specPath, 'utf8');
+    let status;
+    try {
+        status = parseStatus(spec);
+    }
+    catch (error) {
+        console.error(`${specPath} : ${error.message}`);
+        ok = false;
+        continue;
+    }
+    const report = traceFeature(featureId, parseScenarios(featureId, spec), { status, strict }, files);
+    print(dir, report);
+    ok &&= report.ok;
+    requirementRefs.push({ featureDir: dir, status, refs: parseRequirementRefs(spec) });
+}
+const requirements = traceRequirements(index, requirementRefs);
+// Le tableau des exigences n'a de sens que sur toutes les specs.
+printRequirements(requirements, {
+    hasIndex: index !== undefined,
+    showRows: index !== undefined && !strict,
+});
+ok &&= requirements.ok;
+// L'état d'un epic dépend de toutes les specs, même quand on n'en vise qu'une : sinon une v2 en
+// Draft ailleurs passerait inaperçue et l'epic paraîtrait terminé.
+const allRows = strict ? traceRequirements(index, allRequirementRefs()).rows : requirements.rows;
+// Sans index, un test qui cite un parcours reste orphelin.
+const epics = traceEpics(index ?? { requirements: [], epics: [] }, allRows, requirementRefs, files);
+printEpics(epics, { showRows: !strict });
+ok &&= epics.ok;
+if (base)
+    warnDrift(base, globs);
+process.exit(ok ? 0 : 1);

package/dist/core.mjs

@@ -0,0 +1,493 @@
+import { parse as parseYaml } from 'yaml';
+/**
+ * Traçabilité spec → tests : chaque scénario d'acceptation d'une spec Spec Kit
+ * (`specs/NNN-<nom>/spec.md`) porte un identifiant `NNN-US<story>-AS<n>`, et au moins un test
+ * le cite dans son titre. Logique pure ; la lecture des fichiers est dans cli.mts.
+ */
+/**
+ * Cycle de vie d'une spec : Draft (en cours, des scénarios peuvent encore attendre leur test),
+ * Implemented (tous couverts), Shipped (feature flag supprimé), Retired (fonctionnalité retirée :
+ * plus aucun test ne la cite).
+ */
+const SPEC_STATUSES = ['Draft', 'Implemented', 'Shipped', 'Retired'];
+export function featureIdOf(featureDir) {
+    const name = featureDir.replace(/\/+$/, '').split('/').pop() ?? '';
+    const match = /^(\d+)-/.exec(name);
+    if (!match?.[1]) {
+        throw new Error(`Le dossier de feature "${featureDir}" n'a pas de préfixe numérique (attendu : NNN-<nom>).`);
+    }
+    return match[1];
+}
+export function parseStatus(specMarkdown) {
+    const value = /^\*\*Status\*\*:\s*(.*?)\s*$/m.exec(specMarkdown)?.[1];
+    if (value === undefined) {
+        throw new Error(`Ligne **Status** absente (attendu : ${SPEC_STATUSES.join(', ')}).`);
+    }
+    const status = SPEC_STATUSES.find((candidate) => candidate === value);
+    if (!status) {
+        throw new Error(`Statut "${value}" inconnu (attendu : ${SPEC_STATUSES.join(', ')}).`);
+    }
+    return status;
+}
+/**
+ * Scénarios = éléments numérotés de la liste « Acceptance Scenarios » de chaque « User Story N ».
+ * Le numéro est celui écrit dans la spec : retirer un scénario ne renumérote pas les suivants.
+ */
+export function parseScenarios(featureId, specMarkdown) {
+    const scenarios = [];
+    let story;
+    let inScenarios = false;
+    for (const line of specMarkdown.split('\n')) {
+        const heading = /^#{1,6}\s+(.*)$/.exec(line);
+        if (heading) {
+            story = /^User Story (\d+)\b/.exec(heading[1] ?? '')?.[1];
+            inScenarios = false;
+            continue;
+        }
+        if (story && line.startsWith('**Acceptance Scenarios**')) {
+            inScenarios = true;
+            continue;
+        }
+        const item = inScenarios ? /^(\d+)\.\s+(.*)$/.exec(line) : null;
+        if (story && item) {
+            const text = item[2] ?? '';
+            scenarios.push({
+                id: `${featureId}-US${story}-AS${item[1]}`,
+                text,
+                retired: text.startsWith('**Retired**'),
+            });
+        }
+    }
+    return scenarios;
+}
+export function traceFeature(featureId, scenarios, options, testFiles) {
+    // Une spec retirée l'est en entier : chacun de ses scénarios est retiré.
+    const featureRetired = options.status === 'Retired';
+    const retiredIds = new Set(scenarios.filter((scenario) => featureRetired || scenario.retired).map((s) => s.id));
+    const known = new Set(scenarios.map((scenario) => scenario.id));
+    const idPattern = new RegExp(`\\b${featureId}-US\\d+-AS\\d+\\b`, 'g');
+    const testsById = new Map();
+    const orphans = [];
+    const retiredCited = [];
+    for (const file of testFiles) {
+        for (const id of new Set(file.content.match(idPattern) ?? [])) {
+            if (!known.has(id)) {
+                orphans.push({ id, path: file.path });
+                continue;
+            }
+            testsById.set(id, (testsById.get(id) ?? new Set()).add(file.path));
+            if (retiredIds.has(id))
+                retiredCited.push({ id, path: file.path });
+        }
+    }
+    const rows = scenarios.map((scenario) => ({
+        id: scenario.id,
+        text: scenario.text,
+        retired: retiredIds.has(scenario.id),
+        tests: [...(testsById.get(scenario.id) ?? [])].sort(),
+    }));
+    const active = rows.filter((row) => !row.retired);
+    const uncovered = active.filter((row) => row.tests.length === 0).map((row) => row.id);
+    const byIdThenPath = (a, b) => a.id.localeCompare(b.id) || a.path.localeCompare(b.path);
+    orphans.sort(byIdThenPath);
+    retiredCited.sort(byIdThenPath);
+    const coverageRequired = !featureRetired && (options.strict === true || options.status !== 'Draft');
+    const coverageOk = !coverageRequired || (active.length > 0 && uncovered.length === 0);
+    return {
+        featureId,
+        status: options.status,
+        coverageRequired,
+        rows,
+        uncovered,
+        orphans,
+        retiredCited,
+        ok: coverageOk && orphans.length === 0 && retiredCited.length === 0,
+    };
+}
+/**
+ * Dérive probable : un diff (`git diff -U0`) modifie des lignes de test qui citent un scénario
+ * d'une feature, sans que le `spec.md` de cette feature figure parmi les fichiers modifiés.
+ * Simple signal pour la revue : renommer ou refactorer un test ne change pas le comportement.
+ */
+export function driftedFeatures(diff, changedPaths) {
+    const specChanged = new Set(changedPaths.flatMap((path) => /^specs\/(\d+)-[^/]+\/spec\.md$/.exec(path)?.[1] ?? []));
+    const pathsByFeature = new Map();
+    let oldPath;
+    let path;
+    for (const line of diff.split('\n')) {
+        if (line.startsWith('--- ')) {
+            oldPath = line.slice(4).replace(/^a\//, '');
+            continue;
+        }
+        if (line.startsWith('+++ ')) {
+            const newPath = line.slice(4);
+            path = newPath === '/dev/null' ? oldPath : newPath.replace(/^b\//, '');
+            continue;
+        }
+        if (!path || !/^[+-]/.test(line))
+            continue;
+        for (const match of line.matchAll(/\b(\d+)-US\d+-AS\d+\b/g)) {
+            const featureId = match[1] ?? '';
+            if (specChanged.has(featureId))
+                continue;
+            pathsByFeature.set(featureId, (pathsByFeature.get(featureId) ?? new Set()).add(path));
+        }
+    }
+    return [...pathsByFeature]
+        .map(([featureId, paths]) => ({ featureId, paths: [...paths].sort() }))
+        .sort((a, b) => a.featureId.localeCompare(b.featureId));
+}
+const REQUIREMENT_ID = /^[A-Z][A-Z0-9]*-\d+$/;
+const EPIC_ID = /^E\d+$/;
+const JOURNEY_ID = /^E\d+-J\d+$/;
+const PRIORITY = /^P([1-9]\d*)$/;
+function fieldsOf(value, what) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new Error(`${what} : attendu un objet.`);
+    }
+    return value;
+}
+function text(fields, key, owner) {
+    const value = fields[key];
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new Error(`${owner} : champ ${key} absent ou vide.`);
+    }
+    return value;
+}
+function retiredOf(fields, owner) {
+    return fields['retired'] === undefined ? undefined : text(fields, 'retired', owner);
+}
+function textList(fields, key, owner) {
+    const value = fields[key] ?? [];
+    if (!Array.isArray(value) || value.some((item) => typeof item !== 'string')) {
+        throw new Error(`${owner} : ${key} doit être une liste de textes.`);
+    }
+    return value;
+}
+function priorityOf(fields, owner) {
+    const value = fields['priority'];
+    if (value === undefined)
+        return undefined;
+    const level = typeof value === 'string' ? PRIORITY.exec(value)?.[1] : undefined;
+    if (!level) {
+        throw new Error(`${owner} : priority "${String(value)}" invalide (attendu : P1, P2…).`);
+    }
+    return Number(level);
+}
+function assertUnique(ids, what) {
+    const seen = new Set();
+    for (const id of ids) {
+        if (seen.has(id))
+            throw new Error(`${what} ${id} apparaît deux fois.`);
+        seen.add(id);
+    }
+}
+// Premier cycle trouvé dans le graphe des dépendances, sous la forme E01 → E02 → E01.
+function findCycle(epics) {
+    const dependsOn = new Map(epics.map((epic) => [epic.id, epic.dependsOn]));
+    const done = new Set();
+    const visit = (id, path) => {
+        const start = path.indexOf(id);
+        if (start >= 0)
+            return [...path.slice(start), id];
+        if (done.has(id))
+            return undefined;
+        for (const next of dependsOn.get(id) ?? []) {
+            const cycle = visit(next, [...path, id]);
+            if (cycle)
+                return cycle;
+        }
+        done.add(id);
+        return undefined;
+    };
+    for (const epic of epics) {
+        const cycle = visit(epic.id, []);
+        if (cycle)
+            return cycle;
+    }
+    return undefined;
+}
+// Une priorité sur tous les epics ou sur aucun ; un epic ne passe pas avant ce dont il dépend. Un
+// epic retiré (toutes ses exigences le sont) n'a plus rien à livrer : sa priorité ne compte plus.
+function assertPriorities(epics, retired) {
+    if (epics.every((epic) => epic.priority === undefined))
+        return;
+    const missing = epics.find((epic) => epic.priority === undefined);
+    if (missing) {
+        throw new Error(`L'epic ${missing.id} : priority absente, alors que d'autres epics en ont une (tous ou aucun).`);
+    }
+    const priorityOf = new Map(epics.map((epic) => [epic.id, epic.priority ?? 0]));
+    for (const epic of epics.filter((candidate) => !retired.has(candidate.id))) {
+        for (const dependency of epic.dependsOn.filter((id) => !retired.has(id))) {
+            const level = priorityOf.get(dependency) ?? 0;
+            if (level > (epic.priority ?? 0)) {
+                throw new Error(`L'epic ${epic.id} (P${epic.priority}) dépend de ${dependency} (P${level}), moins ` +
+                    'prioritaire : il ne peut pas être livré avant lui.');
+            }
+        }
+    }
+}
+/** Lit et valide l'index : identifiants, références entre epics et exigences, cycles. */
+export function parseProductIndex(yamlText) {
+    let data;
+    try {
+        data = parseYaml(yamlText);
+    }
+    catch (error) {
+        throw new Error(`YAML invalide : ${error.message}`);
+    }
+    const root = (data ?? {});
+    if (!Array.isArray(root['requirements'])) {
+        throw new Error('Attendu : requirements: [{ id: PAY-03, title: … }], puis epics (optionnel).');
+    }
+    const requirements = root['requirements'].map((entry, position) => {
+        const fields = fieldsOf(entry, `Exigence n° ${position + 1}`);
+        const id = fields['id'];
+        if (typeof id !== 'string' || !REQUIREMENT_ID.test(id)) {
+            throw new Error(`Identifiant d'exigence "${String(id)}" invalide (attendu : PAY-03).`);
+        }
+        return {
+            id,
+            title: text(fields, 'title', `L'exigence ${id}`),
+            retired: retiredOf(fields, `L'exigence ${id}`),
+        };
+    });
+    assertUnique(requirements.map((requirement) => requirement.id), "L'exigence");
+    const rawEpics = root['epics'] ?? [];
+    if (!Array.isArray(rawEpics))
+        throw new Error('epics doit être une liste.');
+    const epics = rawEpics.map((entry, position) => {
+        const fields = fieldsOf(entry, `Epic n° ${position + 1}`);
+        const id = fields['id'];
+        if (typeof id !== 'string' || !EPIC_ID.test(id)) {
+            throw new Error(`Identifiant d'epic "${String(id)}" invalide (attendu : E03).`);
+        }
+        const owner = `L'epic ${id}`;
+        const epicRequirements = textList(fields, 'requirements', owner);
+        if (epicRequirements.length === 0) {
+            throw new Error(`${owner} : requirements vide (au moins une exigence).`);
+        }
+        const rawJourneys = fields['journeys'] ?? [];
+        if (!Array.isArray(rawJourneys))
+            throw new Error(`${owner} : journeys doit être une liste.`);
+        const journeys = rawJourneys.map((journeyEntry, index) => {
+            const journey = fieldsOf(journeyEntry, `${owner}, parcours n° ${index + 1}`);
+            const journeyId = journey['id'];
+            if (typeof journeyId !== 'string' || !JOURNEY_ID.test(journeyId)) {
+                throw new Error(`Identifiant de parcours "${String(journeyId)}" invalide (attendu : ${id}-J1).`);
+            }
+            if (!journeyId.startsWith(`${id}-J`)) {
+                throw new Error(`Le parcours ${journeyId} de l'epic ${id} doit s'appeler ${id}-J<n>.`);
+            }
+            const journeyOwner = `Le parcours ${journeyId}`;
+            const retired = retiredOf(journey, journeyOwner);
+            const steps = textList(journey, 'steps', journeyOwner);
+            if (!retired && steps.length === 0) {
+                throw new Error(`${journeyOwner} : steps vide (les étapes que le test enchaîne).`);
+            }
+            return { id: journeyId, title: text(journey, 'title', journeyOwner), steps, retired };
+        });
+        return {
+            id,
+            title: text(fields, 'title', owner),
+            goal: text(fields, 'goal', owner),
+            requirements: epicRequirements,
+            dependsOn: textList(fields, 'depends_on', owner),
+            priority: priorityOf(fields, owner),
+            journeys,
+        };
+    });
+    assertUnique(epics.map((epic) => epic.id), "L'epic");
+    assertUnique(epics.flatMap((epic) => epic.journeys.map((journey) => journey.id)), 'Le parcours');
+    const knownRequirements = new Set(requirements.map((requirement) => requirement.id));
+    const knownEpics = new Set(epics.map((epic) => epic.id));
+    const epicOf = new Map();
+    for (const epic of epics) {
+        for (const requirement of epic.requirements) {
+            if (!knownRequirements.has(requirement)) {
+                throw new Error(`L'epic ${epic.id} cite ${requirement}, absente de requirements.`);
+            }
+            const other = epicOf.get(requirement);
+            if (other) {
+                throw new Error(`L'exigence ${requirement} est dans deux epics : ${other} et ${epic.id}.`);
+            }
+            epicOf.set(requirement, epic.id);
+        }
+        for (const dependency of epic.dependsOn) {
+            if (!knownEpics.has(dependency)) {
+                throw new Error(`L'epic ${epic.id} dépend de ${dependency}, absent de epics.`);
+            }
+        }
+    }
+    if (epics.length > 0) {
+        const orphan = requirements.find((requirement) => !requirement.retired && !epicOf.has(requirement.id));
+        if (orphan)
+            throw new Error(`L'exigence ${orphan.id} n'appartient à aucun epic.`);
+    }
+    const cycle = findCycle(epics);
+    if (cycle)
+        throw new Error(`Dépendances circulaires entre epics : ${cycle.join(' → ')}.`);
+    const retiredRequirements = new Set(requirements.filter((requirement) => requirement.retired).map(({ id }) => id));
+    assertPriorities(epics, new Set(epics
+        .filter((epic) => epic.requirements.every((id) => retiredRequirements.has(id)))
+        .map((epic) => epic.id)));
+    return { requirements, epics };
+}
+export function parseRequirementRefs(specMarkdown) {
+    const value = /^\*\*Product Requirements\*\*:\s*(.*?)\s*$/m.exec(specMarkdown)?.[1];
+    if (value === undefined)
+        return undefined;
+    if (value === '' || value === 'None')
+        return [];
+    return value
+        .split(',')
+        .map((id) => id.trim())
+        .filter((id) => id !== '');
+}
+const STATE_ORDER = ['Draft', 'Implemented', 'Shipped'];
+export function traceRequirements(index, specs) {
+    const known = new Set(index?.requirements.map((requirement) => requirement.id));
+    const retired = new Set(index?.requirements.filter((requirement) => requirement.retired).map(({ id }) => id));
+    const unknown = specs
+        .flatMap(({ featureDir, refs }) => (refs ?? []).map((id) => ({ featureDir, id })))
+        .filter(({ id }) => !known.has(id));
+    // Une spec retirée avant la création de l'index n'a pas à être complétée.
+    const missingLine = index
+        ? specs
+            .filter((spec) => spec.refs === undefined && spec.status !== 'Retired')
+            .map((spec) => spec.featureDir)
+        : [];
+    const retiredCited = specs
+        .filter((spec) => spec.status !== 'Retired')
+        .flatMap(({ featureDir, refs }) => (refs ?? []).map((id) => ({ featureDir, id })))
+        .filter(({ id }) => retired.has(id));
+    const rows = (index?.requirements ?? []).map(({ id, title }) => {
+        const cited = specs
+            .filter((spec) => spec.refs?.includes(id))
+            .map(({ featureDir, status }) => ({ featureDir, status }))
+            .sort((a, b) => a.featureDir.localeCompare(b.featureDir));
+        const active = cited.filter((spec) => spec.status !== 'Retired');
+        // L'exigence n'avance qu'avec sa spec la moins avancée : une v2 en Draft la remet en cours.
+        const state = retired.has(id)
+            ? 'Retired'
+            : cited.length === 0
+                ? 'Unspecified'
+                : active.length === 0
+                    ? 'Retired'
+                    : (STATE_ORDER.find((status) => active.some((spec) => spec.status === status)) ??
+                        'Draft');
+        return { id, title, state, specs: cited };
+    });
+    return {
+        rows,
+        unknown,
+        missingLine,
+        retiredCited,
+        ok: unknown.length === 0 && missingLine.length === 0,
+    };
+}
+// Du moins avancé au plus avancé : l'état d'un epic est celui de son exigence la moins avancée.
+const PROGRESS = [
+    'Unspecified',
+    'Draft',
+    'Implemented',
+    'Shipped',
+];
+const isDone = (state) => state === 'Implemented' || state === 'Shipped';
+/**
+ * Cellules État et Avancement du tableau des epics. L'état reste celui de l'exigence la moins
+ * avancée ; un epic commencé ne s'affiche pas pour autant comme non spécifié.
+ */
+export function epicCells({ state, progress: { total, specified, done }, }) {
+    if (state === 'Retired')
+        return { state, progress: '' };
+    const label = state !== 'Unspecified' ? state : specified > 0 ? '**en cours**' : '**non spécifié**';
+    return { state: label, progress: `${specified}/${total} spécifiées, ${done}/${total} terminées` };
+}
+/**
+ * `requirementRows` vient de toutes les specs (l'état d'un epic en dépend) ; `specs`, seulement de
+ * celles à vérifier (avertissements de dépendance).
+ */
+export function traceEpics(index, requirementRows, specs, testFiles) {
+    const stateOf = new Map(requirementRows.map((row) => [row.id, row.state]));
+    const retiredInIndex = new Set(index.requirements.filter((requirement) => requirement.retired).map(({ id }) => id));
+    // Tri stable : à niveau égal, l'ordre du fichier.
+    const ordered = [...index.epics].sort((a, b) => (a.priority ?? Infinity) - (b.priority ?? Infinity));
+    const rows = ordered.map(({ id, title, requirements, dependsOn, priority }) => {
+        // Seul l'index retire une exigence d'un epic : si toutes ses specs sont retirées alors qu'elle
+        // reste active, elle est à refaire.
+        const states = requirements
+            .filter((requirement) => !retiredInIndex.has(requirement))
+            .map((requirement) => stateOf.get(requirement) ?? 'Unspecified')
+            .map((state) => (state === 'Retired' ? 'Unspecified' : state));
+        const state = states.length === 0
+            ? 'Retired'
+            : (PROGRESS.find((candidate) => states.includes(candidate)) ?? 'Unspecified');
+        const progress = {
+            total: states.length,
+            specified: states.filter((candidate) => candidate !== 'Unspecified').length,
+            done: states.filter(isDone).length,
+        };
+        return { id, title, state, progress, requirements, dependsOn, priority };
+    });
+    const epicState = new Map(rows.map((row) => [row.id, row.state]));
+    // Une dépendance ne retient plus rien une fois terminée, ou retirée : il n'y a plus rien à attendre.
+    const settled = (dependency) => {
+        const state = epicState.get(dependency) ?? 'Unspecified';
+        return isDone(state) || state === 'Retired';
+    };
+    const ready = rows.filter((row) => row.state !== 'Retired' && !isDone(row.state) && row.dependsOn.every(settled));
+    const next = ready.filter((row) => row.priority === ready[0]?.priority).map((row) => row.id);
+    const journeyList = index.epics.flatMap((epic) => epic.journeys.map((journey) => ({ ...journey, epicId: epic.id })));
+    const known = new Map(journeyList.map((journey) => [journey.id, journey]));
+    const testsById = new Map();
+    const orphans = [];
+    const retiredCited = [];
+    for (const file of testFiles) {
+        for (const id of new Set(file.content.match(/\bE\d+-J\d+\b/g) ?? [])) {
+            const journey = known.get(id);
+            if (!journey) {
+                orphans.push({ id, path: file.path });
+                continue;
+            }
+            testsById.set(id, (testsById.get(id) ?? new Set()).add(file.path));
+            if (journey.retired)
+                retiredCited.push({ id, path: file.path });
+        }
+    }
+    const byIdThenPath = (a, b) => a.id.localeCompare(b.id) || a.path.localeCompare(b.path);
+    orphans.sort(byIdThenPath);
+    retiredCited.sort(byIdThenPath);
+    const journeys = journeyList.map(({ id, epicId, title, retired }) => ({
+        id,
+        epicId,
+        title,
+        retired: retired !== undefined,
+        tests: [...(testsById.get(id) ?? [])].sort(),
+    }));
+    const uncovered = journeys
+        .filter((journey) => !journey.retired &&
+        journey.tests.length === 0 &&
+        isDone(epicState.get(journey.epicId) ?? 'Unspecified'))
+        .map((journey) => journey.id);
+    const epicOf = new Map(index.epics.flatMap((epic) => epic.requirements.map((id) => [id, epic])));
+    const blocked = [];
+    for (const spec of specs.filter((candidate) => candidate.status === 'Draft')) {
+        const epics = new Set((spec.refs ?? []).flatMap((id) => epicOf.get(id) ?? []));
+        for (const epic of epics) {
+            const waitingOn = epic.dependsOn.filter((dependency) => !settled(dependency));
+            if (waitingOn.length > 0)
+                blocked.push({ featureDir: spec.featureDir, epicId: epic.id, waitingOn });
+        }
+    }
+    return {
+        rows,
+        next,
+        journeys,
+        uncovered,
+        orphans,
+        retiredCited,
+        blocked,
+        ok: uncovered.length === 0 && orphans.length === 0 && retiredCited.length === 0,
+    };
+}

package/dist/stack.mjs

@@ -0,0 +1,72 @@
+import { parse as parseYaml } from 'yaml';
+/**
+ * Ce que spec-trace lit dans `.specify/stack.yml` : les motifs des fichiers de tests
+ * (`tests.globs`). Sans eux, ceux du boilerplate nx-react-nestjs.
+ */
+export const DEFAULT_TEST_GLOBS = ['**/*.spec.ts', '**/*.spec.tsx'];
+const SHAPE = "tests.globs doit être une liste de motifs (ex. ['src/**/*.test.ts']).";
+export function testGlobs(stackYaml) {
+    if (stackYaml === undefined)
+        return DEFAULT_TEST_GLOBS;
+    let data;
+    try {
+        data = parseYaml(stackYaml);
+    }
+    catch (error) {
+        throw new Error(`YAML invalide : ${error.message}`);
+    }
+    const tests = data?.tests;
+    if (tests === undefined || tests === null)
+        return DEFAULT_TEST_GLOBS;
+    if (typeof tests !== 'object' || Array.isArray(tests)) {
+        throw new Error(`tests doit être un objet (globs, needs). ${SHAPE}`);
+    }
+    const globs = tests.globs;
+    if (globs === undefined || globs === null)
+        return DEFAULT_TEST_GLOBS;
+    if (!Array.isArray(globs) ||
+        globs.length === 0 ||
+        globs.some((glob) => typeof glob !== 'string' || glob.trim() === '')) {
+        throw new Error(SHAPE);
+    }
+    return globs;
+}
+/** `src/*.{test,spec}.ts` → `src/*.test.ts`, `src/*.spec.ts` ; accolades imbriquées comprises. */
+export function expandBraces(glob) {
+    const open = glob.indexOf('{');
+    if (open < 0)
+        return [glob];
+    let depth = 0;
+    const commas = [];
+    for (let at = open; at < glob.length; at++) {
+        const char = glob[at];
+        if (char === '{')
+            depth++;
+        else if (char === '}' && --depth === 0) {
+            const parts = [];
+            let start = open + 1;
+            for (const comma of commas) {
+                parts.push(glob.slice(start, comma));
+                start = comma + 1;
+            }
+            parts.push(glob.slice(start, at));
+            const before = glob.slice(0, open);
+            const after = glob.slice(at + 1);
+            return parts.flatMap((part) => expandBraces(`${before}${part}${after}`));
+        }
+        else if (char === ',' && depth === 1)
+            commas.push(at);
+    }
+    throw new Error(`Accolade non fermée dans le motif « ${glob} ».`);
+}
+/**
+ * Les motifs en pathspecs git (`:(glob)…`) : la liste des tests et l'avertissement de dérive
+ * passent tous deux par git, donc par le même moteur de motifs, quel que soit le runtime. `**`
+ * y couvre aussi la racine et les dossiers à point (`.storybook/`).
+ */
+export function pathspecs(globs) {
+    return globs
+        .flatMap(expandBraces)
+        .map((glob) => glob.replace(/^(\.\/)+/, ''))
+        .map((glob) => `:(glob)${glob}`);
+}

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "@artefact-ci/spec-trace",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Matrice scénarios → tests des specs Spec Kit (méthode artefact-sdd)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/artefact-ci/speckit-artefact.git",
+    "directory": "packages/spec-trace"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "type": "module",
+  "bin": {
+    "spec-trace": "dist/cli.mjs"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=24.11"
+  },
+  "dependencies": {
+    "yaml": "^2.9.1"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "node --test 'src/*.test.mts'"
+  }
 }