tldr-experts 0.5.0 → 0.6.0

package/dist/hooks/{chunk-a6rpj2cp.js → chunk-9w64mxdh.js}

@@ -7708,6 +7708,13 @@ var SRC_RULES = [
     bad: "- no retention policy is recorded [src: absent:]",
     good: "- no retention policy is recorded [src: absent:docs/retention.md]"
   },
+  {
+    id: "absent-needle",
+    rule: "`absent:<path>#<needle>` carries the words you searched for — `#` with nothing after it " + "says you searched for nothing",
+    enforcedBy: ["absent:", "#"],
+    bad: "- no retention policy is recorded [src: absent:docs/retention.md#]",
+    good: "- no retention policy is recorded [src: absent:docs/retention.md#retention]"
+  },
   {
     id: "aidlc-shape",
     rule: "an `aidlc` source is `aidlc:<file>:<line>` or `aidlc:<file>#Q<n>`",
@@ -7814,10 +7821,15 @@ function classifySrc(src, repos) {
   if (raw.startsWith("aidlc:"))
     return parseAidlcSrc(raw);
   if (raw.startsWith("absent:")) {
-    const path = raw.slice("absent:".length);
+    const rest = raw.slice("absent:".length);
+    const hash = rest.indexOf("#");
+    const path = hash === -1 ? rest : rest.slice(0, hash);
+    const needle = hash === -1 ? null : rest.slice(hash + 1);
     if (path === "")
       return refuse(raw, "absent-path");
-    return { kind: "absent", raw, path };
+    if (needle !== null && needle.trim() === "")
+      return refuse(raw, "absent-needle");
+    return { kind: "absent", raw, path, needle };
   }
   if (ANSWER_RE.test(raw))
     return { kind: "answer", raw, q: raw };
@@ -7894,13 +7906,16 @@ function refused(message, resolved) {
 function unverified(message) {
   return { ok: true, outcome: "unverified", message };
 }
+function noted(message) {
+  return { ok: true, outcome: "noted", message };
+}
 function resolveSrc(ref, ctx, section, claim = "") {
   switch (ref.kind) {
     case "file": {
       if (ref.repo !== null && !ctx.repos.has(ref.repo)) {
         return refused(`unknown repo \`${ref.repo}\` (not in workspace.yml)`);
       }
-      const bases = fileBases(ref, ctx);
+      const bases = pathBases(ref.repo, ref.path, ctx);
       let short = null;
       for (const base of bases) {
         if (!existsSync3(base.abs) || !statSync3(base.abs).isFile())
@@ -7939,7 +7954,7 @@ function resolveSrc(ref, ctx, section, claim = "") {
     case "doc":
       return resolveDoc(ref.url, ctx);
     case "absent":
-      return resolveAbsent(ref.path, ctx, section, claim);
+      return resolveAbsent(ref, ctx, section, claim);
     case "aidlc":
       return OK;
   }
@@ -7993,45 +8008,134 @@ function resolveDoc(url, ctx) {
     return OK;
   return unverified(`${url} is not fetched offline and no input, map or knowledge file cites it`);
 }
-function resolveAbsent(path, ctx, section, claim) {
+function resolveAbsent(ref, ctx, section, claim) {
+  const { path, needle } = ref;
   if (section !== "Unknowns" && claim !== "" && !isNegativeClaim(claim)) {
     return refused(`absent:${path} sources a positive claim — an absence can only support a negative one ` + "(say what is NOT there: `no`, `not`, `never`, `none`, `absent`), or move it under Unknowns");
   }
-  const abs = isAbsolute2(path) ? normalize(path) : normalize(join3(ctx.root, path));
-  if (!existsSync3(abs))
+  const found = firstExisting(absentBases(path, ctx));
+  if (found === null)
+    return OK;
+  if (needle !== null)
+    return searchForNeedle(found, needle, path);
+  const held = whatIsThere(found);
+  if (held === null)
+    return OK;
+  return noted(`${path} EXISTS (${held}) — "it is not in there" is a claim about its CONTENT, unchecked here. ` + `Cite \`absent:${path}#<what you searched for>\` to have it checked, or cite the line that proves it.`);
+}
+var NEEDLE_MAX_BYTES = 512 * 1024;
+var EMPTY_PROBE_MAX_BYTES = 64 * 1024;
+function searchForNeedle(abs, needle, path) {
+  let stat;
+  try {
+    stat = statSync3(abs);
+  } catch {
     return OK;
-  return unverified(`${path} EXISTS — "found nothing in it" is a claim about its contents, unchecked here`);
+  }
+  if (stat.isDirectory()) {
+    return refused(`absent:${path}#${needle} searches a DIRECTORY — a needle is searched in one file. ` + `Cite the file you read (\`absent:${path}/<file>#${needle}\`), or drop the needle.`);
+  }
+  if (stat.size > NEEDLE_MAX_BYTES) {
+    return noted(`${path} is ${String(stat.size)} bytes — too large to search here for \`${needle}\``);
+  }
+  let text;
+  try {
+    text = readFileSync2(abs, "utf8");
+  } catch {
+    return noted(`${path} could not be read here to search for \`${needle}\``);
+  }
+  const wanted = needle.toLowerCase();
+  const lines = text.split(`
+`);
+  for (let i = 0;i < lines.length; i++) {
+    if ((lines[i] ?? "").toLowerCase().includes(wanted)) {
+      return refused(`\`${needle}\` IS at ${path}:${String(i + 1)} — that is a presence, not an absence`, abs);
+    }
+  }
+  return OK;
+}
+function whatIsThere(abs) {
+  let stat;
+  try {
+    stat = statSync3(abs);
+  } catch {
+    return null;
+  }
+  if (stat.isDirectory()) {
+    let entries;
+    try {
+      entries = readdirSync2(abs);
+    } catch {
+      return "a directory this check could not read";
+    }
+    if (entries.length === 0)
+      return null;
+    return `${String(entries.length)} entr${entries.length === 1 ? "y" : "ies"}`;
+  }
+  if (!stat.isFile())
+    return "a path that is neither a file nor a directory";
+  if (stat.size === 0)
+    return null;
+  if (stat.size > EMPTY_PROBE_MAX_BYTES)
+    return `${String(stat.size)} bytes`;
+  let text;
+  try {
+    text = readFileSync2(abs, "utf8");
+  } catch {
+    return `${String(stat.size)} bytes`;
+  }
+  if (text.trim() === "")
+    return null;
+  const lines = text.split(`
+`).length;
+  return `${String(lines)} line${lines === 1 ? "" : "s"}`;
+}
+function absentBases(path, ctx) {
+  const colon = path.indexOf(":");
+  if (colon > 0) {
+    const repo = path.slice(0, colon);
+    if (ctx.repos.has(repo))
+      return pathBases(repo, path.slice(colon + 1), ctx);
+  }
+  return pathBases(null, path, ctx);
+}
+function firstExisting(bases) {
+  for (const base of bases) {
+    if (existsSync3(base.abs))
+      return base.abs;
+  }
+  return null;
 }
 var NEGATIVE_RE = /\b(no|not|none|never|nothing|nobody|nowhere|neither|nor|absent|absence|missing|lacks?|lacking|without|unknown|undocumented|unrecorded|untracked|zero|n\/a)\b|n't\b/i;
 function isNegativeClaim(text) {
   return NEGATIVE_RE.test(text);
 }
-function fileBases(ref, ctx) {
-  if (isAbsolute2(ref.path)) {
-    return [{ label: "the absolute path as written", abs: normalize(ref.path) }];
+function pathBases(repo, path, ctx) {
+  if (isAbsolute2(path)) {
+    return [{ label: "the absolute path as written", abs: normalize(path) }];
   }
-  if (ref.repo !== null) {
-    const rel2 = ctx.repos.get(ref.repo) ?? "";
+  if (repo !== null) {
+    const rel2 = ctx.repos.get(repo) ?? "";
     return [
-      ...epicBases(ctx, ref.repo, ref.path),
-      { label: repoLabel(ref.repo, rel2), abs: normalize(join3(ctx.root, rel2, ref.path)) }
+      ...epicBases(ctx, repo, path),
+      { label: repoLabel(repo, rel2), abs: normalize(join3(ctx.root, rel2, path)) }
     ];
   }
   const bases = [];
-  const slash = ref.path.indexOf("/");
-  const named = slash > 0 ? ref.path.slice(0, slash) : "";
+  const slash = path.indexOf("/");
+  const named = slash > 0 ? 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(join3(ctx.root, ref.path)) });
+    bases.push(...epicBases(ctx, named, path.slice(slash + 1)));
+  bases.push({ label: "workspace root", abs: normalize(join3(ctx.root, path)) });
   const runDir = ctx.runDir ?? null;
   if (runDir !== null && runDir !== "") {
-    bases.push({ label: `run dir ${displayPath(ctx.root, runDir)}`, abs: normalize(join3(runDir, ref.path)) });
+    bases.push({ label: `run dir ${displayPath(ctx.root, runDir)}`, abs: normalize(join3(runDir, path)) });
   }
   if (rel !== undefined) {
     bases.push({
       label: repoLabel(named, rel),
-      abs: normalize(join3(ctx.root, rel, ref.path.slice(slash + 1)))
+      abs: normalize(join3(ctx.root, rel, path.slice(slash + 1)))
     });
   }
   return bases;
@@ -8256,4 +8360,223 @@ function readCapped(path) {
   }
 }
 
-export { runtime, parseYaml, parseYamlRepairing, STAGES_DIR, TEMPLATES_DIR, PROJECT_FRAMEWORK_DIR, PROJECT_WORK_DIR, readableSource, SRC_PATTERNS, srcRule, diagnoseSrcToken, parseSrcToken, hasSrcMarker, classifySrc, resolveSrc, locateWork, findWorkspaceRoot, loadWorkspace, toSrcContext, repoPath, factsPath, stageYamlPath, listRunDirs };
+// 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 BULLET_RULE = `every list item under ${HANDOFF_SECTIONS.join(" / ")} ends with a \`[src: …]\` token`;
+var EMPTY_SECTION_RULE = `each of ${HANDOFF_SECTIONS.join(" / ")} holds at least one list item — prose alone is not a claim`;
+var MAX_BULLETS = 200;
+var BULLET_CAP_RULE = `a handoff carries at most ${String(MAX_BULLETS)} list items across the four sections — ` + "beyond that cap it is a document, not a handoff";
+function citationIssue(line, text) {
+  const failure = diagnoseSrcToken(text);
+  if (failure === null) {
+    return { line, message: "malformed citation — the `[src: …]` token could not be read" };
+  }
+  return { line, message: `malformed citation — ${failure.rule.rule}`, rule: failure.rule.id };
+}
+function validateSections(handoff, required, ctx, lineOffset = 0) {
+  const emptySections = [];
+  const unsourced = [];
+  const malformed = [];
+  const unresolved = [];
+  const unverified2 = [];
+  const noted2 = [];
+  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(citationIssue(line, bullet.text));
+        else
+          unsourced.push(line);
+        continue;
+      }
+      for (const error of bullet.token.errors) {
+        unresolved.push({ line, message: `[src: ${error.raw}] — ${error.message}`, rule: error.rule });
+      }
+      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")
+          unverified2.push(issue);
+        else if (resolution.outcome === "noted")
+          noted2.push({ ...issue, src: ref.raw });
+      }
+    }
+  }
+  return { emptySections, unsourced, malformed, unresolved, unverified: unverified2, noted: noted2, 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: `${String(report.bulletCount)} bullets — ${BULLET_CAP_RULE}` });
+  }
+  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,
+    noted: report.noted,
+    bulletCount: report.bulletCount
+  };
+}
+function validateCitations(text, ctx) {
+  const malformed = [];
+  const unresolved = [];
+  const unverified2 = [];
+  const noted2 = [];
+  let cited = 0;
+  for (const item of parseItems(text)) {
+    if (item.token === null) {
+      if (!hasSrcMarker(item.text))
+        continue;
+      cited++;
+      malformed.push(citationIssue(item.line, item.text));
+      continue;
+    }
+    cited++;
+    for (const error of item.token.errors) {
+      unresolved.push({ line: item.line, message: `[src: ${error.raw}] — ${error.message}`, rule: error.rule });
+    }
+    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")
+        unverified2.push(issue);
+      else if (resolution.outcome === "noted")
+        noted2.push({ ...issue, src: ref.raw });
+    }
+  }
+  return { malformed, unresolved, unverified: unverified2, noted: noted2, cited };
+}
+function noneBullet(lookedAt) {
+  return `- none [src: absent:${lookedAt}]`;
+}
+
+export { runtime, parseYaml, parseYamlRepairing, STAGES_DIR, TEMPLATES_DIR, PROJECT_FRAMEWORK_DIR, PROJECT_WORK_DIR, readableSource, SRC_PATTERNS, srcRule, parseSrcToken, classifySrc, locateWork, findWorkspaceRoot, loadWorkspace, toSrcContext, repoPath, factsPath, stageYamlPath, listRunDirs, parseHandoff, isHandoff, BULLET_RULE, EMPTY_SECTION_RULE, validateHandoff, validateCitations, noneBullet };

package/dist/hooks/{chunk-a5dq2dcp.js → chunk-dhbxzjfs.js}

@@ -1,11 +1,9 @@
 import {
   BULLET_RULE,
   EMPTY_SECTION_RULE,
-  noneBullet
-} from "./chunk-q8d3sff9.js";
-import {
+  noneBullet,
   srcRule
-} from "./chunk-a6rpj2cp.js";
+} from "./chunk-9w64mxdh.js";
 
 // src/hooks/lib/messages.ts
 var GRAMMAR = "[src: <repo:path:line> | https://… | Q<n> | F<n> | $ <cmd> → exit <n> | graph:<node> | absent:<path>]";

