@activate-core/test-forge 2.5.0 → 2.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md ADDED
@@ -0,0 +1,31 @@
1
+ # Changelog
2
+
3
+ ## 2.7.0
4
+
5
+ - The names new tests still wait on are looked up once, at generate time, against the journey's code facts; a value is kept only if the code has it.
6
+ - The writer never sees a constant or a "names already asked" entry that is still blank, so rewritten tests do not ask for the same blank names again.
7
+ - A kept file whose tests were taken out to be written again stays as it was when the new tests do not come back (a call that fails or is refused).
8
+ - The facts follow the methods a route handler calls: the class it is given (what `create()` returns) and its response helpers, through the helpers they call (the `{ error: { message } }` shape).
9
+ - `fillPath(URL, …values)` from `reporters/interface.cjs` fills a path's parameters whatever the product calls them.
10
+ - A waiting test says why its name is blank: not a kind TestForge looks up, nothing like it in the code yet, looked for and not found, or the lookup could not run.
11
+ - A rewritten test keeps its title (dashboard history continues).
12
+ - A testkit rebuild that fails, or drops an export the tests use, is not taken: the existing testkit stays.
13
+ - Rules asked for and refused are not asked again until the doc or the journey's code changes.
14
+ - "route", "controller" and "endpoint" no longer match every route line.
15
+ - `env --diff` and `report` read an unfilled `KEY= # hint` as unset; `run --journey` accepts only a journey id.
16
+ - `setup` stops when the config it wrote has problems, before any doc is drafted.
17
+
18
+ ## 2.6.0
19
+
20
+ - The reporters record passed tests in `testforge/passed.json`; generate never removes or rewrites them (only `--force` does).
21
+ - A kept file's tests are reported by newer checks, never removed; when code arrives only the tests using its blank names are written again; a failed rewrite keeps the earlier file.
22
+ - A journey's facts move only when its own code changes; tests written with no code are written again once it is there, with the seed.
23
+ - Route handlers and their rule classes come first in the facts; the doc's Test setup reaches the facts; the testkit's `insert` contract always reaches the writer.
24
+ - Name scan: rule, logic, request and enum files; whole-word matching; the enclosing route prefix; methods, roles, nested fields; values the code no longer has are blanked; blanked names are asked again.
25
+ - `run`: files of a feature that is not live are held back; prints how many tests ran of how many; exits 0 when nothing failed for a product reason.
26
+ - A saved review verdict applies to the same failure only; `report --results` files waiting tests as waiting.
27
+ - Globals-style Jest files parse; an unfilled env line is empty; `coverage.json` keeps other journeys; other AI CLIs get the writer rules; a ticket key counts as a source; a missing `--env-file` stops the run.
28
+
29
+ ### Upgrading
30
+ - New state files under `testforge/`: `passed.json` (commit it with the tests), `last-run.json`, `interface-filled.json`, `interface-status.json`, and `journeys/<area>/<id>/refused.json`.
31
+ - Facts are read once again after upgrading (one grounding call per journey).
package/README.md CHANGED
@@ -271,9 +271,30 @@ prints a note.
271
271
 
272
272
  ## Running the generated tests
273
273
 
274
- testforge generates the tests and seed files — you run them with your
275
- own test runner, the way your project already does. testforge does not
276
- run tests for you; that keeps it out of your test setup and CI.
274
+ Run them with `testforge run` (it fills waiting names from the code first,
275
+ holds back files whose feature is not live yet, and prints how many tests
276
+ ran of how many), or with your own test runner — the generated config
277
+ carries the TestForge reporter either way.
278
+
279
+ **What a run remembers.** Every test that passes is recorded in
280
+ `testforge/passed.json`. From then on `testforge generate` never removes or
281
+ rewrites it — a later failure is a regression to look at, not a test to
282
+ rewrite. Only `generate --force` writes such a test again. A kept file's
283
+ other tests are reported by the checks, never removed; once the code a
284
+ waiting test needs arrives, only that test is written again.
285
+
286
+ **Exit code.** A run whose only non-passing tests are waiting for the
287
+ product or stopped by the environment exits 0: nothing failed for a product
288
+ reason. A real failure exits 1.
289
+
290
+ **Trying a local build in a project** (before a release):
291
+
292
+ ```bash
293
+ # in the testforge repo
294
+ npm run build && npm pack
295
+ # in the project
296
+ npm i --no-save /path/to/activate-core-test-forge-<version>.tgz
297
+ ```
277
298
 
