truecourse 0.7.0-next.5 → 0.7.0-next.6

package/cli.mjs

@@ -105837,6 +105837,153 @@ var init_guard = __esm({
   }
 });
 
+// packages/shared/dist/spec/overlap-resolution.js
+function coveringRelationInAreas(relations, a, b, areas) {
+  return relations.find((r) => {
+    const samePair = r.older === a && r.newer === b || r.older === b && r.newer === a;
+    return samePair && (r.scope === void 0 || areas.includes(r.scope));
+  });
+}
+function dedupeCrossAreaOverlaps(entries) {
+  const byPair = /* @__PURE__ */ new Map();
+  for (const e of entries) {
+    const key4 = unorderedPairKey(e.overlap.docs[0], e.overlap.docs[1]);
+    const list = byPair.get(key4);
+    if (list)
+      list.push(e);
+    else
+      byPair.set(key4, [e]);
+  }
+  const merged = [];
+  for (const members of byPair.values()) {
+    const parent = members.map((_2, i) => i);
+    const find = (i) => {
+      while (parent[i] !== i) {
+        parent[i] = parent[parent[i]];
+        i = parent[i];
+      }
+      return i;
+    };
+    const union = (i, j2) => {
+      const ri = find(i);
+      const rj = find(j2);
+      if (ri !== rj)
+        parent[Math.max(ri, rj)] = Math.min(ri, rj);
+    };
+    const ptrOwner = /* @__PURE__ */ new Map();
+    members.forEach((m, i) => {
+      for (const ptr of sectionPointerKeys(m.overlap)) {
+        const owner = ptrOwner.get(ptr);
+        if (owner === void 0)
+          ptrOwner.set(ptr, i);
+        else
+          union(owner, i);
+      }
+    });
+    const components = /* @__PURE__ */ new Map();
+    members.forEach((_2, i) => {
+      const root2 = find(i);
+      const list = components.get(root2);
+      if (list)
+        list.push(i);
+      else
+        components.set(root2, [i]);
+    });
+    for (const idxs of components.values()) {
+      const group = idxs.map((i) => members[i]);
+      const rep = [...group].sort((x, y) => {
+        const px = preambleCount(x.overlap);
+        const py = preambleCount(y.overlap);
+        if (px !== py)
+          return px - py;
+        if (x.area !== y.area)
+          return x.area < y.area ? -1 : 1;
+        return (x.overlap.note ?? "") < (y.overlap.note ?? "") ? -1 : 1;
+      })[0];
+      const span = /* @__PURE__ */ new Set();
+      for (const g of group) {
+        span.add(g.area);
+        for (const a of g.overlap.areas ?? [])
+          span.add(a);
+      }
+      merged.push({ area: rep.area, areas: [...span].sort(), overlap: rep.overlap });
+    }
+  }
+  merged.sort((x, y) => {
+    if (x.area !== y.area)
+      return x.area < y.area ? -1 : 1;
+    return unorderedPairKey(x.overlap.docs[0], x.overlap.docs[1]) < unorderedPairKey(y.overlap.docs[0], y.overlap.docs[1]) ? -1 : 1;
+  });
+  return merged;
+}
+function buildCorpusConflicts(corpus, decisions) {
+  const userRelations = decisions.relations ?? [];
+  const effectiveRels = [...corpus.relations, ...userRelations];
+  const excludes = new Set(decisions.manualExcludes ?? []);
+  const entries = [];
+  for (const area of corpus.areas)
+    for (const ov of area.overlaps)
+      entries.push({ area: area.id, overlap: ov });
+  const mergedOverlaps = dedupeCrossAreaOverlaps(entries);
+  const flagged = [];
+  for (const m of mergedOverlaps) {
+    const [a, b] = m.overlap.docs;
+    const relation = coveringRelationInAreas(effectiveRels, a, b, m.areas);
+    const userRelation = coveringRelationInAreas(userRelations, a, b, m.areas);
+    const excludedRef = excludes.has(a) ? a : excludes.has(b) ? b : void 0;
+    flagged.push({
+      area: m.area,
+      areas: m.areas,
+      a,
+      b,
+      note: m.overlap.note ?? "",
+      resolved: relation !== void 0 || excludedRef !== void 0,
+      synthesized: false,
+      ...relation ? { relation } : {},
+      ...userRelation ? { userRelation } : {},
+      ...excludedRef ? { excludedRef } : {}
+    });
+  }
+  const coversFlagged = (r) => flagged.some((o) => {
+    const samePair = o.a === r.older && o.b === r.newer || o.a === r.newer && o.b === r.older;
+    return samePair && (r.scope === void 0 || o.areas.includes(r.scope));
+  });
+  const synthesized = userRelations.filter((r) => !coversFlagged(r)).map((r) => ({
+    area: r.scope ?? "",
+    areas: r.scope ? [r.scope] : [],
+    a: r.older,
+    b: r.newer,
+    note: r.note ?? "",
+    resolved: true,
+    synthesized: true,
+    relation: r,
+    userRelation: r
+  }));
+  return [...flagged, ...synthesized];
+}
+function openConflicts(corpus, decisions) {
+  return buildCorpusConflicts(corpus, decisions).filter((c2) => !c2.resolved);
+}
+var PREAMBLE_PTR, NUL, unorderedPairKey, sectionPointerKeys, preambleCount;
+var init_overlap_resolution = __esm({
+  "packages/shared/dist/spec/overlap-resolution.js"() {
+    "use strict";
+    PREAMBLE_PTR = "\0preamble";
+    NUL = "\0";
+    unorderedPairKey = (a, b) => a < b ? `${a}${NUL}${b}` : `${b}${NUL}${a}`;
+    sectionPointerKeys = (ov) => (ov.sections ?? []).map((s) => `${s.doc}${NUL}${s.heading ?? PREAMBLE_PTR}`);
+    preambleCount = (ov) => (ov.sections ?? []).filter((s) => s.heading === null || s.heading === void 0).length;
+  }
+});
+
+// packages/shared/dist/spec/index.js
+var init_spec = __esm({
+  "packages/shared/dist/spec/index.js"() {
+    "use strict";
+    init_overlap_resolution();
+  }
+});
+
 // packages/shared/dist/fs/tcignore.js
 import fs11 from "node:fs";
 import path13 from "node:path";
