spexcode 0.2.0 → 0.2.2

package/spec-yatsu/src/cli.ts

@@ -1,4 +1,4 @@
-import { readFileSync, existsSync } from 'node:fs'
+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 { loadSpecs } from '../../spec-cli/src/specs.js'
@@ -9,10 +9,11 @@ import { readReadings, readSidecar, appendReading, appendRetraction, latestPerSc
 import { staleAxes } from './freshness.js'
 import { scenarioIndex } from './scenariofresh.js'
 import { loadEvalRemarkTracks, trackKey } from '../../spec-cli/src/issues.js'
+import { stripRefSigil } from '../../spec-cli/src/mentions.js'
 import { evaluatorTag } from './evaluator.js'
-import { putBlob, listBlobs, gc, isStrayBlob } from './cache.js'
+import { putBlob, blobPath, listBlobs, gc, isStrayBlob } from './cache.js'
 import { validateTimeline } from './timeline.js'
-import { evalTimeline, type EvalTimeline } from './evaltab.js'
+import { evalTimeline, readBlobByHash, type EvalTimeline } from './evaltab.js'
 
 function flag(args: string[], name: string): string | undefined {
   const i = args.indexOf(`--${name}`)
@@ -206,7 +207,7 @@ async function evalCmd(args: string[]): Promise<number> {
     return 2
   }
   const sel = positional(args)
-  const id = !sel || sel === '.' ? currentNodeId(root) : sel
+  const id = !sel || sel === '.' ? currentNodeId(root) : stripRefSigil(sel)   // node args tolerate @/[[ ]] sigils ([[mentions]])
   if (!id) { console.error('spex yatsu eval .: no current node (no .session/node-branch here) — name a node'); return 2 }
   const node = (await gatherNodes(root)).find((n) => n.id === id)
   if (!node) { console.error(`spex yatsu eval: no yatsu node '${id}' (a node needs a yatsu.md)`); return 1 }
@@ -273,9 +274,34 @@ async function evalCmd(args: string[]): Promise<number> {
     : 'no evidence'
   console.log(`  ✓ '${id}' scenario '${scenario.name}' → ${verdictText(verdict)} @ ${reading.codeSha.slice(0, 7)} [${reading.evaluator}] (${ev})`)
   console.log(`spex yatsu eval: 1 measurement filed`)
+
+  // @@@mis-anchor guard - a codeSha names a COMMIT, never a working tree: filed over uncommitted governed
+  // edits, this reading claims a verdict at HEAD while HEAD lacks the code actually measured — wrong from
+  // birth, and the stale flag after the next commit is freshness exposing it, not an engine bug. Warn,
+  // never block: the honest flow is measure on the tree until green → commit that tested tree → file.
+  const dirty = dirtyGoverned(root, [...(scenario.code?.length ? scenario.code : node.codeFiles), node.yatsuPath])
+  if (dirty.length) {
+    console.error(`  ⚠ mis-anchored reading: uncommitted changes in governed ${dirty.join(', ')}`)
+    console.error(`    this reading anchors to HEAD ${reading.codeSha.slice(0, 7)}, which does NOT contain those edits — it claims a ${verdict.status} for code that never ran, and the commit that lands them will (correctly) read it stale.`)
+    console.error(`    the honest flow: measure on the tree until green → commit that just-tested tree (code+spec) → THEN file the reading against the clean HEAD (retract this one if it recorded the dirty run).`)
+  }
   return 0
 }
 
+// the governed paths with uncommitted changes (staged, unstaged, or untracked) — the mis-anchor guard's
+// probe. Paths are repo-relative pathspecs, so a governed dir prefix or `*` glob scopes the same way
+// nodeChanged matches it; a rename line reports its new name.
+function dirtyGoverned(root: string, paths: string[]): string[] {
+  if (!paths.length) return []
+  const out = git(['-C', root, 'status', '--porcelain', '--', ...paths])
+  const files = out.split('\n').filter(Boolean).map((l) => {
+    const p = l.slice(3)
+    const i = p.indexOf(' -> ')
+    return i >= 0 ? p.slice(i + 4) : p
+  })
+  return [...new Set(files)]
+}
+
 // the verdict from the flags: --pass or --fail sets the status (pass wins if both given); --note <text> is an
 // OPTIONAL annotation attached to either. No status flag → null (a measurement must commit to pass or fail).
 function parseVerdict(args: string[]): Verdict | null {
@@ -309,7 +335,7 @@ async function retractCmd(args: string[]): Promise<number> {
     return 2
   }
   const sel = positional(args)
-  const id = !sel || sel === '.' ? currentNodeId(root) : sel
+  const id = !sel || sel === '.' ? currentNodeId(root) : stripRefSigil(sel)
   if (!id) { console.error('spex yatsu retract .: no current node (no .session/node-branch here) — name a node'); return 2 }
   const node = yatsuNodes(root).find((n) => n.id === id)
   if (!node) { console.error(`spex yatsu retract: no yatsu node '${id}' (a node needs a yatsu.md)`); return 1 }
@@ -410,7 +436,7 @@ function checkStaged(): number {
 async function show(args: string[]): Promise<number> {
   const root = repoRoot()
   const sel = positional(args)
-  const id = !sel || sel === '.' ? currentNodeId(root) : sel
+  const id = !sel || sel === '.' ? currentNodeId(root) : stripRefSigil(sel)
   if (!id) { console.error('spex yatsu show .: no current node (no .session/node-branch here) — name a node'); return 2 }
   const tl = await evalTimeline(id)   // no ctx → evalTimeline derives specs + driftIndex itself for this one id
   if (has(args, 'json')) { console.log(JSON.stringify(tl, null, 2)); return 0 }
@@ -464,16 +490,20 @@ export async function runYatsu(args: string[]): Promise<number> {
   return 2
 }
 
-// `spex blob put <file|->` ([[blob-put]]) — the bare transport half of evidence: stash bytes in the shared
-// content-addressed cache and print the hash, WITHOUT filing a reading (`yatsu eval --video` couples the
-// two). putBlob is idempotent by content, so the same command re-seeds a checkout whose cache lacks a blob
+// `spex blob put <file|->` / `spex blob get <hash> [-o <file>]` ([[blob-put]], [[blob-get]]) — the bare
+// evidence-transport pair: put stashes bytes in the shared content-addressed cache and prints the hash,
+// WITHOUT filing a reading (`yatsu eval --video` couples the two); get is its symmetric read — hash in,
+// bytes out. putBlob is idempotent by content, so re-putting re-seeds a checkout whose cache lacks a blob
 // some thread already references by hash (the clone-evidence-404 repair).
-export function runBlob(args: string[]): number {
-  const file = args[1]
-  if (args[0] !== 'put' || file === undefined) {
-    console.error('spex blob: put <file|-> — stash bytes in the shared evidence cache, print the content hash')
-    return 2
-  }
+export async function runBlob(args: string[]): Promise<number> {
+  if (args[0] === 'put' && args[1] !== undefined) return blobPut(args[1])
+  if (args[0] === 'get') return blobGet(args.slice(1))
+  console.error('spex blob: put <file|-> — stash bytes in the shared evidence cache, print the content hash')
+  console.error('           get <hash> [-o <file>] — read a blob back: local cache first, backend fallback')
+  return 2
+}
+
+function blobPut(file: string): number {
   let bytes: Buffer
   try { bytes = readFileSync(file === '-' ? 0 : file) } catch (e) {
     console.error(`spex blob put: cannot read ${file}: ${(e as Error).message}`)
@@ -483,3 +513,47 @@ export function runBlob(args: string[]): number {
   console.log(putBlob(bytes))
   return 0
 }
+
+// the read half: ① the local content-addressed cache (the evidence usually IS on this disk — no backend
+// needed), ② on a local miss the same GET /api/yatsu/blob/:hash the dashboard streams from (the blob may
+// have been pruned here, or put on another machine sharing the backend), ③ both missed → fail loud naming
+// both paths. No third read mechanism — this reuses readBlobByHash and the existing endpoint verbatim.
+async function blobGet(args: string[]): Promise<number> {
+  const oIdx = args.indexOf('-o')
+  const out = oIdx >= 0 ? args[oIdx + 1] : undefined
+  if (oIdx >= 0 && (out === undefined || out.startsWith('-'))) { console.error('spex blob get: -o needs a <file>'); return 2 }
+  const hash = args.find((a, i) => (oIdx < 0 || (i !== oIdx && i !== oIdx + 1)) && !a.startsWith('-'))
+  if (!hash) { console.error('spex blob get: usage: spex blob get <hash> [-o <file>]'); return 2 }
+  const local = readBlobByHash(hash)   // validates 64-hex before touching the fs, then reads the shared cache
+  if (local.ok) return emitBlob(local.bytes, out)
+  if (local.reason === 'invalid') { console.error(`spex blob get: bad hash '${hash}' — a blob hash is 64 hex chars`); return 2 }
+  const { apiBase } = await import('../../spec-cli/src/sessions.js')
+  const url = `${await apiBase()}/api/yatsu/blob/${hash}`
+  let backendMiss: string
+  try {
+    const r = await fetch(url)
+    if (r.ok) return emitBlob(Buffer.from(await r.arrayBuffer()), out)
+    backendMiss = `HTTP ${r.status}`
+  } catch (e) {
+    backendMiss = `unreachable (${(e as Error).message})`
+  }
+  console.error(`spex blob get: ${hash} — not found on either path:`)
+  console.error(`  local cache: ${blobPath(hash)} — no such blob (pruned, or put on another machine)`)
+  console.error(`  backend:     ${url} — ${backendMiss}`)
+  return 1
+}
+
+// default stdout (pipe-friendly; the cli.ts flushExit drains a large piped dump before exit), -o writes a
+// file. Raw bytes straight at a human's terminal get a one-line stderr warning, not a block.
+function emitBlob(bytes: Buffer, out?: string): number {
+  if (out !== undefined) {
+    try { writeFileSync(out, bytes) } catch (e) {
+      console.error(`spex blob get: cannot write ${out}: ${(e as Error).message}`)
+      return 2
+    }
+    return 0
+  }
+  if (process.stdout.isTTY) console.error(`spex blob get: writing ${bytes.length} raw bytes to a tty — pipe it or use -o <file>`)
+  process.stdout.write(bytes)
+  return 0
+}

package/spec-yatsu/src/scenariofresh.ts

@@ -1,3 +1,4 @@
+import { spawn } from 'node:child_process'
 import { gitA, headSha } from '../../spec-cli/src/git.js'
 import { parseScenarios } from './yatsu.js'
 
@@ -25,49 +26,118 @@ function blockContent(src: string): Map<string, string> {
   return m
 }
 
-// the file's content-versions newest-first, each { hash, blocks }. Skips a version we can't read (git show
-// '') so an unreadable blob never fabricates a remove+re-add diff.
-async function fileVersions(root: string, headPath: string): Promise<{ hash: string; blocks: Map<string, string> }[]> {
-  // --follow + --name-only pairs each commit with the path the file had THERE, so `git show <hash>:<pathAtCommit>`
-  // works across reparents (yatsu.md moves when its node does). `-M` keeps a rename+edit's content.
-  const log = await gitA(['-C', root, '-c', 'core.quotePath=false', 'log', '-M', '--follow', `--format=${RS}%H`, '--name-only', '--', headPath])
-  const out: { hash: string; blocks: Map<string, string> }[] = []
-  for (const rec of log.split(RS)) {
-    const lines = rec.split('\n').map((l) => l.trim()).filter(Boolean)
-    if (!lines.length) continue
-    const hash = lines[0]
-    const pathAt = lines.slice(1).find((l) => l.endsWith('/yatsu.md') || l === 'yatsu.md') ?? headPath
-    const content = await gitA(['-C', root, 'show', `${hash}:${pathAt}`])
-    if (!content) continue
-    out.push({ hash, blocks: blockContent(content) })
+const ZERO = '0'.repeat(40)   // the null OID a delete/add carries on its absent side
+const EMPTY: Map<string, string> = new Map()
+
+// content-addressed: a blob OID -> its canonical per-scenario block map. Git objects are IMMUTABLE, so this
+// memo never needs invalidation and is shared across every root — a per-worktree build reuses the blocks main
+// already parsed, which is what lets a worktree's freshness build stay cheap instead of re-reading everything.
+const blockByOid = new Map<string, Map<string, string>>()
+
+// ONE `git log --raw` walk over all yatsu.md → per head-path version chain [{hash, oid}], newest-first,
+// rename-followed via the `alias` idiom (git.ts buildIndex): the newest sighting of a path IS its head path;
+// an `R` row remaps the older `from` path onto that head. The raw row carries the new blob OID directly, so
+// no per-version path resolution and no `git show`. --full-history is REQUIRED: default pathspec
+// history-simplification prunes commits off HEAD's first-parent chain, but in this repo every spec edit lands
+// via a --no-ff merge of a node branch, so those pruned commits ARE the scenario edits — dropping them would
+// under-report staleness (a stale reading judged fresh). Merge commits emit no raw diff row, so they add no
+// version (exactly as the old `--follow` did).
+async function fileChains(root: string, wanted: Set<string>): Promise<Map<string, { hash: string; oid: string }[]>> {
+  const chains = new Map<string, { hash: string; oid: string }[]>()
+  const alias = new Map<string, string>()
+  const out = await gitA(['-C', root, '-c', 'core.quotePath=false', 'log',
+    '--raw', '--no-abbrev', '--full-history', '-M', `--format=${RS}%H`, '--', '*yatsu.md'])
+  for (const rec of out.split(RS)) {
+    const nl = rec.indexOf('\n')
+    if (nl < 0) continue
+    const hash = rec.slice(0, nl)
+    if (!hash) continue
+    for (const line of rec.slice(nl + 1).split('\n')) {
+      if (line[0] !== ':') continue           // `:<oldmode> <newmode> <oldoid> <newoid> <status>\t<path>[\t<path2>]`
+      const tab = line.indexOf('\t')
+      if (tab < 0) continue
+      const meta = line.slice(1, tab).split(' ')
+      const oid = meta[3], rename = meta[4][0] === 'R' || meta[4][0] === 'C'
+      const paths = line.slice(tab + 1).split('\t')
+      const to = rename ? paths[1] : paths[0]   // the path on the newer side of this commit
+      let head = alias.get(to)
+      if (head === undefined) { head = to; alias.set(to, to) }
+      let arr = chains.get(head); if (!arr) { arr = []; chains.set(head, arr) }
+      arr.push({ hash, oid })
+      if (rename && paths[0] !== to) { alias.set(paths[0], head); alias.delete(to) }   // older history calls it `from`
+    }
   }
-  return out
+  for (const k of [...chains.keys()]) if (!wanted.has(k)) chains.delete(k)   // keep only the head paths asked for
+  return chains
 }
 
-// per-scenario change-commits for one file: walk versions newest->oldest, attribute a commit to every
-// scenario whose block differs from the next-older version (undefined on either side = add/remove = a change).
-async function scenarioCommits(root: string, headPath: string): Promise<Map<string, string[]>> {
-  const versions = await fileVersions(root, headPath)
+// per-scenario change-commits for one file's version chain: newest->oldest, attribute a commit to every
+// scenario whose canonical block differs from the next-older version (undefined either side = add/remove = a
+// change). A ZERO-oid (delete) version is dropped — it carries no readable content, matching the old
+// `git show ''` skip; a pure rename (R100, oid == the older version's oid) diffs to no change for free.
+function scenarioCommits(chain: { hash: string; oid: string }[]): Map<string, string[]> {
   const commits = new Map<string, string[]>()
   const push = (name: string, hash: string) => { const a = commits.get(name); if (a) a.push(hash); else commits.set(name, [hash]) }
-  for (let i = 0; i < versions.length; i++) {
-    const cur = versions[i].blocks
-    const older = versions[i + 1]?.blocks ?? new Map<string, string>()
+  const real = chain.filter((v) => v.oid !== ZERO)
+  for (let i = 0; i < real.length; i++) {
+    const cur = blockByOid.get(real[i].oid) ?? EMPTY
+    const older = i + 1 < real.length ? (blockByOid.get(real[i + 1].oid) ?? EMPTY) : EMPTY
     for (const name of new Set([...cur.keys(), ...older.keys()])) {
-      if (cur.get(name) !== older.get(name)) push(name, versions[i].hash)
+      if (cur.get(name) !== older.get(name)) push(name, real[i].hash)
     }
   }
   return commits
 }
 
+// read MANY blobs in ONE `git cat-file --batch` process (vs one `git show` per blob). Feeds the OIDs on
+// stdin, parses the `<oid> <type> <size>\n<payload>\n` records byte-accurately (size is bytes; blobs are
+// UTF-8). A `<oid> missing` line yields no entry. Env-stripped like git.ts's helpers (a stray GIT_DIR would
+// misroute repo discovery); kept here beside its only caller — a general git-seam primitive if a second
+// caller ever wants one.
+function catFileBatch(root: string, oids: string[]): Promise<Map<string, string>> {
+  const out = new Map<string, string>()
+  if (!oids.length) return Promise.resolve(out)
+  return new Promise((resolve, reject) => {
+    const env = { ...process.env }
+    delete env.GIT_DIR; delete env.GIT_WORK_TREE; delete env.GIT_INDEX_FILE; delete env.GIT_OBJECT_DIRECTORY
+    const p = spawn('git', ['-C', root, 'cat-file', '--batch'], { env })
+    const chunks: Buffer[] = []
+    p.stdout.on('data', (c: Buffer) => chunks.push(c))
+    p.on('error', reject)
+    p.on('close', () => {
+      const buf = Buffer.concat(chunks)
+      let i = 0
+      while (i < buf.length) {
+        const nl = buf.indexOf(0x0a, i)
+        if (nl < 0) break
+        const header = buf.toString('utf8', i, nl)
+        i = nl + 1
+        if (header.endsWith(' missing')) continue   // unknown OID — no payload follows
+        const size = Number(header.slice(header.lastIndexOf(' ') + 1))
+        if (!Number.isFinite(size)) break
+        out.set(header.slice(0, header.indexOf(' ')), buf.toString('utf8', i, i + size))
+        i += size + 1   // payload + its trailing newline
+      }
+      resolve(out)
+    })
+    p.stdin.on('error', () => { /* EPIPE if git exits early; the close handler reports what arrived */ })
+    p.stdin.write(oids.join('\n') + '\n')
+    p.stdin.end()
+  })
+}
+
+// TWO git subprocesses for the whole index (was F logs + V shows): one `--raw` log for the rename-followed
+// chains, one `cat-file --batch` for every distinct blob not already memoized. Then a pure in-memory diff.
 async function build(root: string, yatsuPaths: string[]): Promise<ScenarioIndex> {
-  const idx: ScenarioIndex = new Map()
-  const CONC = 8   // bound the git-show fan-out; the whole index is built once per HEAD then cached
-  for (let i = 0; i < yatsuPaths.length; i += CONC) {
-    const batch = yatsuPaths.slice(i, i + CONC)
-    const done = await Promise.all(batch.map((p) => scenarioCommits(root, p)))
-    batch.forEach((p, j) => idx.set(p, done[j]))
+  const chains = await fileChains(root, new Set(yatsuPaths))
+  const need = new Set<string>()
+  for (const chain of chains.values()) for (const v of chain) if (v.oid !== ZERO && !blockByOid.has(v.oid)) need.add(v.oid)
+  if (need.size) {
+    const blobs = await catFileBatch(root, [...need])
+    for (const [oid, src] of blobs) blockByOid.set(oid, blockContent(src))
   }
+  const idx: ScenarioIndex = new Map()
+  for (const p of yatsuPaths) idx.set(p, scenarioCommits(chains.get(p) ?? []))   // every asked path gets an entry (empty if untracked)
   return idx
 }