@activate-core/test-forge 0.15.0 → 0.16.0

package/README.md

@@ -54,6 +54,29 @@ testforge generate --journey refund-flow
 testforge generate --area ops
 ```
 
+### A feature that arrives on its own document
+
+A ticket turns up with a PDF, or a spec for one feature. Point `discover` at it
+directly — you do not name the journey, the AI reads the document and works out
+which journey it describes:
+
+```bash
+testforge discover --reference ./docs/tickets/zh-4521.pdf
+```
+
+**A reference only writes the journeys it actually covers.** The ticket's PDF
+has never heard of your other journeys, so their docs are left exactly as they
+are, and the project's own source of truth stays where it was. TestForge then
+remembers that this one journey came from that document, and refreshes it from
+there on every later `update` — not from the project spec, which still does not
+describe it.
+
+When a reference really is the whole product's new specification, say so:
+
+```bash
+testforge discover --reference ./docs/prd-v2.md --replace
+```
+
 A journey **is** its doc: `generate` reads `docs/` and treats every markdown
 file there as one journey. So a doc you write by hand — for a feature the
 reference does not cover yet, or one taken from a ticket — works exactly like a

package/dist/cli/index.js

@@ -45,7 +45,11 @@ function flagValue(name) {
 }
 /** Source-of-truth options shared by setup and discover. */
 function sourceOptions() {
-    return { reference: flagValue('--reference'), source: flagValue('--source') };
+    return {
+        reference: flagValue('--reference'),
+        source: flagValue('--source'),
+        replace: process.argv.includes('--replace'),
+    };
 }
 /**
  * The output dirs to scan for env vars the GENERATED suite reads (test
@@ -78,6 +82,9 @@ function printUsage() {
     console.log('  testforge discover          Draft journey docs (asks: map or reference)');
     console.log('  testforge discover --journey <name>  Draft just ONE journey doc');
     console.log('  testforge discover --reference <file|url>  Base docs on a reference');
+    console.log('                              (a reference only writes the journeys it');
+    console.log('                               describes — add --replace to let it');
+    console.log('                               redraft the whole project)');
     console.log('  testforge map               Scan project, write journey + data map');
     console.log('  testforge init              Inspect project and write config');
     console.log('  testforge update            Re-check and update only what changed');

package/dist/core/discover.js

@@ -15,10 +15,12 @@
  * keeps this simple and works for projects of any size.
  */
 import { execFileSync } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync, writeFileSync, } from 'node:fs';
+import { join, relative, sep } from 'node:path';
 import { loadConfig, splitCommand, withEditTools } from './config.js';
 import { DEEP_DOC_GUIDANCE } from './doc-guidance.js';
 import { promptConfirm } from './prompt.js';
-import { resolveDocsSource, saveSourceChoice, } from './source-of-truth.js';
+import { loadSourceChoice, resolveDocsSource, saveJourneyReferences, saveSourceChoice, } from './source-of-truth.js';
 import { analyzeReference, draftDocsFromReference, DIFF_PATH, } from './reference.js';
 /** Scope line: one journey, or all of them. */
 function scopeLines(journey) {
@@ -118,6 +120,30 @@ function runCodeDiscover(srcDir, docsDir, journey) {
     });
     return output.trim();
 }
+/**
+ * Every journey doc currently on disk, keyed by its path relative to the docs
+ * dir ("web/refund-flow.md"), with its exact contents. Taking this BEFORE a
+ * draft is what lets us tell three things apart afterwards: a doc the
+ * reference newly created, one it rewrote, and one it should never have
+ * touched at all.
+ */
+function snapshotDocs(docsDir) {
+    const found = new Map();
+    if (!existsSync(docsDir))
+        return found;
+    const walk = (dir) => {
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            const full = join(dir, entry.name);
+            if (entry.isDirectory())
+                walk(full);
+            else if (entry.name.endsWith('.md')) {
+                found.set(relative(docsDir, full).split(sep).join('/'), readFileSync(full, 'utf-8'));
+            }
+        }
+    };
+    walk(docsDir);
+    return found;
+}
 /**
  * Run discovery. First decides the source of truth for the docs (the
  * code-derived map, or an external reference — see source-of-truth.ts),
@@ -146,9 +172,69 @@ export async function runDiscover(srcDir, docsDir, opts = {}, journey) {
                 return runCodeDiscover(srcDir, docsDir, journey);
             }
         }
-        console.log('\nDrafting docs from the reference...\n');
-        const out = draftDocsFromReference(srcDir, docsDir, source.reference, journey);
-        saveSourceChoice({ mode: 'reference', reference: source.reference });
+        // Is this the product's specification, or one feature's? A ticket's PDF
+        // knows nothing about the other 26 journeys, so letting it rewrite them
+        // would swap a reviewed spec for whatever the code happens to do today —
+        // the exact inversion these tests exist to catch. So a reference only
+        // writes what it covers, unless it IS the project's spec or --replace
+        // says to treat it as one.
+        const stored = loadSourceChoice();
+        const before = snapshotDocs(docsDir);
+        const bootstrapping = before.size === 0;
+        const wholeProject = Boolean(opts.replace) ||
+            bootstrapping ||
+            !stored?.reference ||
+            stored.reference === source.reference;
+        // Docs that belong to a DIFFERENT reference — a ticket's spec, say — are
+        // off limits even to the project's own specification, which has never
+        // heard of that feature and would redraft it from the code.
+        const ownedElsewhere = new Set(Object.entries(stored?.journeys || {})
+            .filter(([, ref]) => ref !== source.reference)
+            .map(([doc]) => doc));
+        const offLimits = wholeProject
+            ? [...ownedElsewhere]
+            : [...new Set([...before.keys(), ...ownedElsewhere])];
+        console.log(wholeProject
+            ? '\nDrafting docs from the reference...\n'
+            : '\nDrafting docs from the reference (adding to the existing docs)...\n');
+        const out = draftDocsFromReference(srcDir, docsDir, source.reference, journey, offLimits.length ? offLimits : undefined);
+        const after = snapshotDocs(docsDir);
+        const added = [];
+        const rewritten = [];
+        for (const [path, text] of after) {
+            const prior = before.get(path);
+            if (prior === undefined)
+                added.push(path);
+            else if (prior !== text)
+                rewritten.push(path);
+        }
+        // Put back anything it reached for that this reference does not own. The
+        // prompt asks it not to; this makes it true whether or not it complied.
+        const restored = rewritten.filter((path) => wholeProject ? ownedElsewhere.has(path) : true);
+        for (const path of restored) {
+            writeFileSync(join(docsDir, path), before.get(path), 'utf-8');
+        }
+        if (wholeProject) {
+            saveSourceChoice({ mode: 'reference', reference: source.reference });
+            if (added.length)
+                saveJourneyReferences(added, source.reference);
+            if (restored.length) {
+                console.log(`\n${restored.length} doc(s) kept as they were — they come from a ` +
+                    'reference of their own, not the project specification.');
+            }
+        }
+        else {
+            saveJourneyReferences(added, source.reference);
+            console.log(`\n${added.length} journey doc(s) written from this reference` +
+                (added.length ? `: ${added.join(', ')}` : '') + '.');
+            if (restored.length) {
+                console.log(`${restored.length} existing doc(s) left as they were — this ` +
+                    'reference does not describe them.');
+            }
+            console.log('The project\'s source of truth is unchanged' +
+                (stored?.reference ? `: ${stored.reference}` : '') +
+                '. Use --replace to hand that role to this reference instead.');
+        }
         return out;
     }
     saveSourceChoice({ mode: 'map' });

package/dist/core/reference.js

@@ -88,7 +88,7 @@ export function buildAnalyzePrompt(reference, docsDir) {
  * treating it as the source of truth for behavior. Mirrors the code-based
  * discover format so the docs are interchangeable downstream.
  */
-export function buildReferenceDiscoverPrompt(srcDir, docsDir, reference, journey) {
+export function buildReferenceDiscoverPrompt(srcDir, docsDir, reference, journey, existingDocs) {
     const scope = journey
         ? [
             `SCOPE: document ONLY the single journey matching "${journey}"`,
@@ -123,11 +123,26 @@ export function buildReferenceDiscoverPrompt(srcDir, docsDir, reference, journey
         `For EACH journey the reference describes, create one markdown file at`,
         `"${docsDir}/<area>/<journey>.md" (area = folder such as api/web/ops,`,
         `short kebab-case journey name; do NOT put the area in the file name).`,
-        `Also create a doc for any journey that exists in the map but NOT in`,
-        `the reference, drafted from the map, and add a line`,
-        `"# TODO: not covered by the reference — confirm expected behavior"`,
-        `at its top so it is clearly flagged.`,
         ``,
+        ...(existingDocs
+            ? [
+                `THIS REFERENCE COVERS PART OF THE PRODUCT, NOT ALL OF IT. The`,
+                `journeys below already have reviewed docs written from the`,
+                `project's own specification, which this reference has never heard`,
+                `of. Do NOT open, rewrite, re-draft or "improve" any of them, and do`,
+                `NOT add a not-covered note to them. Touch ONLY the journey or`,
+                `journeys this reference actually describes — creating a new file if`,
+                `the feature is new, or updating that one file if it already exists.`,
+                ...existingDocs.map((d) => `  - ${d}`),
+                ``,
+            ]
+            : [
+                `Also create a doc for any journey that exists in the map but NOT in`,
+                `the reference, drafted from the map, and add a line`,
+                `"# TODO: not covered by the reference — confirm expected behavior"`,
+                `at its top so it is clearly flagged.`,
+                ``,
+            ]),
         `Each file starts with this header (required):`,
         ``,
         `# Journey: <Name>`,
