@maycombhq/atticus 2.0.0-beta.11 → 2.0.0-beta.12.1

package/dist/{chunk-XPWSNKF3.js → chunk-7VAMO66T.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-GVFUEGGM.js";
+} from "./chunk-34NWVIBC.js";
 import {
   globToRegExp
-} from "./chunk-FMRMTI7W.js";
+} from "./chunk-MRLCNXXR.js";
 import {
   DECLARED_TOPIC,
   DEFAULT_CONVENTIONS,
@@ -40,7 +40,7 @@ import {
   staleCite,
   toCanonicalYaml,
   underFolders
-} from "./chunk-JMOLB347.js";
+} from "./chunk-U25OX22K.js";
 
 // packages/verify/dist/source.js
 import { readdirSync, readFileSync, statSync } from "node:fs";
@@ -138,8 +138,11 @@ var FRAMEWORKS = [
 var KNOWN = [
   // Java and Kotlin
   ["spring-boot*", { name: "spring-boot", topic: "spring", shape: "rest" }],
-  // the annotation a Spring Boot app's main class carries, which a reader may cite instead
+  // the annotations a Spring Boot app's main class carries, which a reader may cite instead
+  // (matched by `annotationKey`, so bare, qualified or with arguments)
   ["@springbootapplication", { name: "spring-boot", topic: "spring", shape: "rest" }],
+  ["@enableautoconfiguration", { name: "spring-boot", topic: "spring", shape: "rest" }],
+  ["@quarkusmain", { name: "quarkus", topic: "quarkus" }],
   ["spring-webmvc", { name: "spring", topic: "spring", shape: "rest" }],
   ["spring-webflux", { name: "spring", topic: "spring", shape: "rest" }],
   ["spring-web", { name: "spring", topic: "spring", shape: "rest" }],
@@ -191,6 +194,10 @@ function declarationKey(declared) {
   const name = colon.split(/[=<>~!,\s[]/)[0] ?? colon;
   return name.replace(/^['"]|['"]$/g, "");
 }
+function annotationKey(declared) {
+  const m = /^@?(?:[a-z_$][\w$]*\.)*([A-Z][\w$]*)\s*(?:\(.*)?$/s.exec(declared.trim());
+  return m ? `@${m[1].toLowerCase()}` : void 0;
+}
 function houseKnown(extra) {
   return extra.map((e) => [
     e.declares.toLowerCase(),
@@ -205,19 +212,27 @@ function frameworkOf(declared, extra = []) {
   const key = declarationKey(declared);
   if (!key)
     return void 0;
-  for (const [pattern, known] of extra.length ? [...houseKnown(extra), ...KNOWN] : KNOWN) {
+  const table = extra.length ? [...houseKnown(extra), ...KNOWN] : KNOWN;
+  for (const [pattern, known] of table) {
     const star = pattern.endsWith("*");
     const p = star ? pattern.slice(0, -1) : pattern;
     if (star ? key.startsWith(p) : key === p)
       return known;
   }
+  const ann = annotationKey(declared);
+  if (ann) {
+    for (const [pattern, known] of table)
+      if (pattern === ann)
+        return known;
+  }
   return void 0;
 }
 function frameworkNameProblem(f, extra = []) {
   const known = frameworkOf(f.cite.value, extra);
   const name = f.name.trim().toLowerCase();
   if (known) {
-    return name === known.name.toLowerCase() ? void 0 : `names the framework "${f.name}", but ${f.cite.file}:${f.cite.line} declares ${f.cite.value}, which is ${known.name}`;
+    const legacy = annotationKey(f.cite.value) === `@${name}`;
+    return name === known.name.toLowerCase() || legacy ? void 0 : `names the framework "${f.name}", but ${f.cite.file}:${f.cite.line} declares ${f.cite.value}, which is ${known.name}`;
   }
   const key = declarationKey(f.cite.value);
   if (declarationKey(name) === key || name === key)
@@ -339,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"],
@@ -1319,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) {
@@ -1403,6 +1418,142 @@ 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 ?? [];
+  for (const f of facts)
+    if (f.kind === "entry" || f.kind === "call")
+      for (const p of citedFiles(f))
+        addRoot(p);
+  for (const p of ordered)
+    if (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")
+      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) {
@@ -1495,6 +1646,17 @@ var topicContext = (line) => {
   const w = wordsOf2(line);
   return w.some((x) => TOPIC_WORDS.has(x)) || w.join(" ").includes("routing key");
 };
+var BUILD_KEY_WORDS = new Set("scm git gitlab github bitbucket repository repositories repo registry mirror mirrors nexus artifactory snapshot snapshots distribution maven npm nuget pypi sonar sonarqube jenkins ci".split(" "));
+var BUILD_BLOCK_TAG = /<(\/?)(repositories|repository|pluginRepositories|pluginRepository|snapshotRepository|distributionManagement|scm|mirrors|mirror|site)\b[^>]*?(\/?)>/gi;
+var BUILD_BLOCK_OPEN = /\b(repositories|publishing|pluginManagement|dependencyResolutionManagement)\s*\{/;
+var keysBefore = (prefix) => [
+  ...[...prefix.matchAll(/<([A-Za-z][\w:.-]*)/g)].map((m) => m[1]),
+  ...[...prefix.matchAll(/["']?([A-Za-z][\w.-]*)["']?\s*[:=]/g)].map((m) => m[1]),
+  ...[...prefix.matchAll(/\b([A-Za-z]\w*)\s*\{/g)].map((m) => m[1])
+];
+var isBuildUrl = (u, prefix) => /\.git\/?$/i.test(u) || /\bscm:\w+:$/i.test(prefix) || keysBefore(prefix).some((k) => wordsOf2(k).some((w) => BUILD_KEY_WORDS.has(w)));
+var HEADER_ARG = /header\w*\s*(?:\.\s*\w+\s*)?\(\s*(?:(?:value|name)\s*=\s*)?$/i;
+var isHeaderName = (s, prefix) => /^x-/i.test(s) || HEADER_ARG.test(prefix.replace(/["'`]$/, ""));
 var cleanUrl = (u) => u.replace(/[.:]+$/, "").replace(/^([a-z0-9+.-]+:\/\/)[^/@\s]+@/i, "$1<redacted>@");
 var hostOf = (u) => /^[a-z0-9+.-]+:\/\/([^/:?#]+)/i.exec(u)?.[1] ?? "";
 function pathOf(s) {
@@ -1544,9 +1706,19 @@ function codeOf(raw, state) {
 function candidatesIn(path, lines) {
   const out = [];
   const state = {};
+  let xmlDepth = 0;
+  let braceDepth = 0;
   lines.forEach((raw, i) => {
     const wasBlock = state.block !== void 0;
     let code2 = codeOf(raw, state);
+    const inBuild = xmlDepth > 0 || braceDepth > 0;
+    for (const m of code2.matchAll(BUILD_BLOCK_TAG))
+      if (!m[3])
+        xmlDepth = Math.max(0, xmlDepth + (m[1] ? -1 : 1));
+    if (braceDepth > 0 || BUILD_BLOCK_OPEN.test(code2)) {
+      const from = braceDepth > 0 ? code2 : code2.slice(BUILD_BLOCK_OPEN.exec(code2).index);
+      braceDepth = Math.max(0, braceDepth + (from.match(/\{/g)?.length ?? 0) - (from.match(/\}/g)?.length ?? 0));
+    }
     if (!code2.trim())
       return;
     if (!wasBlock && isCommentLine(raw))
@@ -1565,19 +1737,24 @@ function candidatesIn(path, lines) {
     };
     const context = topicContext(code2);
     const urls = [];
+    const opened = inBuild || xmlDepth > 0 || braceDepth > 0;
     for (const m of code2.matchAll(URL_RE)) {
       const u = cleanUrl(m[0]);
-      if (!STANDARD_HOST.test(hostOf(u)))
+      const build = opened || isBuildUrl(u, code2.slice(0, m.index));
+      if (!build && !STANDARD_HOST.test(hostOf(u)))
         add("url", u);
       urls.push(m[0]);
     }
-    const strings2 = [...code2.matchAll(QUOTED)].map((m) => m[2]);
+    const strings2 = [...code2.matchAll(QUOTED)].map((m) => ({
+      s: m[2],
+      before: code2.slice(0, m.index + 1)
+    }));
     const kv = KEY_VALUE.exec(code2);
     if (kv)
-      strings2.push(kv[2]);
+      strings2.push({ s: kv[2], before: "" });
     for (const m of code2.matchAll(ELEMENT_TEXT))
-      strings2.push(m[2]);
-    for (const s of strings2) {
+      strings2.push({ s: m[2], before: "" });
+    for (const { s, before } of strings2) {
       if (urls.some((u) => s.includes(u) || u.includes(s)))
         continue;
       const p = pathOf(s);
@@ -1586,7 +1763,7 @@ function candidatesIn(path, lines) {
         continue;
       }
       const t = topicOf(s, context);
-      if (t)
+      if (t && !isHeaderName(t, before))
         add("topic", t);
     }
   });
@@ -2158,23 +2335,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 = [];
@@ -2243,6 +2420,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);
@@ -2252,7 +2434,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);
@@ -2285,7 +2469,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) }] : []),
@@ -2313,10 +2504,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))
@@ -2325,7 +2516,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))
@@ -2441,6 +2632,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()) {
@@ -2456,6 +2649,10 @@ function planBatches(source, o) {
     }
     if (!text.trim())
       continue;
+    if (leaveOut.has(p)) {
+      notReached.push(p);
+      continue;
+    }
     paths.push(p);
     texts.set(p, text);
   }
@@ -2471,7 +2668,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);
@@ -2520,9 +2717,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;
@@ -2830,27 +3038,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;
@@ -2879,7 +3161,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) => {
@@ -2895,14 +3177,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) {
@@ -3458,8 +3741,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) {
@@ -3555,14 +3838,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;
@@ -3751,8 +4034,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);
@@ -3843,14 +4126,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>`;
@@ -4793,13 +5076,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(/\/+$/, "");
@@ -5248,8 +5531,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;
@@ -5263,18 +5546,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)));
 }
@@ -5484,7 +5767,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.]*)/,
@@ -5532,7 +5815,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)
@@ -5582,14 +5865,18 @@ export {
   readRulesOf,
   lineRangeOf,
   parseReviewed,
-  sameCommit,
-  staleMessage,
-  verifyFacts,
+  readingRank,
   FILE_KINDS,
+  fileKinds,
   kindsOf,
   numberedSlice,
   sliceText,
   planBatches,
+  NOT_REACHED_WHY,
+  reachableModels,
+  sameCommit,
+  staleMessage,
+  verifyFacts,
   SHOWN_PROPOSALS,
   proposeExclusions,
   exclusionYaml,