@@ -105960,6 +106107,7 @@ var init_dist5 = __esm({
     init_types3();
     init_schemas();
     init_guard();
+    init_spec();
     init_tcignore();
     init_skip_dirs();
     init_spec_scope();
@@ -171028,7 +171176,7 @@ function readToolVersion() {
   if (cachedVersion)
     return cachedVersion;
   if (true) {
-    cachedVersion = "0.7.0-next.5";
+    cachedVersion = "0.7.0-next.6";
     return cachedVersion;
   }
   try {
@@ -197070,7 +197218,16 @@ var OverlapSchema = external_exports.object({
   /** Short note on what may disagree ("auth0_id vs auth0_sub"). */
   note: external_exports.string().default(""),
   /** The specific conflicting sections per doc (markdown headings), when known. */
-  sections: external_exports.array(OverlapSectionSchema).default([])
+  sections: external_exports.array(OverlapSectionSchema).default([]),
+  /**
+   * The area ids this dispute spans. Detection runs per area, so one disagreement
+   * on a doc pair sharing several areas is flagged in each; the cross-area merge
+   * collapses those to this single record and lists every area it spanned here, so
+   * a resolution scoped to any of them clears the dispute everywhere. Empty for
+   * older corpora written before the merge — the read layer recomputes the span
+   * from the per-area placement of the (then-duplicated) records.
+   */
+  areas: external_exports.array(external_exports.string()).default([])
 });
 var AreaSchema = external_exports.object({
   /** Canonical area id, `product/concern`. */
@@ -197845,6 +198002,7 @@ init_zod();
 import { createHash as createHash7 } from "node:crypto";
 import fs26 from "node:fs";
 init_transport();
+init_dist5();
 var DEFAULT_MAX_PAIRS_PER_AREA = 60;
 async function flagOverlaps(repoRoot5, areas, docs, opts = {}) {
   const result = /* @__PURE__ */ new Map();
@@ -197916,7 +198074,7 @@ async function flagOverlaps(repoRoot5, areas, docs, opts = {}) {
         examineOne(repoRoot5, pair.areaId, pair.a, pair.b, runner).then((verdict) => {
           if (verdict.overlap) {
             const list = result.get(pair.areaId) ?? [];
-            list.push({ docs: [pair.a.path, pair.b.path], note: verdict.note, sections: verdict.sections ?? [] });
+            list.push({ docs: [pair.a.path, pair.b.path], note: verdict.note, sections: verdict.sections ?? [], areas: [] });
             result.set(pair.areaId, list);
           }
         }).catch(() => {
@@ -197934,19 +198092,13 @@ async function flagOverlaps(repoRoot5, areas, docs, opts = {}) {
     };
     launch();
   });
-  const seenKeys = /* @__PURE__ */ new Set();
-  for (const areaId of [...result.keys()].sort()) {
-    const kept = result.get(areaId).filter((ov) => {
-      const key4 = overlapDedupKey(ov);
-      if (seenKeys.has(key4))
-        return false;
-      seenKeys.add(key4);
-      return true;
-    });
-    if (kept.length === 0)
-      result.delete(areaId);
-    else
-      result.set(areaId, kept);
+  const entries = [...result].flatMap(([area, list]) => list.map((overlap) => ({ area, overlap })));
+  const merged = dedupeCrossAreaOverlaps(entries);
+  result.clear();
+  for (const m of merged) {
+    const list = result.get(m.area) ?? [];
+    list.push({ ...m.overlap, areas: m.areas });
+    result.set(m.area, list);
   }
   for (const [areaId, list] of result) {
     list.sort((x, y) => x.docs.join() < y.docs.join() ? -1 : 1);
@@ -197954,11 +198106,6 @@ async function flagOverlaps(repoRoot5, areas, docs, opts = {}) {
   }
   return result;
 }
-function overlapDedupKey(ov) {
-  const docs = [...ov.docs].sort().join("::");
-  const secs = (ov.sections ?? []).map((s) => `${s.doc}|${s.heading}`).sort().join("::");
-  return `${docs}##${secs}`;
-}
 async function examineOne(repoRoot5, areaId, a, b, runner) {
   const cacheKey = computeCacheKey4(areaId, a, b);
   const cached = await readCache3(repoRoot5, cacheKey);
@@ -210356,6 +210503,41 @@ async function storeDecisions(repoKey, next, opts) {
   }
   await saveSpec({ repoKey, commitSha: decisionsRef(opts?.pr) }, "decisions", next);
 }
+async function getDecisions(repoKey, opts) {
+  if (opts?.pr === void 0)
+    return loadDecisions(repoKey);
+  const [base2, overlay] = await Promise.all([
+    loadDecisions(repoKey),
+    loadDecisions(repoKey, { pr: opts.pr })
+  ]);
+  return mergeDecisions(base2, overlay);
+}
+function mergeDecisions(base2, overlay) {
+  const overlayRelKeys = new Set((overlay.relations ?? []).map(relationKey));
+  const relations = [
+    ...(base2.relations ?? []).filter((r) => !overlayRelKeys.has(relationKey(r))),
+    ...overlay.relations ?? []
+  ];
+  const overlayIncludes = new Set(overlay.manualIncludes ?? []);
+  const overlayExcludes = new Set(overlay.manualExcludes ?? []);
+  const manualIncludes = uniqueStrings([
+    ...base2.manualIncludes ?? [],
+    ...overlay.manualIncludes ?? []
+  ]).filter((p2) => !overlayExcludes.has(p2));
+  const manualExcludes = uniqueStrings([
+    ...base2.manualExcludes ?? [],
+    ...overlay.manualExcludes ?? []
+  ]).filter((p2) => !overlayIncludes.has(p2));
+  const overlayAreaDocs = new Set((overlay.manualAreas ?? []).map((a) => a.doc));
+  const manualAreas = [
+    ...(base2.manualAreas ?? []).filter((a) => !overlayAreaDocs.has(a.doc)),
+    ...overlay.manualAreas ?? []
+  ];
+  return { version: 1, manualIncludes, manualExcludes, relations, manualAreas };
+}
+function uniqueStrings(items) {
+  return [...new Set(items)];
+}
 function getCorpus(repoKey) {
   return loadLatestSpec(repoKey, "corpus");
 }
@@ -210738,6 +210920,7 @@ async function runContractsValidate(options = {}) {
 // tools/cli/src/commands/spec.ts
 init_dist4();
 import path74 from "node:path";
+init_dist5();
 init_progress();
 init_registry();
 var repoRoot = (opts = {}) => opts.cwd ?? process.cwd();
@@ -210797,7 +210980,10 @@ async function runSpecScan(opts = {}) {
       O2.message(`  \u2026 (+${s.openOverlaps.length - 10} more)`);
     }
   }
-  gt("Corpus written to .truecourse/specs/corpus.json. Run `truecourse contracts generate`.");
+  const openCount = s.openOverlaps.length;
+  gt(
+    openCount === 0 ? "Corpus written to .truecourse/specs/corpus.json. Run `truecourse guard generate`." : `Corpus written to .truecourse/specs/corpus.json. ${openCount} conflict${openCount === 1 ? "" : "s"} to resolve (\`truecourse spec conflicts list\`), then \`truecourse guard generate\`.`
+  );
 }
 async function runSpecStatus(opts = {}) {
   const root2 = repoRoot(opts);
@@ -210810,19 +210996,9 @@ async function runSpecStatus(opts = {}) {
   }
   const decisions = readCorpusDecisions(root2);
   const userRels = decisions.relations ?? [];
-  const allRels = [...corpus.relations, ...userRels];
-  const covered = (a, b, area) => allRels.some((r) => {
-    const samePair = r.older === a && r.newer === b || r.older === b && r.newer === a;
-    return samePair && (r.scope === void 0 || r.scope === area);
-  });
-  let open = 0;
-  let resolved = 0;
-  for (const area of corpus.areas) {
-    for (const ov of area.overlaps) {
-      if (covered(ov.docs[0], ov.docs[1], area.id)) resolved++;
-      else open++;
-    }
-  }
+  const conflicts2 = buildCorpusConflicts(corpus, decisions);
+  const open = conflicts2.filter((c2) => !c2.resolved).length;
+  const resolved = conflicts2.length - open;
   const rows = [
     ["Docs (kept)", String(corpus.docs.length)],
     ["Areas", String(corpus.areas.length)],
@@ -210837,7 +211013,7 @@ async function runSpecStatus(opts = {}) {
     O2.message(`  ${area.id.padEnd(30)} ${area.docRefs.length} doc${area.docRefs.length === 1 ? "" : "s"}${ov}`);
   }
   gt(
-    open === 0 ? "No open overlaps \u2014 run `truecourse contracts generate`." : "Open overlaps \u2014 see `truecourse spec conflicts list`."
+    open === 0 ? "No open overlaps \u2014 run `truecourse guard generate`." : "Open overlaps \u2014 see `truecourse spec conflicts list`."
   );
 }
 async function runVerify(opts = {}) {
@@ -210954,18 +211130,9 @@ async function runInfer(opts = {}) {
 init_dist4();
 import fs69 from "node:fs";
 import path75 from "node:path";
+init_dist5();
 var root = (opts) => opts.cwd ?? process.cwd();
 var base = (ref) => ref.split("/").pop() ?? ref;
-function effectiveRelations2(corpus, repoRoot5) {
-  const user = readCorpusDecisions(repoRoot5).relations ?? [];
-  return [...corpus.relations, ...user];
-}
-function coveringRelation(rels, a, b, area) {
-  return rels.find((r) => {
-    const samePair = r.older === a && r.newer === b || r.older === b && r.newer === a;
-    return samePair && (r.scope === void 0 || r.scope === area);
-  });
-}
 function loadCorpusOrExit(repoRoot5) {
   const corpus = readCorpus(repoRoot5);
   if (!corpus) {
@@ -210977,25 +211144,17 @@ function loadCorpusOrExit(repoRoot5) {
 async function runSpecConflictsList(opts = {}) {
   const repoRoot5 = root(opts);
   const corpus = loadCorpusOrExit(repoRoot5);
-  const rels = effectiveRelations2(corpus, repoRoot5);
-  let open = 0;
-  let resolved = 0;
+  const conflicts2 = buildCorpusConflicts(corpus, readCorpusDecisions(repoRoot5));
+  const open = conflicts2.filter((c2) => !c2.resolved);
+  const resolved = conflicts2.length - open.length;
   mt("Overlaps (areas where docs may disagree)");
-  for (const area of corpus.areas) {
-    for (const ov of area.overlaps) {
-      const [a, b] = ov.docs;
-      if (coveringRelation(rels, a, b, area.id)) {
-        resolved++;
-        continue;
-      }
-      open++;
-      O2.warn(`${area.id}`);
-      O2.message(`  ${base(a)}  \u2194  ${base(b)}${ov.note ? `   \xB7 ${ov.note}` : ""}`);
-      O2.message(`  resolve: truecourse spec conflicts resolve ${area.id} --older ${a} --newer ${b} --precedence`);
-    }
+  for (const c2 of open) {
+    O2.warn(`${c2.area}`);
+    O2.message(`  ${base(c2.a)}  \u2194  ${base(c2.b)}${c2.note ? `   \xB7 ${c2.note}` : ""}`);
+    O2.message(`  resolve: truecourse spec conflicts resolve ${c2.area} --older ${c2.a} --newer ${c2.b} --precedence`);
   }
-  if (open === 0) O2.step("No open overlaps.");
-  gt(`${open} open \xB7 ${resolved} resolved. Inspect with \`spec conflicts show <area>\`.`);
+  if (open.length === 0) O2.step("No open overlaps.");
+  gt(`${open.length} open \xB7 ${resolved} resolved. Inspect with \`spec conflicts show <area>\`.`);
 }
 function excerpt(repoRoot5, ref, note, max = 20) {
   let text4;
@@ -211018,14 +211177,18 @@ async function runSpecConflictsShow(area, opts = {}) {
     pt(`No such area: ${area}. List areas with \`spec status\`.`);
     process.exit(1);
   }
-  const rels = effectiveRelations2(corpus, repoRoot5);
+  const conflicts2 = buildCorpusConflicts(corpus, readCorpusDecisions(repoRoot5));
   mt(`Overlaps in ${area}`);
   if (a.overlaps.length === 0) O2.step("(no overlaps in this area)");
   for (const ov of a.overlaps) {
     const [da, db] = ov.docs;
-    const rel = coveringRelation(rels, da, db, area);
+    const c2 = conflicts2.find(
+      (x) => x.area === area && (x.a === da && x.b === db || x.a === db && x.b === da)
+    );
     O2.warn(`${base(da)}  \u2194  ${base(db)}${ov.note ? `   \xB7 ${ov.note}` : ""}`);
-    O2.message(rel ? `  resolved \u2192 ${rel.type} (${rel.older} \u21D2 ${rel.newer})` : "  open");
+    if (c2?.relation) O2.message(`  resolved \u2192 ${c2.relation.type} (${c2.relation.older} \u21D2 ${c2.relation.newer})`);
+    else if (c2?.excludedRef) O2.message(`  resolved \u2192 ${c2.excludedRef} excluded`);
+    else O2.message("  open");
     O2.message(`  ${da}:`);
     O2.message(excerpt(repoRoot5, da, ov.note));
     O2.message(`  ${db}:`);
@@ -211044,11 +211207,15 @@ async function runSpecConflictsResolve(area, opts) {
   for (const ref of [opts.older, opts.newer]) {
     if (!known.has(ref)) return fail(`${ref} is not a doc in area ${area}. Docs: ${a.docRefs.join(", ")}`);
   }
+  const conflict = buildCorpusConflicts(corpus, readCorpusDecisions(repoRoot5)).find(
+    (c2) => c2.a === opts.older && c2.b === opts.newer || c2.a === opts.newer && c2.b === opts.older
+  );
+  const scope = conflict && conflict.areas.length > 1 ? void 0 : area;
   await addRelation(repoRoot5, {
     type: opts.type,
     older: opts.older,
     newer: opts.newer,
-    scope: area,
+    scope,
     detectedFrom: "manual",
     note: opts.note
   });
@@ -211056,7 +211223,7 @@ async function runSpecConflictsResolve(area, opts) {
   s.start("Re-scanning to apply the relation");
   await curateInProcess(repoRoot5, {});
   s.stop("Re-scanned");
-  gt(`Recorded ${opts.type}: ${opts.older} \u21D2 ${opts.newer} (scope ${area}).`);
+  gt(`Recorded ${opts.type}: ${opts.older} \u21D2 ${opts.newer} (scope ${scope ?? "all areas"}).`);
 }
 function fail(msg) {
   pt(msg);
@@ -211297,8 +211464,42 @@ import path77 from "node:path";
 init_progress();
 
 // packages/core/dist/commands/guard-in-process.js
+init_dist5();
 init_git();
 init_transport();
+var OpenConflictsError = class extends Error {
+  conflicts;
+  constructor(conflicts2) {
+    super(formatOpenConflictsMessage(conflicts2));
+    this.conflicts = conflicts2;
+    this.name = "OpenConflictsError";
+  }
+};
+function formatOpenConflictsMessage(conflicts2) {
+  const lines = [
+    `${conflicts2.length} open spec conflict${conflicts2.length === 1 ? "" : "s"} must be resolved before guard generate.`,
+    "Extracting both sides of an unresolved overlap births a red finding that is really the dispute.",
+    ""
+  ];
+  for (const c2 of conflicts2) {
+    lines.push(`  ${c2.area}`);
+    lines.push(`    ${c2.a}  \u2194  ${c2.b}`);
+    if (c2.note)
+      lines.push(`    ${c2.note}`);
+  }
+  lines.push("");
+  lines.push("Resolve them with `truecourse spec conflicts list` (or the dashboard Conflicts group), then re-run `truecourse guard generate`.");
+  return lines.join("\n");
+}
+async function assertNoOpenConflicts(repoRoot5) {
+  const corpus = await getCorpus(repoRoot5);
+  if (!corpus)
+    return;
+  const decisions = await getDecisions(repoRoot5);
+  const open = openConflicts(corpus, decisions);
+  if (open.length > 0)
+    throw new OpenConflictsError(open);
+}
 var GUARD_GENERATE_STEPS = [
   { key: "index", label: "Indexing sections" },
   { key: "extract", label: "Extracting claims" },
@@ -211331,6 +211532,7 @@ function resolveTransport2(options) {
 }
 async function guardGenerateInProcess(repoRoot5, options = {}) {
   const { tracker } = options;
+  await assertNoOpenConflicts(repoRoot5);
   if (options.onLlmEstimate) {
     const prices = await getModelPrices();
     const estimate = await estimateGuardTokens(repoRoot5, prices);
@@ -211662,6 +211864,16 @@ async function runGuardGenerate(opts = {}) {
       pt("Generate cancelled.");
       process.exit(0);
     }
+    if (e instanceof OpenConflictsError) {
+      O2.error(`${e.conflicts.length} open spec conflict${e.conflicts.length === 1 ? "" : "s"} block guard generate \u2014 resolve them first:`);
+      for (const c2 of e.conflicts) {
+        O2.message(`  ${c2.area}`);
+        O2.message(`    ${c2.a}  \u2194  ${c2.b}${c2.note ? `   \xB7 ${c2.note}` : ""}`);
+      }
+      O2.step("Resolve with `truecourse spec conflicts list` (or the dashboard Conflicts group), then re-run `truecourse guard generate`.");
+      gt("Aborted \u2014 resolve the conflicts first.");
+      process.exit(1);
+    }
     O2.error(`Guard generate failed: ${e.message}`);
     gt("Aborted.");
     process.exit(1);
@@ -212226,7 +212438,7 @@ async function runHooksRun() {
 
 // tools/cli/src/index.ts
 var program2 = new Command();
-program2.name("truecourse").version("0.7.0-next.5").description("TrueCourse CLI \u2014 analyze your repository and open the dashboard");
+program2.name("truecourse").version("0.7.0-next.6").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.5",
+  "version": "0.7.0-next.6",
   "description": "Visualize your codebase architecture as an interactive graph",
   "type": "module",
   "bin": {