@artefact-ci/spec-trace 0.1.0 → 0.2.0

package/README.md

@@ -12,7 +12,7 @@ npx @artefact-ci/spec-trace --tests 'src/**/*.test.ts'  # autres fichiers de tes
 À 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`).
+- 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

package/dist/cli.mjs

@@ -12,8 +12,8 @@
  * 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, de chaque exigence et la couverture des parcours. Un epic
- * terminé exige un test par parcours (`E03-J1: …`).
+ * 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';
@@ -97,12 +97,20 @@ function printRequirements(report, { hasIndex, showRows }) {
 function printEpics(report, { showRows }) {
     if (showRows && report.rows.length > 0) {
         console.log(`\n## Epics (${REQUIREMENT_INDEX}) : ${report.ok ? 'OK' : 'INCOMPLET'}\n`);
-        console.log('| Epic | État | Avancement | Exigences | Dépend de |');
-        console.log('| ---- | ---- | ---------- | --------- | --------- |');
+        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);
-            console.log(`| ${row.id} ${row.title} | ${state} | ${progress} | ${row.requirements.join(', ')} | ${row.dependsOn.join(', ')} |`);
+            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 |');

package/dist/core.mjs

@@ -140,6 +140,7 @@ export function driftedFeatures(diff, changedPaths) {
 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.`);
@@ -163,6 +164,16 @@ function textList(fields, key, owner) {
     }
     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) {
@@ -196,6 +207,26 @@ function findCycle(epics) {
     }
     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;
@@ -262,6 +293,7 @@ export function parseProductIndex(yamlText) {
             goal: text(fields, 'goal', owner),
             requirements: epicRequirements,
             dependsOn: textList(fields, 'depends_on', owner),
+            priority: priorityOf(fields, owner),
             journeys,
         };
     });
@@ -295,6 +327,10 @@ export function parseProductIndex(yamlText) {
     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) {
@@ -375,7 +411,9 @@ export function epicCells({ state, progress: { total, specified, done }, }) {
 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));
-    const rows = index.epics.map(({ id, title, requirements, dependsOn }) => {
+    // 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
@@ -390,9 +428,16 @@ export function traceEpics(index, requirementRows, specs, testFiles) {
             specified: states.filter((candidate) => candidate !== 'Unspecified').length,
             done: states.filter(isDone).length,
         };
-        return { id, title, state, progress, requirements, dependsOn };
+        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();
@@ -430,13 +475,14 @@ export function traceEpics(index, requirementRows, specs, testFiles) {
     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) => !isDone(epicState.get(dependency) ?? 'Unspecified'));
+            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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@artefact-ci/spec-trace",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Matrice scénarios → tests des specs Spec Kit (méthode artefact-sdd)",
   "license": "MIT",
   "repository": {