@activate-core/test-forge 0.1.1 → 0.3.0

package/dist/core/setup.js

@@ -16,7 +16,7 @@ import { runInit } from './init.js';
 import { runMap } from './map.js';
 import { runDiscover } from './discover.js';
 import { runEnvTemplate } from './env-template.js';
-export function runSetup(srcDir) {
+export async function runSetup(srcDir, opts = {}) {
     // If the project already looks set up, don't redo it — point the user
     // to `update` instead, which only refreshes what actually changed.
     const alreadySetUp = existsSync('testforge.config.json') &&
@@ -49,9 +49,10 @@ export function runSetup(srcDir) {
     else {
         console.log('  warning: testforge.md was not created\n');
     }
-    // Step 3 — discover.
+    // Step 3 — discover. This is where the source-of-truth barrier lives:
+    // the docs may be based on testforge.md or on an external reference.
     console.log('Step 3/3: Drafting a doc for each journey...');
-    runDiscover(srcDir, 'docs');
+    await runDiscover(srcDir, 'docs', opts);
     console.log('  done — docs/\n');
     // Remember the source state so the first `update` can detect "no change".
     const cache = loadCache('.testforge/cache.json');
@@ -60,7 +61,7 @@ export function runSetup(srcDir) {
     // Build an env template so the developer knows which credentials each
     // area/journey needs for running the tests.
     console.log('Building env template...');
-    runEnvTemplate('docs', '.env.testing.example');
+    runEnvTemplate('docs', '.env.testing.example', srcDir);
     console.log('');
     console.log('Setup complete.');
     console.log('Review the drafts in docs/, fix anything the AI got wrong,');

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

@@ -0,0 +1,84 @@
+/**
+ * testforge — deciding where the journey docs come from.
+ *
+ * The docs are the source of truth for the tests, so before drafting
+ * them (in discover / setup) testforge asks WHAT to base them on:
+ *
+ *   1. testforge.md  — the AI's code-derived view. Fast, but only as
+ *      correct as the code it read.
+ *   2. An external reference — a spec/doc/PDF in the repo, a website, or
+ *      a Notion page capturing the human/client EXPECTED behavior.
+ *
+ * The choice is remembered in .testforge/source.json so later refreshes
+ * (`update`) keep using the same source without asking again — otherwise
+ * an update would silently regenerate reference-based docs from the code.
+ *
+ * Non-interactive callers are never blocked:
+ *   - source: 'map'          → use testforge.md, skip the prompt.
+ *   - reference: <locator>   → use that reference, skip the prompt.
+ *   - noPrompt (e.g. update) → reuse the remembered choice, else the map.
+ *   - no TTY                 → fall back to the map with a printed note.
+ */
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { isInteractive, promptChoice, promptLine } from './prompt.js';
+const SOURCE_PATH = '.testforge/source.json';
+/** Read the remembered source choice, or null if none/invalid. */
+export function loadSourceChoice() {
+    if (!existsSync(SOURCE_PATH))
+        return null;
+    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 };
+        }
+    }
+    catch {
+        // ignore a corrupt file — treat as "no choice remembered"
+    }
+    return null;
+}
+/** Remember the source choice for later refreshes. */
+export function saveSourceChoice(choice) {
+    mkdirSync(dirname(SOURCE_PATH), { recursive: true });
+    writeFileSync(SOURCE_PATH, JSON.stringify(choice, null, 2), 'utf-8');
+}
+/**
+ * Decide where the docs should come from for this run. May prompt the
+ * developer interactively; never blocks in non-interactive contexts.
+ */
+export async function resolveDocsSource(opts = {}) {
+    if (opts.source === 'map') {
+        return { mode: 'map', origin: 'flag' };
+    }
+    if (opts.reference) {
+        return { mode: 'reference', reference: opts.reference, origin: 'flag' };
+    }
+    // Reuse a previously remembered choice (so `update` stays consistent).
+    const stored = loadSourceChoice();
+    if (stored) {
+        return { ...stored, origin: 'stored' };
+    }
+    // Nothing chosen and nowhere to ask — safe default.
+    if (opts.noPrompt || !isInteractive()) {
+        if (!opts.noPrompt) {
+            console.log('Basing docs on testforge.md (non-interactive; pass ' +
+                '--reference <file|url> to use an external reference).');
+        }
+        return { mode: 'map', origin: 'default' };
+    }
+    // Interactive: ask what the docs should be based on.
+    const choice = await promptChoice('What should the journey docs be based on?', [
+        'testforge.md (what the AI derived from your code)',
+        'An external reference (a file/PDF in scope, a website, or a Notion link)',
+    ], 1);
+    if (choice === 1) {
+        return { mode: 'map', origin: 'prompt' };
+    }
+    const reference = await promptLine('\nProvide the reference (a file path, a URL, or a Notion link): ');
+    if (!reference) {
+        console.log('No reference given — basing docs on testforge.md.\n');
+        return { mode: 'map', origin: 'prompt' };
+    }
+    return { mode: 'reference', reference, origin: 'prompt' };
+}

package/dist/core/update.js

@@ -16,7 +16,7 @@ import { hashProjectSource, loadCache, saveCache } from './cache.js';
 import { runEnvTemplate } from './env-template.js';
 const CACHE_PATH = '.testforge/cache.json';
 const SOURCE_KEY = '__source__';
-export function runUpdate(srcDir) {
+export async function runUpdate(srcDir) {
     if (!existsSync('testforge.md') || !existsSync('testforge.config.json')) {
         console.log("This project isn't set up yet.");
         console.log('Run `testforge setup` first.');
@@ -35,8 +35,10 @@ export function runUpdate(srcDir) {
     console.log('Re-mapping the project...');
     runMap(srcDir);
     console.log('  done — testforge.md\n');
+    // Reuse the source of truth chosen at setup (map or a reference)
+    // without prompting — an update is a refresh, not a re-decision.
     console.log('Updating journey docs...');
-    runDiscover(srcDir, 'docs');
+    await runDiscover(srcDir, 'docs', { noPrompt: true });
     console.log('  done — docs/\n');
     console.log('Regenerating tests for changed journeys...');
     const results = runGenerate('docs', true, false);
@@ -46,7 +48,7 @@ export function runUpdate(srcDir) {
     cache[SOURCE_KEY] = newHash;
     saveCache(CACHE_PATH, cache);
     console.log('Refreshing env template...');
-    runEnvTemplate('docs', '.env.testing.example');
+    runEnvTemplate('docs', '.env.testing.example', srcDir);
     console.log('');
     console.log('Update complete.');
 }

package/dist/core/validate.js

@@ -0,0 +1,82 @@
+/**
+ * testforge — generated-code syntax gate.
+ *
+ * Before any generated test/seed is written to disk, its content is
+ * parse-checked here. This is what stops malformed output (prose that
+ * leaked past cleaning, a half-written file, an unbalanced brace) from
+ * ever reaching the project — the single gate that would have prevented
+ * the broken-seed defects.
+ *
+ * We stay dependency-free:
+ *   - JavaScript (.js/.cjs/.mjs): checked EXACTLY with Node's built-in
+ *     `node --check`, which parses without executing.
+ *   - TypeScript (.ts/.tsx): no exact parser is guaranteed at runtime
+ *     (the project we run inside may not have `typescript` installed),
+ *     so we fall back to a structural sanity check that still catches
+ *     the common failure — prose leaking into the file — without
+ *     false-rejecting valid TypeScript.
+ */
+import { execFileSync } from 'node:child_process';
+import { writeFileSync, mkdtempSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+/** True if `content` parses (or, for TS, passes a structural check). */
+export function isSyntaxValid(content, ext) {
+    if (!content.trim())
+        return false;
+    const isJs = /\.(c|m)?js$/i.test(ext);
+    if (isJs) {
+        return nodeCheck(content, ext);
+    }
+    return looksStructurallyClean(content);
+}
+/** Write to a temp file and run `node --check` on it. */
+function nodeCheck(content, ext) {
+    const dir = mkdtempSync(join(tmpdir(), 'testforge-check-'));
+    // `.mjs` gets ES-module parsing; anything else checks fine as `.js`
+    // (CommonJS), and `node --check` accepts both `import` and `require`
+    // there depending on extension — so preserve an explicit `.mjs`.
+    const fileExt = /\.mjs$/i.test(ext) ? '.mjs' : '.js';
+    const file = join(dir, `check${fileExt}`);
+    try {
+        writeFileSync(file, content, 'utf-8');
+        execFileSync(process.execPath, ['--check', file], { stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+/**
+ * Best-effort TypeScript check: the file must START with code (not a
+ * sentence) and have balanced braces/parens. This catches leaked prose
+ * — the actual failure mode we saw — without a real TS parser.
+ */
+function looksStructurallyClean(content) {
+    const firstLine = content
+        .trim()
+        .split('\n')
+        .find((l) => l.trim() !== '') ?? '';
+    const t = firstLine.trim();
+    const startsWithCode = 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"');
+    if (!startsWithCode)
+        return false;
+    const count = (s, ch) => s.split(ch).length - 1;
+    const balanced = count(content, '{') === count(content, '}') &&
+        count(content, '(') === count(content, ')');
+    return balanced;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@activate-core/test-forge",
-  "version": "0.1.1",
+  "version": "0.3.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": {