@maycombhq/atticus 2.0.0-beta.12 → 2.0.0-beta.12.2

package/dist/{chunk-MLAACAES.js → chunk-DLSPFAC5.js}

@@ -5,10 +5,10 @@ var __atticusUrl = (p) => new URL("./" + p, import.meta.url).href;
 var __atticusPath = (p) => __atticusFileURLToPath(__atticusUrl(p));
 import {
   readOpenApiDocument
-} from "./chunk-34NWVIBC.js";
+} from "./chunk-UA4DLNV7.js";
 import {
   globToRegExp
-} from "./chunk-MRLCNXXR.js";
+} from "./chunk-FT2E2DHW.js";
 import {
   DECLARED_TOPIC,
   DEFAULT_CONVENTIONS,
@@ -40,7 +40,7 @@ import {
   staleCite,
   toCanonicalYaml,
   underFolders
-} from "./chunk-U25OX22K.js";
+} from "./chunk-LZABEKI6.js";
 
 // packages/verify/dist/source.js
 import { readdirSync, readFileSync, statSync } from "node:fs";
@@ -354,6 +354,29 @@ function parseReviewed(text) {
 }
 var isGlob = (path) => /[*?]/.test(path);
 
+// packages/verify/dist/conventions.js
+var SPEC_NAME = /(^|\/)[^/]*(openapi|swagger|asyncapi|api-docs)[^/]*\.(ya?ml|json|xml)$|\.oas\.(ya?ml|json)$/i;
+function rulesOf(c) {
+  const folders = underFolders(c.apiSpecFolders, { tail: "(.+/)?[^/]+\\.(ya?ml|json)$" });
+  return {
+    apiSpec: new RegExp(`${SPEC_NAME.source}|${folders.source}`, "i"),
+    notProduct: underFolders(c.notProductFolders),
+    notRead: underFolders(c.notReadFolders),
+    gatewayBundle: gatewayBundleTest(c.gatewayBundleFolders),
+    frameworks: c.frameworks
+  };
+}
+var DEFAULT_READ_RULES = rulesOf(DEFAULT_CONVENTIONS);
+var made = /* @__PURE__ */ new WeakMap();
+function readRulesOf(c) {
+  if (!c || c === DEFAULT_CONVENTIONS)
+    return DEFAULT_READ_RULES;
+  let r = made.get(c);
+  if (!r)
+    made.set(c, r = rulesOf(c));
+  return r;
+}
+
 // packages/verify/dist/apigee-policy.js
 var MAKES = {
   OAuthV1: ["oauth2"],
@@ -1334,29 +1357,6 @@ function derivedNamesAt(file, lines, line, env) {
   return out;
 }
 
-// packages/verify/dist/conventions.js
-var SPEC_NAME = /(^|\/)[^/]*(openapi|swagger|asyncapi|api-docs)[^/]*\.(ya?ml|json|xml)$|\.oas\.(ya?ml|json)$/i;
-function rulesOf(c) {
-  const folders = underFolders(c.apiSpecFolders, { tail: "(.+/)?[^/]+\\.(ya?ml|json)$" });
-  return {
-    apiSpec: new RegExp(`${SPEC_NAME.source}|${folders.source}`, "i"),
-    notProduct: underFolders(c.notProductFolders),
-    notRead: underFolders(c.notReadFolders),
-    gatewayBundle: gatewayBundleTest(c.gatewayBundleFolders),
-    frameworks: c.frameworks
-  };
-}
-var DEFAULT_READ_RULES = rulesOf(DEFAULT_CONVENTIONS);
-var made = /* @__PURE__ */ new WeakMap();
-function readRulesOf(c) {
-  if (!c || c === DEFAULT_CONVENTIONS)
-    return DEFAULT_READ_RULES;
-  let r = made.get(c);
-  if (!r)
-    made.set(c, r = rulesOf(c));
-  return r;
-}
-
 // packages/verify/dist/not-product.js
 var LOCALE_BUNDLE = /(^|\/)(i18n|l10n|locales?|lang|langs|languages|translations?)\/(.+\/)?[^/]+\.(json|ya?ml|properties)$|(^|\/)res\/values[^/]*\/(strings|plurals|arrays)\.xml$/i;
 function isLocaleBundle(path) {
@@ -1418,6 +1418,144 @@ function pageRouteMatches(file, lines, exists, path) {
   return norm(route) === norm(path);
 }
 
+// packages/verify/dist/reachable.js
+var CODE = /\.(java|kt|kts|scala|groovy|cs|vb|fs|py|rb|go|rs|php|swift|ts|tsx|js|mjs|cjs|dart)$/i;
+var MODEL_DIR = /(^|\/)(models?|dtos?|payloads?|schemas?|pojos?|beans|viewmodels?)\//i;
+var MODEL_NAME = /(dto|request|response|payload|model|body)$/i;
+var MODEL_PART = /[._-](dto|model|schema|payload|request|response)\.[^/.]+$/i;
+var MAPS_TABLE = /@Entity\b|@Table\b|@Document\b|\[Table\(|__tablename__|models\.Model\b|@Entity\(|\bgorm\.Model\b/;
+var ROOT_PART = /[._-](controller|resolver|gateway|handlers?|router|routes?|consumer|listener|subscriber|client|publisher|producer|endpoints?)\.[^/.]+$/i;
+var CLIENT_NAME = /(client|gateway|publisher|producer|sender|feign|proxy|connector)$/i;
+var CLIENT_DIR = /(^|\/)(clients?|gateways?|integrations?|publishers?|producers?|outbound)\//i;
+var base = (path) => path.slice(path.lastIndexOf("/") + 1);
+var stem = (path) => {
+  const b = base(path);
+  const dot = b.indexOf(".");
+  return dot > 0 ? b.slice(0, dot) : b;
+};
+function isModelFile(path, text) {
+  if (!CODE.test(path) || readingRank(path) === 5)
+    return false;
+  if (!MODEL_DIR.test(path) && !MODEL_NAME.test(stem(path)) && !MODEL_PART.test(path))
+    return false;
+  return text === void 0 || !MAPS_TABLE.test(text);
+}
+var ENTRY_POINT_NAME = /(controller|resource|router|routes?|handlers?|listener|consumer|subscriber|endpoints?|servlet|webhook|resolver)$/i;
+var ENTRY_POINT_DIR = /(^|\/)(controllers?|routes|routers|handlers|endpoints|listeners|consumers)\//i;
+var ENTRY_POINT_PART = /[._-](controller|resolver|handlers?|router|routes?|consumer|listener|subscriber|endpoints?)\.[^/.]+$/i;
+function isEntryPointFile(path) {
+  if (!CODE.test(path) || readingRank(path) === 5 || isModelFile(path))
+    return false;
+  return ENTRY_POINT_NAME.test(stem(path)) || ENTRY_POINT_DIR.test(path) || ENTRY_POINT_PART.test(path);
+}
+function isRootFile(path) {
+  if (!CODE.test(path) || readingRank(path) === 5 || isModelFile(path))
+    return false;
+  return readingRank(path) === 2 || isEntryPointFile(path) || ROOT_PART.test(path) || CLIENT_NAME.test(stem(path)) || CLIENT_DIR.test(path);
+}
+var DECLARES = /\b(?:class|record|interface|struct|enum|object)\s+([A-Za-z_][A-Za-z0-9_]*)|^\s*(?:export\s+)?(?:declare\s+)?type\s+([A-Za-z_][A-Za-z0-9_]*)/gm;
+var IDENT = /[A-Za-z_][A-Za-z0-9_]*/g;
+function declaredTypes(path, text) {
+  const out = [];
+  const s = stem(path);
+  if (/^[A-Z][A-Za-z0-9_]*$/.test(s))
+    out.push(s);
+  for (const m of text.matchAll(DECLARES)) {
+    const n = m[1] ?? m[2];
+    if (n && !out.includes(n))
+      out.push(n);
+  }
+  return out;
+}
+function identifiers(text) {
+  return [...new Set(text.match(IDENT) ?? [])];
+}
+var NOT_REACHED_WHY = "model classes no entry point, call or field fact reaches (ADR 0169): left out of the read; atticus map <repo> --models all reads them";
+function reachableModels(o) {
+  const texts = /* @__PURE__ */ new Map();
+  const textOf = (p) => {
+    if (!texts.has(p))
+      texts.set(p, o.read(p) ?? "");
+    return texts.get(p);
+  };
+  const ordered = readingOrder(o.paths);
+  const models = ordered.filter((p) => isModelFile(p, textOf(p))).sort();
+  const isModel = new Set(models);
+  const byName = /* @__PURE__ */ new Map();
+  const declared = /* @__PURE__ */ new Map();
+  for (const p of models) {
+    const names = declaredTypes(p, textOf(p));
+    declared.set(p, names);
+    for (const n of names)
+      byName.set(n, [...byName.get(n) ?? [], p]);
+  }
+  const known = new Set(o.paths);
+  const roots = [];
+  const addRoot = (p) => {
+    if (known.has(p) && !isModel.has(p) && !roots.includes(p))
+      roots.push(p);
+  };
+  const facts = o.facts ?? [];
+  const entries = o.from === "entries";
+  const calls2 = new Set(facts.filter((f) => f.kind === "call").map((f) => f.id));
+  for (const f of facts)
+    if (f.kind === "entry" || f.kind === "call" && !entries)
+      for (const p of citedFiles(f))
+        addRoot(p);
+  for (const p of ordered)
+    if (entries ? isEntryPointFile(p) : isRootFile(p))
+      addRoot(p);
+  const reached = /* @__PURE__ */ new Map();
+  const queue = [];
+  const reach = (names, from, own = []) => {
+    for (const n of names) {
+      if (own.includes(n))
+        continue;
+      for (const p of byName.get(n) ?? []) {
+        const r = reached.get(p);
+        if (r) {
+          if (r.from === from && !r.types.includes(n))
+            r.types.push(n);
+          continue;
+        }
+        reached.set(p, { path: p, types: [n], from });
+        queue.push(p);
+      }
+    }
+  };
+  for (const p of roots)
+    reach(identifiers(textOf(p)), p);
+  for (const f of facts) {
+    for (const p of citedFiles(f))
+      if (isModel.has(p) && !reached.has(p)) {
+        reached.set(p, { path: p, types: [...(declared.get(p) ?? []).slice(0, 1)], from: f.id });
+        queue.push(p);
+      }
+    if (f.kind === "field" && !(entries && calls2.has(f.owner)))
+      reach(identifiers([f.type ?? "", f.transform === "message type" ? f.name : ""].join(" ")), f.id);
+  }
+  const rooted = roots.length > 0 || reached.size > 0;
+  if (!rooted)
+    return {
+      rooted,
+      roots,
+      reached: models.map((p) => ({ path: p, types: declared.get(p) ?? [], from: "" })),
+      notReached: [],
+      models: models.length
+    };
+  for (let i = 0; i < queue.length; i++) {
+    const p = queue[i];
+    reach(identifiers(textOf(p)), p, declared.get(p));
+  }
+  return {
+    rooted,
+    roots,
+    reached: queue.map((p) => reached.get(p)),
+    notReached: models.filter((p) => !reached.has(p)),
+    models: models.length
+  };
+}
+
 // packages/verify/dist/method.js
 var HTTP_METHODS = /* @__PURE__ */ new Set(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]);
 function wordsOf(line) {
@@ -2199,23 +2337,23 @@ async function verifyFacts(o) {
   const accepted = facts.filter((f) => !rejected.has(f.id)).map((f) => {
     o.room?.();
     const verified = f.by === "person" && f.verified !== "none" ? f.verified : "line";
-    const base = { ...f, verified, cite: fixQuote(f.cite) };
-    if (base.kind === "entry" && base.auth !== void 0 && !base.authCite && f.by !== "person")
+    const base2 = { ...f, verified, cite: fixQuote(f.cite) };
+    if (base2.kind === "entry" && base2.auth !== void 0 && !base2.authCite && f.by !== "person")
       authUncited.push({
-        id: base.id,
-        auth: base.auth,
-        cite: `${base.cite.file}:${base.cite.line}`
+        id: base2.id,
+        auth: base2.auth,
+        cite: `${base2.cite.file}:${base2.cite.line}`
       });
-    const unseen = methodUnseenOf(base, linesOf2, factById);
+    const unseen = methodUnseenOf(base2, linesOf2, factById);
     if (unseen)
       methodUnseen.push(unseen);
-    if (base.kind === "flow")
+    if (base2.kind === "flow")
       return {
-        ...base,
-        steps: base.steps.map((s) => ({ ...s, cite: fixQuote(s.cite) })),
-        errors: base.errors.map((e) => ({ ...e, cite: fixQuote(e.cite) }))
+        ...base2,
+        steps: base2.steps.map((s) => ({ ...s, cite: fixQuote(s.cite) })),
+        errors: base2.errors.map((e) => ({ ...e, cite: fixQuote(e.cite) }))
       };
-    return base;
+    return base2;
   });
   const excludeRes = (o.exclude ?? []).map(globToRegExp);
   const sources = [];
@@ -2284,6 +2422,11 @@ async function verifyFacts(o) {
         refuse("is not in the repo at this commit; name a file you read");
       continue;
     }
+    const entryPoints = re ? matched.filter((p) => isSource.has(p) && !touched.has(p) && isEntryPointFile(p)) : [];
+    if (entryPoints.length) {
+      refuse(`covers ${entryPoints[0]}, an entry point (a controller, route, handler or listener)${entryPoints.length > 1 ? ` and ${entryPoints.length - 1} more` : ""} no fact cites: read it, and write its entries and the fields of the classes it takes and returns; never mark an entry point reviewed with a glob (name it alone if it truly holds nothing)`);
+      continue;
+    }
     const files = matched.filter((p) => isSource.has(p) && !touched.has(p)).sort();
     for (const p of files)
       reviewedSet.add(p);
@@ -2293,7 +2436,9 @@ async function verifyFacts(o) {
   }
   const read = sources.filter((p) => touched.has(p)).sort();
   const reviewedFiles = sources.filter((p) => reviewedSet.has(p)).sort();
-  const unknown = sources.filter((p) => !touched.has(p) && !reviewedSet.has(p)).sort();
+  const leftOut = new Set(o.notReached ?? []);
+  const notReached = sources.filter((p) => leftOut.has(p) && !touched.has(p) && !reviewedSet.has(p)).sort();
+  const unknown = sources.filter((p) => !touched.has(p) && !reviewedSet.has(p) && !leftOut.has(p)).sort();
   const total = read.length + reviewedFiles.length + unknown.length;
   const ratio = total === 0 ? 1 : Math.round(read.length / total * 1e3) / 1e3;
   const ix = indexFacts(accepted);
@@ -2326,7 +2471,14 @@ async function verifyFacts(o) {
     accepted,
     // a rejected fact goes back as it was read, at its own commit, even one that was carried
     rejected: [...rejected.values()].map((r) => carriedFrom.has(r.fact.id) ? { ...r, fact: { ...r.fact, commit: carriedFrom.get(r.fact.id) } } : r).sort((a, b) => a.fact.id < b.fact.id ? -1 : a.fact.id > b.fact.id ? 1 : 0),
-    coverage: { read, reviewed: reviewedFiles, unknown, excluded: excluded.sort(), ratio },
+    coverage: {
+      read,
+      reviewed: reviewedFiles,
+      unknown,
+      excluded: excluded.sort(),
+      notReached,
+      ratio
+    },
     redacted,
     quotesDropped,
     carried: accepted.flatMap((f) => carriedFrom.has(f.id) ? [{ id: f.id, from: carriedFrom.get(f.id) }] : []),
@@ -2354,10 +2506,10 @@ var BOUNDARY_NAME = /(client|gateway|repository|repo|dao|mapper|entity|model|dto
 var BOUNDARY_FILE = /\.(sql|proto|graphql|gql|avsc|wsdl|xsd)$|(^|\/)(openapi|swagger)[^/]*\.(ya?ml|json)$/i;
 var BOUNDARY_DIR = /(^|\/)(clients?|gateways?|repositories|dao|models?|entities|dto|migrations?)\//i;
 var TEST = /(^|\/)(test|tests|__tests__|spec|specs|e2e|it)\/|[._-](test|spec)\.[^/.]+$|(Test|Tests|IT|Spec)\.[^/.]+$|(^|\/)test_[^/]+$|_test\.go$/;
-var stem = (path) => {
-  const base = path.slice(path.lastIndexOf("/") + 1);
-  const dot = base.indexOf(".");
-  return dot > 0 ? base.slice(0, dot) : base;
+var stem2 = (path) => {
+  const base2 = path.slice(path.lastIndexOf("/") + 1);
+  const dot = base2.indexOf(".");
+  return dot > 0 ? base2.slice(0, dot) : base2;
 };
 function readingRank(path) {
   if (TEST.test(path))
@@ -2366,7 +2518,7 @@ function readingRank(path) {
     return 0;
   if (CONFIG.test(path))
     return 1;
-  const s = stem(path);
+  const s = stem2(path);
   if (ENTRY_NAME.test(s) || ENTRY_DIR.test(path))
     return 2;
   if (BOUNDARY_NAME.test(s) || BOUNDARY_FILE.test(path) || BOUNDARY_DIR.test(path))
@@ -2482,6 +2634,8 @@ function planBatches(source, o) {
   const rules = readRulesOf(o.conventions);
   const excludeRes = (o.exclude ?? []).map(globToRegExp);
   const excluded = [];
+  const leaveOut = new Set(o.reach?.leaveOut ?? []);
+  const notReached = [];
   const paths = [];
   const texts = /* @__PURE__ */ new Map();
   for (const p of source.list()) {
@@ -2497,6 +2651,10 @@ function planBatches(source, o) {
     }
     if (!text.trim())
       continue;
+    if (leaveOut.has(p)) {
+      notReached.push(p);
+      continue;
+    }
     paths.push(p);
     texts.set(p, text);
   }
@@ -2512,7 +2670,7 @@ function planBatches(source, o) {
   const slices = [];
   let lines = 0;
   let leastRoom = room;
-  for (const path of readingOrder(paths)) {
+  for (const path of reachOrder(paths, o.reach?.first)) {
     const kinds2 = fileKinds(path, rules);
     const left = room - overhead(kinds2);
     leastRoom = Math.min(leastRoom, left);
@@ -2561,9 +2719,20 @@ function planBatches(source, o) {
     tokens: slices.reduce((n, s) => n + s.tokens, 0),
     batches,
     excluded: excluded.sort(),
-    leastRoom
+    leastRoom,
+    notReached: notReached.sort()
   };
 }
+function reachOrder(paths, first) {
+  const order = readingOrder(paths);
+  if (!first?.length)
+    return order;
+  const has = new Set(paths);
+  const head = order.filter((p) => readingRank(p) <= 1);
+  const lead = [...new Set(first)].filter((p) => has.has(p) && readingRank(p) > 1);
+  const taken = /* @__PURE__ */ new Set([...head, ...lead]);
+  return [...head, ...lead, ...order.filter((p) => !taken.has(p))];
+}
 
 // packages/verify/dist/vendored.js
 var LICENSE_FILE = /^(LICEN[CS]E|COPYING)([._-][^/]*)?$/i;
@@ -2871,27 +3040,101 @@ function unitsOf(dir, fs, room) {
     out.push(...unitsOf(child, children.get(child), room));
   return out;
 }
-function planParts(files, room = SESSION_TOKENS) {
+function groupUnits(dir, fs, room, holds) {
+  const prefix = dir ? `${dir}/` : "";
+  const direct = [];
+  const children = /* @__PURE__ */ new Map();
+  for (const f of fs) {
+    const rest = f.path.slice(prefix.length);
+    const slash = rest.indexOf("/");
+    if (slash < 0)
+      direct.push(f);
+    else {
+      const child = prefix + rest.slice(0, slash);
+      children.set(child, [...children.get(child) ?? [], f]);
+    }
+  }
+  if (dir && holds(dir, true, fs.length) && (sum(fs) <= room || !children.size))
+    return [{ glob: `${dir}/**`, files: fs.length, tokens: sum(fs) }];
+  const out = [];
+  if (direct.length) {
+    if (holds(dir, false, direct.length))
+      out.push({ glob: `${prefix}*`, files: direct.length, tokens: sum(direct) });
+    else
+      for (const f of [...direct].sort((a, b) => byPath2(a.path, b.path)))
+        out.push({ glob: f.path, files: 1, tokens: f.tokens });
+  }
+  for (const child of [...children.keys()].sort(byPath2))
+    out.push(...groupUnits(child, children.get(child), room, holds));
+  return out;
+}
+function rangeUnits(f, room) {
+  return lineRanges({ ...f, lines: f.lines }, room).map((r, i) => ({
+    glob: `${f.path}#L${r.from}-L${r.to}`,
+    files: i === 0 ? 1 : 0,
+    tokens: r.tokens
+  }));
+}
+function orderedUnits(files, room, o) {
+  const isBig = (f) => f.tokens > room && (f.lines ?? 0) > 1;
+  const byFile = new Map(files.map((f) => [f.path, f]));
+  const head = new Set(o.head.filter((p) => byFile.has(p)));
+  const models = [...new Set(o.models)].filter((p) => byFile.has(p) && !head.has(p));
+  const inModels = new Set(models);
+  const rest = files.filter((f) => !head.has(f.path) && !inModels.has(f.path));
+  const all2 = [...files.map((f) => f.path), ...o.leftOut];
+  const counts = () => {
+    const deep = /* @__PURE__ */ new Map();
+    const own = /* @__PURE__ */ new Map();
+    const count = (m, k) => m.set(k, (m.get(k) ?? 0) + 1);
+    for (const p of all2) {
+      const parts = p.split("/");
+      count(own, parts.slice(0, -1).join("/"));
+      for (let d = 1; d < parts.length; d++)
+        count(deep, parts.slice(0, d).join("/"));
+    }
+    return (dir, isDeep, n) => (isDeep ? deep.get(dir) : own.get(dir)) === n;
+  };
+  const holds = counts();
+  const unitsOfGroup = (group) => {
+    const small = group.filter((f) => !isBig(f)).sort((a, b) => byPath2(a.path, b.path));
+    const out = groupUnits("", small, room, holds);
+    for (const f of group.filter(isBig))
+      out.push(...rangeUnits(f, room));
+    return out;
+  };
+  return [
+    ...unitsOfGroup(files.filter((f) => head.has(f.path))),
+    ...models.flatMap((p) => {
+      const f = byFile.get(p);
+      return isBig(f) ? rangeUnits(f, room) : [{ glob: p, files: 1, tokens: f.tokens }];
+    }),
+    ...unitsOfGroup(rest)
+  ];
+}
+function planParts(files, room = SESSION_TOKENS, order) {
   const total = sum(files);
   if (total <= room)
     return [];
-  const big = files.filter((f) => f.tokens > room && (f.lines ?? 0) > 1);
-  const rest = files.filter((f) => !big.includes(f));
-  const ranges = [];
-  for (const f of big)
-    for (const [i, r] of lineRanges({ ...f, lines: f.lines }, room).entries())
-      ranges.push({
-        glob: `${f.path}#L${r.from}-L${r.to}`,
-        files: i === 0 ? 1 : 0,
-        tokens: r.tokens,
-        key: `${f.path}\0${String(r.start).padStart(12, "0")}`
-      });
-  const sorted = [...rest].sort((a, b) => byPath2(a.path, b.path));
-  const keyOf = (g) => g.replace(/\/?\*\*?$/, "");
-  const units = [
-    ...unitsOf("", sorted, room).map((u) => ({ ...u, key: keyOf(u.glob) })),
-    ...ranges
-  ].sort((a, b) => byPath2(a.key, b.key));
+  let units;
+  if (order)
+    units = orderedUnits(files, room, order);
+  else {
+    const big = files.filter((f) => f.tokens > room && (f.lines ?? 0) > 1);
+    const rest = files.filter((f) => !big.includes(f));
+    const ranges = [];
+    for (const f of big)
+      for (const [i, r] of lineRanges({ ...f, lines: f.lines }, room).entries())
+        ranges.push({
+          glob: `${f.path}#L${r.from}-L${r.to}`,
+          files: i === 0 ? 1 : 0,
+          tokens: r.tokens,
+          key: `${f.path}\0${String(r.start).padStart(12, "0")}`
+        });
+    const sorted = [...rest].sort((a, b) => byPath2(a.path, b.path));
+    const keyOf = (g) => g.replace(/\/?\*\*?$/, "");
+    units = [...unitsOf("", sorted, room).map((u) => ({ ...u, key: keyOf(u.glob) })), ...ranges].sort((a, b) => byPath2(a.key, b.key)).map(({ key: _k, ...u }) => u);
+  }
   const target = total / Math.ceil(total / room);
   const parts = [];
   let current;
@@ -2920,7 +3163,7 @@ function split(cite2) {
   const m = /^(.+):(\d+)$/.exec(cite2);
   return m ? { file: m[1], line: Number(m[2]) } : void 0;
 }
-function planGaps(from, size, room) {
+function planGaps(from, size, room, o = {}) {
   const whole = new Set(from.unknown ?? []);
   const lines = /* @__PURE__ */ new Map();
   const note = (cite2, why) => {
@@ -2936,14 +3179,15 @@ function planGaps(from, size, room) {
   for (const h of from.reviewedHolds ?? [])
     for (const s of h.skipped)
       note(s.cite, `writes the ${s.kind} ${quoted2(s.value)}, but ${quoted2(h.path)} is reviewed as ${quoted2(h.why)}: write its fact, or narrow the reviewed line`);
-  for (const o of from.specOpsUncovered ?? [])
-    note(o.cite, `declares ${o.method} ${quoted2(o.path)}, which no entry covers: find the code that serves it`);
+  for (const o2 of from.specOpsUncovered ?? [])
+    note(o2.cite, `declares ${o2.method} ${quoted2(o2.path)}, which no entry covers: find the code that serves it`);
   for (const e of from.entriesNoFlowFollows ?? [])
     note(e.cite, `is ${e.id} (${[e.entryType, e.method, quoted2(e.path)].filter(Boolean).join(" ")}), which no flow follows: write its flow`);
   const unlisted = Math.max(0, (from.skippedCount ?? 0) - (from.skipped?.length ?? 0)) + Math.max(0, (from.specOpsUncoveredCount ?? 0) - (from.specOpsUncovered?.length ?? 0));
   const gone = [];
   const reads = [];
-  const files = [.../* @__PURE__ */ new Set([...whole, ...lines.keys()])].sort(byPath3);
+  const named = [.../* @__PURE__ */ new Set([...whole, ...lines.keys()])].sort(byPath3);
+  const files = o.first?.length ? reachOrder(named, o.first) : named;
   for (const file of files) {
     const sz = size(file);
     if (!sz) {
@@ -3499,8 +3743,8 @@ function changeView(records2, change, flows, known = []) {
   const nodes = [];
   for (const id of comps) {
     const sys = c.components.has(id) ? c.systemOf(id) : void 0;
-    const base = c.components.has(id) || c.isSystem(id) ? c.endNode(id, sys) : { id, label: id, kind: "component" };
-    const { legend: _status, ...rest } = base;
+    const base2 = c.components.has(id) || c.isSystem(id) ? c.endNode(id, sys) : { id, label: id, kind: "component" };
+    const { legend: _status, ...rest } = base2;
     nodes.push({ ...rest, label: marked(rest.label, legends.get(id)), ...withMark(id) });
   }
   for (const t of tables) {
@@ -3596,14 +3840,14 @@ var Ids = class {
     const known = this.map.get(key);
     if (known)
       return known;
-    let base = raw.replace(/[^A-Za-z0-9_]/g, "_");
-    if (!/^[A-Za-z]/.test(base))
-      base = `n_${base}`;
-    if (RESERVED.has(base.toLowerCase()))
-      base = `${base}_`;
-    let id = base;
+    let base2 = raw.replace(/[^A-Za-z0-9_]/g, "_");
+    if (!/^[A-Za-z]/.test(base2))
+      base2 = `n_${base2}`;
+    if (RESERVED.has(base2.toLowerCase()))
+      base2 = `${base2}_`;
+    let id = base2;
     for (let n = 2; this.used.has(id); n++)
-      id = `${base}_${n}`;
+      id = `${base2}_${n}`;
     this.used.add(id);
     this.map.set(key, id);
     return id;
@@ -3792,8 +4036,8 @@ function nodeStyle(n) {
     return styleText(SHAPES.topic, legend);
   if (n.boundary === "vendor")
     return styleText(SHAPES.vendor, n.kind === "component" ? { atticusKind: "component" } : {}, legend);
-  const base = n.kind === "system" ? SHAPES.system : SHAPES.component;
-  return styleText(base, n.boundary ? BOUNDARY[n.boundary] : void 0, legend);
+  const base2 = n.kind === "system" ? SHAPES.system : SHAPES.component;
+  return styleText(base2, n.boundary ? BOUNDARY[n.boundary] : void 0, legend);
 }
 function groupStyle(g) {
   return styleText(SHAPES.group, g.kind === "datastore" ? { atticusKind: "datastore-group" } : {}, g.boundary ? { strokeColor: BOUNDARY[g.boundary].strokeColor } : void 0, g.legend ? LEGEND[g.legend] : void 0);
@@ -3884,14 +4128,14 @@ function edgeStyle(e) {
 }
 var compress = (xml) => deflateRawSync(Buffer.from(encodeURIComponent(xml), "utf8"), { level: 9 }).toString("base64");
 function shapeLibrary() {
-  const base = [
+  const base2 = [
     ["System", SHAPES.system, W, H],
     ["Component", SHAPES.component, W, H],
     ["Vendor", SHAPES.vendor, W, H + 20],
     ["Data store", SHAPES.datastore, 120, 80],
     ["Topic", SHAPES.topic, W, H]
   ];
-  const entries = base.flatMap(([title, style, w, h]) => [void 0, "new", "modify", "retire"].map((legend) => {
+  const entries = base2.flatMap(([title, style, w, h]) => [void 0, "new", "modify", "retire"].map((legend) => {
     const value = attr(title);
     const st = attr(styleText(style, legend ? LEGEND[legend] : void 0));
     const xml = `<mxGraphModel><root><mxCell id="0"/><mxCell id="1" parent="0"/><mxCell id="2" value="${value}" style="${st}" vertex="1" parent="1"><mxGeometry width="${w}" height="${h}" as="geometry"/></mxCell></root></mxGraphModel>`;
@@ -4834,13 +5078,13 @@ function codeLinkerFor(o) {
       web = `https://${scp[1]}/${scp[2]}`;
   }
   if (web) {
-    const base = web.replace(/\/+$/, "").replace(/\.git$/, "");
-    const ado = /(^https?:\/\/dev\.azure\.com\/)|(\.visualstudio\.com\/)/i.test(base);
+    const base2 = web.replace(/\/+$/, "").replace(/\.git$/, "");
+    const ado = /(^https?:\/\/dev\.azure\.com\/)|(\.visualstudio\.com\/)/i.test(base2);
     return (path, line, commit) => {
       const p = encodeURI(path);
       if (ado)
-        return `${base}?path=/${p}${commit ? `&version=GC${commit}` : ""}${line ? `&line=${line}` : ""}`;
-      return `${base}/blob/${commit ?? "HEAD"}/${p}${line ? `#L${line}` : ""}`;
+        return `${base2}?path=/${p}${commit ? `&version=GC${commit}` : ""}${line ? `&line=${line}` : ""}`;
+      return `${base2}/blob/${commit ?? "HEAD"}/${p}${line ? `#L${line}` : ""}`;
     };
   }
   const dir = (o.dir ?? "").replace(/\/+$/, "");
@@ -5289,8 +5533,8 @@ function ctxOf(i, file) {
 }
 function renderMap(i) {
   const files = {};
-  const base = ctxOf(i, "map.md");
-  for (const comp of [...base.comps].sort(cmp2)) {
+  const base2 = ctxOf(i, "map.md");
+  for (const comp of [...base2.comps].sort(cmp2)) {
     const yaml = openApiOf(i, comp);
     if (yaml)
       files[`contracts/${comp}.openapi.yaml`] = yaml;
@@ -5304,18 +5548,18 @@ function renderMap(i) {
     HEADER2(i.repo, "the catalog and its specs"),
     "",
     ...aboutLine(i.about, i.repo),
-    ...builtOnLine(base),
+    ...builtOnLine(base2),
     trustLine(i.trust, i.repo),
     "",
-    ...section("What it serves", serves(base)),
-    ...section("What it calls", calls(base)),
-    ...section("What it stores", stores(base)),
-    ...section("Where it runs", deploys(base)),
-    ...section("Config that names other systems", config(base)),
-    ...i.terms?.length ? section("Terms", terms(base)) : [],
-    ...section("Flows", flowsList(base)),
-    ...section("Contracts", contracts(base, files)),
-    ...section("Open questions", openQuestions(base))
+    ...section("What it serves", serves(base2)),
+    ...section("What it calls", calls(base2)),
+    ...section("What it stores", stores(base2)),
+    ...section("Where it runs", deploys(base2)),
+    ...section("Config that names other systems", config(base2)),
+    ...i.terms?.length ? section("Terms", terms(base2)) : [],
+    ...section("Flows", flowsList(base2)),
+    ...section("Contracts", contracts(base2, files)),
+    ...section("Open questions", openQuestions(base2))
   ].join("\n");
   return Object.fromEntries(Object.entries(files).sort(([a], [b]) => cmp2(a, b)));
 }
@@ -5525,7 +5769,7 @@ function repairFormSlips(facts, bad, onFile = []) {
 }
 
 // packages/verify/dist/house-imports.js
-var CODE = /\.(java|kt|kts|scala|groovy|cs|vb|fs|ts|tsx|js|jsx|mjs|cjs|vue|svelte|py|go|rb|php|swift)$/i;
+var CODE2 = /\.(java|kt|kts|scala|groovy|cs|vb|fs|ts|tsx|js|jsx|mjs|cjs|vue|svelte|py|go|rb|php|swift)$/i;
 var IMPORTS = [
   // Java, Kotlin, Scala, Groovy, Python's `import a.b`, Go's one-line import
   /^\s*import\s+(?:static\s+)?([A-Za-z_][\w.]*)/,
@@ -5573,7 +5817,7 @@ function houseImportsUntaught(source, o) {
   const prefixes = o.prefixes.map(lower);
   const taught = o.taught.map(lower);
   const found = /* @__PURE__ */ new Map();
-  const paths = source.list().filter((p) => CODE.test(p) && !rules.notRead.test(p) && !(o.exclude ?? []).some((re) => re.test(p)) && isSourceFile(p, "", void 0, rules)).sort();
+  const paths = source.list().filter((p) => CODE2.test(p) && !rules.notRead.test(p) && !(o.exclude ?? []).some((re) => re.test(p)) && isSourceFile(p, "", void 0, rules)).sort();
   for (const p of paths) {
     const text = source.read(p);
     if (text === void 0)
@@ -5623,9 +5867,6 @@ export {
   readRulesOf,
   lineRangeOf,
   parseReviewed,
-  sameCommit,
-  staleMessage,
-  verifyFacts,
   readingRank,
   FILE_KINDS,
   fileKinds,
@@ -5633,6 +5874,12 @@ export {
   numberedSlice,
   sliceText,
   planBatches,
+  isEntryPointFile,
+  NOT_REACHED_WHY,
+  reachableModels,
+  sameCommit,
+  staleMessage,
+  verifyFacts,
   SHOWN_PROPOSALS,
   proposeExclusions,
   exclusionYaml,