278
299
  A typical run:
279
300
 
package/dist/cli/index.js CHANGED
@@ -93,7 +93,7 @@ function printUsage() {
93
93
  console.log(' testforge generate --basic Use the basic generator only');
94
94
  console.log(' testforge generate --force Regenerate everything');
95
95
  console.log(' testforge generate --no-wait Stop when the AI hits its usage limit (default: wait for the reset and resume)');
96
- console.log(' testforge generate --plan-only Plan and check each journey (testforge/memory/<area>/<id>/plan-check.md), write no tests');
96
+ console.log(' testforge generate --plan-only Plan and check each journey (testforge/journeys/<area>/<id>/plan-check.md), write no tests', ' testforge generate --journey <name> --refresh-code Read the code again and rewrite the tests still waiting on names (after the feature code lands)');
97
97
  console.log(' testforge generate --journey <name> Generate just ONE journey');
98
98
  console.log(' testforge generate --area <area> Generate a whole area (e.g. api)');
99
99
  console.log(' testforge discover Draft journey docs (asks: map or reference)');
@@ -249,6 +249,7 @@ async function main() {
249
249
  ? true
250
250
  : undefined, // undefined -> config.waitForLimit (default on)
251
251
  planOnly: process.argv.includes('--plan-only'),
252
+ refreshCode: process.argv.includes('--refresh-code'),
252
253
  });
253
254
  if (results.length === 0) {
254
255
  console.log('No journey files found in testforge/docs/. Add a .md file and try again.');
@@ -17,7 +17,7 @@ export function sourceRoot(base = '.') {
17
17
  const FILE_REF = /((?:[\w.-]+\/)+[\w.-]+\.(?:tsx?|jsx?|mjs|cjs|vue|svelte|php|py|rb|go))(?::(\d+)(?:[-–](\d+))?)?/g;
18
18
  const QUOTED = /"([^"\n]{4,60})"/g;
19
19
  /** Words in a control's name that name no component in particular. */
