spexcode 0.5.2 → 0.5.4

package/spec-eval/src/cli.ts

@@ -1,13 +1,14 @@
 import { readFileSync, writeFileSync, existsSync } from 'node:fs'
 import { join, relative, dirname } from 'node:path'
-import { repoRoot, headSha, driftIndex, stagedFiles, git } from '../../spec-cli/src/git.js'
+import { repoRoot, headSha, driftIndex, stagedFiles, git, commitReachable } from '../../spec-cli/src/git.js'
 import { loadSpecs } from '../../spec-cli/src/specs.js'
 import { loadConfig } from '../../spec-cli/src/lint.js'
 import { trackedSourceFiles } from '../../spec-cli/src/source-files.js'
 import { mainBranch, envSessionId, readRawRecord } from '../../spec-cli/src/layout.js'
-import { evalNodes, validateScenarios, resolveEvalNode, scenarioHash, EVAL_FILE, type EvalNode, type ScenarioTestReference } from './scenarios.js'
+import { evalNodes, evalNodesAt, validateScenarios, resolveEvalNode, scenarioCodeAxis, scenarioHash, scenarioProjection, writeScenarioMeasurementMetadata, EVAL_FILE, type EvalNode, type ScenarioTestReference } from './scenarios.js'
 import { readReadings, readSidecar, appendReading, appendRetraction, latestPerScenario, evidenceOf, isJsonBlob, type Reading, type Verdict, type Evidence, type EvidenceKind, type Retraction } from './sidecar.js'
-import { staleAxes, contentProbeFor } from './freshness.js'
+import { staleAxes, contentProbeFor, anchorProbeFor, anchorProblems } from './freshness.js'
+import { parseRelation, relationClaimsPath } from '../../spec-cli/src/anchors.js'
 import { scenarioIndex } from './scenariofresh.js'
 import { loadEvalRemarkTracks, trackKey } from '../../spec-cli/src/issues.js'
 import { stripRefSigil } from '../../spec-cli/src/mentions.js'
