tldr-experts 0.3.0 → 0.4.0

package/dist/hooks/{chunk-t8tdv11p.js → chunk-7y2dq0pj.js}

@@ -1,6 +1,6 @@
 import {
   toolInput
-} from "./chunk-1zwcxd3f.js";
+} from "./chunk-tzzwddct.js";
 
 // src/hooks/lib/wouldBe.ts
 import { existsSync, readFileSync } from "node:fs";

package/dist/hooks/chunk-9zsqxr6y.js

@@ -0,0 +1,213 @@
+import {
+  hasSrcMarker,
+  parseSrcToken,
+  resolveSrc
+} from "./chunk-m3mewgnw.js";
+
+// src/core/text/handoff.ts
+var HANDOFF_SECTIONS = ["Findings", "Decisions", "Unknowns", "Evidence ledger"];
+var H2_RE = /^##\s+(.+?)\s*$/;
+var BULLET_RE = /^(?: {0,3}-|\d{1,9}[.)])\s+(\S.*)$/;
+var CONTINUATION_RE = /^\s+\S/;
+function parseHandoff(text) {
+  const lines = text.split(`
+`);
+  const sections = [];
+  const headings = [];
+  let current = null;
+  let pending = null;
+  const flushBullet = () => {
+    if (pending === null)
+      return;
+    if (current !== null) {
+      const joined = pending.parts.join(" ");
+      current.bullets.push({ line: pending.line, text: joined, token: parseSrcToken(joined) });
+    }
+    pending = null;
+  };
+  const flush = () => {
+    flushBullet();
+    if (current !== null)
+      sections.push(current);
+    current = null;
+  };
+  for (let i = 0;i < lines.length; i++) {
+    const line = lines[i] ?? "";
+    const heading = H2_RE.exec(line);
+    if (heading !== null && heading[1] !== undefined) {
+      flush();
+      headings.push(heading[1]);
+      current = { name: heading[1], headingLine: i + 1, bullets: [] };
+      continue;
+    }
+    if (line.startsWith("# ")) {
+      flush();
+      continue;
+    }
+    if (current === null)
+      continue;
+    const bullet = BULLET_RE.exec(line);
+    if (bullet !== null && bullet[1] !== undefined) {
+      flushBullet();
+      pending = { line: i + 1, parts: [bullet[1]] };
+      continue;
+    }
+    if (pending !== null && CONTINUATION_RE.test(line)) {
+      pending.parts.push(line.trim());
+      continue;
+    }
+    flushBullet();
+  }
+  flush();
+  return { sections, headings };
+}
+function parseItems(text) {
+  const items = [];
+  let section = "";
+  let pending = null;
+  const flush = () => {
+    if (pending === null)
+      return;
+    const joined = pending.parts.join(" ");
+    items.push({ line: pending.line, text: joined, section: pending.section, token: parseSrcToken(joined) });
+    pending = null;
+  };
+  const lines = text.split(`
+`);
+  for (let i = 0;i < lines.length; i++) {
+    const line = lines[i] ?? "";
+    const heading = H2_RE.exec(line);
+    if (heading !== null && heading[1] !== undefined) {
+      flush();
+      section = heading[1];
+      continue;
+    }
+    const bullet = BULLET_RE.exec(line);
+    if (bullet !== null && bullet[1] !== undefined) {
+      flush();
+      pending = { line: i + 1, parts: [bullet[1]], section };
+      continue;
+    }
+    if (pending !== null && CONTINUATION_RE.test(line)) {
+      pending.parts.push(line.trim());
+      continue;
+    }
+    flush();
+  }
+  flush();
+  return items;
+}
+function isHandoff(text) {
+  return missingSections(parseHandoff(text)).length === 0;
+}
+function missingSections(handoff, required = HANDOFF_SECTIONS) {
+  const present = handoff.headings;
+  const missing = [];
+  let cursor = 0;
+  for (const name of required) {
+    const at = present.indexOf(name, cursor);
+    if (at === -1)
+      missing.push(name);
+    else
+      cursor = at + 1;
+  }
+  return missing;
+}
+var MAX_BULLETS = 200;
+function validateSections(handoff, required, ctx, lineOffset = 0) {
+  const emptySections = [];
+  const unsourced = [];
+  const malformed = [];
+  const unresolved = [];
+  const unverified = [];
+  let bulletCount = 0;
+  const wanted = new Set(required);
+  for (const section of handoff.sections) {
+    if (!wanted.has(section.name))
+      continue;
+    if (section.bullets.length === 0) {
+      emptySections.push({ name: section.name, line: section.headingLine + lineOffset });
+    }
+    for (const bullet of section.bullets) {
+      bulletCount++;
+      const line = bullet.line + lineOffset;
+      if (bullet.token === null) {
+        if (hasSrcMarker(bullet.text)) {
+          malformed.push({
+            line,
+            message: "malformed citation — the `[src: …]` token must be the last thing on the line " + "(closing quotes, brackets and a final `.` are allowed after it, words are not)"
+          });
+        } else {
+          unsourced.push(line);
+        }
+        continue;
+      }
+      for (const error of bullet.token.errors) {
+        unresolved.push({ line, message: `[src: ${error.raw}] — ${error.message}` });
+      }
+      const claim = bullet.text.replace(bullet.token.raw, " ").trim();
+      for (const ref of bullet.token.refs) {
+        const resolution = resolveSrc(ref, ctx, section.name, claim);
+        const issue = { line, message: `[src: ${ref.raw}] — ${resolution.message ?? "unresolvable"}` };
+        if (resolution.outcome === "refused")
+          unresolved.push(issue);
+        else if (resolution.outcome === "unverified")
+          unverified.push(issue);
+      }
+    }
+  }
+  return { emptySections, unsourced, malformed, unresolved, unverified, bulletCount };
+}
+function validateHandoff(text, ctx) {
+  const handoff = parseHandoff(text);
+  const missing = missingSections(handoff);
+  const report = validateSections(handoff, HANDOFF_SECTIONS, ctx);
+  const unresolved = [...report.unresolved];
+  if (report.bulletCount > MAX_BULLETS) {
+    unresolved.push({ line: 0, message: `${report.bulletCount} bullets exceeds the ${MAX_BULLETS} cap` });
+  }
+  return {
+    ok: missing.length === 0 && report.emptySections.length === 0 && report.unsourced.length === 0 && report.malformed.length === 0 && unresolved.length === 0,
+    missingSections: missing,
+    emptySections: report.emptySections,
+    unsourced: report.unsourced,
+    malformed: report.malformed,
+    unresolved,
+    unverified: report.unverified,
+    bulletCount: report.bulletCount
+  };
+}
+function validateCitations(text, ctx) {
+  const malformed = [];
+  const unresolved = [];
+  const unverified = [];
+  let cited = 0;
+  for (const item of parseItems(text)) {
+    if (item.token === null) {
+      if (!hasSrcMarker(item.text))
+        continue;
+      cited++;
+      malformed.push({
+        line: item.line,
+        message: "malformed citation — the `[src: …]` token must be the last thing on the line " + "(closing quotes, brackets and a final `.` are allowed after it, words are not)"
+      });
+      continue;
+    }
+    cited++;
+    for (const error of item.token.errors) {
+      unresolved.push({ line: item.line, message: `[src: ${error.raw}] — ${error.message}` });
+    }
+    const claim = item.text.replace(item.token.raw, " ").trim();
+    for (const ref of item.token.refs) {
+      const resolution = resolveSrc(ref, ctx, item.section, claim);
+      const issue = { line: item.line, message: `[src: ${ref.raw}] — ${resolution.message ?? "unresolvable"}` };
+      if (resolution.outcome === "refused")
+        unresolved.push(issue);
+      else if (resolution.outcome === "unverified")
+        unverified.push(issue);
+    }
+  }
+  return { malformed, unresolved, unverified, cited };
+}
+
+export { parseHandoff, isHandoff, validateHandoff, validateCitations };

