@spexcode/spec-core 0.6.2

package/src/review/reviewQuery.js

@@ -0,0 +1,174 @@
+// The ONE token-query engine ([[review-query]]) — pure JS, no React/DOM. Both review ListViews, the
+// route layer's legacy replay, and any consumer minting canonical eval/issue addresses import from HERE:
+// the visible query TEXT is the single source of truth, and every tab/menu/autocomplete is only a
+// BUILDER that rewrites tokens in it (GitHub-measured semantics).
+
+export const ISSUE_QUERY_DEFAULT = 'is:issue state:open'
+export const EVAL_QUERY_DEFAULT = 'is:eval'
+// the session doors' scoped-list address: the default view, scoped — the text shows exactly that.
+export const scopedEvalQuery = (sessionId) => setToken(EVAL_QUERY_DEFAULT, 'scope', sessionId)
+// the aggregate score/count doors' address ([[eval-score-badge]]): the default view, node-filtered.
+export const nodeEvalQuery = (nodeId) => setToken(EVAL_QUERY_DEFAULT, 'node', nodeId)
+
+const KEY_RE = /^([A-Za-z][A-Za-z0-9-]*):(.*)$/s
+const unquote = (v) => (v.length >= 2 && v.startsWith('"') && v.endsWith('"') ? v.slice(1, -1) : v)
+export const quoteValue = (v) => (/\s/.test(String(v)) ? `"${v}"` : String(v))
+
+// segment scan preserving EVERY character — whitespace runs and tokens (a `"` swallows spaces until it
+// closes), each with [start,end) offsets — so the aria-hidden highlight overlay mirrors the input
+// glyph-for-glyph and the autocomplete can find the token under the caret.
+export function scanQuery(text) {
+  const s = String(text ?? '')
+  const out = []
+  let i = 0
+  while (i < s.length) {
+    let j = i
+    if (/\s/.test(s[i])) {
+      while (j < s.length && /\s/.test(s[j])) j++
+      out.push({ ws: true, raw: s.slice(i, j), start: i, end: j })
+    } else {
+      while (j < s.length && !/\s/.test(s[j])) {
+        if (s[j] === '"') {
+          j++
+          while (j < s.length && s[j] !== '"') j++
+          if (j < s.length) j++
+        } else j++
+      }
+      const raw = s.slice(i, j)
+      const m = KEY_RE.exec(raw)
+      out.push(m
+        ? { ws: false, raw, start: i, end: j, key: m[1].toLowerCase(), value: unquote(m[2]) }
+        : { ws: false, raw, start: i, end: j, key: null, value: unquote(raw) })
+    }
+    i = j
+  }
+  return out
+}
+
+export const tokenize = (text) => scanQuery(text).filter((seg) => !seg.ws)
+export const serialize = (tokens) => tokens.map((t) => t.raw).join(' ')
+export const normalizeQuery = (text) => serialize(tokenize(text))
+export const sameQuery = (a, b) => normalizeQuery(a) === normalizeQuery(b)
+
+// duplicate qualifiers: the LAST occurrence wins; bare words all apply.
+export const effectiveTokens = (tokens) => {
+  const last = new Map()
+  for (const t of tokens) if (t.key != null) last.set(t.key, t)
+  return tokens.filter((t) => t.key == null || last.get(t.key) === t)
+}
+
+export const readToken = (text, key) => {
+  const tokens = tokenize(text)
+  for (let i = tokens.length - 1; i >= 0; i--) if (tokens[i].key === key) return tokens[i].value
+  return ''
+}
+
+// token SURGERY: rewrite the key at its first position, drop later duplicates, append when absent,
+// remove the key entirely on an empty value. Every other token — known or not — survives verbatim.
+export function setToken(text, key, value) {
+  const next = value == null || String(value) === ''
+    ? null
+    : { ws: false, raw: `${key}:${quoteValue(value)}`, key, value: String(value) }
+  const out = []
+  let placed = false
+  for (const t of tokenize(text)) {
+    if (t.key === key) {
+      if (next && !placed) { out.push(next); placed = true }
+      continue
+    }
+    out.push(t)
+  }
+  if (next && !placed) out.push(next)
+  return serialize(out)
+}
+
+// MATCHING is deliberately NOT here: this module owns text — scan/serialize/surgery/suggestions and the
+// canonical-address discipline — while the conjunctive field matching (including the unknown-qualifier
+// IMPOSSIBLE state) lives in the ONE [[review-filters]] engine, reached through its tokenFilterState
+// bridge. A second predicate here would be the exact fork the fusion removed.
+
+// canonical address discipline: the default view is the BARE page address; any other state is exactly
+// ?q=<raw text>. An emptied submit falls back to the default (→ bare).
+export const queryParam = (text, defaultText) => {
+  const trimmed = String(text ?? '').trim()
+  if (!trimmed || sameQuery(trimmed, defaultText)) return null
+  return { q: trimmed }
+}
+
+// A query/filter action resets by omitting page; a PAGINATION action passes a page (including 1) and
+// therefore records GitHub's explicit page=1 history form. The distinction is the action, not equivalence.
+export const reviewRouteQuery = (text, defaultText, page = null) => {
+  const query = queryParam(text, defaultText) || {}
+  if (page != null) query.page = String(page)
+  return Object.keys(query).length ? query : null
+}
+
+// LEGACY structured params → token pairs. `kind=all` maps to nothing: the evidence default IS all.
+const LEGACY_PARAMS = {
+  state: (v) => ['state', v],
+  concluded: (v) => (v === '1' ? ['state', 'closed'] : null),
+  ok: (v) => (v === '1' ? ['state', 'reviewed'] : null),
+  verdict: (v) => ['verdict', v],
+  freshness: (v) => ['freshness', v],
+  kind: (v) => (v === 'all' ? null : ['evidence', v]),
+  store: (v) => ['store', v],
+  author: (v) => ['author', v],
+  node: (v) => ['node', v],
+  filer: (v) => ['filer', v],
+  live: (v) => (v === '1' ? ['session', 'present'] : null),
+  session: (v) => ['scope', v],
+}
+
+export const hasLegacyParams = (query) =>
+  Object.keys(LEGACY_PARAMS).some((k) => query?.[k] != null && query[k] !== '')
+
+// the legacy free q was ONE substring search — it must replay as ONE text token. Quote it whenever the
+// tokenizer would read it as anything else: spaces (several words), a colon (q=drift:check would become
+// an unknown qualifier and match zero), or a stray quote (which would swallow neighbours).
+const freeTextToken = (v) => (/[\s:"]/.test(v) ? `"${v.replace(/"/g, '')}"` : v)
+
+// a legacy LIST address replays as the FULL visible state: the page's default tokens with each legacy
+// param surgically applied (live=1→session:present, session=<id>→scope:<id>, ok=1→state:reviewed,
+// kind→evidence:), the free-text q appended as ONE bare/phrase token preserving the old
+// single-substring search. Returns null when nothing legacy is present.
+export function legacyQueryText(defaultText, query) {
+  if (!hasLegacyParams(query)) return null
+  let text = defaultText
+  for (const [param, toPair] of Object.entries(LEGACY_PARAMS)) {
+    const v = query[param]
+    if (v == null || v === '') continue
+    const pair = toPair(String(v))
+    if (pair) text = setToken(text, pair[0], pair[1])
+  }
+  const free = String(query.q ?? '').trim()
+  if (free) text = `${text} ${freeTextToken(free)}`.trim()
+  return text
+}
+
+// inline autocomplete at the caret — client-side and BOUNDED. A bare prefix completes qualifier KEYS
+// (insert `key:`, keep typing); a `key:prefix` completes VALUES from the page-supplied candidate list
+// only (data-derived; scope = sessions on the current board), capped at 8. Everything else stays
+// hand-typable and submits verbatim.
+export function suggestAt(text, caret, keys = [], values = {}) {
+  const s = String(text ?? '')
+  const at = Math.max(0, Math.min(caret ?? s.length, s.length))
+  const seg = scanQuery(s).find((g) => !g.ws && g.start < at && at <= g.end)
+  if (!seg) return { start: at, end: at, items: [] }
+  const typed = s.slice(seg.start, at)
+  const m = KEY_RE.exec(typed)
+  if (!m) {
+    const w = typed.toLowerCase()
+    if (!w || w.includes('"')) return { start: seg.start, end: seg.end, items: [] }
+    const items = keys.filter((k) => k.startsWith(w)).slice(0, 8)
+      .map((k) => ({ type: 'key', key: k, insert: `${k}:` }))
+    return { start: seg.start, end: seg.end, items }
+  }
+  const key = m[1].toLowerCase()
+  const prefix = m[2].replace(/^"/, '').replace(/"$/, '').toLowerCase()
+  const pool = values[key] || []
+  const items = pool
+    .filter((c) => String(c.value).toLowerCase().startsWith(prefix) && String(c.value).toLowerCase() !== prefix)
+    .slice(0, 8)
+    .map((c) => ({ type: 'value', key, value: String(c.value), label: c.label || null, insert: `${key}:${quoteValue(c.value)} ` }))
+  return { start: seg.start, end: seg.end, items }
+}

package/src/review/session.js

@@ -0,0 +1,13 @@
+export const sessionPresent = (sessions, id) => {
+  const session = id ? (sessions || []).find((item) => item.id === id) : null
+  return session || null
+}
+
+export const sessionHeadline = (session) =>
+  session?.title || session?.headline || session?.name || session?.activity || session?.note
+  || session?.promptPreview || session?.node || session?.raw?.title || session?.branch || session?.id
+
+export const sessionHandle = (session) =>
+  session?.label || session?.name || session?.node || session?.title || session?.branch || session?.id
+
+export const sessionTitle = sessionHeadline

package/src/reviewSnapshot.ts

@@ -0,0 +1,28 @@
+export type ReviewEvalNode = {
+  id: string
+  hue?: number
+  scenarios: any[]
+  evals: any[]
+  readings: any[]
+}
+
+export type ReviewSnapshot = {
+  issues: any[]
+  evalNodes: ReviewEvalNode[]
+  forgeRevision: number
+}
+
+let current: ReviewSnapshot | null = null
+
+export function publishReviewSnapshot(snapshot: ReviewSnapshot): void {
+  current = snapshot
+}
+
+export function readReviewSnapshot(): ReviewSnapshot {
+  if (!current) throw new Error('review snapshot is unavailable before the first successful graph build')
+  return current
+}
+
+export function hasReviewSnapshot(): boolean {
+  return current !== null
+}

package/src/root-lru.ts

@@ -0,0 +1,54 @@
+// @@@ root-lru - ONE bounded root→key cache policy, for every layer that keeps immutable per-HEAD work warm.
+// A leaf module on purpose: it imports nothing from the spec graph, the eval sidecar, or git, so both layers
+// can depend on it without either owning the other ([[source-of-truth]]).
+//
+// The policy is reference-counted, not plain LRU, and the distinction is the whole point. Entries are keyed by
+// something IMMUTABLE (a HEAD, or a ledger path + HEAD), so two checkouts sitting on the same commit must share
+// one entry rather than build it twice. A root moving A→B therefore drops A only when NO other root still
+// points at it; otherwise a sequence of successful rebuilds retains one whole index per commit until the slot
+// bound finally evicts them. Bumping an unchanged root is a pure recency touch (delete + reinsert), which is
+// what makes `roots` insertion-ordered enough for the eviction loop to mean "oldest root".
+//
+// This existed twice, verbatim in logic and even in name — `touchRoot` in git.ts (index/drift) and again in
+// spec-eval's scenariofresh.ts (scenario chains), whose comment said it was "mirroring historyIndex/driftIndex
+// in git.ts". Both authors knew; neither had anywhere to put it. Now they do.
+
+// slot bound for one cache family. Every caller names its own env knob and default so operators can tune the
+// families independently, but nobody gets to invent a different FLOOR or a bare literal — a cache whose bound
+// is a magic number cannot be tuned in the field at all (scenariofresh's was a hardcoded 16).
+// @@@ unparseable is not zero - the shape both copies used, `Math.max(4, Number(env || fallback))`, returns
+// NaN for a mistyped value, and `size > NaN` is always false: one typo in an env var silently turned the
+// bound OFF and let the cache grow without limit. A bound that fails open is worse than no bound, because
+// nothing reports it. Anything that does not parse to a positive number falls back to the caller's default.
+export const rootSlots = (env: string | undefined, fallback: number): number => {
+  const asked = Number(env)
+  return Math.max(4, Number.isFinite(asked) && asked > 0 ? asked : fallback)
+}
+
+// Record that `root` now wants `key`, evicting what no root wants any more and keeping `roots` within `slots`.
+// `cache` is the caller's own keyed store; this owns only the ROOT→key bookkeeping and the eviction decision.
+export function touchRoot(
+  roots: Map<string, string>,
+  cache: Map<string, unknown> & { delete(key: string): boolean },
+  root: string,
+  key: string,
+  slots: number,
+): void {
+  const previous = roots.get(root)
+  if (previous !== key) {
+    roots.set(root, key)
+    // the old key survives only while some OTHER root still names it — immutable entries are shared, so
+    // dropping one root's view must not throw away a sibling checkout's warm work.
+    if (previous && ![...roots.values()].includes(previous)) cache.delete(previous)
+  } else {
+    roots.delete(root)
+    roots.set(root, key)   // recency bump: reinsertion is what makes the eviction loop below pick the oldest
+  }
+  while (roots.size > slots) {
+    const oldest = roots.keys().next().value as string | undefined
+    if (oldest === undefined) break
+    const oldKey = roots.get(oldest)
+    roots.delete(oldest)
+    if (oldKey && ![...roots.values()].includes(oldKey)) cache.delete(oldKey)
+  }
+}