create-ailk 0.24.0 → 0.26.0

package/templates/tools/lint-architecture.ts

@@ -23,7 +23,24 @@
  *     patches an in-scope package; and every declaration of one in-scope
  *     package (dependencies, devDependencies, peerDependencies,
  *     optionalDependencies, `pnpm.overrides`, `resolutions`, workspace
- *     `overrides`) uses the same caret range.
+ *     `overrides`) uses the same caret range;
+ *   - the `customizations` rules, when declared (#9223) — every code file
+ *     under `apps/` the scaffold did not ship maps to an entry in
+ *     `customizations.yaml` recording its request and its build-in decision:
+ *     a file in neither `.ailk-template-files.json` nor `scaffold_paths` and
+ *     matched by no entry is refused; an `undecided` entry passes only while
+ *     `undecided_ok_until` is in the future; a `build-in: ailk#N` entry whose
+ *     paths still match the site's own test files is refused (tests belong
+ *     in AILK); a malformed or missing manifest is refused naming the field.
+ *     With no template record the lint warns and skips the file rules;
+ *   - the shadow-copy rule (#9201), under the same block and record — a
+ *     site-authored file under `apps/` most of whose substantive lines are a
+ *     module's that an installed `@working-theory/*` package ships (found
+ *     through its export map) is a copy, edited or not, and is refused naming
+ *     the file and the `<package>/<subpath>` module it shadows; a wrapper that
+ *     imports and re-exports or composes the module passes. An installed
+ *     package that is one of this site's own workspaces (`apps/*`, `database`
+ *     — pnpm may hoist one) is its source, not a shipped module (#9558).
  *
  * An import target is checked only when it is a workspace present in this
  * repo (`apps/*`, `database`); `@working-theory/*` libraries install from npm
@@ -31,16 +48,30 @@
  *
  * Usage:
  *   pnpm architecture            # or: tsx tools/lint-architecture.ts
+ *   tsx tools/lint-architecture.ts --seed-customizations
+ *                                # print the customizations.yaml entries an
+ *                                # existing site needs (undecided); writes nothing
+ *   tsx tools/lint-architecture.ts --verbose
+ *                                # also warn which installed packages the
+ *                                # shadow-copy check skipped as this site's own
  *
  * Exit codes:
  *   0 — no violations
  *   1 — violations found (each names the file, the line and the rule)
  */
 
-import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
 import { dirname, join, relative, resolve, sep } from "node:path";
 
-import { parse as parseYaml } from "yaml";
+import {
+  isMap,
+  isScalar,
+  isSeq,
+  LineCounter,
+  parse as parseYaml,
+  parseDocument,
+  type Node,
+} from "yaml";
 
 interface ForbiddenPattern {
   pattern: string;
@@ -61,11 +92,17 @@ interface UpgradeableConsumer {
   scaffold_packages?: string[];
 }
 
+interface Customizations {
+  manifest?: string;
+  scaffold_paths?: string[];
+}
+
 interface ArchConfig {
   apps?: Record<string, AppRule>;
   forbidden_patterns?: ForbiddenPattern[];
   namespaces?: { members?: Record<string, { path: string }> };
   upgradeable_consumer?: UpgradeableConsumer;
+  customizations?: Customizations;
 }
 
 interface Violation {
@@ -101,12 +138,12 @@ function rel(abs: string): string {
   return toPosix(relative(ROOT, abs));
 }
 
-function walk(dir: string, match: RegExp, out: string[] = []): string[] {
+function walk(dir: string, match: RegExp, out: string[] = [], skip = SKIP_DIRS): string[] {
   if (!existsSync(dir)) return out;
-  for (const entry of readdirSync(dir)) {
-    if (SKIP_DIRS.has(entry)) continue;
+  for (const entry of readdirSync(dir).sort()) {
+    if (skip.has(entry)) continue;
     const p = join(dir, entry);
-    if (statSync(p).isDirectory()) walk(p, match, out);
+    if (statSync(p).isDirectory()) walk(p, match, out, skip);
     else if (match.test(entry) && !entry.endsWith(".d.ts")) out.push(p);
   }
   return out;
@@ -469,6 +506,508 @@ function checkUpgradeableConsumer(cfg: ArchConfig): Violation[] {
   return out;
 }
 
+// ── Customizations manifest (#9223) ──────────────────────────────────────
+//
+// A customization in a site is the exception: AILK builds it in unless it
+// decides not to, and the decision is recorded next to the code. "Site-
+// authored" is membership only — a code file under `apps/` that is neither a
+// template-record key nor on `scaffold_paths` — never a hash: an edited
+// template file is still the template's.
+
+const MANIFEST_PATH = "customizations.yaml";
+const RECORD_PATH = ".ailk-template-files.json";
+const CODE_FILE_RE = /\.(?:[cm]?[jt]sx?)$/;
+const TEST_FILE_RE = /\.(test|spec)\.[cm]?[jt]sx?$/;
+const ID_RE = /^[a-z0-9][a-z0-9-]*$/;
+const REQUEST_RE = /^([\w.-]+\/[\w.-]+)?#\d+$/;
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+const DECISION_AILK = /^build-in: ailk#(\d+)(?: [—-] .+)?$/;
+const DECISION_SITE = /^build-in: site [—-] [^,]+, \d{4}-\d{2}-\d{2}, .+$/;
+const DECISION_GRAMMAR =
+  "undecided | build-in: ailk#<N>[ — <text>] | build-in: site — <decider>, <YYYY-MM-DD>, <reason>";
+const NO_RECORD_WARNING = `architecture: warning — no ${RECORD_PATH}: site-authored files cannot be told from template files; run create-ailk update to write it`;
+
+/** Warnings main() prints to stderr; they never change the exit code. */
+const warnings: string[] = [];
+const VERBOSE = process.argv.includes("--verbose");
+
+interface Entry {
+  id: string;
+  line: number;
+  patterns: RegExp[];
+  decision: string;
+}
+
+/**
+ * A path pattern as a regex: `**` matches zero or more whole segments, `*`
+ * matches within one segment, and every other character is literal — route
+ * segments carry `[locale]` and `(authed)`, so brackets are never syntax.
+ */
+function globToRegExp(glob: string): RegExp {
+  const segments = glob.split("/");
+  let re = "^";
+  segments.forEach((seg, i) => {
+    const last = i === segments.length - 1;
+    if (seg === "**") {
+      re += last ? ".*" : "(?:[^/]+/)*";
+      return;
+    }
+    re += seg.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, "[^/]*");
+    if (!last) re += "/";
+  });
+  return new RegExp(`${re}$`);
+}
+
+function isTestFile(relPath: string): boolean {
+  const segments = relPath.split("/");
+  return segments.includes("__tests__") || TEST_FILE_RE.test(segments[segments.length - 1] ?? "");
+}
+
+/** The template record's file keys, or null when the site has no record. */
+function readRecord(): Set<string> | null {
+  const path = join(ROOT, RECORD_PATH);
+  if (!existsSync(path)) return null;
+  try {
+    const files = (JSON.parse(readFileSync(path, "utf8")) as { files?: unknown }).files;
+    return new Set(files && typeof files === "object" ? Object.keys(files) : []);
+  } catch {
+    return null;
+  }
+}
+
+/** Every site-authored code file under `apps/`, root-relative, sorted. */
+function siteAuthoredFiles(record: Set<string>, scaffoldPaths: string[]): string[] {
+  const shipped = scaffoldPaths.map(globToRegExp);
+  return walk(join(ROOT, "apps"), CODE_FILE_RE)
+    .map(rel)
+    .filter((p) => !record.has(p) && !shipped.some((re) => re.test(p)))
+    .sort();
+}
+
+/**
+ * Parse `customizations.yaml` into entries, pushing one violation per schema
+ * fault, each naming the field. A faulty entry is kept when it has an `id`
+ * and `paths`, so one fault never turns its files into unmatched ones.
+ */
+/** Null when the manifest is missing — the caller reports only that. */
+function readManifest(out: Violation[]): { entries: Entry[]; graceUntil: string | undefined } | null {
+  const file = join(ROOT, MANIFEST_PATH);
+  const entries: Entry[] = [];
+  let graceUntil: string | undefined;
+  if (!existsSync(file)) {
+    out.push({
+      file,
+      line: 1,
+      rule: `no ${MANIFEST_PATH} — architecture.yaml declares customizations`,
+      reason: `Fix: create ${MANIFEST_PATH} at the site root with \`customizations: []\` (copy it from a fresh scaffold).`,
+    });
+    return null;
+  }
+  const text = readFileSync(file, "utf8");
+  const counter = new LineCounter();
+  const doc = parseDocument(text, { lineCounter: counter });
+  const lineOf = (node: Node | null | undefined, fallback = 1): number =>
+    node?.range ? counter.linePos(node.range[0]).line : fallback;
+  const fault = (line: number, rule: string, fix: string) =>
+    out.push({ file, line, rule, reason: `Fix: ${fix}` });
+  if (doc.errors.length > 0) {
+    const err = doc.errors[0]!;
+    fault(err.linePos?.[0]?.line ?? 1, `${MANIFEST_PATH} does not parse: ${err.message.split("\n")[0]}`, "make it valid YAML — copy the shape from a fresh scaffold's customizations.yaml.");
+    return { entries, graceUntil };
+  }
+  const root = doc.contents;
+  if (!isMap(root)) {
+    fault(1, `${MANIFEST_PATH} is not a map`, "the file holds `undecided_ok_until` (optional) and `customizations` (a list).");
+    return { entries, graceUntil };
+  }
+  const scalarText = (node: unknown): string | undefined => {
+    if (!isScalar(node)) return undefined;
+    const v: unknown = node.value;
+    return typeof v === "string" ? v : typeof v === "number" || typeof v === "boolean" ? String(v) : undefined;
+  };
+  let list: unknown;
+  let listLine = 1;
+  for (const pair of root.items) {
+    const key = scalarText(pair.key);
+    const keyLine = lineOf(pair.key as Node);
+    if (key === "undecided_ok_until") {
+      const value = scalarText(pair.value);
+      if (value === undefined || !DATE_RE.test(value) || Number.isNaN(Date.parse(value))) {
+        fault(keyLine, `undecided_ok_until ${JSON.stringify(value ?? null)} is not a YYYY-MM-DD date`, "write it as YYYY-MM-DD, e.g. undecided_ok_until: 2027-01-31.");
+      } else {
+        graceUntil = value;
+      }
+    } else if (key === "customizations") {
+      list = pair.value;
+      listLine = keyLine;
+    } else {
+      fault(keyLine, `unknown key ${JSON.stringify(key)} — the keys are undecided_ok_until and customizations`, "remove it, or move it under the entry it describes.");
+    }
+  }
+  if (list === undefined) {
+    fault(1, "customizations is required (a list; [] when the site has none)", "add `customizations: []`.");
+    return { entries, graceUntil };
+  }
+  if (!isSeq(list)) {
+    fault(lineOf(list as Node, listLine), "customizations is not a list", "write `customizations: []` or a sequence of entries (- id: … / paths: … / request: … / decision: …).");
+    return { entries, graceUntil };
+  }
+  const seen = new Set<string>();
+  list.items.forEach((item, index) => {
+    if (!isMap(item)) {
+      fault(lineOf(item as Node), `customizations[${index}] is not a map`, "an entry is a map with id, paths, request and decision.");
+      return;
+    }
+    const line = lineOf(item);
+    const fields = new Map<string, unknown>();
+    for (const pair of item.items) {
+      const key = scalarText(pair.key) ?? "";
+      if (["id", "paths", "request", "decision"].includes(key)) fields.set(key, pair.value);
+      else fault(lineOf(pair.key as Node, line), `unknown key ${JSON.stringify(key)} — an entry's keys are id, paths, request, decision`, "remove it.");
+    }
+    const id = scalarText(fields.get("id"));
+    if (!fields.has("id")) fault(line, "id is required on every entry", "give the entry a short kebab-case id, e.g. booking-embed.");
+    else if (id === undefined || !ID_RE.test(id)) fault(lineOf(fields.get("id") as Node, line), `id ${JSON.stringify(id ?? null)} is not /^[a-z0-9][a-z0-9-]*$/`, "use lowercase letters, digits and hyphens.");
+    else if (seen.has(id)) fault(lineOf(fields.get("id") as Node, line), `duplicate id ${JSON.stringify(id)}`, "every entry's id is unique; merge the two entries or rename one.");
+    else seen.add(id);
+
+    const patterns: RegExp[] = [];
+    const paths = fields.get("paths");
+    if (!fields.has("paths")) fault(line, "paths is required on every entry", "list the paths (or globs) under apps/ the customization owns.");
+    else if (!isSeq(paths) || paths.items.length === 0) fault(lineOf(paths as Node, line), "paths must be a non-empty list", "list at least one path under apps/.");
+    else {
+      for (const node of paths.items) {
+        const p = scalarText(node);
+        const pLine = lineOf(node as Node, line);
+        if (p === undefined) fault(pLine, "paths entry is not a string", "write each path as a quoted string.");
+        else if (p.includes("\\")) fault(pLine, `paths entry ${JSON.stringify(p)} has a backslash`, "use `/` separators.");
+        else if (!p.startsWith("apps/")) fault(pLine, `paths entry ${JSON.stringify(p)} is outside apps/`, "an entry covers source files under apps/ only.");
+        else if (p.split("/").includes("..")) fault(pLine, `paths entry ${JSON.stringify(p)} has a .. segment`, "write the path from the site root, with no ..");
+        else if (p.split("/").some((s) => s.includes("**") && s !== "**")) fault(pLine, `paths entry ${JSON.stringify(p)} has a ** inside a segment`, "`**` must be a whole segment, e.g. apps/web/lib/**.");
+        else patterns.push(globToRegExp(p));
+      }
+    }
+
+    const decision = scalarText(fields.get("decision"));
+    if (!fields.has("decision")) fault(line, `decision is required on every entry (${DECISION_GRAMMAR})`, "record the build-in decision, or `undecided` while undecided_ok_until is in the future.");
+    else if (decision === undefined || (decision !== "undecided" && ![DECISION_AILK, DECISION_SITE].some((re) => re.test(decision)))) fault(lineOf(fields.get("decision") as Node, line), `decision ${JSON.stringify(decision ?? null)} is not one of: ${DECISION_GRAMMAR}`, "write exactly one of the three forms (the separator is — or -, with a space on each side).");
+
+    const request = scalarText(fields.get("request"));
+    if (fields.has("request") && (request === undefined || !REQUEST_RE.test(request))) fault(lineOf(fields.get("request") as Node, line), `request ${JSON.stringify(request ?? null)} is not <owner/repo>#<N> or #<N>`, "name the issue that requested the customization, e.g. acme/acme-site#12.");
+    else if (!fields.has("request") && decision !== undefined && decision.startsWith("build-in:")) fault(line, "request is required on a build-in: entry", "name the issue that requested the customization, e.g. request: acme/acme-site#12.");
+
+    if (id !== undefined && patterns.length > 0 && decision !== undefined) {
+      entries.push({ id, line, patterns, decision });
+    }
+  });
+  return { entries, graceUntil };
+}
+
+function checkCustomizations(cfg: ArchConfig): Violation[] {
+  const block = cfg.customizations;
+  if (!block) return [];
+  const out: Violation[] = [];
+  const parsed = readManifest(out);
+  if (parsed === null) return out;
+  const { entries, graceUntil } = parsed;
+  const manifest = join(ROOT, MANIFEST_PATH);
+  const today = new Date().toISOString().slice(0, 10);
+
+  // R5b — undecided only inside the grace.
+  for (const e of entries) {
+    if (e.decision !== "undecided") continue;
+    if (graceUntil !== undefined && graceUntil > today) continue;
+    out.push({
+      file: manifest,
+      line: e.line,
+      rule: `customization "${e.id}" is undecided and undecided_ok_until is ${graceUntil === undefined ? "absent" : `${graceUntil}, not in the future`}`,
+      reason:
+        "Fix: record the decision (build-in: ailk#N — AILK builds it in | build-in: site — <decider>, <date>, <reason>), or set undecided_ok_until to a future YYYY-MM-DD while the request is decided.",
+    });
+  }
+
+  const record = readRecord();
+  if (record === null) {
+    warnings.push(NO_RECORD_WARNING);
+    return out;
+  }
+  const authored = siteAuthoredFiles(record, block.scaffold_paths ?? []);
+
+  // R5a — every site-authored file maps to an entry.
+  for (const p of authored) {
+    if (entries.some((e) => e.patterns.some((re) => re.test(p)))) continue;
+    out.push({
+      file: join(ROOT, p),
+      line: 1,
+      rule: `site-authored source file with no ${MANIFEST_PATH} entry`,
+      reason:
+        "Fix: add an entry to customizations.yaml whose paths match it, with its request issue and its build-in decision (build-in: ailk#N | build-in: site — <decider>, <date>, <reason> | undecided while undecided_ok_until is in the future). AILK builds a customization in unless it decides not to.",
+    });
+  }
+
+  // R5c — a build-in AILK will carry takes its tests with it.
+  for (const e of entries) {
+    const n = DECISION_AILK.exec(e.decision)?.[1];
+    if (!n) continue;
+    const tests = authored.filter((p) => isTestFile(p) && e.patterns.some((re) => re.test(p)));
+    if (tests.length === 0) continue;
+    out.push({
+      file: manifest,
+      line: e.line,
+      rule: `customization "${e.id}" is build-in: ailk#${n} but its paths still match test files in this site: ${tests.join(", ")}`,
+      reason: `tests belong in AILK — move them into ailk#${n}'s PR and delete the site copies when the bump lands.`,
+    });
+  }
+  return out;
+}
+
+// ── Shadow copies (#9201) ────────────────────────────────────────────────
+//
+// #9191 refuses a fork by name; a module copied out of node_modules into an
+// app carries none. A site-authored file most of whose substantive lines are
+// a shipped module's is a copy, edited or not. A wrapper that imports and
+// re-exports or composes the module shares almost none of them. The shipped
+// modules are the code files under the roots the installed packages' export
+// maps (`exports`, `main`, `module`) point at, read from the site root's,
+// each workspace's and pnpm's hoisted (`node_modules/.pnpm/node_modules`)
+// `node_modules`, and indexed once per run — and not at all while no
+// site-authored file reaches the size floor (a fresh scaffold). Two paths:
+// an edited copy of a module of 12+ lines at 60% overlap, and a verbatim or
+// near-verbatim copy of one of 5+ lines at 90% — nearly half the shipped
+// modules are under 12 lines, and no wrapper reproduces a small module's
+// lines verbatim. The shipped form is compiled JS; a copy of a package's
+// TypeScript source compiles to different lines and is outside this check.
+
+/** An edited copy: both sides have at least this many substantive lines ... */
+const SHADOW_MIN_LINES = 12;
+/** ... and this share of the shorter side's lines is found in the other. */
+const SHADOW_MIN_OVERLAP = 0.6;
+/** A verbatim copy: both sides have at least this many substantive lines ... */
+const SHADOW_VERBATIM_MIN_LINES = 5;
+/** ... and this share of the shorter side's lines is found in the other. */
+const SHADOW_VERBATIM_OVERLAP = 0.9;
+/**
+ * Either way, this share of the FILE's own lines is the module's: a file most
+ * of whose lines are its own merely contains a helper the module also has.
+ */
+const SHADOW_MIN_OWN_SHARE = 0.3;
+/** A line in more shipped modules than this is boilerplate and carries no evidence. */
+const SHADOW_COMMON_LINE = 20;
+/** A longer line is a minified bundle's, never a line of a copy; it is not indexed. */
+const SHADOW_MAX_LINE_CHARS = 2000;
+const NOT_A_MODULE_RE = /\.(?:d\.[cm]?ts|map)$|\.(?:test|spec|stories)\.[cm]?[jt]sx?$/;
+/** A whole-line comment: `//`, a block-comment opener, a ` * ` body line or its closer. */
+const COMMENT_LINE_RE = /^\s*(?:\/\/|\/\*|\*)/;
+/** A shipped root is walked whole — `dist` is not skipped here. */
+const SHIPPED_SKIP_DIRS = new Set(["node_modules", "__tests__"]);
+
+/**
+ * A module's substantive lines: whole-line comments (never a `/*` inside a
+ * string or glob literal — an inline comment stays part of its line, on both
+ * sides alike), directives and import/export-from lines (the specifiers a copy
+ * rewrites) dropped, all whitespace removed, quotes unified, and anything
+ * under ten characters left out (`}`, `);`, `return(`). Order is kept;
+ * callers take the set.
+ */
+function substantiveLines(content: string): string[] {
+  const out: string[] = [];
+  for (const raw of content.split("\n")) {
+    if (raw.length > SHADOW_MAX_LINE_CHARS || COMMENT_LINE_RE.test(raw)) continue;
+    const line = raw.replace(/\s+/g, "").replace(/'/g, '"');
+    if (line.length < 10) continue;
+    if (/^(?:import|export)(?:[^"]*from)?"/.test(line) || /^"use[a-z]+"/.test(line)) continue;
+    out.push(line);
+  }
+  return out;
+}
+
+/** Every code-file target in an export-map value (a string, an array or a conditions object). */
+function exportTargets(value: unknown, out: string[] = []): string[] {
+  if (typeof value === "string") {
+    if (CODE_FILE_RE.test(value) && !NOT_A_MODULE_RE.test(value)) out.push(value);
+  } else if (Array.isArray(value)) {
+    for (const v of value) exportTargets(v, out);
+  } else if (value && typeof value === "object") {
+    for (const v of Object.values(value)) exportTargets(v, out);
+  }
+  return out;
+}
+
+/** A package's export map with its subpath keys at the top: a bare conditions object is the root's. */
+function exportsBySubpath(exports: unknown): Record<string, unknown> {
+  if (!exports || typeof exports !== "object" || Array.isArray(exports)) return { ".": exports };
+  const map = exports as Record<string, unknown>;
+  return Object.keys(map).some((k) => k.startsWith(".")) ? map : { ".": map };
+}
+
+/** The installed in-scope packages' shipped modules, each labelled `<package>/<subpath>`, sorted by label. */
+function shippedModules(scope: string): { label: string; file: string }[] {
+  const out: { label: string; file: string }[] = [];
+  const seen = new Set<string>();
+  // A package's realpath is compared against the real root: a temp or home dir may sit behind a symlink.
+  const realRoot = realpathSync(ROOT);
+  const own = workspacesOnDisk();
+  const slash = scope.indexOf("/");
+  const [scopeDir, prefix] = slash === -1 ? ["", scope] : [scope.slice(0, slash), scope.slice(slash + 1)];
+  const dirs = ["", ...own].map((ws) => join(ROOT, ws, "node_modules", scopeDir));
+  dirs.push(join(ROOT, "node_modules", ".pnpm", "node_modules", scopeDir)); // pnpm's hoisted transitive packages
+  for (const dir of dirs) {
+    if (!existsSync(dir)) continue;
+    for (const entry of readdirSync(dir).sort()) {
+      if (!entry.startsWith(prefix) || !existsSync(join(dir, entry, "package.json"))) continue;
+      let pkg: PackageJson;
+      let pkgDir: string;
+      try {
+        pkgDir = realpathSync(join(dir, entry));
+        pkg = JSON.parse(readFileSync(join(pkgDir, "package.json"), "utf8")) as PackageJson;
+      } catch {
+        warnings.push(`architecture: warning — shadow-copy check skipped ${rel(join(dir, entry))}: unreadable package.json`);
+        continue;
+      }
+      const name = typeof pkg.name === "string" ? pkg.name : `${scopeDir}/${entry}`;
+      const key = `${name}@${String(pkg.version)}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      // pnpm may hoist the site's own workspace (`@working-theory/mcp` is apps/mcp); its dist is the site's build.
+      const ownPath = toPosix(relative(realRoot, pkgDir));
+      if (own.includes(ownPath)) {
+        if (VERBOSE) {
+          warnings.push(
+            `architecture: warning — shadow-copy check skipped ${name}: ${ownPath} is this site's own workspace, not an installed package`,
+          );
+        }
+        continue;
+      }
+
+      // Each export key's code targets are named by the key; every other file
+      // under the shipped roots is named by its path inside the package.
+      const labels = new Map<string, string>();
+      const targets = exportTargets([pkg.main, pkg.module]);
+      for (const [subpath, value] of Object.entries(exportsBySubpath(pkg.exports))) {
+        const files = exportTargets(value);
+        targets.push(...files);
+        if (!subpath.startsWith(".") || subpath.includes("*")) continue;
+        for (const f of files) {
+          const file = resolve(pkgDir, f);
+          if (!labels.has(file)) labels.set(file, subpath === "." ? name : `${name}/${subpath.slice(2)}`);
+        }
+      }
+      const roots = [...new Set(targets.map((t) => dirname(resolve(pkgDir, t))))]
+        .filter((r) => r.startsWith(pkgDir) && existsSync(r))
+        .filter((r, _, all) => !all.some((o) => o !== r && r.startsWith(`${o}/`)));
+      const files = roots.flatMap((r) => walk(r, CODE_FILE_RE, [], SHIPPED_SKIP_DIRS));
+      for (const file of files.filter((f) => !NOT_A_MODULE_RE.test(f))) {
+        out.push({ file, label: labels.get(file) ?? `${name}/${toPosix(relative(pkgDir, file))}` });
+      }
+    }
+  }
+  // Sorted so a tie between two modules with the same lines reports the same label on every machine.
+  return out.sort((a, b) => a.label.localeCompare(b.label) || a.file.localeCompare(b.file));
+}
+
+/** A file's distinct substantive lines, or null when it cannot be read (a dangling symlink). */
+function lineSet(file: string): Set<string> | null {
+  try {
+    return new Set(substantiveLines(readFileSync(file, "utf8")));
+  } catch {
+    return null;
+  }
+}
+
+function checkShadowCopies(cfg: ArchConfig): Violation[] {
+  const record = cfg.customizations ? readRecord() : null;
+  if (record === null) return []; // without the site-authored set there is nothing to compare
+  const scope = cfg.upgradeable_consumer?.package_scope ?? "@working-theory/";
+  // Walked again rather than threaded out of checkCustomizations: apps/ is small.
+  const candidates = siteAuthoredFiles(record, cfg.customizations?.scaffold_paths ?? [])
+    .map((p) => ({ path: p, lines: lineSet(join(ROOT, p)) }))
+    .filter((c): c is { path: string; lines: Set<string> } => (c.lines?.size ?? 0) >= SHADOW_VERBATIM_MIN_LINES);
+  if (candidates.length === 0) return [];
+
+  const modules = shippedModules(scope);
+  const index = new Map<string, number[]>();
+  const sizes = modules.map(() => 0);
+  modules.forEach((m, id) => {
+    for (const line of lineSet(m.file) ?? []) {
+      const ids = index.get(line);
+      if (ids) ids.push(id);
+      else index.set(line, [id]);
+    }
+  });
+  const common = new Set<string>();
+  for (const [line, ids] of index) {
+    if (ids.length > SHADOW_COMMON_LINE) {
+      common.add(line);
+      index.delete(line);
+    } else {
+      for (const id of ids) sizes[id] = sizes[id]! + 1;
+    }
+  }
+
+  const out: Violation[] = [];
+  for (const c of candidates) {
+    const own = [...c.lines].filter((line) => !common.has(line));
+    if (own.length < SHADOW_VERBATIM_MIN_LINES) continue;
+    const shared = new Map<number, number>();
+    for (const line of own) {
+      for (const id of index.get(line) ?? []) shared.set(id, (shared.get(id) ?? 0) + 1);
+    }
+    let best: { id: number; overlap: number } | undefined;
+    for (const [id, n] of shared) {
+      const shorter = Math.min(own.length, sizes[id]!);
+      if (shorter < SHADOW_VERBATIM_MIN_LINES || n < own.length * SHADOW_MIN_OWN_SHARE) continue;
+      const overlap = n / shorter;
+      if (overlap < (shorter < SHADOW_MIN_LINES ? SHADOW_VERBATIM_OVERLAP : SHADOW_MIN_OVERLAP)) continue;
+      if (!best || overlap > best.overlap) best = { id, overlap };
+    }
+    if (!best) continue;
+    out.push({
+      file: join(ROOT, c.path),
+      line: 1,
+      rule: `shadow copy of ${modules[best.id]!.label} — ${Math.round(best.overlap * 100)}% of the shorter side's substantive lines are shared`,
+      reason:
+        "Fix: delete the copy and import, compose or configure the published module instead — a copy stops taking upstream fixes.",
+    });
+  }
+  return out;
+}
+
+/** `--seed-customizations`: print the entries an existing site needs; write nothing. */
+function seedCustomizations(cfg: ArchConfig): void {
+  if (!cfg.customizations) {
+    console.error("architecture: architecture.yaml declares no customizations: block — run create-ailk --sync-architecture <modules> first");
+    process.exitCode = 1;
+    return;
+  }
+  const record = readRecord();
+  if (record === null) {
+    console.error(`architecture: cannot seed without ${RECORD_PATH} — run create-ailk update first`);
+    process.exitCode = 1;
+    return;
+  }
+  const entries = readManifest([])?.entries ?? [];
+  const unmatched = siteAuthoredFiles(record, cfg.customizations.scaffold_paths ?? []).filter(
+    (p) => !entries.some((e) => e.patterns.some((re) => re.test(p))),
+  );
+  const byDir = new Map<string, string[]>();
+  for (const p of unmatched) {
+    const dir = p.slice(0, p.lastIndexOf("/"));
+    byDir.set(dir, [...(byDir.get(dir) ?? []), p]);
+  }
+  const ids = new Set(entries.map((e) => e.id));
+  const lines: string[] = [];
+  for (const dir of [...byDir.keys()].sort()) {
+    const base = dir.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+    let id = base;
+    for (let n = 2; ids.has(id); n++) id = `${base}-${n}`;
+    ids.add(id);
+    lines.push(`  - id: ${JSON.stringify(id)}`, "    paths:");
+    for (const p of byDir.get(dir)!) lines.push(`      - ${JSON.stringify(p)}`);
+    lines.push('    decision: "undecided"');
+  }
+  if (lines.length > 0) process.stdout.write(`${lines.join("\n")}\n`);
+}
+
 function main(): void {
   const yamlPath = join(ROOT, "architecture.yaml");
   if (!existsSync(yamlPath)) {
@@ -477,6 +1016,10 @@ function main(): void {
     return;
   }
   const cfg = (parseYaml(readFileSync(yamlPath, "utf8")) ?? {}) as ArchConfig;
+  if (process.argv.includes("--seed-customizations")) {
+    seedCustomizations(cfg);
+    return;
+  }
   const workspaces = workspacesOnDisk();
   const names = packageNames(workspaces);
   const violations: Violation[] = [];
@@ -501,7 +1044,10 @@ function main(): void {
   }
   violations.push(...checkNamespaces(cfg));
   violations.push(...checkUpgradeableConsumer(cfg));
+  violations.push(...checkCustomizations(cfg));
+  violations.push(...checkShadowCopies(cfg));
 
+  for (const w of warnings) console.error(w);
   if (violations.length === 0) {
     console.log("architecture: OK");
     return;

package/templates/tsconfig.json

@@ -3,7 +3,6 @@
   "references": [
     { "path": "./apps/api" },
     { "path": "./apps/mcp" },
-    { "path": "./apps/web" },
-    { "path": "./database/tsconfig.build.json" }
+    { "path": "./apps/web" }
   ]
 }