@codedology/code-forge 0.1.0 → 0.2.1

package/src/install/wizard/summary.mjs

@@ -0,0 +1,168 @@
+/**
+ * The "Project settings (detected)" block `code-forge init` prints instead of asking for gates and
+ * proof settings (B24). Every gate and proof value is listed with where it came from; a blank value
+ * says so and why, and the block ends with the one line that says how to fill the blanks later.
+ * Agent/JSON mode gets the same facts as `settings` + `blank`. Pure apart from `existsSync` reads
+ * that name the file a detected gate came from.
+ */
+
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { LINK_DIR_MANIFESTS, copyCandidates, linkDirsFromManifests } from './answers.mjs';
+import { GATE_NAMES } from './flags.mjs';
+
+export const SUMMARY_TITLE = 'Project settings (detected)';
+
+/** The config key each summarised value is written to. */
+export const SETTING_KEYS = Object.freeze({
+  test: 'gates.test',
+  lint: 'gates.lint',
+  types: 'gates.types',
+  format: 'gates.format',
+  high: 'proof.tiers.high.paths',
+  isolation: 'proof.isolation',
+  link_dirs: 'proof.export.link_dirs',
+  copy_untracked: 'proof.export.copy_untracked',
+});
+
+/** What a blank gate means, in the words the summary prints. */
+const GATE_MISSING = Object.freeze({
+  test: 'no test command found',
+  lint: 'no linter found',
+  types: 'no type checker found',
+  format: 'no formatter found',
+});
+
+/** The summary's label for each proof value. */
+const PROOF_LABELS = Object.freeze({
+  high: 'high-risk paths',
+  isolation: 'isolation',
+  link_dirs: 'link dirs',
+  copy_untracked: 'copy untracked',
+});
+
+/** The marker file that decides each non-Node stack in `detectGates`. */
+const STACK_MARKER = Object.freeze({ rust: 'Cargo.toml', python: 'pyproject.toml', go: 'go.mod' });
+
+/**
+ * @typedef {object} Setting
+ * @property {unknown} value - what is written to the config.
+ * @property {'flag'|'existing'|'detected'|'default'} source
+ * @property {string} note - where it came from, or why it is blank, in the summary's words.
+ */
+
+/**
+ * @typedef {object} SettingsSummary
+ * @property {Record<string, Setting>} settings - keyed by config path (`gates.test`, …).
+ * @property {string[]} blank - the config paths left blank, in summary order.
+ * @property {string[]} lines - the printed block, title first, the "set later" line last.
+ */
+
+/** @param {string[]} argv @returns {string} */
+function shown(argv) {
+  return argv.map((w) => (/[\s"'\\]/.test(w) || w === '' ? JSON.stringify(w) : w)).join(' ');
+}
+
+/** @param {string} cwd @param {string[]} names @returns {string|undefined} */
+function firstPresent(cwd, names) {
+  return names.find((n) => existsSync(path.join(cwd, n)));
+}
+
+/**
+ * The file a detected gate came from (the evidence `detectGates` read).
+ * @param {string} stack @param {string} name @param {string[]} argv @param {string} cwd
+ * @returns {string}
+ */
+export function gateEvidence(stack, name, argv, cwd) {
+  if (stack.startsWith('php')) {
+    const tool = path.basename(argv[0] ?? '');
+    if (tool === 'phpstan') return firstPresent(cwd, ['phpstan.neon', 'phpstan.neon.dist']) ?? 'vendor/bin/phpstan';
+    if (tool === 'pint') return firstPresent(cwd, ['pint.json']) ?? 'vendor/bin/pint';
+    if (tool === 'php' && argv[1] === 'artisan') return 'artisan';
+    if (tool === 'pest') return 'vendor/bin/pest';
+    return 'composer.json';
+  }
+  if (stack === 'node') {
+    if (argv[0] === 'npx' && argv[1] === 'tsc') return 'tsconfig.json';
+    if (argv[0] === 'npx' && argv[1] === 'prettier') return firstPresent(cwd, ['.prettierrc', '.prettierrc.json', '.prettierrc.js']) ?? 'package.json';
+    return 'package.json';
+  }
+  return STACK_MARKER[/** @type {keyof typeof STACK_MARKER} */ (stack)] ?? 'the project';
+}
+
+/** @param {unknown} value @returns {boolean} an empty proof value: null, undefined, '' or [] */
+function isBlankValue(value) {
+  return value === null || value === undefined || value === '' || (Array.isArray(value) && value.length === 0);
+}
+
+/** @param {'flag'|'existing'|'detected'|'default'} source @param {string} flag @returns {string} */
+function keptFrom(source, flag) {
+  return source === 'flag' ? flag : source === 'existing' ? '.code-forge.yml' : 'default';
+}
+
+/**
+ * @param {import('./answers.mjs').Answers} values
+ * @param {import('./answers.mjs').Origins} origins
+ * @param {{cwd: string, profile: string, detected: {stack: string}}} ctx
+ * @returns {SettingsSummary}
+ */
+export function summarizeSettings(values, origins, ctx) {
+  /** @type {Record<string, Setting>} */
+  const settings = {};
+  /** @type {string[]} */
+  const blank = [];
+  const lines = [SUMMARY_TITLE];
+
+  for (const name of GATE_NAMES) {
+    const key = SETTING_KEYS[/** @type {keyof typeof SETTING_KEYS} */ (name)];
+    const argv = values.gates[/** @type {keyof typeof values.gates} */ (name)];
+    const source = origins.gates[name] ?? 'detected';
+    let note;
+    if (argv === null || argv === undefined || argv.length === 0) {
+      if (source === 'flag') note = 'set blank by --gate';
+      else if (source === 'existing') note = 'empty in .code-forge.yml';
+      else note = GATE_MISSING[/** @type {keyof typeof GATE_MISSING} */ (name)];
+      blank.push(key);
+      lines.push(`  ${name}: blank — ${note}`);
+    } else {
+      note = source === 'detected' ? gateEvidence(ctx.detected.stack, name, argv, ctx.cwd) : keptFrom(source, '--gate');
+      lines.push(`  ${name}: ${shown(argv)} (from ${note})`);
+    }
+    settings[key] = { value: argv, source, note };
+  }
+
+  const found = new Map(linkDirsFromManifests(ctx.cwd).map((e) => [e.dir, e.manifests]));
+  for (const pk of /** @type {Array<keyof typeof PROOF_LABELS>} */ (Object.keys(PROOF_LABELS))) {
+    const key = SETTING_KEYS[pk];
+    const value = values.proof[pk];
+    const source = origins.proof[pk] ?? 'default';
+    const label = PROOF_LABELS[pk];
+    let note;
+    if (isBlankValue(value)) {
+      if (source === 'flag') note = 'set blank by --proof';
+      else if (source === 'existing') note = 'empty in .code-forge.yml';
+      else if (pk === 'high') note = 'none set (all files light tier by path)';
+      else if (pk === 'link_dirs') note = 'no dependency manifest found';
+      else {
+        const looked = copyCandidates(ctx.profile);
+        note = looked.length > 0 ? `none found (looked for ${looked.join(', ')})` : 'none for this stack';
+      }
+      blank.push(key);
+      lines.push(`  ${label}: blank — ${note}`);
+    } else {
+      const list = Array.isArray(value) ? value : [String(value)];
+      // copied files are evidence themselves; everything else names where it came from
+      const foundOnDisk = source === 'detected' && pk === 'copy_untracked';
+      if (foundOnDisk) note = 'found in the project';
+      else if (source !== 'detected') note = keptFrom(source, '--proof');
+      else note = [...new Set(list.flatMap((d) => found.get(d) ?? LINK_DIR_MANIFESTS[/** @type {keyof typeof LINK_DIR_MANIFESTS} */ (d)] ?? []))].join(', ');
+      lines.push(`  ${label}: ${list.join(', ')} (${foundOnDisk ? note : `from ${note}`})`);
+    }
+    settings[key] = { value, source, note };
+  }
+
+  lines.push(blank.length > 0
+    ? `Set the blanks later: edit .code-forge.yml (${blank.join(', ')}), then run \`code-forge validate\`.`
+    : 'Change any of these later: edit .code-forge.yml, then run `code-forge validate`.');
+  return { settings, blank, lines };
+}

package/src/worker/engine.mjs

@@ -21,6 +21,10 @@
  * else `findings` = the open fix list, `next` = what the orchestrator does (`fix` at `level`,
  * `trigger: review_stall | review_rounds`, `patch`), `stopped` = the stop reason.
  * Without `ctx.key` (a direct call) the hook is the engine alone and writes no approval row.
+ * Every packet (round 1, recheck, patch check) carries the block's acceptance clauses from the run
+ * record in its facts slot, labelled `Acceptance clauses` (`acceptanceExcerpt`): redacted, capped
+ * at an eighth of `review.budgets.full_in` with a truncation marker, and `(acceptance unavailable)`
+ * when the record has none — a missing acceptance never fails the review.
  * The first keyed ticket of a block (no `review.budget` row for it in the run yet) records the
  * block's review budget (§4.10, B19): the forecast over the block's changed owned files (tier from
  * the path floors, before S1), one `review.budget` row per block; a failure there never fails the
@@ -34,6 +38,7 @@ import { rmSync } from 'node:fs';
 import path from 'node:path';
 import { askJev } from '../decide/jev-client.mjs';
 import { planAndRecord, tierOf } from '../review/budget.mjs';
+import { budgetFor } from '../review/packet.mjs';
 import { reviewFile, rulesRisk } from '../review/engine.mjs';
 import { computeFileSet, ownsFile } from '../gates/scope.mjs';
 import { newFileState, runRound } from '../review/fixloop.mjs';
@@ -84,14 +89,14 @@ import { assertTicketId } from './ticket.mjs';
  * `block-unknown`; a record that cannot be read or parsed throws `run-record-unreadable`, and a
  * block entry without a base `block-base-missing` — a guessed base could let a change escape review.
  * @param {string} runId @param {string} block
- * @returns {Promise<{base: string | null, level: string, owned: string[]}>}
+ * @returns {Promise<{base: string | null, level: string, owned: string[], acceptance?: unknown}>}
  */
 export async function blockEntryFor(runId, block) {
   let record;
   try {
     record = await readRun(runId);
   } catch (err) {
-    if (/** @type {any} */ (err)?.code === 'no-run') return { base: null, level: 'L2', owned: [] };
+    if (/** @type {any} */ (err)?.code === 'no-run') return { base: null, level: 'L2', owned: [], acceptance: undefined };
     throw new Error('run-record-unreadable');
   }
   if (!record || typeof record !== 'object' || !record.blocks || typeof record.blocks !== 'object') throw new Error('run-record-unreadable');
@@ -100,7 +105,43 @@ export async function blockEntryFor(runId, block) {
   const sha = entry?.base_sha;
   if (typeof sha !== 'string' || sha.length === 0) throw new Error('block-base-missing');
   const owned = Array.isArray(entry.owned_files) ? entry.owned_files.filter((f) => typeof f === 'string') : [];
-  return { base: sha, level: typeof entry.level === 'string' && /^L[0-3]$/.test(entry.level) ? entry.level : 'L2', owned };
+  return { base: sha, level: typeof entry.level === 'string' && /^L[0-3]$/.test(entry.level) ? entry.level : 'L2', owned, acceptance: entry.acceptance };
+}
+
+/** The acceptance line written when the block's clauses cannot be read. */
+export const ACCEPTANCE_UNAVAILABLE = '(acceptance unavailable)';
+const ACCEPTANCE_HEAD = 'Acceptance clauses (what the change must do):';
+
+/**
+ * The block's acceptance clauses as the packet's facts-slot text: one `- <clause>` line each
+ * (whitespace folded, so a clause can never open a packet section), redacted, cut at an eighth of
+ * the `full_in` budget (bytes = tokens × 4) with a marker naming how many clauses were left out.
+ * Not a list of `{clause}` objects with text ⇒ `(acceptance unavailable)`.
+ * @param {unknown} acceptance - the run record's `blocks.<id>.acceptance`
+ * @param {Record<string, any> | undefined} cfg
+ * @returns {string}
+ */
+export function acceptanceExcerpt(acceptance, cfg) {
+  const clauses = Array.isArray(acceptance)
+    ? acceptance.map((c) => (typeof c?.clause === 'string' ? /** @type {string} */ (redact(c.clause.replace(/\s+/g, ' ').trim())) : '')).filter((c) => c.length > 0)
+    : [];
+  if (clauses.length === 0) return `${ACCEPTANCE_HEAD}\n${ACCEPTANCE_UNAVAILABLE}`;
+  const maxBytes = Math.max(256, Math.floor((budgetFor(cfg, 'full_in') * 4) / 8));
+  const lines = [ACCEPTANCE_HEAD];
+  let used = Buffer.byteLength(ACCEPTANCE_HEAD) + 1;
+  for (let i = 0; i < clauses.length; i += 1) {
+    const line = `- ${clauses[i]}`;
+    const size = Buffer.byteLength(line) + 1;
+    if (used + size > maxBytes) {
+      if (lines.length === 1) lines.push(`${Buffer.from(line).subarray(0, Math.max(0, maxBytes - used - 4)).toString('utf8')} …`);
+      const left = clauses.length - (lines.length - 1);
+      if (left > 0) lines.push(`(acceptance truncated: ${left} more clause(s) over the packet budget)`);
+      break;
+    }
+    lines.push(line);
+    used += size;
+  }
+  return lines.join('\n');
 }
 
 /**
@@ -151,11 +192,11 @@ export async function reviewTicket(ticket, ctx) {
   try {
     if (!ctx.key) {
       return await reviewFile(
-        { repoRoot: ctx.repoRoot, file: ticket.file, base: entry.base, cfg: ctx.cfg, workDir },
+        { repoRoot: ctx.repoRoot, file: ticket.file, base: entry.base, cfg: ctx.cfg, workDir, factsExcerpt: acceptanceExcerpt(entry.acceptance, ctx.cfg) },
         { spawn: ctx.spawn, ...(ctx.writeRow ? { writeRow: ctx.writeRow } : {}) },
       );
     }
-    return await fixLoopRound(ticket, ctx, { base: entry.base, level: entry.level, owned: entry.owned, key: ctx.key, workDir });
+    return await fixLoopRound(ticket, ctx, { base: entry.base, level: entry.level, owned: entry.owned, key: ctx.key, workDir, factsExcerpt: acceptanceExcerpt(entry.acceptance, ctx.cfg) });
   } finally {
     rmSync(workDir, { recursive: true, force: true });
   }
@@ -164,10 +205,10 @@ export async function reviewTicket(ticket, ctx) {
 /**
  * One fix-loop round for the ticket (see the module doc).
  * @param {import('./queue.mjs').Ticket} ticket @param {ReviewContext} ctx
- * @param {{base: string | null, level: string, owned: string[], key: Buffer, workDir: string}} opts
+ * @param {{base: string | null, level: string, owned: string[], key: Buffer, workDir: string, factsExcerpt: string}} opts
  * @returns {Promise<ReviewOutcome>}
  */
-async function fixLoopRound(ticket, ctx, { base, level, owned, key, workDir }) {
+async function fixLoopRound(ticket, ctx, { base, level, owned, key, workDir, factsExcerpt }) {
   if (!ctx.readRows || !ctx.writeRow) return { status: 'unavailable', reason: 'no-ledger', approved: false, engine: 'adaptive', sessions: [] };
   let rows;
   try {
@@ -232,9 +273,10 @@ async function fixLoopRound(ticket, ctx, { base, level, owned, key, workDir }) {
         workDir,
         base,
         writeRow,
+        factsExcerpt,
         ...(jev ? { jev } : {}),
         review: async () => {
-          engineOutcome = await reviewFile({ repoRoot: ctx.repoRoot, file: ticket.file, base, cfg: ctx.cfg, workDir }, { spawn: ctx.spawn, writeRow });
+          engineOutcome = await reviewFile({ repoRoot: ctx.repoRoot, file: ticket.file, base, cfg: ctx.cfg, workDir, factsExcerpt }, { spawn: ctx.spawn, writeRow });
           return engineOutcome;
         },
         spawn: async (opts) => {