package/dist/hooks/{chunk-hcrbr430.js → chunk-g4db8rbs.js}

@@ -3,7 +3,7 @@ import {
 } from "./chunk-39zh2e44.js";
 import {
   parseYaml
-} from "./chunk-a6rpj2cp.js";
+} from "./chunk-9w64mxdh.js";
 
 // src/core/schemas/planCommon.ts
 var STORY_ID_RE = /^S\d{1,4}$/;
@@ -132,33 +132,5 @@ function message(error) {
   return error instanceof Error ? error.message.split(`
 `)[0] ?? "parse error" : String(error);
 }
-// src/core/schemas/story.ts
-var DOD_FENCE_OPEN_RE = /^\s*```+\s*dod\s*$/i;
-var DOD_FENCE_CLOSE_RE = /^\s*```+\s*$/;
-var FENCE_OPEN_RE = DOD_FENCE_OPEN_RE;
-var FENCE_CLOSE_RE = DOD_FENCE_CLOSE_RE;
-function parseDodBlock(text) {
-  const commands = [];
-  let present = false;
-  let inside = false;
-  for (const line of text.split(`
-`)) {
-    if (inside) {
-      if (FENCE_CLOSE_RE.test(line)) {
-        inside = false;
-        continue;
-      }
-      const command = line.trim();
-      if (command !== "" && !command.startsWith("#"))
-        commands.push(command);
-      continue;
-    }
-    if (FENCE_OPEN_RE.test(line)) {
-      present = true;
-      inside = true;
-    }
-  }
-  return { present, commands };
-}
 
-export { STORY_ID_RE, WAVE_ID_RE, MAX_WAVES, MAX_STORIES_PER_WAVE, MAX_PLAN_STORIES, requireStringList, requirePattern, requireVersion1, parseFrontMatter, parseDodBlock };
+export { STORY_ID_RE, WAVE_ID_RE, MAX_WAVES, MAX_STORIES_PER_WAVE, MAX_PLAN_STORIES, requireStringList, requirePattern, requireVersion1, parseFrontMatter };