tldr-experts 0.3.0

package/dist/hooks/chunk-x98qs959.js

@@ -0,0 +1,302 @@
+import {
+  emitFactsYaml,
+  withWorkspaceLock,
+  workspaceRootOfFactsPath
+} from "./chunk-j234zf0t.js";
+import {
+  noteDeprecations
+} from "./chunk-t56k6146.js";
+import {
+  asDocument,
+  isRecord,
+  requireArray,
+  requireEnum,
+  requireKeys,
+  requireString,
+  requireVersion,
+  result
+} from "./chunk-0bt6yb2q.js";
+import {
+  parseYaml
+} from "./chunk-p274ckxv.js";
+
+// src/core/facts/FactsStore.ts
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+// src/core/facts/Fact.ts
+var FACT_KINDS = ["answer", "observed", "derived"];
+var FACT_CONFIDENCES = ["measured", "inferred", "stated"];
+var MAX_FACTS = 5000;
+var MAX_FACT_CHARS = 300;
+function isRetired(fact) {
+  return fact.retired !== null && fact.retired.at !== null;
+}
+function factNumber(id) {
+  return Number.parseInt(id.slice(1), 10);
+}
+function formatFactId(n) {
+  return `F${String(n).padStart(3, "0")}`;
+}
+
+// src/core/facts/validateFactsFile.ts
+var ID_RE = /^F\d{3,6}$/;
+var Q_RE = /^Q\d{1,6}$/;
+function validateFactsFile(input) {
+  const issues = [];
+  const deprecations = [];
+  const doc = asDocument(input, issues);
+  if (!doc)
+    return result(issues);
+  requireVersion(doc, issues, deprecations);
+  requireKeys(doc, ["facts"], "", issues);
+  if (!requireArray(doc.facts, "facts", issues))
+    return result(issues, deprecations);
+  const rows = doc.facts;
+  if (rows.length > MAX_FACTS) {
+    issues.push({ path: "facts", message: `${rows.length} facts exceeds the ${MAX_FACTS} cap` });
+  }
+  const byId = new Map;
+  let previous = 0;
+  rows.forEach((row, i) => {
+    const path = `facts[${i}]`;
+    if (!isRecord(row)) {
+      issues.push({ path, message: "expected a mapping" });
+      return;
+    }
+    requireKeys(row, ["id", "fact", "area", "repos", "kind", "confidence", "source", "supersedes", "superseded_by", "retired"], path, issues);
+    const id = typeof row.id === "string" ? row.id : "";
+    if (!ID_RE.test(id))
+      issues.push({ path: `${path}.id`, message: "id must match ^F\\d{3,6}$" });
+    else if (byId.has(id))
+      issues.push({ path: `${path}.id`, message: `duplicate fact id ${id}` });
+    else {
+      const n = factNumber(id);
+      if (n <= previous)
+        issues.push({ path: `${path}.id`, message: `fact ids must ascend (${id} follows F${previous})` });
+      previous = n;
+      byId.set(id, row);
+    }
+    requireString(row.fact, `${path}.fact`, issues);
+    if (typeof row.fact === "string" && row.fact.length > MAX_FACT_CHARS) {
+      issues.push({ path: `${path}.fact`, message: `fact is ${row.fact.length} chars (max ${MAX_FACT_CHARS})` });
+    }
+    requireString(row.area, `${path}.area`, issues);
+    requireArray(row.repos, `${path}.repos`, issues);
+    requireEnum(row.kind, FACT_KINDS, `${path}.kind`, issues);
+    requireEnum(row.confidence, FACT_CONFIDENCES, `${path}.confidence`, issues);
+    if (isRecord(row.source)) {
+      requireKeys(row.source, ["who", "when", "run", "q"], `${path}.source`, issues);
+      const q = row.source.q;
+      if (typeof q === "string" && !Q_RE.test(q)) {
+        issues.push({ path: `${path}.source.q`, message: "expected ^Q\\d+$ or null" });
+      }
+    } else if (row.source !== undefined) {
+      issues.push({ path: `${path}.source`, message: "expected a mapping" });
+    }
+    const superseded = typeof row.superseded_by === "string";
+    const retired = isRecord(row.retired) && row.retired.at !== null && row.retired.at !== undefined;
+    if (superseded && retired) {
+      issues.push({ path, message: "a fact may be superseded or retired, not both" });
+    }
+  });
+  for (const [id, row] of byId) {
+    const forward = row.superseded_by;
+    if (typeof forward === "string") {
+      const target = byId.get(forward);
+      if (target === undefined) {
+        issues.push({ path: `facts.${id}.superseded_by`, message: `${forward} is not in this file` });
+      } else if (target.supersedes !== id) {
+        issues.push({ path: `facts.${id}.superseded_by`, message: `${forward}.supersedes must be ${id} (links are reciprocal)` });
+      }
+    }
+    const back = row.supersedes;
+    if (typeof back === "string") {
+      const target = byId.get(back);
+      if (target === undefined) {
+        issues.push({ path: `facts.${id}.supersedes`, message: `${back} is not in this file` });
+      } else if (target.superseded_by !== id) {
+        issues.push({ path: `facts.${id}.supersedes`, message: `${back}.superseded_by must be ${id} (links are reciprocal)` });
+      }
+    }
+  }
+  return result(issues, deprecations);
+}
+function asFactsFile(input) {
+  const doc = input;
+  return { version: doc.version, facts: doc.facts };
+}
+
+// src/core/facts/findDuplicate.ts
+var DEFAULT_JACCARD_THRESHOLD = 0.6;
+var MIN_TOKEN_LENGTH = 4;
+var WORD_RE = /[a-z0-9]+/g;
+function tokenize(text) {
+  const tokens = new Set;
+  for (const word of text.toLowerCase().matchAll(WORD_RE)) {
+    const token = word[0];
+    if (token.length >= MIN_TOKEN_LENGTH)
+      tokens.add(token);
+  }
+  return tokens;
+}
+function jaccard(a, b) {
+  if (a.size === 0 || b.size === 0)
+    return 0;
+  let intersection = 0;
+  for (const token of a)
+    if (b.has(token))
+      intersection++;
+  const union = a.size + b.size - intersection;
+  return union === 0 ? 0 : intersection / union;
+}
+function findDuplicate(question, area, facts, threshold = DEFAULT_JACCARD_THRESHOLD) {
+  const asked = tokenize(question);
+  if (asked.size === 0)
+    return null;
+  let best = null;
+  for (const fact of facts) {
+    if (fact.area !== area)
+      continue;
+    if (isRetired(fact))
+      continue;
+    const score = jaccard(asked, tokenize(fact.fact));
+    if (score < threshold)
+      continue;
+    if (best === null || score > best.score || score === best.score && fact.id > best.fact.id) {
+      best = { fact, score };
+    }
+  }
+  return best;
+}
+
+// src/core/facts/FactsStore.ts
+var NEW_FILE_HEADER = `# .tldrx/memory/facts.yml — durable, provenanced answers (spec §2.5).
+` + "# Append-mostly: supersede or retire, never edit. A fact without a source is not a fact.";
+
+class FactsStore {
+  path;
+  version;
+  rows;
+  constructor(path, version, rows) {
+    this.path = path;
+    this.version = version;
+    this.rows = [...rows];
+  }
+  static load(path) {
+    const text = readFileSync(path, "utf8");
+    const doc = parseYaml(text);
+    const validation = validateFactsFile(doc);
+    noteDeprecations(path, validation);
+    if (!validation.ok) {
+      const first = validation.issues[0];
+      throw new Error(`invalid facts.yml (${path}): ${first?.path ?? ""} ${first?.message ?? "schema error"}`);
+    }
+    const file = asFactsFile(doc);
+    return new FactsStore(path, file.version, file.facts);
+  }
+  static loadOrEmpty(path) {
+    if (!existsSync(path))
+      return new FactsStore(path, 1, []);
+    return FactsStore.load(path);
+  }
+  get facts() {
+    return this.rows;
+  }
+  get active() {
+    return this.rows.filter((f) => !isRetired(f));
+  }
+  get(id) {
+    return this.rows.find((f) => f.id === id);
+  }
+  nextId() {
+    const highest = this.rows.reduce((max, f) => Math.max(max, factNumber(f.id)), 0);
+    return formatFactId(highest + 1);
+  }
+  append(input) {
+    const fact = {
+      id: this.nextId(),
+      fact: input.fact.length > MAX_FACT_CHARS ? `${input.fact.slice(0, MAX_FACT_CHARS - 1)}…` : input.fact,
+      area: input.area,
+      repos: [...input.repos],
+      kind: input.kind,
+      confidence: input.confidence,
+      source: { ...input.source },
+      supersedes: input.supersedes ?? null,
+      superseded_by: null,
+      retired: input.retired ?? null
+    };
+    this.rows.push(fact);
+    return fact;
+  }
+  supersede(oldId, input) {
+    const index = this.rows.findIndex((f) => f.id === oldId);
+    if (index === -1)
+      throw new Error(`cannot supersede ${oldId}: no such fact`);
+    const old = this.rows[index];
+    if (old.superseded_by !== null) {
+      throw new Error(`${oldId} is already superseded by ${old.superseded_by}`);
+    }
+    if (isRetired(old))
+      throw new Error(`${oldId} is retired; a retired fact is not superseded`);
+    const replacement = this.append({ ...input, supersedes: oldId });
+    this.rows[index] = { ...old, superseded_by: replacement.id };
+    return replacement;
+  }
+  retire(id, retirement) {
+    const index = this.rows.findIndex((f) => f.id === id);
+    if (index === -1)
+      throw new Error(`cannot retire ${id}: no such fact`);
+    const fact = this.rows[index];
+    if (fact.superseded_by !== null) {
+      throw new Error(`${id} is superseded by ${fact.superseded_by}; a superseded fact is not retired`);
+    }
+    const retired = { ...fact, retired: retirement };
+    this.rows[index] = retired;
+    return retired;
+  }
+  findDuplicate(question, area, threshold) {
+    return findDuplicate(question, area, this.active, threshold);
+  }
+  toFile() {
+    return { version: this.version, facts: this.rows };
+  }
+  toYaml() {
+    return emitFactsYaml(this.toFile(), existsSync(this.path) ? undefined : NEW_FILE_HEADER);
+  }
+  save(path = this.path) {
+    const text = this.toYaml();
+    const validation = validateFactsFile(parseYaml(text));
+    if (!validation.ok) {
+      const first = validation.issues[0];
+      throw new Error(`refusing to write an invalid facts.yml: ${first?.path ?? ""} ${first?.message ?? ""}`);
+    }
+    withWorkspaceLock(workspaceRootOfFactsPath(path), () => {
+      writeFactsAtomic(path, text);
+    });
+  }
+  static update(path, fn) {
+    return withWorkspaceLock(workspaceRootOfFactsPath(path), () => {
+      const store = FactsStore.loadOrEmpty(path);
+      const value = fn(store);
+      store.save(path);
+      return value;
+    });
+  }
+}
+function writeFactsAtomic(path, text) {
+  const temp = `${path}.tmp-${String(process.pid)}`;
+  mkdirSync(dirname(path), { recursive: true });
+  try {
+    writeFileSync(temp, text, "utf8");
+    renameSync(temp, path);
+  } catch (error) {
+    try {
+      if (existsSync(temp))
+        rmSync(temp, { force: true });
+    } catch {}
+    throw error;
+  }
+}
+
+export { MAX_FACT_CHARS, FactsStore };