truecourse 0.7.0-next.6 → 0.7.0-next.8

package/cli.mjs

@@ -171176,7 +171176,7 @@ function readToolVersion() {
   if (cachedVersion)
     return cachedVersion;
   if (true) {
-    cachedVersion = "0.7.0-next.6";
+    cachedVersion = "0.7.0-next.8";
     return cachedVersion;
   }
   try {
@@ -197210,7 +197210,17 @@ var OverlapSectionSchema = external_exports.object({
    * from older corpora still parses; `null` is the preamble marker the viewer
    * bands as the pre-first-heading block.
    */
-  heading: external_exports.string().nullable()
+  heading: external_exports.string().nullable(),
+  /**
+   * A short verbatim excerpt (≤ ~25 words) of the disputed sentence, copied from
+   * the doc — the model's evidence for the heading it picked. Persisted (optional,
+   * so older corpora without it still parse) for verification transparency and so
+   * the viewer can later highlight the exact disputed sentence, not just band the
+   * section. Consumed at assembly by `verifyOverlapSections` to anchor the pointer
+   * by exact location; NOT part of the cross-area dedup identity (that stays
+   * doc + heading).
+   */
+  quote: external_exports.string().optional()
 });
 var OverlapSchema = external_exports.object({
   /** The two docs that overlap, by ref. */
@@ -198003,6 +198013,237 @@ import { createHash as createHash7 } from "node:crypto";
 import fs26 from "node:fs";
 init_transport();
 init_dist5();
+
+// packages/spec-consolidator/dist/pointer-verifier.js
+var MIN_MEANINGFUL_SCORE = 1.5;
+var NEGLIGIBLE_RATIO = 0.25;
+var STOPWORDS2 = /* @__PURE__ */ new Set([
+  "the",
+  "a",
+  "an",
+  "and",
+  "or",
+  "but",
+  "if",
+  "then",
+  "else",
+  "of",
+  "to",
+  "in",
+  "on",
+  "at",
+  "by",
+  "for",
+  "with",
+  "as",
+  "is",
+  "are",
+  "was",
+  "were",
+  "be",
+  "been",
+  "being",
+  "it",
+  "its",
+  "this",
+  "that",
+  "these",
+  "those",
+  "they",
+  "them",
+  "their",
+  "there",
+  "here",
+  "no",
+  "not",
+  "yes",
+  "so",
+  "than",
+  "too",
+  "very",
+  "can",
+  "could",
+  "will",
+  "would",
+  "shall",
+  "should",
+  "may",
+  "might",
+  "must",
+  "do",
+  "does",
+  "did",
+  "done",
+  "has",
+  "have",
+  "had",
+  "from",
+  "up",
+  "out",
+  "down",
+  "over",
+  "under",
+  "again",
+  "we",
+  "you",
+  "your",
+  "our",
+  "us",
+  "i",
+  "he",
+  "she",
+  "his",
+  "her",
+  "each",
+  "any",
+  "all",
+  "both",
+  "some",
+  "such",
+  "only",
+  "own",
+  "same",
+  "more",
+  "most",
+  "other",
+  "into",
+  "about",
+  "when",
+  "where",
+  "which",
+  "who",
+  "whom",
+  "what",
+  "how",
+  "why",
+  "per",
+  "via",
+  "also"
+]);
+function tokenize(text4, drop) {
+  const lowered = text4.toLowerCase().replace(/[`*_~#>]/g, " ");
+  const out = [];
+  for (const raw of lowered.split(/[^a-z0-9]+/)) {
+    if (raw.length < 2)
+      continue;
+    if (STOPWORDS2.has(raw))
+      continue;
+    if (drop.has(raw))
+      continue;
+    out.push(raw);
+  }
+  return out;
+}
+function pathWords(p2) {
+  return p2.toLowerCase().split(/[^a-z0-9]+/).filter((t2) => t2.length >= 2);
+}
+var HEADING_RE = /^ {0,3}#{1,6}\s+(.*)$/;
+function splitDocSections(body, drop) {
+  const raws = [];
+  let cur = { heading: "", text: "" };
+  for (const line of body.split(/\r?\n/)) {
+    const m = HEADING_RE.exec(line);
+    if (m) {
+      if (cur.text.trim() || cur.heading)
+        raws.push(cur);
+      cur = { heading: m[1].trim(), text: `${line}
+` };
+    } else {
+      cur.text += `${line}
+`;
+    }
+  }
+  if (cur.text.trim() || cur.heading)
+    raws.push(cur);
+  return raws.map((r) => ({
+    realHeading: r.heading === "" ? null : r.heading,
+    tokens: new Set(tokenize(r.text, drop)),
+    text: r.text
+  }));
+}
+function headingKey(h) {
+  return h.replace(/[`*_~]/g, "").trim().toLowerCase();
+}
+function normalizeForQuote(text4) {
+  return text4.replace(/[`*_~]/g, "").toLowerCase().replace(/\s+/g, " ").trim();
+}
+function locateQuote(sections, quote) {
+  const needle = normalizeForQuote(quote);
+  if (!needle)
+    return [];
+  const hits = [];
+  for (let i = 0; i < sections.length; i++) {
+    if (normalizeForQuote(sections[i].text).includes(needle))
+      hits.push(i);
+  }
+  return hits;
+}
+function scoreSections(sections, noteTokens) {
+  const N = sections.length;
+  const df = /* @__PURE__ */ new Map();
+  for (const s of sections)
+    for (const t2 of s.tokens)
+      df.set(t2, (df.get(t2) ?? 0) + 1);
+  const idf = (t2) => {
+    const d3 = df.get(t2) ?? 0;
+    if (d3 === 0)
+      return 0;
+    return Math.max(0, Math.log2((N + 1) / (d3 + 1)));
+  };
+  return sections.map((s) => {
+    let score = 0;
+    for (const t2 of noteTokens)
+      if (s.tokens.has(t2))
+        score += idf(t2);
+    return score;
+  });
+}
+function verifyOverlapSections(input) {
+  const { docs, note, sections, bodyOf } = input;
+  if (sections.length === 0)
+    return [...sections];
+  const drop = /* @__PURE__ */ new Set([...pathWords(docs[0]), ...pathWords(docs[1])]);
+  const noteTokens = new Set(tokenize(note, drop));
+  return sections.map((ptr) => {
+    const body = bodyOf(ptr.doc);
+    if (body === void 0)
+      return { ...ptr };
+    const candidates = splitDocSections(body, drop);
+    if (candidates.length === 0)
+      return { ...ptr };
+    let pointedIdx;
+    if (ptr.heading === null) {
+      pointedIdx = 0;
+    } else {
+      const key4 = headingKey(ptr.heading);
+      pointedIdx = candidates.findIndex((c2) => c2.realHeading !== null && headingKey(c2.realHeading) === key4);
+    }
+    if (ptr.quote !== void 0) {
+      const hits = locateQuote(candidates, ptr.quote);
+      if (hits.length > 0) {
+        if (pointedIdx >= 0 && hits.includes(pointedIdx))
+          return { ...ptr };
+        const target = hits[0];
+        return { ...ptr, heading: target === 0 ? null : candidates[target].realHeading };
+      }
+    }
+    if (noteTokens.size === 0)
+      return { ...ptr };
+    const scores = scoreSections(candidates, noteTokens);
+    let bestIdx = 0;
+    for (let i = 1; i < scores.length; i++)
+      if (scores[i] > scores[bestIdx])
+        bestIdx = i;
+    const bestScore = scores[bestIdx];
+    const pointedScore = pointedIdx >= 0 ? scores[pointedIdx] : 0;
+    const reanchor = bestIdx !== pointedIdx && bestScore >= MIN_MEANINGFUL_SCORE && pointedScore < MIN_MEANINGFUL_SCORE && pointedScore <= NEGLIGIBLE_RATIO * bestScore;
+    if (!reanchor)
+      return { ...ptr };
+    return { ...ptr, heading: bestIdx === 0 ? null : candidates[bestIdx].realHeading };
+  });
+}
+
+// packages/spec-consolidator/dist/overlap-detector.js
 var DEFAULT_MAX_PAIRS_PER_AREA = 60;
 async function flagOverlaps(repoRoot5, areas, docs, opts = {}) {
   const result = /* @__PURE__ */ new Map();
@@ -198092,6 +198333,19 @@ async function flagOverlaps(repoRoot5, areas, docs, opts = {}) {
     };
     launch();
   });
+  for (const list of result.values()) {
+    for (const overlap of list) {
+      overlap.sections = verifyOverlapSections({
+        docs: overlap.docs,
+        note: overlap.note,
+        sections: overlap.sections,
+        bodyOf: (ref) => {
+          const d3 = byPath.get(ref);
+          return d3 ? docBody2(d3) : void 0;
+        }
+      });
+    }
+  }
   const entries = [...result].flatMap(([area, list]) => list.map((overlap) => ({ area, overlap })));
   const merged = dedupeCrossAreaOverlaps(entries);
   result.clear();
@@ -198146,9 +198400,12 @@ NOT a disagreement (do NOT flag):
 
 Bias: when there is a PLAUSIBLE contradiction a human should check, flag it. When the docs are clearly complementary or agree, do not.
 
-When you flag an overlap, also identify the SECTIONS that conflict: the nearest markdown heading (the \`#\`/\`##\`/\`###\` title, verbatim, WITHOUT the leading #s) above the conflicting text in EACH doc. List one entry per side; omit a side only when it genuinely has no conflicting passage.
+When you flag an overlap, point at WHERE each side's disputed claim lives. Below each doc you are given a CLOSED list of that doc's section options \u2014 its headings, plus a "lead" option. Do NOT recall or guess a heading; SELECT from the list. For EACH side output a pointer with two fields:
+  - \`heading\`: EXACTLY one of that doc's listed section headings, copied verbatim \u2014 OR the JSON literal \`null\` (not the string "null", not "") for the LEAD, the text ABOVE its first heading (or, when the doc opens straight with a title, that opening title block). Never emit a heading that is not one of the listed options.
+  - \`quote\`: a SHORT verbatim excerpt (\u2264 25 words) of the disputed sentence, copied EXACTLY from that doc \u2014 the words that state the claim in dispute. This is your evidence for the heading you picked; copy it, do not paraphrase.
+List one entry per side; omit a side only when it genuinely has no conflicting passage.
 
-PREAMBLE: when a doc's conflicting passage sits ABOVE its first \`#\` heading \u2014 the preamble block (a README's badges, tagline, or the intro line before any heading) \u2014 there is no heading to name. Set that side's \`heading\` to the JSON literal \`null\` (not the string "null", not ""). Use \`null\` ONLY for that pre-first-heading block; whenever the passage is under a heading, name the heading verbatim.
+PREAMBLE: use \`heading\`: \`null\` ONLY for that lead/preamble block; whenever the disputed passage is under a listed heading, select that heading verbatim.
 
 In the NOTE, refer to each doc by its FILENAME (the basename shown in the header, e.g. \`users.md\`) \u2014 NEVER "doc A" / "doc B", which mean nothing to the reader.
 
@@ -198156,13 +198413,19 @@ Output ONLY a JSON object, no prose, no code fences:
 
 { "overlap": true,
   "note": "users.md uses auth0_id; identity.md uses auth0_sub for the same user column",
-  "sections": [ { "side": "A", "heading": "User model" }, { "side": "B", "heading": "Identity" } ] }
+  "sections": [
+    { "side": "A", "heading": "User model", "quote": "the auth0_id column stores the Auth0 subject" },
+    { "side": "B", "heading": "Identity", "quote": "we persist the Auth0 subject in auth0_sub" }
+  ] }
 
-Preamble example \u2014 doc A's claim is a README badge/tagline above any heading, so its side uses null:
+Preamble example \u2014 doc A's disputed claim is a README tagline ABOVE its first heading, so its side uses \`heading\`: null and quotes that tagline verbatim:
 
 { "overlap": true,
   "note": "README.md lists C# as a supported language in the preamble; plan.md's Tech Stack omits it",
-  "sections": [ { "side": "A", "heading": null }, { "side": "B", "heading": "Tech Stack" } ] }
+  "sections": [
+    { "side": "A", "heading": null, "quote": "Supports TypeScript, Python, and C# out of the box" },
+    { "side": "B", "heading": "Tech Stack", "quote": "The stack is TypeScript and Python" }
+  ] }
 
 Use { "overlap": false, "note": "", "sections": [] } when they are complementary or agree. The note is shown to the user \u2014 name the specific thing that differs.`;
 var OVERLAP_PREVIEW_LINES = 120;
@@ -198196,31 +198459,59 @@ function hasConcernHeading(doc, concern, vocab) {
   }
   return false;
 }
+function sectionHeadings(body) {
+  const out = [];
+  for (const line of body.split(/\r?\n/)) {
+    const m = /^ {0,3}#{1,6}\s+(.*)$/.exec(line);
+    if (!m)
+      continue;
+    const text4 = m[1].replace(/\s*#*\s*$/, "").trim();
+    if (text4)
+      out.push(text4);
+  }
+  return out;
+}
+function sectionOptions(slice5) {
+  const lines = ["  - the lead (text above the first heading, or the opening title block) \u2192 use heading: null"];
+  for (const h of sectionHeadings(slice5))
+    lines.push(`  - ${h}`);
+  return lines;
+}
 function buildOverlapUserPrompt(areaId, a, b) {
   const slice5 = (d3) => docBody2(d3).split(/\r?\n/).slice(0, OVERLAP_PREVIEW_LINES).join("\n");
+  const sliceA = slice5(a);
+  const sliceB = slice5(b);
   return [
     `Area: ${areaId}`,
     "",
     `--- doc A: ${a.path} ---`,
-    slice5(a),
+    sliceA,
     `--- end doc A ---`,
     "",
     `--- doc B: ${b.path} ---`,
-    slice5(b),
+    sliceB,
     `--- end doc B ---`,
     "",
+    "SECTION OPTIONS \u2014 each side pointer MUST be one of these (verbatim), or the lead (heading: null):",
+    "",
+    `doc A (${a.path}):`,
+    ...sectionOptions(sliceA),
+    "",
+    `doc B (${b.path}):`,
+    ...sectionOptions(sliceB),
+    "",
     "Return the JSON object as specified."
   ].join("\n");
 }
 var LlmOverlapSchema = external_exports.object({
   overlap: external_exports.boolean(),
   note: external_exports.string().default(""),
-  sections: external_exports.array(external_exports.object({ side: external_exports.enum(["A", "B"]), heading: external_exports.string().nullable() })).default([])
+  sections: external_exports.array(external_exports.object({ side: external_exports.enum(["A", "B"]), heading: external_exports.string().nullable(), quote: external_exports.string().optional() })).default([])
 });
 var OverlapVerdictSchema = external_exports.object({
   overlap: external_exports.boolean(),
   note: external_exports.string().default(""),
-  sections: external_exports.array(external_exports.object({ doc: external_exports.string(), heading: external_exports.string().nullable() })).default([])
+  sections: external_exports.array(external_exports.object({ doc: external_exports.string(), heading: external_exports.string().nullable(), quote: external_exports.string().optional() })).default([])
 });
 function spawnOverlapRunner(opts = {}) {
   const transport = opts.transport ?? cliTransport({ bin: opts.bin });
@@ -198240,7 +198531,11 @@ function spawnOverlapRunner(opts = {}) {
     return {
       overlap: inner.overlap,
       note: inner.note,
-      sections: inner.sections.map((s) => ({ doc: s.side === "A" ? a.path : b.path, heading: s.heading }))
+      sections: inner.sections.map((s) => ({
+        doc: s.side === "A" ? a.path : b.path,
+        heading: s.heading,
+        ...s.quote !== void 0 ? { quote: s.quote } : {}
+      }))
     };
   };
 }
@@ -212438,7 +212733,7 @@ async function runHooksRun() {
 
 // tools/cli/src/index.ts
 var program2 = new Command();
-program2.name("truecourse").version("0.7.0-next.6").description("TrueCourse CLI \u2014 analyze your repository and open the dashboard");
+program2.name("truecourse").version("0.7.0-next.8").description("TrueCourse CLI \u2014 analyze your repository and open the dashboard");
 function warnDiscontinued(command) {
   process.stderr.write(
     `\u26A0 \`${command}\` is discontinued in favor of \`truecourse guard\` \u2014 see the README. Planned removal: 0.8.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "truecourse",
-  "version": "0.7.0-next.6",
+  "version": "0.7.0-next.8",
   "description": "Visualize your codebase architecture as an interactive graph",
   "type": "module",
   "bin": {