@@ -60,16 +61,31 @@ function currentNodeId(root: string): string | null {
 const UI_FILE = /\.(jsx|tsx|vue|svelte|css)$/
 export const isUiPath = (p: string) => UI_FILE.test(p) || p.includes('spec-dashboard/')
 
-// merge-base anchored so the main branch advancing isn't counted as this branch's change; a git error yields ∅ (--changed scan stays silent)
-function changedSinceBase(root: string): Set<string> {
-  const out = new Set<string>()
-  const add = (s: string) => { for (const l of s.split('\n')) { const t = l.trim(); if (t) out.add(t) } }
+type ChangedScope = { base: string; paths: Set<string>; config: string }
+
+// Merge-base anchored so main advancing is not counted as this branch's change. Scope construction is
+// indivisible: a missing base/diff is no scope at all, never an empty set that can masquerade as clean.
+function changedScope(root: string): ChangedScope {
+  const branch = mainBranch()
+  const paths = new Set<string>()
+  const add = (path: string | undefined) => { if (path) paths.add(path) }
   try {
-    const base = git(['-C', root, 'merge-base', mainBranch(), 'HEAD']).trim()
-    if (base) add(git(['-C', root, '-c', 'core.quotePath=false', 'diff', '--name-only', base]))
-    add(git(['-C', root, '-c', 'core.quotePath=false', 'ls-files', '--others', '--exclude-standard']))
-  } catch { /* no base → empty set */ }
-  return out
+    const base = git(['-C', root, 'merge-base', branch, 'HEAD']).trim()
+    if (!base) throw new Error('git merge-base returned no commit')
+    const fields = git(['-C', root, '-c', 'core.quotePath=false', 'diff', '--name-status', '-z', '-M', base])
+      .split('\0').filter(Boolean)
+    for (let i = 0; i < fields.length;) {
+      const status = fields[i++]
+      if (/^[RC]/.test(status)) { add(fields[i++]); add(fields[i++]) }
+      else add(fields[i++])
+    }
+    for (const path of git(['-C', root, '-c', 'core.quotePath=false', 'ls-files', '--others', '--exclude-standard']).split('\n')) add(path.trim())
+    const config = existsSync(join(root, 'spexcode.json')) ? join(root, 'spexcode.json') : 'defaults'
+    return { base, paths, config }
+  } catch (error) {
+    const detail = error instanceof Error ? error.message.trim() : String(error)
+    throw new Error(`cannot establish changed scope against '${branch}': ${detail}`)
+  }
 }
 
 // A node owns the files under its spec dir except those under a descendant node. Its other selection axis
@@ -81,27 +97,35 @@ export function nodeChanged(dirRel: string, codeFiles: readonly string[], change
     const inDescendant = descendants.some((d) => c === d || c.startsWith(d + '/'))
     if (inNodeDir && !inDescendant) return true
   }
-  return codeFiles.some((cf) => {
-    if (changed.has(cf)) return true
-    const dir = cf.replace(/\/+$/, '') + '/'
-    const re = cf.includes('*') ? new RegExp('^' + cf.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*') + '$') : null
-    for (const c of changed) { if (c.startsWith(dir)) return true; if (re && re.test(c)) return true }
-    return false
-  })
+  return codeFiles.some((claim) => [...changed].some((file) => relationClaimsPath(claim, file)))
 }
 
 async function scan(args: string[] = []): Promise<number> {
   const root = repoRoot()
   const cfg = loadConfig(root)
+  const changedOnly = has(args, 'changed')
+  let changed: Set<string> | null = null
+  if (changedOnly) {
+    try {
+      const scope = changedScope(root)
+      changed = scope.paths
+      console.error(`spex eval lint --changed scope: base=${scope.base} paths=${scope.paths.size} config=${scope.config}`)
+    } catch (error) {
+      console.error(`spex eval lint --changed: ${error instanceof Error ? error.message : String(error)}`)
+      return 2
+    }
+  }
   // eval-coverage fires on ANY governed source file per the same classifier as spec coverage, not just
   // frontend — so backend/CLI/non-web source is held to the loss discipline too, not exempted.
   const sourceFiles = new Set(trackedSourceFiles(root, cfg.governedRoots, cfg))
-  const changedOnly = has(args, 'changed')
-  const changed = changedOnly ? changedSinceBase(root) : null
   const idx = await driftIndex(root)
   // the off-history content fallback ([[eval-core]]): a rebased/folded-away anchor with byte-identical
   // governed content reads fresh instead of false-positive stale. Lazy — in-history readings never probe.
   const probe = contentProbeFor(root)
+  // the code axis's spatial narrowing ([[eval-core]]): an anchored `code:` entry stales a reading only when a
+  // window commit touched one of its named units. Same lazy shape as the content probe — a bare entry never
+  // reaches it, so an unanchored corpus pays nothing.
+  const anchors = anchorProbeFor(root, idx)
   const scidx = await scenarioIndex(root, evalNodes(root).map((n) => n.evalPath))
   const specs = await loadSpecs()
   // the non-git REMARK freshness axis ([[remark-teeth]]): the trunk remark track, read ONCE — the CLI is the
@@ -133,16 +157,26 @@ async function scan(args: string[] = []): Promise<number> {
         // a scenario's own `code` narrows its freshness CODE axis to a subset; a path that does not exist
         // would make that axis silently immortal (changedSince finds no commits for it), so flag it LOUD as a
         // malformed declaration — the same loud-fail spirit as a bad node `code:`.
+        // ONE resolution of the axis: base paths for every path consumer (existence, changed-scan selection,
+        // drift display), folded selectors for the narrowing. A raw `path#symbol` matches no real file, so
+        // reading it as a path would report a ghost and drop the scenario out of --changed selection.
+        const axis = scenarioCodeAxis(sc.code, s.code)
         if (nodeSelected) {
-          for (const [field, paths] of [['code', sc.code], ['related', sc.related]] as const) {
-            const ghosts = (paths ?? []).filter((p) => !existsSync(join(root, p)))
+          for (const [field, paths] of [['code', axis.paths], ['related', parseRelation(sc.related ?? [], 'related').entries.map((e) => e.path)]] as const) {
+            const ghosts = paths.filter((p) => !existsSync(join(root, p)))
             if (ghosts.length) {
               malformed++
               findings.push(`  • eval-schema: '${s.id}' scenario '${sc.name}' \`${field}\` path(s) not found: ${ghosts.join(', ')} — fix ${y.evalPath}`)
             }
           }
+          // an anchor is a claim a named unit exists — dead/ambiguous/unextractable is LOUD, and until it is
+          // repaired the probe issues no verdict, so the reading stays conservatively stale.
+          for (const p of [...axis.problems, ...anchorProblems(root, axis.entries)]) {
+            malformed++
+            findings.push(`  • eval-schema: '${s.id}' scenario '${sc.name}' ${p} — fix ${y.evalPath}`)
+          }
         }
-        const codeFiles = sc.code?.length ? sc.code : s.code   // scenario's own subset, else the node's list
+        const codeFiles = axis.paths   // scenario's own subset, else the node's list
         const driftSelected = !changed || nodeChanged(dirRel, codeFiles, changed, nodeDirs)
         // carry the scenario's tags on the finding line — its SURFACE (e.g. frontend-e2e = browser-measured)
         // is what routes a drift/missing gap to the right measuring hand, so the proactive nudge and a human
@@ -158,7 +192,9 @@ async function scan(args: string[] = []): Promise<number> {
         }
         if (!driftSelected) continue
         const remSignals = (remarkTracks.get(trackKey(s.id, sc.name))?.remarks ?? []).map((rm) => ({ resolved: !!rm.resolved, resolvedAt: rm.resolvedAt }))
-        const axes = staleAxes(r, codeFiles, y.evalPath, idx, scidx, remSignals, probe, sc)
+        if (!commitReachable(idx, r.codeSha)) await probe.prime?.(r.codeSha, codeFiles, y.evalPath)
+        await anchors.prime?.(r.codeSha, axis.entries)
+        const axes = staleAxes(r, sc.code?.length ? sc.code : s.code, y.evalPath, idx, scidx, remSignals, probe, sc, anchors)
         if (axes.length) {
           staleScores++
           // a remark-stale scenario is unlocked by a second-party resolve, then a fresh reading; the git axes
@@ -196,7 +232,11 @@ async function scan(args: string[] = []): Promise<number> {
   if (!changedOnly) {
     const maxOwners = cfg.maxOwners
     const govCount = new Map<string, number>()
-    for (const n of yByDir.values()) for (const sc of n.scenarios) for (const f of sc.code ?? []) govCount.set(f, (govCount.get(f) ?? 0) + 1)
+    // scoped entries stay OUT of the bound ([[code-anchor]]): a scenario claiming named units does NOT claim
+    // the file, so narrowing an axis can never manufacture an eval-owners smell — the count stays a fact
+    // about how many scenarios measure the WHOLE file.
+    for (const n of yByDir.values()) for (const sc of n.scenarios)
+      for (const e of scenarioCodeAxis(sc.code).entries) if (!e.selectors.length) govCount.set(e.path, (govCount.get(e.path) ?? 0) + 1)
     const over = [...govCount].filter(([, c]) => c > maxOwners).sort((a, b) => b[1] - a[1])
     if (over.length) {
       overOwned = over.length
@@ -621,6 +661,52 @@ export function scenarioListRows(nodes: EvalNode[], unmeasuredOnly = false): Sce
   return rows
 }
 
+function scenarioProjectionProvenance(root: string): { head: string; treeSha: string } {
+  // These are fixed-tree provenance fields, deliberately outside semanticIndexHash/fullIndexHash. A mode or
+  // type change therefore remains visible to a tree consumer without changing the content-derived scenario
+  // identities. The command runs inside a Git project, so failure is loud instead of manufacturing provenance.
+  const head = git(['-C', root, 'rev-parse', 'HEAD']).trim()
+  if (!head) throw new Error('cannot resolve one fixed HEAD provenance')
+  const treeSha = git(['-C', root, 'rev-parse', `${head}^{tree}`]).trim()
+  if (!treeSha) throw new Error(`cannot resolve tree provenance for fixed HEAD ${head}`)
+  return { head, treeSha }
+}
+
+function scenarioWrite(args: string[]): number {
+  let rawMutation: string | undefined
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]
+    if (arg !== '--mutation') {
+      console.error(`spex eval scenario write: unknown argument '${arg}' — accepts only --mutation <json>; eval.md bytes come from stdin`)
+      return 2
+    }
+    if (rawMutation !== undefined) {
+      console.error('spex eval scenario write: --mutation must be supplied exactly once')
+      return 2
+    }
+    const value = args[++i]
+    if (value === undefined) {
+      console.error('spex eval scenario write: --mutation needs one JSON value')
+      return 2
+    }
+    rawMutation = value
+  }
+  if (rawMutation === undefined) {
+    console.error('spex eval scenario write: usage: spex eval scenario write --mutation <json> < eval.md')
+    return 2
+  }
+
+  try {
+    const mutation = JSON.parse(rawMutation)
+    const source = readFileSync(0, 'utf8')
+    process.stdout.write(writeScenarioMeasurementMetadata(source, mutation))
+    return 0
+  } catch (e: any) {
+    console.error(`spex eval scenario write: ${e?.message ?? e}`)
+    return 1
+  }
+}
+
 async function scenarioLs(args: string[]): Promise<number> {
   for (const a of args) {
     if (!a.startsWith('--')) continue
@@ -632,6 +718,32 @@ async function scenarioLs(args: string[]): Promise<number> {
   }
   const root = repoRoot()
   const sel = positional(args)
+  const unmeasuredOnly = has(args, 'unmeasured')
+  if (has(args, 'json')) {
+    if (unmeasuredOnly) {
+      console.error('spex eval scenario ls --json: --unmeasured needs evals; JSON is the complete declaration projection and reads no eval sidecar')
+      return 2
+    }
+    try {
+      const before = scenarioProjectionProvenance(root)
+      // Read declarations from the exact commit named by `before`, never from a dirty/staged working tree.
+      const fixedNodes = evalNodesAt(root, before.head)
+      const selected = sel
+        ? (() => {
+            const ref = sel === '.' ? currentNodeId(root) : stripRefSigil(sel)
+            if (!ref) throw new Error('no current node (no session/node-branch here) — name a node')
+            const res = resolveEvalNode(fixedNodes, ref)
+            if (!res.ok) throw new Error(res.error)
+            return [res.node]
+          })()
+        : fixedNodes
+      console.log(JSON.stringify(scenarioProjection(selected, before), null, 2))
+      return 0
+    } catch (e: any) {
+      console.error(`spex eval scenario ls --json: ${e?.message ?? e}`)
+      return 1
+    }
+  }
   let nodes = evalNodes(root)
   if (sel) {
     const ref = sel === '.' ? currentNodeId(root) : stripRefSigil(sel)
@@ -640,9 +752,7 @@ async function scenarioLs(args: string[]): Promise<number> {
     if (!res.ok) { console.error(`spex eval scenario ls: ${res.error}`); return 1 }
     nodes = [res.node]
   }
-  const unmeasuredOnly = has(args, 'unmeasured')
   const rows = scenarioListRows(nodes, unmeasuredOnly)
-  if (has(args, 'json')) { console.log(JSON.stringify(rows, null, 2)); return 0 }
   if (!rows.length) {
     console.log(`spex eval scenario ls: ${unmeasuredOnly ? 'no unmeasured scenarios' : 'no scenarios declared'}${sel ? ` on '${nodes[0]?.id ?? sel}'` : ''}`)
     return 0
@@ -659,8 +769,9 @@ async function scenarioLs(args: string[]): Promise<number> {
 }
 
 // the `spex eval` drawer's node-scoped verbs ([[cli-surface]]): add (file a measurement) · ls (a node's
-// reading timeline) · scenario ls (the declared contracts, --unmeasured = blind spots) · lint (the
-// measurement-layer lint — advisory, always exit 0) · ok (the human sign-off) · retract · clean.
+// reading timeline) · scenario ls/write (the declared contracts and their canonical metadata writer) · lint (the
+// measurement-layer lint — findings are advisory; an unreadable --changed scope fails) · ok (the human
+// sign-off) · retract · clean.
 // The session-scoped read (`spex eval ls --session <SEL>`) is intercepted in cli.ts before this runs;
 // `check-staged` is hook plumbing, exported separately for `spex internal check-staged`.
 export async function runEval(args: string[]): Promise<number> {
@@ -679,10 +790,11 @@ export async function runEval(args: string[]): Promise<number> {
   }
   if (sub === 'scenario') {
     if (args[1] === 'ls') return scenarioLs(args.slice(2))
-    console.error('spex eval scenario: ls [<node>|.] [--unmeasured] [--json] — list declared scenarios (the measurement contracts)')
+    if (args[1] === 'write') return scenarioWrite(args.slice(2))
+    console.error('spex eval scenario: ls [<node>|.] [--unmeasured] [--json] | write --mutation <json> < eval.md')
     return 2
   }
-  console.error('spex eval: add [.|<node>] [--scenario <name>] (--pass|--fail) [--note <text>] [--image <path> …repeatable] [--result <path|->] [--video <path>] [--timeline <json>] | ls [.|<node>] [--json] | ls --session <SEL> [--export] | scenario ls [<node>|.] [--unmeasured] [--json] | matrix <launcher> [--node <id>] [--rows k1,k2] | lint [--changed] | ok <node> [--scenario <name>] | retract [.|<node>] [--scenario <name>] [--last | --ts <iso>] [--note <why>] | clean [--keep-latest|--all]')
+  console.error('spex eval: add [.|<node>] [--scenario <name>] (--pass|--fail) [--note <text>] [--image <path> …repeatable] [--result <path|->] [--video <path>] [--timeline <json>] | ls [.|<node>] [--json] | ls --session <SEL> [--export] | scenario ls [<node>|.] [--unmeasured] [--json] | scenario write --mutation <json> < eval.md | matrix <launcher> [--node <id>] [--rows k1,k2] | lint [--changed] | ok <node> [--scenario <name>] | retract [.|<node>] [--scenario <name>] [--last | --ts <iso>] [--note <why>] | clean [--keep-latest|--all]')
   return 2
 }
 

package/spec-eval/src/evaltab.ts

@@ -1,10 +1,10 @@
 import { relative, dirname } from 'node:path'
-import { repoRoot, driftIndex, historyIndex, type DriftIndex, type HistoryIndex } from '../../spec-cli/src/git.js'
+import { repoRoot, driftIndex, historyIndex, commitReachable, type DriftIndex, type HistoryIndex } from '../../spec-cli/src/git.js'
 import { loadSpecs } from '../../spec-cli/src/specs.js'
 import { loadEvalRemarkTracks, trackKey, type RemarkTrack, type Issue, type Reply } from '../../spec-cli/src/issues.js'
-import { evalNodes, type EvalNode, type ScenarioTestReference } from './scenarios.js'
+import { evalNodes, scenarioCodeAxis, type EvalNode, type ScenarioTestReference } from './scenarios.js'
 import { readSidecar, applyRetractions, evidenceOf, isJsonBlob, humanOkFor, type Verdict, type EvidenceKind, type Retraction } from './sidecar.js'
-import { staleAxes, codeDrift, contentProbeFor, type StaleAxis } from './freshness.js'
+import { staleAxes, codeDrift, contentProbeFor, anchorProbeFor, type StaleAxis } from './freshness.js'
 import { scenarioIndex, type ScenarioIndex } from './scenariofresh.js'
 import { hasBlob, getBlob, MISS_BLOB } from './cache.js'
 
@@ -171,17 +171,24 @@ export async function evalTimeline(id: string, ctx?: EvalContext): Promise<EvalT
   // along as the undo trace (newest-first, like the readings), the human-ok events as the sign-off overlay.
   const { readings: rawReadings, retractions, oks } = readSidecar(ynode.sidecarPath)
   // the off-history content fallback ([[eval-core]]): fed to both git axes so a rebased/folded-away
-  // anchor with byte-identical governed content reads fresh. Lazy — an in-history reading never probes.
+  // anchor with byte-identical governed content reads fresh. An in-history reading never probes.
   const probe = contentProbeFor(root)
-  const readings: EvalEntry[] = applyRetractions(rawReadings, retractions).map((r) => {
+  const anchors = anchorProbeFor(root, idx)
+  const readings: EvalEntry[] = []
+  for (const r of applyRetractions(rawReadings, retractions)) {
     // a scenario's own `code` is its freshness code axis when it declares one; else the whole node's list.
     const sc = byName.get(r.scenario)
     // the teeth feed the WHOLE scenario track against THIS reading — an unresolved (or not-yet-out-run)
     // remark makes it remark-stale (T1). Display attachment (which reading each remark pins to) is a separate
     // read-time overlay below; freshness never depends on that pin.
     const cf = sc?.code?.length ? sc.code : codeFiles
+    // an entry may be anchored (`path#symbol`); every PATH consumer below reads base paths, the narrowing
+    // reads the folded selectors ([[eval-core]]).
+    const axis = scenarioCodeAxis(sc?.code, codeFiles)
+    if (!commitReachable(idx, r.codeSha)) await probe.prime?.(r.codeSha, axis.paths, ynode.evalPath)
+    await anchors.prime?.(r.codeSha, axis.entries)
     const axes = staleAxes(r, cf, ynode.evalPath, idx, scidx,
-      remarksFor(r.scenario).map((rm) => ({ resolved: !!rm.resolved, resolvedAt: rm.resolvedAt })), probe, sc)
+      remarksFor(r.scenario).map((rm) => ({ resolved: !!rm.resolved, resolvedAt: rm.resolvedAt })), probe, sc, anchors)
     // when the code axis is stale, explain it: which of THIS reading's governed files moved, by how many commits.
     const drift = axes.includes('code') ? codeDrift(idx, r.codeSha, cf, probe) : []
     // the reading's evidence list, each entry resolved to its live blob state; the primary (video-first, else
@@ -191,7 +198,7 @@ export async function evalTimeline(id: string, ctx?: EvalContext): Promise<EvalT
     // the sign-off join ([[human-ok]]): the ok binds by exact (scenario, ts), so only the very reading the
     // human blessed carries it — a newer or retract-revealed reading reads unblessed.
     const okRow = humanOkFor(oks, r.scenario, r.ts)
-    return {
+    readings.push({
       scenario: r.scenario,
       expected: byName.get(r.scenario)?.expected ?? '',
       codeSha: r.codeSha,
@@ -209,8 +216,8 @@ export async function evalTimeline(id: string, ctx?: EvalContext): Promise<EvalT
       blobState: primary ? primary.state : 'none',
       ...(threadFor(r.scenario) ? { thread: threadFor(r.scenario) } : {}),
       ...(okRow ? { humanOk: { by: okRow.by, ts: okRow.ts } } : {}),
-    }
-  })
+    })
+  }
   readings.reverse()   // newest-first
   // R2 display overlay ([[remark-teeth]]): pin each remark to the reading it JUDGED (targetCodeSha match),
   // else the scenario's latest reading (first in newest-first order) — a dangling target never HIDES the