@activate-core/test-forge 0.1.1 → 0.3.0

package/README.md

@@ -40,7 +40,7 @@ testforge update     # re-check and refresh only what changed
 | Command              | What it does                                                                                                                       |
 | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
 | `testforge setup`    | One-time setup: runs init, map, and discover in order, with progress.                                                              |
-| `testforge generate` | Generates a test file and a seed file for each journey doc. Only changed docs are regenerated.                                     |
+| `testforge generate` | Generates a test file and a seed file for each journey doc. Only changed docs are regenerated. |
 | `testforge update`   | Detects source-code changes and refreshes the map, docs, and tests when needed. Skips everything if nothing changed (no AI calls). |
 
 ### Advanced (run a single step)
@@ -73,6 +73,57 @@ generates a seed file that provisions the test data each test needs.
 **update** hashes your source code and compares it to the last run. No
 change means no work and no AI calls; a change triggers a refresh.
 
+## Source of truth
+
+The journey docs in `docs/` are the source of truth for the tests —
+`generate` reads the docs and nothing else. So where the docs come from
+decides everything.
+
+By default the docs are derived from your **code** (the AI reads the
+project, writes `testforge.md`, then drafts the docs from it). That is
+fast, but it inherits whatever the code does: if a flow is buggy or a
+scenario is mishandled, the AI faithfully documents the wrong behavior,
+and the tests then lock that wrong behavior in.
+
+So when the docs are drafted — during `testforge setup` (or `testforge
+discover`) — testforge asks what they should be based on:
+
+```
+What should the journey docs be based on?
+  [1] testforge.md (what the AI derived from your code) (default)
+  [2] An external reference (a file/PDF in scope, a website, or a Notion link)
+```
+
+Choose **[2]** to give testforge an authoritative reference of the
+_expected_ behavior — a spec or requirements doc in the repo, a PDF, a
+website, or a Notion page. testforge then:
+
+1. reads the reference and compares it against `testforge.md`,
+2. writes a full comparison to **`testforge.diff.md`** and prints a short
+   summary of the differences,
+3. asks you to confirm, and on confirmation **drafts the docs from the
+   reference** — expected behavior comes from the reference, while routes,
+   fields, models, and env var names come from the code/map,
+4. `generate` then turns those docs into tests as usual.
+
+The reference becomes the source of truth — expected behavior from a human
+or client, not just what the code happens to do. The choice is remembered
+in `.testforge/source.json`, so a later `testforge update` refreshes the
+docs from the same source without asking again. Your review of
+`testforge.diff.md` stays as an audit of what differed and why.
+
+**Non-interactive use (CI, scripts):**
+
+```bash
+testforge setup --source map              # base the docs on testforge.md, no prompt
+testforge setup --reference ./spec.md     # base the docs on a reference, no prompts
+testforge setup --reference https://…     # a URL or Notion link works too
+```
+
+The same flags work on `testforge discover`. With no flags and no terminal
+attached, testforge does not block — it falls back to `testforge.md` and
+prints a note.
+
 ## Running the generated tests
 
 testforge generates the tests and seed files — you run them with your
@@ -159,7 +210,12 @@ The test runner produces its own pass/fail report.
 
 - **aiCommand** — the CLI used to call the AI. Any tool that reads a
   prompt from stdin and prints the reply works, so testforge is not tied
-  to one provider.
+  to one provider. testforge appends the right flags per phase: the
+  setup phases (init/map/discover) run with edit permission because the
+  model writes files, while the generation phases (tests/seeds) run with
+  no tools (`--allowedTools ""` for Claude) so the model just prints code
+  instead of trying to create files — which would otherwise leak "the
+  write wasn't approved…" prose into the output.
 - **testOutput** — where tests go, per area. Areas are not fixed — use
   whatever your project has (`api`, `web`, `ops`, `lambda`, ...).
 - **framework** — which test framework each area uses.

package/dist/cli/index.js

@@ -3,9 +3,16 @@
  * testforge — command-line entry point.
  *
  * Commands:
