tldr-experts 0.3.0

package/dist/hooks/chunk-g395gk7e.js

@@ -0,0 +1,503 @@
+import {
+  PROJECT_FRAMEWORK_DIR,
+  parseYaml
+} from "./chunk-p274ckxv.js";
+
+// src/core/text/srcToken.ts
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { isAbsolute, join, normalize, relative, sep } from "node:path";
+var LINE_RE = /^\d{1,9}$/;
+var LINE_RANGE_RE = /^(\d{1,9})-(\d{1,9})$/;
+var ANSWER_RE = /^Q\d{1,6}$/;
+var FACT_RE = /^F\d{3,6}$/;
+var CMD_RE = /^\$ (.+) → exit (\d{1,3})$/;
+var TRAILING_TOKEN_RE = /\[src: ([^\]]*)\]$/;
+var TRAILING_CLOSER_RE = /[`'"’”»)\s.,;:!?]+$/;
+var SRC_MARKER = "[src:";
+var AIDLC_LINE_RE = /^(.+):(\d{1,9})$/;
+var AIDLC_Q_RE = /^(.+)#(Q\d{1,6})$/;
+function parseSrcToken(line, repos) {
+  const trimmed = trimTrailingClosers(line);
+  const match = TRAILING_TOKEN_RE.exec(trimmed);
+  if (match === null)
+    return null;
+  const inner = match[1] ?? "";
+  const refs = [];
+  const errors = [];
+  for (const piece of inner.split("; ")) {
+    const parsed = classifySrc(piece, repos);
+    if ("message" in parsed)
+      errors.push(parsed);
+    else
+      refs.push(parsed);
+  }
+  if (inner.trim() === "") {
+    return { raw: match[0], refs: [], errors: [{ raw: "", message: "empty [src: ] token" }] };
+  }
+  return { raw: match[0], refs, errors };
+}
+function trimTrailingClosers(line) {
+  const trimmed = line.replace(/\s+$/, "");
+  if (trimmed.endsWith("]"))
+    return trimmed;
+  const stripped = trimmed.replace(TRAILING_CLOSER_RE, "");
+  return stripped.endsWith("]") ? stripped : trimmed;
+}
+function hasSrcMarker(line) {
+  return line.includes(SRC_MARKER);
+}
+function classifySrc(src, repos) {
+  const raw = src;
+  if (raw === "")
+    return { raw, message: "empty source" };
+  if (raw.startsWith("https://")) {
+    if (raw.length <= "https://".length || /\s/.test(raw)) {
+      return { raw, message: "`doc` must be https:// followed by a non-space URL" };
+    }
+    return { kind: "doc", raw, url: raw };
+  }
+  if (raw.startsWith("http://")) {
+    return { raw, message: "`doc` sources must be https:// — http:// is rejected" };
+  }
+  if (raw.startsWith("$ ")) {
+    const m = CMD_RE.exec(raw);
+    if (m === null || m[1] === undefined || m[2] === undefined) {
+      return { raw, message: "`cmd` must read `$ <command> → exit <n>`" };
+    }
+    return { kind: "cmd", raw, command: m[1], exitCode: Number(m[2]) };
+  }
+  if (raw.startsWith("graph:")) {
+    const node = raw.slice("graph:".length);
+    if (node === "" || /\s/.test(node))
+      return { raw, message: "`graph:` needs a non-empty node id" };
+    return { kind: "graph", raw, node };
+  }
+  if (raw.startsWith("aidlc:"))
+    return parseAidlcSrc(raw);
+  if (raw.startsWith("absent:")) {
+    const path = raw.slice("absent:".length);
+    if (path === "")
+      return { raw, message: "`absent:` needs a path" };
+    return { kind: "absent", raw, path };
+  }
+  if (ANSWER_RE.test(raw))
+    return { kind: "answer", raw, q: raw };
+  if (FACT_RE.test(raw))
+    return { kind: "fact", raw, id: raw };
+  if (raw.startsWith("Q") || raw.startsWith("F")) {
+    if (!raw.includes(":")) {
+      return { raw, message: "expected `Q<n>` or `F<nnn>`" };
+    }
+  }
+  return parseFileSrc(raw, repos);
+}
+function parseAidlcSrc(raw) {
+  const rest = raw.slice("aidlc:".length);
+  if (rest === "")
+    return { raw, message: "`aidlc:` needs a path" };
+  if (rest.includes(".."))
+    return { raw, message: "`..` is not allowed in a source path" };
+  const question = AIDLC_Q_RE.exec(rest);
+  if (question !== null && question[1] !== undefined && question[2] !== undefined) {
+    return { kind: "aidlc", raw, path: question[1], line: null, q: question[2] };
+  }
+  const located = AIDLC_LINE_RE.exec(rest);
+  if (located !== null && located[1] !== undefined && located[2] !== undefined) {
+    const line = Number(located[2]);
+    if (line < 1)
+      return { raw, message: "line numbers are 1-based" };
+    return { kind: "aidlc", raw, path: located[1], line, q: null };
+  }
+  return { raw, message: "expected `aidlc:<file>:<line>` or `aidlc:<file>#Q<n>`" };
+}
+function parseFileSrc(raw, repos) {
+  const lastColon = raw.lastIndexOf(":");
+  if (lastColon <= 0) {
+    return { raw, message: "expected `[repo:]path:line[-line]`" };
+  }
+  const lineSpec = raw.slice(lastColon + 1);
+  const head = raw.slice(0, lastColon);
+  let startLine;
+  let endLine = null;
+  if (LINE_RE.test(lineSpec)) {
+    startLine = Number(lineSpec);
+  } else {
+    const range = LINE_RANGE_RE.exec(lineSpec);
+    if (range === null || range[1] === undefined || range[2] === undefined) {
+      return { raw, message: "expected a line number or `line-line` range after the last `:`" };
+    }
+    startLine = Number(range[1]);
+    endLine = Number(range[2]);
+    if (endLine < startLine)
+      return { raw, message: "line range ends before it starts" };
+  }
+  if (startLine < 1)
+    return { raw, message: "line numbers are 1-based" };
+  let repo = null;
+  let path = head;
+  const firstColon = head.indexOf(":");
+  if (firstColon > 0) {
+    const candidate = head.slice(0, firstColon);
+    if (/^[a-z0-9][a-z0-9-]{0,31}$/.test(candidate) && (repos === undefined || repos.has(candidate))) {
+      repo = candidate;
+      path = head.slice(firstColon + 1);
+    }
+  }
+  if (path === "")
+    return { raw, message: "empty path" };
+  if (path.includes(".."))
+    return { raw, message: "`..` is not allowed in a source path" };
+  return { kind: "file", raw, repo, path, startLine, endLine };
+}
+var lineCountCache = new Map;
+var OK = { ok: true, outcome: "ok" };
+function refused(message, resolved) {
+  return resolved === undefined ? { ok: false, outcome: "refused", message } : { ok: false, outcome: "refused", message, resolved };
+}
+function unverified(message) {
+  return { ok: true, outcome: "unverified", 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);
+      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);
+        }
+        return { ok: true, outcome: "ok", resolved: base.abs };
+      }
+      const tried = bases.map((b) => b.label).join(", ");
+      return refused(`no such file: ${ref.path} — tried ${tried}`, bases[0]?.abs);
+    }
+    case "cmd": {
+      if (section !== "Evidence ledger") {
+        return refused("`$ … → exit n` sources are only allowed in the Evidence ledger");
+      }
+      if (ctx.commands.size === 0) {
+        return unverified("no workspace.yml commands to check `$ … → exit n` against");
+      }
+      if (!ctx.commands.has(ref.command)) {
+        return refused(`command \`${ref.command}\` is not one of workspace.yml's commands`);
+      }
+      return OK;
+    }
+    case "fact":
+      return resolveFact(ref.id, ctx);
+    case "answer":
+      return resolveAnswer(ref.q, ctx);
+    case "graph":
+      return resolveGraph(ref.node, ctx);
+    case "doc":
+      return resolveDoc(ref.url, ctx);
+    case "absent":
+      return resolveAbsent(ref.path, ctx, section, claim);
+    case "aidlc":
+      return OK;
+  }
+}
+function resolveFact(id, ctx) {
+  const facts = loadFacts(ctx.root);
+  if (facts === null) {
+    return unverified(`no ${PROJECT_FRAMEWORK_DIR}/memory/facts.yml to check ${id} against`);
+  }
+  if (facts.retired.has(id)) {
+    return refused(`${id} is RETIRED in facts.yml — a retired fact is not evidence`);
+  }
+  if (!facts.live.has(id)) {
+    const known = facts.live.size === 0 ? "it has no live facts" : `it has ${String(facts.live.size)} live fact(s)`;
+    return refused(`no such fact ${id} in ${PROJECT_FRAMEWORK_DIR}/memory/facts.yml — ${known}`);
+  }
+  return OK;
+}
+function resolveAnswer(q, ctx) {
+  const runDir = ctx.runDir ?? null;
+  if (runDir === null || runDir === "") {
+    return unverified(`no run directory in context to look ${q} up in`);
+  }
+  const ids = loadQuestionIds(runDir);
+  if (ids === null)
+    return refused(`no questions.md anywhere in this run — ${q} cites a question nobody asked`);
+  if (!ids.has(q)) {
+    const known = ids.size === 0 ? "none are declared" : `declared: ${[...ids].sort().join(", ")}`;
+    return refused(`no such question ${q} in this run's questions.md — ${known}`);
+  }
+  return OK;
+}
+function resolveGraph(node, ctx) {
+  const graph = loadGraphNodes(ctx.root);
+  if (graph !== null) {
+    if (graph.has(node))
+      return OK;
+    return refused(`no node \`${node}\` in graphify-out/graph.json (${String(graph.size)} node(s))`);
+  }
+  const map = loadMapTokens(ctx.root);
+  if (map === null) {
+    return unverified(`no graphify-out/graph.json and no ${PROJECT_FRAMEWORK_DIR}/map/ to check \`${node}\` against`);
+  }
+  if (map.has(node))
+    return OK;
+  return refused(`\`${node}\` is not a node id or a path named anywhere in ${PROJECT_FRAMEWORK_DIR}/map/`);
+}
+function resolveDoc(url, ctx) {
+  const known = loadDeclaredUrls(ctx);
+  if (known.has(url) || known.has(url.replace(/[/#?]+$/, "")))
+    return OK;
+  return unverified(`${url} is not fetched offline and no input, map or knowledge file cites it`);
+}
+function resolveAbsent(path, ctx, section, claim) {
+  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 = isAbsolute(path) ? normalize(path) : normalize(join(ctx.root, path));
+  if (!existsSync(abs))
+    return OK;
+  return unverified(`${path} EXISTS — "found nothing in it" is a claim about its contents, unchecked here`);
+}
+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 (isAbsolute(ref.path)) {
+    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 bases = [
+    { 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)))
+      });
+    }
+  }
+  return bases;
+}
+function repoLabel(name, rel) {
+  const at = rel === "" || rel === "." ? "workspace root" : rel;
+  return `repo \`${name}\` (${at})`;
+}
+function displayPath(root, dir) {
+  const rel = relative(root, dir);
+  return rel === "" || rel.startsWith("..") ? dir : rel.split(sep).join("/");
+}
+function countLines(path) {
+  const cached = lineCountCache.get(path);
+  if (cached !== undefined)
+    return cached;
+  const text = readFileSync(path, "utf8");
+  const count = text === "" ? 0 : text.split(`
+`).length - (text.endsWith(`
+`) ? 1 : 0);
+  lineCountCache.set(path, count);
+  return count;
+}
+var factsCache = new Map;
+var questionsCache = new Map;
+var graphCache = new Map;
+var mapCache = new Map;
+var urlCache = new Map;
+var MAX_SCAN_FILES = 400;
+var MAX_SCAN_BYTES = 512 * 1024;
+var MAX_SCAN_DEPTH = 4;
+function loadFacts(root) {
+  const cached = factsCache.get(root);
+  if (cached !== undefined)
+    return cached;
+  const index = readFacts(join(root, PROJECT_FRAMEWORK_DIR, "memory", "facts.yml"));
+  factsCache.set(root, index);
+  return index;
+}
+function readFacts(path) {
+  if (!existsSync(path))
+    return null;
+  const live = new Set;
+  const retired = new Set;
+  try {
+    const doc = parseYaml(readFileSync(path, "utf8"));
+    const rows = doc?.facts;
+    if (!Array.isArray(rows))
+      return { live, retired };
+    for (const row of rows) {
+      const id = typeof row?.id === "string" ? row.id : null;
+      if (id === null)
+        continue;
+      const gone = row.retired;
+      const isGone = gone !== null && gone !== undefined && typeof gone === "object" && gone.at !== null && gone.at !== undefined;
+      if (isGone)
+        retired.add(id);
+      else
+        live.add(id);
+    }
+  } catch {
+    return null;
+  }
+  return { live, retired };
+}
+function loadQuestionIds(runDir) {
+  const cached = questionsCache.get(runDir);
+  if (cached !== undefined)
+    return cached;
+  const files = findFiles(runDir, (name) => name === "questions.md", MAX_SCAN_DEPTH);
+  if (files.length === 0) {
+    questionsCache.set(runDir, null);
+    return null;
+  }
+  const ids = new Set;
+  const heading = /^#{2,4}\s*(Q\d{1,6})\b/gm;
+  for (const file of files) {
+    const text = readCapped(file);
+    for (const match of text.matchAll(heading)) {
+      if (match[1] !== undefined)
+        ids.add(match[1]);
+    }
+  }
+  questionsCache.set(runDir, ids);
+  return ids;
+}
+function loadGraphNodes(root) {
+  const cached = graphCache.get(root);
+  if (cached !== undefined)
+    return cached;
+  const ids = readGraphNodes(root);
+  graphCache.set(root, ids);
+  return ids;
+}
+function readGraphNodes(root) {
+  const roots = [join(root, PROJECT_FRAMEWORK_DIR, "graphify-out"), join(root, "graphify-out")];
+  const files = [];
+  for (const dir of roots) {
+    if (!existsSync(dir))
+      continue;
+    files.push(...findFiles(dir, (name) => name === "graph.json", MAX_SCAN_DEPTH));
+  }
+  if (files.length === 0)
+    return null;
+  const ids = new Set;
+  for (const file of files) {
+    try {
+      const doc = JSON.parse(readCapped(file));
+      const nodes = doc?.nodes;
+      if (!Array.isArray(nodes))
+        continue;
+      for (const node of nodes) {
+        for (const key of ["id", "name", "label"]) {
+          const value = node?.[key];
+          if (typeof value === "string" && value !== "") {
+            ids.add(value);
+            break;
+          }
+        }
+      }
+    } catch {}
+  }
+  return ids.size === 0 ? null : ids;
+}
+function loadMapTokens(root) {
+  const cached = mapCache.get(root);
+  if (cached !== undefined)
+    return cached;
+  const dir = join(root, PROJECT_FRAMEWORK_DIR, "map");
+  if (!existsSync(dir)) {
+    mapCache.set(root, null);
+    return null;
+  }
+  const tokens = new Set;
+  const word = /[A-Za-z0-9_./-]{2,}/g;
+  for (const file of findFiles(dir, (name) => name.endsWith(".md") || name.endsWith(".json"), MAX_SCAN_DEPTH)) {
+    for (const match of readCapped(file).matchAll(word))
+      tokens.add(match[0]);
+  }
+  mapCache.set(root, tokens);
+  return tokens;
+}
+function loadDeclaredUrls(ctx) {
+  const key = `${ctx.root}\x00${ctx.runDir ?? ""}`;
+  const cached = urlCache.get(key);
+  if (cached !== undefined)
+    return cached;
+  const urls = new Set;
+  const url = /https:\/\/[^\s)\]"'`<>]+/g;
+  const runDir = ctx.runDir ?? "";
+  const dirs = [
+    join(ctx.root, PROJECT_FRAMEWORK_DIR, "map"),
+    join(ctx.root, PROJECT_FRAMEWORK_DIR, "knowledge"),
+    join(ctx.root, PROJECT_FRAMEWORK_DIR, "experts"),
+    ...runDir === "" ? [] : [runDir]
+  ];
+  for (const dir of dirs) {
+    if (!existsSync(dir))
+      continue;
+    for (const file of findFiles(dir, (name) => name.endsWith(".md") && name !== "handoff.md", MAX_SCAN_DEPTH)) {
+      for (const match of readCapped(file).matchAll(url)) {
+        urls.add(match[0].replace(/[.,;:]+$/, ""));
+      }
+    }
+  }
+  urlCache.set(key, urls);
+  return urls;
+}
+function findFiles(dir, accept, depth) {
+  const found = [];
+  const walk = (current, left) => {
+    if (left < 0 || found.length >= MAX_SCAN_FILES)
+      return;
+    let entries;
+    try {
+      entries = readdirSync(current);
+    } catch {
+      return;
+    }
+    for (const name of entries) {
+      if (found.length >= MAX_SCAN_FILES)
+        return;
+      if (name.startsWith(".") && name !== PROJECT_FRAMEWORK_DIR)
+        continue;
+      if (name === "node_modules")
+        continue;
+      const abs = join(current, name);
+      let isDir;
+      try {
+        isDir = statSync(abs).isDirectory();
+      } catch {
+        continue;
+      }
+      if (isDir)
+        walk(abs, left - 1);
+      else if (accept(name))
+        found.push(abs);
+    }
+  };
+  walk(dir, depth);
+  return found;
+}
+function readCapped(path) {
+  try {
+    const text = readFileSync(path, "utf8");
+    return text.length > MAX_SCAN_BYTES ? text.slice(0, MAX_SCAN_BYTES) : text;
+  } catch {
+    return "";
+  }
+}
+
+export { parseSrcToken, hasSrcMarker, classifySrc, resolveSrc };