@@ -181,6 +196,6 @@ export function analyzeReference(reference, docsDir) {
  * Draft the journey docs from the reference. Returns the AI's summary of
  * the journeys it documented.
  */
-export function draftDocsFromReference(srcDir, docsDir, reference, journey) {
-    return runAI(buildReferenceDiscoverPrompt(srcDir, docsDir, reference, journey));
+export function draftDocsFromReference(srcDir, docsDir, reference, journey, existingDocs) {
+    return runAI(buildReferenceDiscoverPrompt(srcDir, docsDir, reference, journey, existingDocs));
 }

package/dist/core/source-of-truth.js

@@ -30,7 +30,13 @@ export function loadSourceChoice() {
     try {
         const parsed = JSON.parse(readFileSync(SOURCE_PATH, 'utf-8'));
         if (parsed && (parsed.mode === 'map' || parsed.mode === 'reference')) {
-            return { mode: parsed.mode, reference: parsed.reference };
+            return {
+                mode: parsed.mode,
+                reference: parsed.reference,
+                journeys: parsed.journeys && typeof parsed.journeys === 'object'
+                    ? parsed.journeys
+                    : undefined,
+            };
         }
     }
     catch {
@@ -38,10 +44,39 @@ export function loadSourceChoice() {
     }
     return null;
 }
-/** Remember the source choice for later refreshes. */
+/**
+ * Remember the PROJECT's source choice. The per-journey map is carried over
+ * untouched: a ticket-sized reference must never cost the project the record
+ * of where its other journeys came from.
+ */
 export function saveSourceChoice(choice) {
+    const existing = loadSourceChoice();
+    const journeys = choice.journeys ?? existing?.journeys;
+    const next = { mode: choice.mode };
+    if (choice.reference)
+        next.reference = choice.reference;
+    if (journeys && Object.keys(journeys).length)
+        next.journeys = journeys;
     mkdirSync(dirname(SOURCE_PATH), { recursive: true });
-    writeFileSync(SOURCE_PATH, JSON.stringify(choice, null, 2), 'utf-8');
+    writeFileSync(SOURCE_PATH, JSON.stringify(next, null, 2), 'utf-8');
+}
+/**
+ * Record that these docs came from a reference of their own — a ticket, a
+ * one-feature PDF — so a later refresh goes back to THAT document and not to
+ * the project-wide spec, which has never heard of the feature.
+ */
+export function saveJourneyReferences(docPaths, reference) {
+    if (!docPaths.length)
+        return;
+    const existing = loadSourceChoice() || { mode: 'reference' };
+    const journeys = { ...(existing.journeys || {}) };
+    for (const d of docPaths)
+        journeys[d] = reference;
+    saveSourceChoice({
+        mode: existing.mode,
+        reference: existing.reference,
+        journeys,
+    });
 }
 /**
  * Decide where the docs should come from for this run. May prompt the

package/dist/core/update.js

@@ -70,6 +70,16 @@ export async function runUpdate(srcDir, opts = {}) {
     // without prompting — an update is a refresh, not a re-decision.
     console.log('Updating journey docs...');
     await runDiscover(srcDir, 'docs', { noPrompt: true });
+    // Journeys that arrived on their own document — a ticket's attached spec —
+    // are refreshed from THAT document. The project specification does not
+    // describe them, so refreshing them from it would quietly replace a written
+    // requirement with whatever the code currently does.
+    const ownRefs = Object.entries(src.journeys || {}).filter(([, ref]) => ref !== src.reference);
+    for (const [doc, ref] of ownRefs) {
+        const name = doc.replace(/\.md$/, '').split('/').pop();
+        console.log(`  refreshing ${name} from its own reference: ${ref}`);
+        await runDiscover(srcDir, 'docs', { reference: ref, noPrompt: true }, name);
+    }
     console.log('  done — docs/\n');
     console.log('Regenerating tests for changed journeys...');
     const results = await runGenerate('docs', true, false);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@activate-core/test-forge",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "AI-powered QA automation. Scans a project, drafts journey docs, and generates seeded Jest/Playwright tests. Works in any project, with any AI CLI.",
   "type": "module",
   "bin": {