- *   testforge generate           Generate tests for changed journeys (AI).
- *   testforge generate --basic   Use the built-in basic generator only.
- *   testforge generate --force   Regenerate everything, ignoring the cache.
+ *   testforge setup                    init + map + discover. discover asks
+ *                                      whether the docs come from testforge.md
+ *                                      or an external reference (the source of
+ *                                      truth for every test).
+ *   testforge setup --reference <x>    Base the docs on reference <x> (a file
+ *                                      path, URL, or Notion link) — no prompt.
+ *   testforge setup --source map       Base the docs on testforge.md — no prompt.
+ *   testforge generate                 Generate tests from the journey docs.
+ *   testforge generate --basic         Use the built-in basic generator only.
+ *   testforge generate --force         Regenerate everything, ignoring the cache.
  */
 import { VERSION } from '../core/index.js';
 import { runGenerate } from '../core/run-generate.js';
@@ -18,74 +25,112 @@ import { runEnvTemplate } from '../core/env-template.js';
 const command = process.argv[2];
 const useBasic = process.argv.includes('--basic');
 const force = process.argv.includes('--force');
-if (command === 'update') {
-    runUpdate('.');
+/** Read the value that follows a `--flag <value>` option, if present. */
+function flagValue(name) {
+    const i = process.argv.indexOf(name);
+    if (i === -1)
+        return undefined;
+    const value = process.argv[i + 1];
+    if (value === undefined || value.startsWith('--'))
+        return undefined;
+    return value;
 }
-else if (command === 'setup') {
-    runSetup('.');
+/** Source-of-truth options shared by setup and discover. */
+function sourceOptions() {
+    return { reference: flagValue('--reference'), source: flagValue('--source') };
 }
-else if (command === 'init') {
-    console.log('Inspecting your project to set up testforge...\n');
-    const output = runInit();
-    console.log(output);
-    console.log('\ntestforge.config.json written. Review it, then run `testforge map`.');
-}
-else if (command === 'map') {
-    console.log('Building a high-level map of your project with AI...');
-    console.log('This scans your source code and writes testforge.md\n');
-    const output = runMap('.');
-    console.log(output);
-    console.log('\nProject map written to testforge.md');
-}
-else if (command === 'discover') {
-    console.log('Scanning your project with AI to draft journey files...');
-    console.log('This reads your source code and writes drafts into docs/.\n');
-    const output = runDiscover('.', 'docs');
-    console.log(output);
-    console.log('\nDraft journeys written to docs/. Please review and edit them,');
-    console.log('then run `testforge generate`.');
-}
-else if (command === 'env') {
-    runEnvTemplate('docs', '.env.testing.example');
-}
-else if (command === 'generate') {
-    const useAI = !useBasic;
-    console.log(useAI
-        ? 'Generating tests with AI for changed journeys...\n'
-        : 'Generating tests with the basic generator...\n');
-    const results = runGenerate('docs', useAI, force);
-    if (results.length === 0) {
-        console.log('No journey files found in docs/. Add a .md file and try again.');
-    }
-    else {
-        for (const r of results) {
-            if (r.status === 'skipped') {
-                console.log(`  [skip] ${r.journeyName} (unchanged)`);
-            }
-            else {
-                const tag = r.status === 'ai' ? '[AI]' : '[basic]';
-                console.log(`  ${tag} ${r.journeyName}`);
-                console.log(`         test: ${r.testPath}`);
-                if (r.status === 'ai')
-                    console.log(`         seed: ${r.seedPath}`);
-            }
-        }
-        const generated = results.filter((r) => r.status !== 'skipped').length;
-        const skipped = results.filter((r) => r.status === 'skipped').length;
-        console.log(`\nDone. ${generated} generated, ${skipped} skipped (unchanged).`);
-    }
-}
-else {
+function printUsage() {
     console.log(`testforge v${VERSION}`);
     console.log('');
     console.log('Usage:');
-    console.log('  testforge generate           Generate tests for changed journeys');
+    console.log('  testforge setup             Run init + map + discover in order');
+    console.log('  testforge setup --reference <file|url>  Base the docs on a reference');
+    console.log('  testforge setup --source map            Base the docs on testforge.md');
+    console.log('  testforge generate           Generate tests from the journey docs');
     console.log('  testforge generate --basic   Use the basic generator only');
     console.log('  testforge generate --force   Regenerate everything');
-    console.log('  testforge discover          Scan source code and draft journey files');
+    console.log('  testforge discover          Draft journey docs (asks: map or reference)');
     console.log('  testforge map               Scan project, write journey + data map');
     console.log('  testforge init              Inspect project and write config');
-    console.log('  testforge setup             Run init + map + discover in order');
     console.log('  testforge update            Re-check and update only what changed');
     console.log('  testforge env               Write .env.testing.example from docs');
 }
+async function main() {
+    if (command === 'update') {
+        await runUpdate('.');
+    }
+    else if (command === 'setup') {
+        await runSetup('.', sourceOptions());
+    }
+    else if (command === 'init') {
+        console.log('Inspecting your project to set up testforge...\n');
+        const output = runInit();
+        console.log(output);
+        console.log('\ntestforge.config.json written. Review it, then run `testforge map`.');
+    }
+    else if (command === 'map') {
+        console.log('Building a high-level map of your project with AI...');
+        console.log('This scans your source code and writes testforge.md\n');
+        const output = runMap('.');
+        console.log(output);
+        console.log('\nProject map written to testforge.md');
+    }
+    else if (command === 'discover') {
+        console.log('Drafting journey files with AI...');
+        console.log('This writes drafts into docs/ from your chosen source.\n');
+        const output = await runDiscover('.', 'docs', sourceOptions());
+        console.log(output);
+        console.log('\nDraft journeys written to docs/. Please review and edit them,');
+        console.log('then run `testforge generate`.');
+    }
+    else if (command === 'env') {
+        runEnvTemplate('docs', '.env.testing.example');
+    }
+    else if (command === 'generate') {
+        const useAI = !useBasic;
+        console.log(useAI
+            ? 'Generating tests with AI for changed journeys...\n'
+            : 'Generating tests with the basic generator...\n');
+        const results = runGenerate('docs', useAI, force);
+        if (results.length === 0) {
+            console.log('No journey files found in docs/. Add a .md file and try again.');
+        }
+        else {
+            for (const r of results) {
+                if (r.status === 'skipped') {
+                    console.log(`  [skip] ${r.journeyName} (unchanged)`);
+                }
+                else {
+                    const tag = r.status === 'ai' ? '[AI]' : '[basic]';
+                    console.log(`  ${tag} ${r.journeyName}`);
+                    console.log(`         test: ${r.testPath}`);
+                    if (r.status === 'ai') {
+                        if (r.seedStatus === 'ok') {
+                            console.log(`         seed: ${r.seedPath}`);
+                        }
+                        else if (r.seedStatus === 'failed') {
+                            console.log(`         seed: (not written — generation failed)`);
+                        }
+                    }
+                }
+                for (const w of r.warnings ?? []) {
+                    console.log(`         ! ${w}`);
+                }
+            }
+            const generated = results.filter((r) => r.status !== 'skipped').length;
+            const skipped = results.filter((r) => r.status === 'skipped').length;
+            const seedFailures = results.filter((r) => r.seedStatus === 'failed').length;
+            console.log(`\nDone. ${generated} generated, ${skipped} skipped (unchanged).`);
+            if (seedFailures > 0) {
+                console.log(`Warning: ${seedFailures} seed file(s) could not be generated — see notes above.`);
+            }
+        }
+    }
+    else {
+        printUsage();
+    }
+}
+main().catch((err) => {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+});

package/dist/core/ai-generator.js

@@ -12,10 +12,10 @@
  */
 import { execFileSync } from 'node:child_process';
 import { readFileSync, existsSync } from 'node:fs';
-import { loadConfig, splitCommand } from './config.js';
+import { loadConfig, splitCommand, withTextOnlyTools } from './config.js';
 const MAP_PATH = 'testforge.md';
 /** Build the prompt we send to the AI for one journey. */
-export function buildPrompt(journey, map) {
+export function buildPrompt(journey, map, testPath) {
     const config = loadConfig();
     const fw = config.framework?.[journey.type];
     const isApi = journey.type === 'api' || fw === 'jest' || fw === 'supertest';
@@ -42,6 +42,16 @@ export function buildPrompt(journey, map) {
         `useful). For payment/webhook journeys, test idempotency, amount/`,
         `price tampering, and signature/verification where relevant.`,
         ``,
+        `IMPORTANT — do not presume the app is vulnerable. For every security`,
+        `probe, assert the SECURE expectation (e.g. auth bypass returns 401/403,`,
+        `a tampered amount is rejected, a duplicate charge is idempotent). Only`,
+        `assert that a vulnerability exists when the journey doc EXPLICITLY`,
+        `documents it as a known/accepted behavior. If you cannot tell from the`,
+        `journey or map whether a defense exists, write the check as`,
+        `test.todo(...) or it.skip(...) with a "// TODO:" note — never assume a`,
+        `guard is missing and produce a failing test that falsely brands the`,
+        `product as vulnerable.`,
+        ``,
         isApi
             ? [
                 `Because this is an API journey, write Jest tests that call the`,
@@ -60,6 +70,17 @@ export function buildPrompt(journey, map) {
                 `they are real.`,
             ].join('\n'),
         ``,
+        ...(testPath
+            ? [
+                `This test file will be saved at EXACTLY this path:`,
+                `  ${testPath}`,
+                `Compute every require()/import path (to app source, helpers, the`,
+                `seed file, etc.) RELATIVE TO THAT EXACT location — count the`,
+                `directory depth from that path, do not assume a conventional`,
+                `depth. Getting the relative depth wrong breaks the whole file.`,
+                ``,
+            ]
+            : []),
         `This test relies on seeded test data (a separate seed file provisions`,
         `the database before tests run). Assume the seed has created the`,
         `records described in the journey's Data section, using stable test`,
@@ -96,10 +117,12 @@ export function buildPrompt(journey, map) {
  * journey. Reads the project map (testforge.md) for data-layer
  * context. Returns the test file content.
  */
-export function generateWithAI(journey) {
+export function generateWithAI(journey, testPath) {
     const map = existsSync(MAP_PATH) ? readFileSync(MAP_PATH, 'utf-8') : '';
-    const prompt = buildPrompt(journey, map);
-    const { program, args } = splitCommand(loadConfig().aiCommand);
+    const prompt = buildPrompt(journey, map, testPath);
+    // Generation is pure text — run with NO tools so the model just
+    // prints code instead of trying to write files.
+    const { program, args } = withTextOnlyTools(splitCommand(loadConfig().aiCommand));
     const output = execFileSync(program, args, {
         input: prompt,
         encoding: 'utf-8',
@@ -107,35 +130,65 @@ export function generateWithAI(journey) {
     });
     return cleanOutput(output);
 }
+/** Does this line look like the start (or body) of real code? */
+function looksLikeCode(line) {
+    const t = line.trim();
+    return (t.startsWith('//') ||
+        t.startsWith('/*') ||
+        t.startsWith('*') ||
+        t.startsWith('import ') ||
+        t.startsWith('export ') ||
+        t.startsWith('const ') ||
+        t.startsWith('let ') ||
+        t.startsWith('var ') ||
+        t.startsWith('function ') ||
+        t.startsWith('async ') ||
+        t.startsWith('require(') ||
+        t.startsWith("'use strict'") ||
+        t.startsWith('"use strict"'));
+}
 /**
  * Extract clean code from the AI's reply.
  *
  * 1. If there's a fenced code block, take its contents.
- * 2. Otherwise, drop any leading prose by starting from the first line
- *    that looks like code (a comment, import, require, or known
- *    statement keyword). This rescues cases where the AI adds a
- *    sentence before the code despite instructions.
+ * 2. Otherwise, keep only the span between the first and the last
+ *    code-ish line — this strips BOTH leading prose ("Here is the
+ *    code:") and trailing prose ("Note: I attempted to write the
+ *    file...") that the model sometimes adds despite instructions.
+ * 3. If no code can be detected at all, throw so the caller can
+ *    retry or skip — we never return junk to be written to disk.
+ *
+ * Exported so the seed generator can share the exact same cleaning
+ * logic instead of a weaker fence-only strip.
  */
-function cleanOutput(text) {
+export function cleanOutput(text) {
     // 1. Prefer a fenced code block if present.
-    const fence = text.match(/```[a-zA-Z]*\n([\s\S]*?)\n```/);
+    const fence = text.match(/```[a-zA-Z]*\n([\s\S]*?)```/);
     if (fence) {
-        return fence[1].trim();
+        const inner = fence[1].trim();
+        if (!inner) {
+            throw new Error('AI output contained an empty code fence');
+        }
+        return inner;
     }
-    // 2. No fence — find the first line that looks like real code.
+    // 2. No fence — locate the first line that looks like real code.
     const lines = text.split('\n');
-    const codeStart = lines.findIndex((line) => {
-        const t = line.trim();
-        return (t.startsWith('//') ||
-            t.startsWith('/*') ||
-            t.startsWith('import ') ||
-            t.startsWith('const ') ||
-            t.startsWith('require(') ||
-            t.startsWith("'use strict'") ||
-            t.startsWith('"use strict"'));
-    });
-    if (codeStart > 0) {
-        return lines.slice(codeStart).join('\n').trim();
+    const codeStart = lines.findIndex(looksLikeCode);
+    if (codeStart === -1) {
+        throw new Error('AI output contained no recognizable code');
+    }
+    // Trim trailing prose: walk back from the end to the last line that
+    // is code-ish or ends with a code terminator (; } ) ]). A trailing
+    // sentence ("Note: ...") ends with a word/period, so it is dropped.
+    let codeEnd = codeStart;
+    for (let i = lines.length - 1; i >= codeStart; i--) {
+        const t = lines[i].trim();
+        if (t === '')
+            continue;
+        if (looksLikeCode(t) || /[;})\]]$/.test(t)) {
+            codeEnd = i;
+            break;
+        }
     }
-    return text.trim();
+    return lines.slice(codeStart, codeEnd + 1).join('\n').trim();
 }

package/dist/core/config.js

@@ -14,7 +14,16 @@
  *
  * If no config file exists, we default to "claude -p" so users with
  * Claude installed work out of the box. Users of other tools (Gemini,
- * Codex, etc.) set aiCommand to their own CLI.
+ * Codex, etc.) set aiCommand to their own CLI — it just needs to read a
+ * prompt on stdin and print the reply to stdout.
+ *
+ * The command is a BASE. Each phase appends the flags it needs (these
+ * are tool-specific; for Claude): the setup phases (init/map/discover)
+ * add `--permission-mode acceptEdits` because the model reads/writes
+ * files, while the pure-text generation phases add `--allowedTools ""`
+ * so the model has NO tools and just prints code — it can't try (and
+ * fail) to write a file and leak "the write wasn't approved..." prose
+ * into the output. See withTextOnlyTools / withEditTools.
  */
 import { readFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
@@ -44,14 +53,80 @@ export function loadConfig() {
 }
 /**
  * Split an AI command string into a program and its arguments.
- * Example: "claude -p" -> { program: "claude", args: ["-p"] }
+ *
+ * Quote-aware: single or double quotes group a token and can produce an
+ * EMPTY-string argument, which matters for invocations like
+ * `claude -p --allowedTools ""` (disable all tools). A naive
+ * whitespace split would turn "" into the literal two-char token `""`.
+ *
+ * Example: `claude -p --allowedTools ""`
+ *   -> { program: "claude", args: ["-p", "--allowedTools", ""] }
  */
 export function splitCommand(command) {
-    const parts = command.trim().split(/\s+/);
-    const program = parts[0];
-    const args = parts.slice(1);
+    const tokens = [];
+    let current = '';
+    let quote = null;
+    let started = false; // did the current token have any chars (incl. empty quotes)?
+    for (const ch of command.trim()) {
+        if (quote) {
+            if (ch === quote) {
+                quote = null; // closing quote — token may be empty
+            }
+            else {
+                current += ch;
+            }
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            started = true;
+            continue;
+        }
+        if (/\s/.test(ch)) {
+            if (started) {
+                tokens.push(current);
+                current = '';
+                started = false;
+            }
+            continue;
+        }
+        current += ch;
+        started = true;
+    }
+    if (started)
+        tokens.push(current);
+    const program = tokens[0] ?? '';
+    const args = tokens.slice(1);
     return { program, args };
 }
+/** Is this command Claude's CLI (so Claude-specific flags apply)? */
+function isClaude(program) {
+    const base = program.split(/[\\/]/).pop() ?? program;
+    return base === 'claude';
+}
+/**
+ * Args for a pure-text generation call (test/seed): no tools at all, so
+ * the model prints code instead of attempting file writes. Only applies
+ * the Claude flag when the base command is Claude; other CLIs get the
+ * command unchanged (configure their own text-only mode if needed).
+ */
+export function withTextOnlyTools(cmd) {
+    if (!isClaude(cmd.program))
+        return cmd;
+    return { program: cmd.program, args: [...cmd.args, '--allowedTools', ''] };
+}
+/**
+ * Args for a phase where the model must read/write files (init, map,
+ * discover). Mirrors withTextOnlyTools but grants edit permission.
+ */
+export function withEditTools(cmd) {
+    if (!isClaude(cmd.program))
+        return cmd;
+    return {
+        program: cmd.program,
+        args: [...cmd.args, '--permission-mode', 'acceptEdits'],
+    };
+}
 /**
  * Decide where a journey's test file should go, based on its type
  * and the config. Falls back to "generated-tests/<area>" when the

package/dist/core/discover.js

@@ -15,7 +15,10 @@
  * keeps this simple and works for projects of any size.
  */
 import { execFileSync } from 'node:child_process';
-import { loadConfig, splitCommand } from './config.js';
+import { loadConfig, splitCommand, withEditTools } from './config.js';
+import { promptConfirm } from './prompt.js';
+import { resolveDocsSource, saveSourceChoice, } from './source-of-truth.js';
+import { analyzeReference, draftDocsFromReference, DIFF_PATH, } from './reference.js';
 /** Build the discovery prompt. */
 export function buildDiscoverPrompt(srcDir, docsDir) {
     return [
@@ -83,21 +86,56 @@ export function buildDiscoverPrompt(srcDir, docsDir) {
     ].join('\n');
 }
 /**
- * Run discovery. This invokes the Claude CLI with permission to read
- * and write files in the project. Returns the CLI's text output (the
- * summary of what it created).
+ * Draft the docs from the project's own code (the default). Invokes the
+ * AI CLI with permission to read source and write markdown files.
  */
-export function runDiscover(srcDir, docsDir) {
+function runCodeDiscover(srcDir, docsDir) {
     const prompt = buildDiscoverPrompt(srcDir, docsDir);
     // Use the configured AI command. Note: discovery needs the AI to
     // read source files and write markdown files. The flags for that
     // are tool-specific; for Claude we add acceptEdits. Other tools may
     // need different setup (see README).
-    const { program, args } = splitCommand(loadConfig().aiCommand);
-    const output = execFileSync(program, [...args, '--permission-mode', 'acceptEdits'], {
+    const { program, args } = withEditTools(splitCommand(loadConfig().aiCommand));
+    const output = execFileSync(program, args, {
         input: prompt,
         encoding: 'utf-8',
         maxBuffer: 10 * 1024 * 1024,
     });
     return output.trim();
 }
+/**
+ * Run discovery. First decides the source of truth for the docs (the
+ * code-derived map, or an external reference — see source-of-truth.ts),
+ * then drafts the journey docs from it. When a reference is chosen it is
+ * compared against the map first (writing testforge.diff.md), and, for a
+ * fresh interactive choice, confirmed before the docs are rewritten.
+ *
+ * Async because the source-of-truth barrier may prompt the developer.
+ * Returns the AI's text summary of what it created.
+ */
+export async function runDiscover(srcDir, docsDir, opts = {}) {
+    const source = await resolveDocsSource(opts);
+    if (source.mode === 'reference' && source.reference) {
+        console.log(`\nComparing the reference against testforge.md: ${source.reference}`);
+        console.log('(reading the reference and the map — this may take a moment)\n');
+        const summary = analyzeReference(source.reference, docsDir);
+        console.log(summary);
+        console.log(`\nFull comparison written to ${DIFF_PATH}.`);
+        // Only a freshly-typed interactive choice gets a confirmation step;
+        // an explicit flag or a remembered choice proceeds directly.
+        if (source.origin === 'prompt') {
+            const ok = await promptConfirm('\nDraft the docs from this reference (make it the source of truth)?', true);
+            if (!ok) {
+                console.log('Basing docs on testforge.md instead.\n');
+                saveSourceChoice({ mode: 'map' });
+                return runCodeDiscover(srcDir, docsDir);
+            }
+        }
+        console.log('\nDrafting docs from the reference...\n');
+        const out = draftDocsFromReference(srcDir, docsDir, source.reference);
+        saveSourceChoice({ mode: 'reference', reference: source.reference });
+        return out;
+    }
+    saveSourceChoice({ mode: 'map' });
+    return runCodeDiscover(srcDir, docsDir);
+}