package/dist/hooks/{chunk-a8p2rc94.js → chunk-b8kxzna2.js}

@@ -1,6 +1,6 @@
 import {
   runtime
-} from "./chunk-p274ckxv.js";
+} from "./chunk-sq44k6g2.js";
 
 // src/core/hooks/passthrough.ts
 async function readStdin() {

package/dist/hooks/{chunk-j234zf0t.js → chunk-c6t5nx0r.js}

@@ -1,170 +1,7 @@
-import {
-  parseSrcToken
-} from "./chunk-g395gk7e.js";
 import {
   PROJECT_FRAMEWORK_DIR,
   PROJECT_WORK_DIR
-} from "./chunk-p274ckxv.js";
-
-// src/core/text/questions.ts
-var REQUIRED_METADATA_KEYS = ["id", "status", "area", "asked_by", "asked_at"];
-var HEADING_RE = /^##\s+(Q\d{1,6})\s+·\s+(.+?)\s*$/;
-var METADATA_RE = /^<!--\s*(.*?)\s*-->$/;
-var WHY_RE = /^Why asked:\s*(.*)$/;
-var OPTION_RE = /^-\s+([A-E])\)\s*(.*)$/;
-var ANSWER_RE = /^\[Answer\]:[ \t]*(\S.*)$/;
-var ANSWER_SLOT_RE = /^\[Answer\]:/;
-var FOOTER_KEYS = ["answered_by", "answered_at", "fact"];
-function parseQuestions(text) {
-  const trailingNewline = text.endsWith(`
-`);
-  const body = trailingNewline ? text.slice(0, -1) : text;
-  const lines = body === "" ? [] : body.split(`
-`);
-  const preamble = [];
-  const blocks = [];
-  let pending = null;
-  const close = () => {
-    if (pending === null)
-      return;
-    blocks.push(buildBlock(pending.start + 1, pending.lines));
-    pending = null;
-  };
-  for (let i = 0;i < lines.length; i++) {
-    const line = lines[i] ?? "";
-    if (HEADING_RE.test(line)) {
-      close();
-      pending = { start: i, lines: [line] };
-      continue;
-    }
-    if (pending === null)
-      preamble.push(line);
-    else
-      pending.lines.push(line);
-  }
-  close();
-  return { preamble, blocks, trailingNewline };
-}
-function buildBlock(startLine, lines) {
-  const heading = HEADING_RE.exec(lines[0] ?? "");
-  const id = heading?.[1] ?? "";
-  const title = heading?.[2] ?? "";
-  let metadata = null;
-  let metadataIndex = -1;
-  let whyAsked = null;
-  let whySrc = null;
-  const options = [];
-  let answer = "";
-  let answerIndex = -1;
-  let footer = null;
-  for (let i = 1;i < lines.length; i++) {
-    const line = lines[i] ?? "";
-    const comment = METADATA_RE.exec(line);
-    if (comment !== null && comment[1] !== undefined) {
-      const pairs = parsePipeComment(comment[1]);
-      if (metadata === null && pairs.some(([k]) => k === "id")) {
-        metadata = toMetadata(pairs);
-        metadataIndex = i;
-      } else if (footer === null && pairs.some(([k]) => k === "answered_by")) {
-        footer = toFooter(pairs);
-      }
-      continue;
-    }
-    const why = WHY_RE.exec(line);
-    if (why !== null && whyAsked === null) {
-      whyAsked = why[1] ?? "";
-      whySrc = parseSrcToken(line);
-      continue;
-    }
-    const option = OPTION_RE.exec(line);
-    if (option !== null && option[1] !== undefined && option[2] !== undefined) {
-      options.push({ letter: option[1], text: option[2] });
-      continue;
-    }
-    if (ANSWER_SLOT_RE.test(line) && answerIndex === -1) {
-      answerIndex = i;
-      const captured = ANSWER_RE.exec(line);
-      answer = (captured?.[1] ?? "").trim();
-    }
-  }
-  return {
-    id,
-    title,
-    metadata,
-    metadataIndex,
-    whyAsked,
-    whySrc,
-    options,
-    answer,
-    answerIndex,
-    footer,
-    startLine,
-    lines: [...lines]
-  };
-}
-function parsePipeComment(inner) {
-  const pairs = [];
-  for (const part of inner.split("|")) {
-    const colon = part.indexOf(":");
-    if (colon === -1)
-      continue;
-    pairs.push([part.slice(0, colon).trim(), part.slice(colon + 1).trim()]);
-  }
-  return pairs;
-}
-function toMetadata(pairs) {
-  const map = new Map(pairs);
-  const extra = pairs.filter(([k]) => !REQUIRED_METADATA_KEYS.includes(k));
-  return {
-    id: map.get("id") ?? "",
-    status: map.get("status") ?? "",
-    area: map.get("area") ?? "",
-    asked_by: map.get("asked_by") ?? "",
-    asked_at: map.get("asked_at") ?? "",
-    extra
-  };
-}
-function toFooter(pairs) {
-  const map = new Map(pairs);
-  return {
-    answered_by: map.get("answered_by") ?? "",
-    answered_at: map.get("answered_at") ?? "",
-    fact: map.get("fact") ?? ""
-  };
-}
-function serializeQuestions(doc) {
-  const out = [...doc.preamble];
-  for (const block of doc.blocks)
-    out.push(...block.lines);
-  const text = out.join(`
-`);
-  return doc.trailingNewline ? `${text}
-` : text;
-}
-function detectAnswered(blocks) {
-  return blocks.filter((b) => b.metadata?.status === "open" && b.answer !== "");
-}
-function openBlocks(blocks) {
-  return blocks.filter((b) => b.metadata?.status === "open");
-}
-function recordAnswer(block, footer) {
-  const lines = [...block.lines];
-  if (block.metadataIndex >= 0) {
-    const line = lines[block.metadataIndex] ?? "";
-    lines[block.metadataIndex] = line.replace(/(\|\s*status:\s*)open(\s*\|)/, "$1answered$2");
-  }
-  const footerLine = `<!-- ${FOOTER_KEYS.map((k) => `${k}: ${footer[k]}`).join(" | ")} -->`;
-  const insertAt = block.answerIndex >= 0 ? block.answerIndex + 1 : lines.length;
-  lines.splice(insertAt, 0, footerLine);
-  const metadata = block.metadata === null ? null : { ...block.metadata, status: "answered" };
-  return { ...block, lines, metadata, footer };
-}
-function replaceBlock(doc, block) {
-  return {
-    ...doc,
-    blocks: doc.blocks.map((b) => b.id === block.id ? block : b)
-  };
-}
+} from "./chunk-sq44k6g2.js";
 
 // src/core/lock/workspaceLock.ts
 import { existsSync as existsSync2, mkdirSync as mkdirSync2, openSync, readFileSync as readFileSync2, rmSync as rmSync2, writeSync, closeSync } from "node:fs";
