@inerrata-corporation/errata 2.0.21 → 2.0.22

package/resources/claude-mods/errata-minimap/hooks/chains.ts

@@ -0,0 +1,427 @@
+import type { ChainFacts, FarNode, MapGraph, MapNode } from '../types'
+
+/**
+ * The burst bound into BOOKS: a book is one causal chain — RootCause → Problem
+ * → Solution, any subset — the way the splash's lesson stacks read a node's
+ * neighbourhood (apps/splash/src/network/components/library/lesson-model.ts).
+ * Books stand in BOOKCASES by technology and on SHELVES by community.
+ *
+ * Two sources, merged: the burst rows themselves (their `via` edge says how
+ * each was reached, so a cause or fix walked off a problem joins its book at
+ * once), and `errata_neighbors` answers fetched after the first draw
+ * (`ChainFacts`), which complete a chain beyond the burst and place it — its
+ * package, its local community, its patterns, the file it is anchored at.
+ */
+export type Role = 'cause' | 'problem' | 'fix'
+
+export type Part = {
+  id: string
+  label: string
+  name: string
+  /** Entered the agent's context with this burst; false = completed from the graph afterwards. */
+  isDelivered: boolean
+}
+
+export type Book = {
+  /** The problem's id, or the lone cause/fix's when no problem is known. */
+  key: string
+  cause?: Part
+  problem?: Part
+  fix?: Part
+  /** Causes / fixes the chain holds beyond the one on its card. */
+  moreCauses: number
+  moreFixes: number
+  /** The strongest member's burst score. */
+  score: number
+  isSeed: boolean
+  memberIds: string[]
+  tech?: string
+  community?: string
+  patterns: string[]
+  anchor?: string
+  /** Its `errata_neighbors` answer has arrived. */
+  isCatalogued: boolean
+}
+
+export type Shelf = {
+  key: string
+  name: string
+  /** 1-based, top shelf first: the middle term of a call number. */
+  number: number
+  books: Book[]
+  isMiscellany: boolean
+}
+
+export type Bookcase = {
+  tech: string
+  /** Three letters of the tech, the call number's class mark (CHO for chokidar). */
+  code: string
+  shelves: Shelf[]
+  isGeneral: boolean
+}
+
+export type Catalog = { cases: Bookcase[]; books: Book[] }
+
+const ROLE_OF: Record<string, Role> = {
+  Problem: 'problem',
+  Vulnerability: 'problem',
+  AntiPattern: 'problem',
+  Claim: 'problem',
+  RootCause: 'cause',
+  Constraint: 'cause',
+  Solution: 'fix',
+  Technique: 'fix',
+}
+
+/** A node's place in a chain; a seed not yet named reads its role off its id prefix. */
+export function roleOf(label: string, id = ''): Role | undefined {
+  if (ROLE_OF[label]) return ROLE_OF[label]
+  if (label !== 'Seed') return undefined
+  if (/^dprob_/.test(id)) return 'problem'
+  if (/^dcause_/.test(id)) return 'cause'
+  if (/^(dfix|dsol)_/.test(id)) return 'fix'
+  return undefined
+}
+
+type Edge = { from: string; to: string; type: string }
+
+const CAUSE_EDGES = new Set(['CAUSED_BY'])
+const CAUSES_EDGES = new Set(['MANIFESTS_AS', 'CAUSES'])
+const FIX_EDGES = new Set(['SOLVED_BY', 'FIXED_BY', 'RESOLVED_BY'])
+const FIXES_EDGES = new Set(['SOLVES', 'FIXES', 'RESOLVES'])
+const TECH_EDGES = new Set(['DEPENDS_ON', 'CONCERNS', 'OCCURS_IN'])
+const TECH_LABELS = new Set(['Package', 'Tool', 'Component', 'Language'])
+
+/** Each walked row's edge, oriented: `forward` ⇒ parent —type→ node. */
+function burstEdges(graph: MapGraph): Edge[] {
+  return graph.nodes.flatMap(n => {
+    const parent = graph.nodes[n.parent]
+    if (n.isSeed || !parent || !n.edge) return []
+    return [n.forward === false ? { from: n.id, to: parent.id, type: n.edge } : { from: parent.id, to: n.id, type: n.edge }]
+  })
+}
+
+/** What a cause or fix node belongs to, by the walk's own edges: problem ids, and (for a fix) cause ids. */
+function ownersOf(id: string, role: Role, edges: Edge[]): string[] {
+  const out: string[] = []
+  for (const e of edges) {
+    if (role === 'cause') {
+      if (e.to === id && CAUSE_EDGES.has(e.type)) out.push(e.from)
+      if (e.from === id && CAUSES_EDGES.has(e.type)) out.push(e.to)
+    } else if (role === 'fix') {
+      if (e.to === id && FIX_EDGES.has(e.type)) out.push(e.from)
+      if (e.from === id && FIXES_EDGES.has(e.type)) out.push(e.to)
+    }
+  }
+  return out
+}
+
+const part = (n: { id: string; label: string; name: string }, isDelivered: boolean): Part => ({ id: n.id, label: n.label, name: n.name, isDelivered })
+
+/**
+ * `vitest@3.2.6` → `vitest`, `@hono/zod-validator@0.7.6` → `@hono/zod-validator`:
+ * a bookcase holds the technology, not one release of it.
+ */
+export function techName(name: string): string {
+  return name.replace(/^(@?[^@\s]+)@[^@\s]*$/, '$1')
+}
+
+/**
+ * How strongly a tech anchor names a chain's bookcase, lower first. A versioned
+ * package is a dependency the problem is ABOUT; an unversioned one is nearly
+ * always the workspace's own package (`@inerrata-corporation/cloud-client`),
+ * which says where the code lives, not what it fights. Language last: on the
+ * live store `typescript` anchors 398 of 428 anchored chains — it separates
+ * nothing, so it only names a case when nothing else does.
+ */
+function techTier(n: FarNode): number {
+  if (n.label === 'Package') return /^@?[^@\s]+@\S+$/.test(n.name) ? 0 : 1
+  if (n.label === 'Tool' || n.label === 'Component') return 2
+  return 3
+}
+
+/**
+ * Each book's bookcase: within the best tier a chain has, the tech the most
+ * books in view share (greedy set cover), so a burst consolidates into a few
+ * cases instead of one per package a problem happens to touch (a problem has
+ * ~1.6 DEPENDS_ON edges on the live store).
+ */
+function assignTech(books: Book[], candidates: Map<string, FarNode[]>): void {
+  let open = books.filter(b => (candidates.get(b.key) ?? []).length > 0)
+  for (let tier = 0; tier <= 3 && open.length > 0; tier++) {
+    const inTier = (b: Book) => (candidates.get(b.key) ?? []).filter(c => techTier(c) === tier).map(c => techName(c.name))
+    for (;;) {
+      const count = new Map<string, number>()
+      for (const b of open) for (const t of new Set(inTier(b))) count.set(t, (count.get(t) ?? 0) + 1)
+      if (count.size === 0) break
+      // Ties go to the tech met first, in book order (strongest first).
+      const best = [...count].reduce((a, b) => (b[1] > a[1] ? b : a))[0]
+      for (const b of open) if (inTier(b).includes(best)) b.tech = best
+      open = open.filter(b => b.tech === undefined)
+    }
+  }
+}
+
+/** A path-like anchor (a file, or a symbol), or the `@ path:line` a problem title carries. */
+function anchorOf(facts: ChainFacts | null | undefined, name: string | undefined): string | undefined {
+  const fromTitle = name ? /\s@\s+(\S+:\d+)\s*$/.exec(name)?.[1] : undefined
+  if (fromTitle) return fromTitle
+  const anchors = facts?.anchors ?? []
+  return anchors.find(a => a.includes('/')) ?? anchors[0]
+}
+
+/** The burst bound into chains and placed: books strongest first, in bookcases and on shelves. */
+export function catalogue(graph: MapGraph, facts: Record<string, ChainFacts | null> = {}): Catalog {
+  const edges = burstEdges(graph)
+  const ranked = graph.nodes
+    .map((n, i) => ({ n, i, role: roleOf(n.label, n.id) }))
+    .filter((x): x is { n: MapNode; i: number; role: Role } => x.role !== undefined)
+    .sort((a, b) => Number(b.n.isSeed) - Number(a.n.isSeed) || b.n.score - a.n.score || a.i - b.i)
+  const books = new Map<string, Book>()
+  const bookOf = new Map<string, Book>()
+  const open = (key: string, score: number, isSeed: boolean): Book => {
+    const book: Book = { key, moreCauses: 0, moreFixes: 0, score, isSeed, memberIds: [], patterns: [], isCatalogued: false }
+    books.set(key, book)
+    return book
+  }
+  const join = (book: Book, role: Role, p: Part, score = 0) => {
+    if (book.memberIds.includes(p.id)) return
+    book.memberIds.push(p.id)
+    bookOf.set(p.id, book)
+    book.score = Math.max(book.score, score)
+    if (role === 'problem') book.problem ??= p
+    else if (role === 'cause') book.cause ? book.moreCauses++ : (book.cause = p)
+    else book.fix ? book.moreFixes++ : (book.fix = p)
+  }
+
+  for (const { n, role } of ranked) if (role === 'problem') join(open(n.id, n.score, n.isSeed), 'problem', part(n, true), n.score)
+  // Causes before fixes: a fix walked off a cause joins the cause's book.
+  for (const want of ['cause', 'fix'] as const) {
+    for (const { n, role } of ranked) {
+      if (role !== want || bookOf.has(n.id)) continue
+      const owner = ownersOf(n.id, role, edges)
+        .map(id => bookOf.get(id))
+        .find(b => b !== undefined)
+      const factProblem = facts[n.id]?.problems[0]
+      const book = owner ?? (factProblem ? books.get(factProblem.id) : undefined) ?? open(factProblem?.id ?? n.id, n.score, n.isSeed)
+      if (!owner && factProblem && !book.problem) join(book, 'problem', part(factProblem, false))
+      join(book, role, part(n, true), n.score)
+      if (n.isSeed) book.isSeed = true
+    }
+  }
+
+  const candidates = new Map<string, FarNode[]>()
+  const byId = new Map(graph.nodes.map(n => [n.id, n]))
+  for (const book of books.values()) {
+    const head = book.problem?.id ?? book.key
+    const f = facts[head]
+    const techs: FarNode[] = []
+    for (const e of edges) {
+      const far = byId.get(e.to)
+      if (!far || !book.memberIds.includes(e.from)) continue
+      if (TECH_EDGES.has(e.type) && TECH_LABELS.has(far.label)) techs.push({ id: far.id, label: far.label, name: far.name })
+      if (e.type === 'INSTANCE_OF' && far.label === 'Pattern') book.patterns.push(far.name)
+    }
+    if (f) {
+      book.isCatalogued = true
+      for (const [role, links] of [['cause', f.causes], ['fix', f.fixes]] as const) {
+        for (const link of links) {
+          const other = bookOf.get(link.id)
+          // A cause/fix the burst shelved alone turns out to be this chain's: fold its book into this one.
+          if (other && other !== book) {
+            if (other.problem) continue
+            books.delete(other.key)
+            for (const [r, p] of [['cause', other.cause], ['fix', other.fix]] as const) if (p) join(book, r, p, other.score)
+            continue
+          }
+          const delivered = byId.get(link.id)
+          join(book, role, delivered ? part(delivered, true) : part(link, false), delivered?.score ?? 0)
+        }
+      }
+      techs.push(...f.techs)
+      for (const p of f.patterns) if (!book.patterns.includes(p.name)) book.patterns.push(p.name)
+      if (f.community) book.community = f.community
+    } else if (f === null) {
+      book.isCatalogued = true
+    }
+    // Only cloud-merged rows carry a community; theirs is the cloud partition's, kept apart from the local one.
+    const cloud = book.community ? undefined : graph.nodes.find(n => book.memberIds.includes(n.id) && n.community)?.community
+    if (cloud) book.community = `cloud_${cloud.id}`
+    book.anchor = anchorOf(f, book.problem?.name)
+    candidates.set(book.key, techs.filter((t, i) => techs.findIndex(u => u.name === t.name) === i))
+  }
+
+  const list = [...books.values()].sort((a, b) => Number(b.isSeed) - Number(a.isSeed) || b.score - a.score)
+  assignTech(list, candidates)
+  return { cases: bookcases(list), books: list }
+}
+
+const GENERAL = 'general'
+/** A shelf holds a community, or a shared Pattern, only when two of its books are in view. */
+const MIN_SHELF = 2
+/** The shelf for books that share neither with another book in view. */
+export const LOOSE = 'loose volumes'
+
+function bookcases(books: Book[]): Bookcase[] {
+  const byTech = new Map<string, Book[]>()
+  for (const b of books) byTech.set(b.tech ?? GENERAL, [...(byTech.get(b.tech ?? GENERAL) ?? []), b])
+  return [...byTech]
+    .sort((a, b) => Number(a[0] === GENERAL) - Number(b[0] === GENERAL))
+    .map(([tech, held]) => ({ tech, code: classMark(tech), shelves: shelves(held), isGeneral: tech === GENERAL }))
+}
+
+/**
+ * Shelves in three tiers: a community with two books in view; then, among the
+ * books left, a Pattern two of them instance (agent-named shapes are often the
+ * truest grouping there is); then the loose volumes. A burst of ten chains
+ * rarely holds two from one community — they are small — so community alone
+ * put nearly every book on one catch-all shelf.
+ */
+function shelves(books: Book[]): Shelf[] {
+  const out: Shelf[] = []
+  const byCommunity = new Map<string, Book[]>()
+  for (const b of books) if (b.community) byCommunity.set(b.community, [...(byCommunity.get(b.community) ?? []), b])
+  for (const [key, held] of byCommunity) {
+    if (held.length >= MIN_SHELF) out.push({ key, name: shelfName(held), number: 0, books: held, isMiscellany: false })
+  }
+  let rest = books.filter(b => !out.some(s => s.books.includes(b)))
+  // The most-shared Pattern first, so a book that instances several joins the biggest group.
+  for (;;) {
+    const count = new Map<string, Book[]>()
+    for (const b of rest) for (const p of new Set(b.patterns)) count.set(p, [...(count.get(p) ?? []), b])
+    const best = [...count].sort((a, b) => b[1].length - a[1].length || a[0].localeCompare(b[0]))[0]
+    if (!best || best[1].length < MIN_SHELF) break
+    out.push({ key: `pattern:${best[0]}`, name: patternTitle(best[0]), number: 0, books: best[1], isMiscellany: false })
+    rest = rest.filter(b => !best[1].includes(b))
+  }
+  if (rest.length > 0) out.push({ key: 'loose', name: LOOSE, number: 0, books: rest, isMiscellany: true })
+  out.forEach((s, i) => (s.number = i + 1))
+  return out
+}
+
+/**
+ * A community has no name of its own (the local partition's label is null), so
+ * the shelf is named from what its books share: the Pattern most of its books
+ * are INSTANCE_OF — the graph's own generalisation of what those problems have
+ * in common — else its strongest problem, the shelf's exemplar. Never the cloud
+ * community's theme label: those can describe other members entirely (#43
+ * "Canvas zoom/scroll…" held SQLite busy_timeout problems).
+ */
+export function shelfName(books: Book[]): string {
+  const count = new Map<string, number>()
+  for (const b of books) for (const p of new Set(b.patterns)) count.set(p, (count.get(p) ?? 0) + 1)
+  if (count.size > 0) return patternTitle([...count].reduce((a, b) => (b[1] > a[1] ? b : a))[0])
+  const exemplar = books.find(b => b.problem) ?? books[0]!
+  return (exemplar.problem ?? exemplar.fix ?? exemplar.cause)!.name
+}
+
+/** `pattern ×64 (exemplar): harvestInlineTags is … @ apps/daemon/src/engine.ts:1036` → the exemplar's words. */
+export function patternTitle(name: string): string {
+  return name
+    .replace(/^pattern\s*[×x]\d+\s*\(exemplar\):\s*/i, '')
+    .replace(/\s+@\s+\S+$/, '')
+    .trim()
+}
+
+/** Three letters of the tech, scope dropped: chokidar → CHO, @hono/zod-validator → ZOD. */
+export function classMark(tech: string): string {
+  const bare = tech.replace(/^@[^/]+\//, '').replace(/[^A-Za-z]/g, '')
+  return (bare.slice(0, 3) || 'GEN').toUpperCase()
+}
+
+/** A book's call number: class mark, shelf, place on the shelf (CHO 1.2). */
+export function callNumber(catalog: Catalog, book: Book): string {
+  for (const c of catalog.cases)
+    for (const s of c.shelves) {
+      const at = s.books.indexOf(book)
+      if (at >= 0) return `${c.code} ${s.number}.${at + 1}`
+    }
+  return ''
+}
+
+export function placeOf(catalog: Catalog, book: Book): { bookcase: Bookcase; shelf: Shelf } | undefined {
+  for (const bookcase of catalog.cases) for (const shelf of bookcase.shelves) if (shelf.books.includes(book)) return { bookcase, shelf }
+  return undefined
+}
+
+/** The book holding a node, if any. */
+export function bookHolding(catalog: Catalog, id: string | undefined): Book | undefined {
+  return id ? catalog.books.find(b => b.key === id || b.memberIds.includes(id)) : undefined
+}
+
+/**
+ * The ids worth an `errata_neighbors` call, strongest chain first: each book's
+ * problem (or its lone cause/fix) whose facts have not been asked yet.
+ */
+export function enrichTargets(catalog: Catalog, facts: Record<string, ChainFacts | null>, max: number): string[] {
+  const out: string[] = []
+  for (const b of catalog.books) {
+    const head = b.problem?.id ?? b.key
+    if (!(head in facts) && !out.includes(head)) out.push(head)
+    if (out.length >= max) break
+  }
+  return out
+}
+
+type NeighborsJson = {
+  found?: boolean
+  node?: { id?: string; label?: string; name?: string; community?: unknown }
+  out?: { type?: string; to?: Partial<FarNode> }[]
+  in?: { type?: string; from?: Partial<FarNode> }[]
+  nearby?: { id?: string; label?: string; name?: string; via?: { edgeType?: string; parentId?: string; forward?: boolean } }[]
+}
+
+const far = (n: Partial<FarNode> | undefined): FarNode | undefined =>
+  n?.id && n.label ? { id: n.id, label: n.label, name: n.name ?? n.id, ...(typeof n.community === 'string' ? { community: n.community } : {}) } : undefined
+
+/**
+ * An `errata_neighbors` answer → the facts that bind and place a chain. The
+ * collective fallback (a cloud id not in the local store) answers with
+ * `nearby` rows instead of typed out/in lists; their `via` is read the same way.
+ * `null` = the node was not found (asked; nothing to add).
+ */
+export function parseNeighbors(texts: string[]): ChainFacts | null | undefined {
+  for (const text of texts) {
+    let json: NeighborsJson
+    try {
+      json = JSON.parse(text) as NeighborsJson
+    } catch {
+      continue
+    }
+    if (json.found === false) return null
+    if (!json.node?.id) continue
+    const id = json.node.id
+    const out: { type: string; to: FarNode }[] = []
+    const inn: { type: string; from: FarNode }[] = []
+    for (const e of json.out ?? []) {
+      const to = far(e.to)
+      if (e.type && to) out.push({ type: e.type, to })
+    }
+    for (const e of json.in ?? []) {
+      const from = far(e.from)
+      if (e.type && from) inn.push({ type: e.type, from })
+    }
+    for (const n of json.nearby ?? []) {
+      const node = far(n)
+      if (!node || !n.via?.edgeType || n.via.parentId !== id) continue
+      if (n.via.forward === false) inn.push({ type: n.via.edgeType, from: node })
+      else out.push({ type: n.via.edgeType, to: node })
+    }
+    const outOf = (types: Set<string>, labels?: Set<string>) => out.filter(e => types.has(e.type) && (!labels || labels.has(e.to.label))).map(e => e.to)
+    const inOf = (types: Set<string>) => inn.filter(e => types.has(e.type)).map(e => e.from)
+    const problemsOf = [...inOf(CAUSE_EDGES), ...inOf(FIX_EDGES), ...outOf(CAUSES_EDGES), ...outOf(FIXES_EDGES)].filter(n => roleOf(n.label) === 'problem')
+    return {
+      id,
+      label: json.node.label ?? 'Node',
+      name: json.node.name ?? id,
+      community: typeof json.node.community === 'string' ? json.node.community : null,
+      causes: [...outOf(CAUSE_EDGES), ...inOf(CAUSES_EDGES)].filter(n => roleOf(n.label) === 'cause'),
+      fixes: [...outOf(FIX_EDGES), ...inOf(FIXES_EDGES)].filter(n => roleOf(n.label) === 'fix'),
+      problems: problemsOf,
+      techs: outOf(TECH_EDGES, TECH_LABELS),
+      patterns: outOf(new Set(['INSTANCE_OF']), new Set(['Pattern'])),
+      anchors: outOf(new Set(['ANCHORED_AT'])).map(n => n.name),
+    }
+  }
+  return undefined
+}