20
- const GENERIC = new Set(['button', 'buttons', 'field', 'input', 'inputs', 'header', 'footer', 'items', 'entry', 'entries', 'shown', 'guest', 'logged', 'customer', 'computer', 'phone', 'sized', 'screen', 'page', 'pages', 'where', 'opens', 'close', 'link', 'links', 'text', 'label', 'click', 'state', 'result', 'neighbour', 'neighbouring', 'other', 'while', 'their', 'there', 'which', 'every', 'itself', 'changes', 'layout']);
20
+ const GENERIC = new Set(['route', 'routes', 'controller', 'endpoint', 'button', 'buttons', 'field', 'input', 'inputs', 'header', 'footer', 'items', 'entry', 'entries', 'shown', 'guest', 'logged', 'customer', 'computer', 'phone', 'sized', 'screen', 'page', 'pages', 'where', 'opens', 'close', 'link', 'links', 'text', 'label', 'click', 'state', 'result', 'neighbour', 'neighbouring', 'other', 'while', 'their', 'there', 'which', 'every', 'itself', 'changes', 'layout']);
21
21
  function walk(dir, out) {
22
22
  let entries;
23
23
  try {
@@ -62,7 +62,7 @@ function locate(ref, roots, all) {
62
62
  * cites (around the cited lines), then every file that contains a text the
63
63
  * doc quotes, most hits first, until `budget` characters.
64
64
  */
65
- export function sourceExcerpts(markdown, roots, budget = 50_000) {
65
+ export function sourceExcerpts(markdown, roots, budget = 70_000) {
66
66
  const windows = new Map();
67
67
  const add = (file, from, to) => {
68
68
  const w = windows.get(file) ?? [];
@@ -95,6 +95,54 @@ export function sourceExcerpts(markdown, roots, budget = 50_000) {
95
95
  const p = relative(process.cwd(), f).toLowerCase();
96
96
  return [...new Set(controlWords)].some((w) => p.includes(w));
97
97
  });
98
+ // A feature's own code is often named after the feature ("Smart Assignment"
99
+ // → app/Service/Assignment/…) and the doc names none of its classes: the
100
+ // journey's title finds it, and the classes the rest of the app calls are
101
+ // the way in (a search, a controller, a setting).
102
+ const titleWords = ((/^#\s*Journey:\s*(.+)$/m.exec(markdown)?.[1] ?? '').toLowerCase().match(/[a-z]{6,}/g) ?? [])
103
+ .filter((w) => !GENERIC.has(w));
104
+ if (titleWords.length) {
105
+ const texts = new Map();
106
+ const textOf = (f) => {
107
+ if (!texts.has(f)) {
108
+ try {
109
+ texts.set(f, readFileSync(f, 'utf-8'));
110
+ }
111
+ catch {
112
+ texts.set(f, '');
113
+ }
114
+ }
115
+ return texts.get(f);
116
+ };
117
+ const own = files.filter((f) => {
118
+ const p = relative(process.cwd(), f).toLowerCase();
119
+ return !p.startsWith('..') && !/(^|[\\/])(tests?|__tests__|testforge|node_modules|vendor)[\\/]/.test(p) && titleWords.some((w) => p.includes(w));
120
+ });
121
+ const stem = (f) => f.replace(/^.*[\\/]/, '').replace(/\.\w+$/, '');
122
+ const usersOf = (f) => {
123
+ const name = stem(f);
124
+ if (name.length < 4 || name === 'index')
125
+ return [];
126
+ const re = new RegExp(`(?:\\b(?:use|import)\\s[^;\\n]*\\b${name}\\b|\\b${name}::|\\bnew\\s+\\\\?[\\w\\\\]*\\b${name}\\s*\\(|from\\s+['"][^'"]*\\b${name}['"])`);
127
+ return files.filter((u) => u !== f && !own.includes(u)).flatMap((u) => {
128
+ const lines = textOf(u).split('\n').flatMap((l, i) => (re.test(l) || (l.includes(name) && /::|->|new\s/.test(l)) ? [i + 1] : []));
129
+ return lines.length && re.test(textOf(u)) ? [{ file: u, lines }] : [];
130
+ });
131
+ };
132
+ // The feature's files most used elsewhere first: those are its entry points.
133
+ const ranked = own.map((f) => ({ f, users: usersOf(f) })).sort((a, b) => b.users.length - a.users.length);
134
+ for (const { f, users } of ranked.slice(0, 10)) {
135
+ add(f, 1, 60);
136
+ if (!order.includes(f))
137
+ order.push(f);
138
+ for (const u of users.slice(0, 6)) {
139
+ for (const n of u.lines.slice(0, 8))
140
+ add(u.file, n - 12, n + 12);
141
+ if (!order.includes(u.file))
142
+ order.push(u.file);
143
+ }
144
+ }
145
+ }
98
146
  // How a component is reached and fed: the files that import it, up to the
99
147
  // page that serves it (its route), and the hooks and API modules they use.
100
148
  const importersOf = (target) => {
@@ -207,7 +255,8 @@ export function sourceExcerpts(markdown, roots, budget = 50_000) {
207
255
  // word with the doc, first in the excerpts. A doc rarely names a route; a
208
256
  // test cannot call one without its real path.
209
257
  const words = [...new Set((markdown.toLowerCase().match(/[a-z]{5,}/g) ?? []).filter((w) => !GENERIC.has(w)))];
210
- const stems = [...new Set(words.map((w) => w.replace(/(?:ings?|ed|es|s)$/, '')).filter((w) => w.length >= 5))];
258
+ // A stem too short to search on ("book" from booking) keeps its word.
259
+ const stems = [...new Set(words.map((w) => { const st = w.replace(/(?:ings?|ed|es|s)$/, ''); return st.length >= 5 ? st : w; }))];
211
260
  const ROUTE_FILE = /(^|[\\/])(routes?|router|urls)([\\/]|\.[a-z]+$)|\.routes?\.[a-z]+$|[\\/]routes?\.[a-z]+$/i;
212
261
  const ROUTE_LINE = /Route::\w+\(|\brouter\.(?:get|post|put|patch|delete|all|use)\(|\bapp\.(?:get|post|put|patch|delete)\(|@(?:Get|Post|Put|Patch|Delete)\(|\bpath\(\s*['"]|\bre_path\(/;
213
262
  // Only this package's own routes: a related repo's are another area's.
@@ -216,6 +265,7 @@ export function sourceExcerpts(markdown, roots, budget = 50_000) {
216
265
  // most 120 across the project; the prefix and group lines that complete
217
266
  // their paths come with them. Commented-out routes are not routes.
218
267
  const candidates = [];
268
+ const docLow = markdown.toLowerCase().replace(/[-_]/g, ' ');
219
269
  for (const f of routeFiles.slice(0, 8)) {
220
270
  let lines;
221
271
  try {
@@ -227,20 +277,140 @@ export function sourceExcerpts(markdown, roots, budget = 50_000) {
227
277
  lines.forEach((l, i) => {
228
278
  if (/^\s*(?:\/\/|#|\*)/.test(l))
229
279
  return;
230
- const low = l.toLowerCase();
280
+ // The controller class is on every route it serves: only the path and method tell routes apart.
281
+ const low = l.toLowerCase().replace(/[\w\\]*controller(?=::class|@)/g, '');
231
282
  if (/->prefix\(|::prefix\(|\bprefix\s*[:=]|->group\(|::group\(/i.test(l)) {
232
283
  add(f, i + 1, i + 1);
233
284
  return;
234
285
  }
235
286
  if (!ROUTE_LINE.test(l))
236
287
  return;
237
- const score = stems.filter((w) => low.includes(w)).length;
288
+ // A path the doc writes as words ("booking order" for booking-order) is
289
+ // a route its tests call: ahead of lines that only share words.
290
+ const path = /['"]([\w/{}.-]*[-_][\w/{}.-]*)['"]/.exec(l)?.[1] ?? '';
291
+ const named = path.toLowerCase().split('/').filter((seg) => /[-_]/.test(seg) && docLow.includes(seg.replace(/[-_]/g, ' '))).length;
292
+ const score = stems.filter((w) => low.includes(w)).length + 10 * named;
238
293
  if (score)
239
294
  candidates.push({ file: f, line: i + 1, score });
240
295
  });
241
296
  }
242
- for (const c of candidates.sort((a, b) => b.score - a.score).slice(0, 120))
297
+ for (const c of candidates.sort((a, b) => b.score - a.score).slice(0, 60))
243
298
  add(c.file, c.line, c.line);
299
+ // What a request must carry is in its handler: the start of the method a
300
+ // route names (Laravel's [Controller::class, 'method'] or 'Controller@method')
301
+ // holds its validation rules, so a test sends the real fields.
302
+ const handlers = new Set();
303
+ const handlerFiles = [];
304
+ const seenRules = new Set();
305
+ const seenMethods = new Set();
306
+ // Only the routes the doc names by their path: theirs are the requests its tests send.
307
+ for (const c of candidates.filter((x) => x.score >= 10).slice(0, 12)) {
308
+ let line = '';
309
+ try {
310
+ line = readFileSync(c.file, 'utf-8').split('\n')[c.line - 1] ?? '';
311
+ }
312
+ catch {
313
+ continue;
314
+ }
315
+ const m = /\[\s*\\?([\w\\]*?)(\w+Controller)::class\s*,\s*['"](\w+)['"]\s*\]/.exec(line) ?? /['"](\w+Controller)@(\w+)['"]/.exec(line);
316
+ if (!m)
317
+ continue;
318
+ const [cls, method] = m.length === 4 ? [m[2], m[3]] : [m[1], m[2]];
319
+ if (handlers.has(`${cls}@${method}`))
320
+ continue;
321
+ handlers.add(`${cls}@${method}`);
322
+ for (const f of files.filter((x) => x.endsWith(`${cls}.php`))) {
323
+ let text;
324
+ try {
325
+ text = readFileSync(f, 'utf-8').split('\n');
326
+ }
327
+ catch {
328
+ continue;
329
+ }
330
+ const at = text.findIndex((l) => new RegExp(`function\\s+${method}\\s*\\(`).test(l));
331
+ if (at === -1)
332
+ continue;
333
+ add(f, at + 1, at + 45);
334
+ if (!handlerFiles.includes(f))
335
+ handlerFiles.push(f);
336
+ // A handler that hands the request to a class it is given
337
+ // (bookingOrderV2(Request $r, OrderLogicV2 $logic)) keeps its rules there.
338
+ const sig = text[at].match(/\(([^)]*)\)/)?.[1] ?? '';
339
+ const deps = [...sig.matchAll(/\b([A-Z]\w+)\s+\$(\w+)/g)].filter((d) => d[1] !== 'Request');
340
+ for (const d of deps)
341
+ rulesOf(d[1], 2);
342
+ // What the response looks like is in the methods the handler calls: the
343
+ // class it is given ($order_logic->create() → what create() returns) and
344
+ // its own response helpers ($this->respondWithSuccess, often in a trait).
345
+ const body = text.slice(at, at + 45).join('\n');
346
+ for (const d of deps) {
347
+ for (const call of new Set([...body.matchAll(new RegExp(`\\$${d[2]}->(\\w+)\\(`, 'g'))].map((x) => x[1]))) {
348
+ if (/^(?:setInput|getErrors|fails|validate)$/.test(call))
349
+ continue;
350
+ methodWindow(d[1], call, 60);
351
+ }
352
+ }
353
+ for (const call of new Set([...body.matchAll(/\$this->(respond\w*|\w*[Rr]esponse\w*|json\w*)\(/g)].map((x) => x[1])))
354
+ methodWindow('', call, 15, 3);
355
+ }
356
+ }
357
+ // The body of `method` in class `cls` (any class when cls is ''), where it is defined.
358
+ function methodWindow(cls, method, lines, helperDepth = 0) {
359
+ if (seenMethods.has(`${cls}::${method}`))
360
+ return;
361
+ seenMethods.add(`${cls}::${method}`);
362
+ const re = new RegExp(`function\\s+${method}\\s*\\(`);
363
+ for (const f of files.filter((x) => x.endsWith('.php') && (!cls || x.endsWith(`/${cls}.php`))).slice(0, 4000)) {
364
+ let text;
365
+ try {
366
+ text = readFileSync(f, 'utf-8').split('\n');
367
+ }
368
+ catch {
369
+ continue;
370
+ }
371
+ const i = text.findIndex((l) => re.test(l));
372
+ if (i === -1)
373
+ continue;
374
+ add(f, i + 1, i + lines);
375
+ if (!handlerFiles.includes(f))
376
+ handlerFiles.push(f);
377
+ // A helper that builds its answer through another (respondInvalidParameters → respondWithError).
378
+ if (helperDepth > 1) {
379
+ for (const next of new Set([...text.slice(i, i + lines).join('\n').matchAll(/(?:->|::)(respond\w*|\w*[Rr]esponse\w*|json\w*)\(/g)].map((x) => x[1]))) {
380
+ if (next !== method)
381
+ methodWindow('', next, lines, helperDepth - 1);
382
+ }
383
+ }
384
+ if (!cls)
385
+ return; // a helper is defined once (a trait or base controller)
386
+ }
387
+ }
388
+ // The rule methods of a class (validate, rules, getXRules), and of the
389
+ // classes its constructor is given, `depth` hops down.
390
+ function rulesOf(cls, depth) {
391
+ if (!depth || seenRules.has(cls))
392
+ return;
393
+ seenRules.add(cls);
394
+ for (const f of files.filter((x) => x.endsWith(`/${cls}.php`))) {
395
+ let text;
396
+ try {
397
+ text = readFileSync(f, 'utf-8').split('\n');
398
+ }
399
+ catch {
400
+ continue;
401
+ }
402
+ text.forEach((l, i) => {
403
+ if (/function\s+(?:validate|rules|\w*Rules)\s*\(/.test(l))
404
+ add(f, i + 1, i + 50);
405
+ const ctor = /function\s+__construct\s*\(([^)]*)\)/.exec(l);
406
+ if (ctor)
407
+ for (const d of ctor[1].matchAll(/\b([A-Z]\w+)\s+\$\w+/g))
408
+ rulesOf(d[1], depth - 1);
409
+ });
410
+ if (windows.has(f) && !handlerFiles.includes(f))
411
+ handlerFiles.push(f);
412
+ }
413
+ }
244
414
  for (const f of routeFiles.slice(0, 8)) {
245
415
  if (candidates.some((c) => c.file === f) && windows.has(f)) {
246
416
  const at = order.indexOf(f);
@@ -249,6 +419,16 @@ export function sourceExcerpts(markdown, roots, budget = 50_000) {
249
419
  order.unshift(f);
250
420
  }
251
421
  }
422
+ // Handlers and their rules right after the routes, ahead of the budget cut:
423
+ // without them a test sends fields the product does not take.
424
+ const firstOther = order.findIndex((f) => !routeFiles.includes(f) || !candidates.some((c) => c.file === f));
425
+ const handlersIn = handlerFiles.filter((f) => windows.has(f));
426
+ for (const f of handlersIn) {
427
+ const i = order.indexOf(f);
428
+ if (i !== -1)
429
+ order.splice(i, 1);
430
+ }
431
+ order.splice(firstOther === -1 ? order.length : Math.min(firstOther, order.length), 0, ...handlersIn);
252
432
  // A page's own parts (its total, its operator card, its pickers) live in the
253
433
  // components it imports from its own folder. Their visible texts and labels
254
434
  // come right after it, ahead of files that only share a word with the doc.
@@ -17,12 +17,12 @@
17
17
  * journey document remains the sole source of what is CORRECT, and the
18
18
  * generation prompt says so in the same breath as it presents these facts.
19
19
  */
20
+ import { createHash } from 'node:crypto';
20
21
  import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
21
22
  import { dirname, join } from 'node:path';
22
23
  import { loadConfig, splitCommand, withNoTools } from '../project/config.js';
23
24
  import { readRules, ruleIndex } from '../generate/journey-memory.js';
24
25
  import { sourceExcerpts } from './excerpts.js';
25
- import { hashProjectSource } from './cache.js';
26
26
  import { journeyDir } from '../paths.js';
27
27
  import { loadEnvFile } from '../project/config.js';
28
28
  import { originsFrom, pathsFrom, observeApp } from './observe.js';
@@ -37,7 +37,7 @@ const MAP_PATH = 'testforge.md';
37
37
  * that upgrades keeps serving the facts it cached under the old version —
38
38
  * so the new facts never reach a single prompt and the upgrade does nothing.
39
39
  */
40
- const FACTS_VERSION = 7;
40
+ const FACTS_VERSION = 11;
41
41
  /** Where a journey's grounded facts live, mirroring the plan cache layout. */
42
42
  function groundingPath(journey) {
43
43
  return join(journeyDir(journey), 'facts.json');
@@ -107,7 +107,61 @@ function compactJourney(markdown) {
107
107
  const m = readRules(markdown);
108
108
  if (!m.rules.length)
109
109
  return markdown;
110
- return [m.header, ``, `CONTROLS:`, ...Object.entries(m.controls).map(([id, c]) => `${id}: ${c}`), ``, `RULES:`, ruleIndex(m)].join('\n');
110
+ // The setup names the requests the tests send (booking, payment): without it
111
+ // their routes look unused and drop out of the facts.
112
+ return [m.header, ``, `CONTROLS:`, ...Object.entries(m.controls).map(([id, c]) => `${id}: ${c}`), ``, `RULES:`, ruleIndex(m), ...(m.setup ? [``, `TEST SETUP:`, m.setup] : [])].join('\n');
113
+ }
114
+ /**
115
+ * The code this journey reads, as the excerpts collect it (no AI): only a
116
+ * change to THESE files moves the journey's facts. A commit elsewhere in the
117
+ * project costs nothing; a feature's code arriving changes them.
118
+ */
119
+ function journeyCode(journey, srcDir) {
120
+ let excerpts = '';
121
+ try {
122
+ excerpts = sourceExcerpts(journey.rawMarkdown || '', [srcDir, ...(loadConfig().relatedDirs ?? [])]);
123
+ }
124
+ catch { /* unreadable tree: no code */ }
125
+ return { excerpts, hash: createHash('sha1').update(excerpts).digest('hex').slice(0, 16) };
126
+ }
127
+ /** A short fingerprint of the code this journey reads (no AI). */
128
+ export function journeyCodeHash(journey, srcDir = 'src') {
129
+ return journeyCode(journey, srcDir).hash;
130
+ }
131
+ /** True when the journey's facts were read from code that has since changed. */
132
+ export function factsCodeMoved(journey, srcDir = 'src') {
133
+ const path = groundingPath(journey);
134
+ if (!existsSync(path))
135
+ return false;
136
+ try {
137
+ const key = String(JSON.parse(readFileSync(path, 'utf-8')).key ?? '');
138
+ return !key.endsWith(`:${journeyCode(journey, srcDir).hash}`);
139
+ }
140
+ catch {
141
+ return false;
142
+ }
143
+ }
144
+ /**
145
+ * True when the journey's tests were last written with no code to read (the
146
+ * feature was not built, or none of its code was found). Once code is there,
147
+ * those tests are written again from it — their "how" was a guess.
148
+ */
149
+ export function writtenWithoutCode(journey) {
150
+ try {
151
+ return JSON.parse(readFileSync(groundingPath(journey), 'utf-8')).noFacts === true;
152
+ }
153
+ catch {
154
+ return false;
155
+ }
156
+ }
157
+ /** Record that this journey's tests were written with no code to read. */
158
+ export function markWrittenWithoutCode(journey, srcDir = 'src') {
159
+ const path = groundingPath(journey);
160
+ try {
161
+ mkdirSync(dirname(path), { recursive: true });
162
+ writeFileSync(path, JSON.stringify({ key: `v${FACTS_VERSION}::${journeyCode(journey, srcDir).hash}`, facts: '', noFacts: true }, null, 2), 'utf-8');
163
+ }
164
+ catch { /* best effort */ }
111
165
  }
112
166
  /**
113
167
  * Establish (or reuse) the journey's code facts. Cached against the doc hash
@@ -119,21 +173,21 @@ function compactJourney(markdown) {
119
173
  */
120
174
  export async function groundJourney(journey, docHash, srcDir = 'src', markdown = '',
121
175
  /** A doc edit, not a new journey: reuse the facts already read, whatever version of the doc they came from. */
122
- reuseOnly = false) {
176
+ reuseOnly = false,
177
+ /** Read the code again whatever is cached (generate --refresh-code). */
178
+ fresh = false) {
123
179
  const path = groundingPath(journey);
124
180
  const map = existsSync(MAP_PATH) ? readFileSync(MAP_PATH, 'utf-8') : '';
125
- let sourceHash = '';
126
- try {
127
- sourceHash = hashProjectSource(srcDir);
128
- }
129
- catch {
130
- // unreadable source tree — fall back to keying on the doc alone
131
- }
181
+ const code = journeyCode(journey, srcDir);
182
+ const sourceHash = code.hash;
132
183
  const key = `v${FACTS_VERSION}:${docHash}:${sourceHash}`;
133
- if (existsSync(path)) {
184
+ if (existsSync(path) && !fresh) {
134
185
  try {
135
186
  const cached = JSON.parse(readFileSync(path, 'utf-8'));
136
- if (typeof cached.facts === 'string' && cached.facts.trim() && (cached.key === key || (reuseOnly && String(cached.key).startsWith(`v${FACTS_VERSION}:`)))) {
187
+ // A doc edit reuses facts from an earlier version of the doc, but only
188
+ // while the code is the same: new code is exactly what the facts are for.
189
+ const sameCode = String(cached.key).startsWith(`v${FACTS_VERSION}:`) && String(cached.key).endsWith(`:${sourceHash}`);
190
+ if (typeof cached.facts === 'string' && cached.facts.trim() && (cached.key === key || (reuseOnly && sameCode))) {
137
191
  return cached.facts;
138
192
  }
139
193
  }
@@ -141,15 +195,27 @@ reuseOnly = false) {
141
195
  // corrupt cache — re-ground
142
196
  }
143
197
  }
144
- if (reuseOnly)
198
+ if (reuseOnly && !existsSync(path))
145
199
  return null;
200
+ if (reuseOnly && !fresh) {
201
+ // A doc edit on unchanged code reuses the facts already read, even ones an
202
+ // older TestForge wrote: facts in an older shape beat writing with none.
203
+ try {
204
+ const cached = JSON.parse(readFileSync(path, 'utf-8'));
205
+ if (String(cached.key).endsWith(`:${sourceHash}`))
206
+ return typeof cached.facts === 'string' && cached.facts.trim() ? cached.facts : null;
207
+ }
208
+ catch { /* corrupt: read again */ }
209
+ }
146
210
  const config = loadConfig();
147
211
  // The source the doc points at, collected here, goes into one tool-less call.
148
212
  // A doc that points at nothing findable gets no facts: its tests are written
149
213
  // from the doc, which is the contract, rather than paying an AI to go looking.
150
- const excerpts = sourceExcerpts(journey.rawMarkdown || '', [srcDir, ...(config.relatedDirs ?? [])]);
151
- if (!excerpts)
214
+ const excerpts = code.excerpts;
215
+ if (!excerpts) {
216
+ markWrittenWithoutCode(journey, srcDir);
152
217
  return null;
218
+ }
153
219
  // Excerpts only from other packages (a backend matched on a quoted text) say
154
220
  // nothing about this area's screens: a call on them returns "unknown" for
155
221
  // every section and costs as much as a real one.
@@ -37,6 +37,8 @@ export async function readReference(reference) {
37
37
  if (!text.trim())
38
38
  fail(reference, 'it is empty');
39
39
  read.set(reference, text);
40
+ if (existsSync(reference))
41
+ return text; // a file is its own copy
40
42
  try {
41
43
  const dir = join(RUNS_DIR, 'reference');
42
44
  mkdirSync(dir, { recursive: true });
@@ -44,6 +44,15 @@ export function writeCoverageManifest(results) {
44
44
  });
45
45
  if (!journeys.length)
46
46
  return;
47
+ // Journeys this run did not touch keep their earlier entry: the manifest is
48
+ // the project's coverage, not this run's.
49
+ try {
50
+ const prev = JSON.parse(readFileSync(COVERAGE_PATH, 'utf-8'));
51
+ for (const j of prev.journeys ?? [])
52
+ if (!journeys.some((n) => n.journey === j.journey))
53
+ journeys.push(j);
54
+ }
55
+ catch { /* no earlier manifest */ }
47
56
  const totalReal = journeys.reduce((n, j) => n + j.real, 0);
48
57
  const totalDeferred = journeys.reduce((n, j) => n + j.deferred, 0);
49
58
  try {