@@ -290,6 +127,8 @@ function withWorkspaceLock(root, fn, timeoutMs = WORKSPACE_LOCK_TIMEOUT_MS) {
 // src/core/facts/emitFactsYaml.ts
 var PLAIN_SAFE = /^[A-Za-z][A-Za-z0-9_./-]*$/;
 var YAML_KEYWORDS = new Set(["true", "false", "null", "yes", "no", "on", "off", "~"]);
+var LONE_HIGH_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])/g;
+var LONE_LOW_SURROGATE = /(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g;
 function yamlScalar(value) {
   if (value === null)
     return "null";
@@ -297,7 +136,7 @@ function yamlScalar(value) {
     return String(value);
   if (PLAIN_SAFE.test(value) && !YAML_KEYWORDS.has(value.toLowerCase()))
     return value;
-  return `"${value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"")}"`;
+  return JSON.stringify(value.replace(LONE_HIGH_SURROGATE, "�").replace(LONE_LOW_SURROGATE, "�"));
 }
 function inlineList(values) {
   return `[${values.map((v) => yamlScalar(v)).join(", ")}]`;
@@ -315,6 +154,8 @@ function emitFact(fact, indent = "  ") {
     `${inner}supersedes: ${yamlScalar(fact.supersedes)}`,
     `${inner}superseded_by: ${yamlScalar(fact.superseded_by)}`
   ];
+  if (fact.truncated === true)
+    lines.push(`${inner}truncated: true`);
   if (fact.retired === null) {
     lines.push(`${inner}retired: null`);
   } else {
@@ -336,4 +177,34 @@ function emitFactsYaml(file, header) {
 `;
 }
 
-export { readLock, isAlive, workspaceRootOfRunDir, workspaceRootOfFactsPath, withWorkspaceLock, yamlScalar, emitFactsYaml, parseQuestions, serializeQuestions, detectAnswered, openBlocks, recordAnswer, replaceBlock };
+// src/core/fs/writeAtomic.ts
+import { copyFileSync, existsSync as existsSync3, mkdirSync as mkdirSync3, renameSync, rmSync as rmSync3, writeFileSync as writeFileSync2 } from "node:fs";
+import { dirname as dirname3 } from "node:path";
+var BACKUP_SUFFIX = ".bak";
+function backupPathFor(path) {
+  return `${path}${BACKUP_SUFFIX}`;
+}
+function writeAtomic(path, content) {
+  const temp = `${path}.tmp-${String(process.pid)}`;
+  mkdirSync3(dirname3(path), { recursive: true });
+  try {
+    writeFileSync2(temp, content, "utf8");
+    keepPreviousVersion(path);
+    renameSync(temp, path);
+  } catch (error) {
+    try {
+      if (existsSync3(temp))
+        rmSync3(temp, { force: true });
+    } catch {}
+    throw error;
+  }
+}
+function keepPreviousVersion(path) {
+  if (!existsSync3(path))
+    return;
+  try {
+    copyFileSync(path, backupPathFor(path));
+  } catch {}
+}
+
+export { readLock, isAlive, workspaceRootOfRunDir, workspaceRootOfFactsPath, withWorkspaceLock, yamlScalar, emitFactsYaml, backupPathFor, writeAtomic };

package/dist/hooks/{chunk-g395gk7e.js → chunk-m3mewgnw.js}

@@ -1,7 +1,7 @@
 import {
   PROJECT_FRAMEWORK_DIR,
   parseYaml
-} from "./chunk-p274ckxv.js";
+} from "./chunk-sq44k6g2.js";
 
 // src/core/text/srcToken.ts
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
@@ -164,16 +164,20 @@ function resolveSrc(ref, ctx, section, claim = "") {
         return refused(`unknown repo \`${ref.repo}\` (not in workspace.yml)`);
       }
       const bases = fileBases(ref, ctx);
+      let short = null;
       for (const base of bases) {
         if (!existsSync(base.abs) || !statSync(base.abs).isFile())
           continue;
         const lines = countLines(base.abs);
         const highest = ref.endLine ?? ref.startLine;
         if (highest > lines) {
-          return refused(`${ref.path} has ${lines} line(s); cited line ${highest}`, base.abs);
+          short ??= refused(`${ref.path} has ${lines} line(s); cited line ${highest}`, base.abs);
+          continue;
         }
         return { ok: true, outcome: "ok", resolved: base.abs };
       }
+      if (short !== null)
+        return short;
       const tried = bases.map((b) => b.label).join(", ");
       return refused(`no such file: ${ref.path} — tried ${tried}`, bases[0]?.abs);
     }
@@ -270,26 +274,41 @@ function fileBases(ref, ctx) {
     return [{ label: "the absolute path as written", abs: normalize(ref.path) }];
   }
   if (ref.repo !== null) {
-    const rel = ctx.repos.get(ref.repo) ?? "";
-    return [{ label: repoLabel(ref.repo, rel), abs: normalize(join(ctx.root, rel, ref.path)) }];
+    const rel2 = ctx.repos.get(ref.repo) ?? "";
+    return [
+      ...epicBases(ctx, ref.repo, ref.path),
+      { label: repoLabel(ref.repo, rel2), abs: normalize(join(ctx.root, rel2, ref.path)) }
+    ];
   }
-  const bases = [
-    { label: "workspace root", abs: normalize(join(ctx.root, ref.path)) }
-  ];
+  const bases = [];
+  const slash = ref.path.indexOf("/");
+  const named = slash > 0 ? ref.path.slice(0, slash) : "";
+  const rel = named === "" ? undefined : ctx.repos.get(named);
+  if (rel !== undefined)
+    bases.push(...epicBases(ctx, named, ref.path.slice(slash + 1)));
+  bases.push({ label: "workspace root", abs: normalize(join(ctx.root, ref.path)) });
   const runDir = ctx.runDir ?? null;
   if (runDir !== null && runDir !== "") {
     bases.push({ label: `run dir ${displayPath(ctx.root, runDir)}`, abs: normalize(join(runDir, ref.path)) });
   }
-  const slash = ref.path.indexOf("/");
-  if (slash > 0) {
-    const name = ref.path.slice(0, slash);
-    const rel = ctx.repos.get(name);
-    if (rel !== undefined) {
-      bases.push({
-        label: repoLabel(name, rel),
-        abs: normalize(join(ctx.root, rel, ref.path.slice(slash + 1)))
-      });
-    }
+  if (rel !== undefined) {
+    bases.push({
+      label: repoLabel(named, rel),
+      abs: normalize(join(ctx.root, rel, ref.path.slice(slash + 1)))
+    });
+  }
+  return bases;
+}
+function epicBases(ctx, repo, path) {
+  const trees = ctx.epicWorktrees ?? [];
+  const bases = [];
+  for (const tree of trees) {
+    if (tree.repo !== repo)
+      continue;
+    bases.push({
+      label: `epic worktree ${displayPath(ctx.root, tree.dir)}`,
+      abs: normalize(join(tree.dir, path))
+    });
   }
   return bases;
 }