archstrict 0.0.0 → 0.1.0

package/dist/verbs/todo.js

@@ -0,0 +1,163 @@
+// Responsibility: the `todo` verb (packwerk's shape). Freezes known
+// violations into one project-root archstrict.todo.json, grouped by module
+// name. First run adds every current freezable violation; every later run
+// only prunes entries whose identity no longer matches a current violation
+// — todo never adds again after the first run, so "run todo" cannot be
+// used to accept a new violation quietly. Also folds in the old per-module
+// layout the first time it finds one (todo-migration.ts), so a project
+// that adopted archstrict before this file existed keeps its frozen debt.
+// Boundary: freeze/prune/migrate policy only. The on-disk shape and
+// fingerprint identity live in todo-store.ts, shared with check.ts, so
+// both agree on the same identity for the same violation without
+// depending on each other.
+import { join } from "node:path";
+import { buildModuleGraphForRules } from "../module-graph.js";
+import { ReportError } from "../report-error.js";
+import { buildTodoEntry, buildTodoIndex, findMatchingEntry, readTodoFile, writeTodoFile, } from "../todo-store.js";
+import { deleteLegacyTodoFiles, readLegacyTodoState } from "../todo-migration.js";
+import { loadConfig, runRules } from "./check.js";
+function isFreezable(v) {
+    return "todoModule" in v;
+}
+// An uncovered-module violation has no todoModule (module-graph.ts's
+// outsideFiles matches no declared module at all, so there is no module
+// name to freeze it under - see isFreezable's own comment) - it can never
+// be frozen, first run or later. If the first run happens while one
+// exists, it freezes every OTHER current violation and writes the file,
+// after which "never add again" permanently forecloses freezing it once
+// it's later declared: check would stay at exit 1 forever (measured on
+// two real repository shapes: 12 and 52 such violations). Refusing the
+// first run outright - no file written at all - keeps the freeze
+// available until every file is actually covered. A later (prune-only)
+// run is unaffected: pruning only ever shrinks, so an uncovered file
+// already past the first run does not block it.
+function refuseIfUncovered(violations) {
+    const uncovered = violations.filter((v) => v.rule === "uncovered-module");
+    if (uncovered.length === 0)
+        return;
+    const noun = uncovered.length === 1 ? "file matches" : "files match";
+    throw new ReportError(`todo's first run refuses: ${uncovered.length} ${noun} no declared module`, "add each to declaredModules or exclude in archstrict.config.ts, then run archstrict todo");
+}
+export function freezeOrPrune(projectRoot, graph, config, violations) {
+    const strict = new Set(config.strict ?? []);
+    const freezable = violations.filter(isFreezable);
+    // graph.rootDir, not the raw projectRoot parameter: rootDir is
+    // realpath'd (module-graph.ts's own prepareGraph does this so every
+    // relative-path computation agrees with the paths TypeScript itself
+    // resolved to), while projectRoot may not be (e.g. macOS's own
+    // /tmp -> /private/tmp). Reading and normalizing an absolute stored path
+    // against the wrong base would silently fail to relativize it back to
+    // what a live violation's own (realpath'd) path relativizes to,
+    // un-matching an otherwise-identical entry - the same reasoning
+    // check.ts's own applyTodo already applies.
+    const rootDir = graph.rootDir;
+    const moduleDirs = new Map([...graph.modules].map(([name, m]) => [name, m.dir]));
+    const parsed = readTodoFile(rootDir);
+    // Only consulted when the new file itself is absent - a project already
+    // migrated (the new file exists) never re-reads the old layout, even if
+    // a stray legacy file somehow still sits on disk.
+    const legacy = parsed === undefined ? readLegacyTodoState(rootDir, moduleDirs) : undefined;
+    // "First run" is now the new file's own absence, AND no sign the old
+    // layout ever ran either - a project moving from the old layout to this
+    // one is a migration (folding in whatever the old layout had already
+    // frozen), not a fresh first run that would freeze today's live
+    // violations instead of what was actually already accepted as debt.
+    const firstRun = parsed === undefined && !(legacy?.present ?? false);
+    if (firstRun)
+        refuseIfUncovered(violations);
+    const currentByModule = new Map();
+    if (parsed !== undefined) {
+        for (const [name, entries] of parsed.modules)
+            currentByModule.set(name, entries);
+    }
+    else if (legacy !== undefined) {
+        for (const [name, entries] of legacy.entriesByModule)
+            currentByModule.set(name, entries);
+    }
+    let added = 0;
+    let pruned = 0;
+    const nextByModule = new Map();
+    for (const name of graph.modules.keys()) {
+        const current = currentByModule.get(name) ?? [];
+        const currentViolations = freezable.filter((v) => v.todoModule === name);
+        if (firstRun) {
+            // A strict module never gains an entry, not even on the first run:
+            // its violations simply stay reported by check, uncovered by any
+            // todo. Every other module's current violations all freeze at once.
+            const toFreeze = strict.has(name) ? [] : currentViolations;
+            const entries = toFreeze.map((v) => buildTodoEntry(v, graph.relativePath));
+            if (entries.length > 0) {
+                nextByModule.set(name, entries);
+                added += entries.length;
+            }
+        }
+        else {
+            // Prune (and, on a migration run, fold in): keep an existing entry
+            // exactly when some current violation still names it (todo-store.ts's
+            // own findMatchingEntry, indexed once per module rather than
+            // rescanned per violation - see buildTodoIndex's own comment). A
+            // strict module's entries prune the same as any other module's -
+            // strict blocks this verb from adding, not from shrinking. It never
+            // hides an existing entry from check, though: check reports any
+            // entry in a strict module's todo as its own violation
+            // (clean-module-has-todo), so an entry that survives pruning here
+            // still fails check until it's fixed.
+            //
+            // Every surviving entry is rewritten from the live violation that
+            // matched it (todo-store.ts's own buildTodoEntry), not kept
+            // byte-for-byte - self-healing for every rule (a legacy entry
+            // migrated with an absolute path, or one frozen under an older
+            // fingerprint formula, is rewritten into today's shape the first
+            // time it's pruned again). One entry's own object identity in
+            // `current` (not its content, which duplicate rows can share)
+            // decides which live violation refreshes it, so a genuine duplicate
+            // stored row - runRules can report the same edge twice - collapses
+            // to the one `buildTodoIndex`'s own map can still reference, instead
+            // of being rewritten twice over.
+            const index = buildTodoIndex(current);
+            const matchedViolationByEntry = new Map();
+            for (const v of currentViolations) {
+                const entry = findMatchingEntry(index, v, graph.relativePath);
+                if (entry !== undefined && !matchedViolationByEntry.has(entry))
+                    matchedViolationByEntry.set(entry, v);
+            }
+            const kept = current
+                .filter((e) => matchedViolationByEntry.has(e))
+                .map((e) => buildTodoEntry(matchedViolationByEntry.get(e), graph.relativePath));
+            pruned += current.length - kept.length;
+            if (kept.length > 0)
+                nextByModule.set(name, kept);
+        }
+    }
+    // An entry under a module name today's graph no longer declares (the
+    // module was renamed or removed since it was frozen) matches no current
+    // violation by construction - nothing this run's rules produced even
+    // claims that module name - so it can only ever be pruned, never kept or
+    // re-added.
+    for (const [name, entries] of currentByModule) {
+        if (graph.modules.has(name))
+            continue;
+        pruned += entries.length;
+    }
+    // Written unconditionally, even with an empty module map, so the file's
+    // own existence keeps meaning "todo has run" - see todo-store.ts's own
+    // writeTodoFile comment.
+    writeTodoFile(rootDir, nextByModule);
+    if (legacy !== undefined)
+        deleteLegacyTodoFiles(legacy.filesToDelete);
+    return { firstRun, added, pruned };
+}
+export async function todo(projectRoot) {
+    const configPath = join(projectRoot, "archstrict.config.ts");
+    const config = await loadConfig(configPath);
+    // See check.ts's own comment: declaredModules is the only source of
+    // scope now.
+    const graph = buildModuleGraphForRules({
+        projectRoot,
+        declaredModules: config.declaredModules,
+        exclude: config.exclude,
+        surface: config.surface,
+    });
+    const result = runRules(graph, config);
+    return freezeOrPrune(projectRoot, graph, config, result.violations);
+}

package/dist/warm-graph.js

@@ -0,0 +1,82 @@
+// Responsibility: across repeated refresh calls in one long-lived process
+// (the MCP server's check tool, and fix's apply-and-recheck loop), skip re-parsing a file whose
+// content hasn't changed while resolving every specifier afresh - a
+// resolution answer can go stale even when the importing file itself has
+// not (an unrelated file elsewhere gaining, losing, or reordering a
+// preferred target).
+// Boundary: no process, socket, daemon, or CLI integration; this object
+// holds no resolved edges, no ts.Program, and no parsed AST of any kind
+// across calls - only each file's own small, syntactic import list. A
+// refresh whose graph a caller then asks for `program`/`checker` (an MCP
+// `check` call, unless it is scoped to a non-surface file; also search,
+// fix)
+// builds a whole-project ts.Program fresh, every time, and drops it again
+// at the end of that one refresh - a real, paid cost each time rule 6
+// runs, kept bounded (module-graph.ts's own header: a whole-project
+// Program's own parsed SourceFile/Node trees are what dominate memory on
+// a large codebase) by never carrying that Program into the next refresh.
+import ts from "typescript";
+import { statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { buildPreparedGraph, prepareGraph, graphBuildFingerprint, parseFileForImports } from "./module-graph.js";
+function mtime(path) {
+    try {
+        return statSync(path).mtimeMs;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function createWarmGraph() {
+    // Keyed by absolute file path; holds the file's own syntactic import
+    // list (never its AST - see this module's own header) plus the mtime
+    // it was parsed at. A cache hit skips ts.createSourceFile and the
+    // import walk entirely; resolution still runs for every import record,
+    // hit or miss (module-graph.ts's own buildPreparedGraph does that part,
+    // outside this cache).
+    const cache = new Map();
+    let fingerprint;
+    return {
+        refresh(options) {
+            const prepared = prepareGraph(options);
+            // The CLI reads config afresh before each edge-cache lookup. This holder instead retains state across refresh calls.
+            // The config mtime therefore provides a separate signal that the architecture config changed since the previous refresh.
+            const currentFingerprint = JSON.stringify({ ...graphBuildFingerprint(options, prepared),
+                configMtime: mtime(join(prepared.projectRoot, "archstrict.config.ts")) });
+            // A changed fingerprint can mean new compiler options or package
+            // metadata - a parse cached under the old options (module kind,
+            // jsx setting, ...) is not safe to reuse under the new ones.
+            if (fingerprint !== currentFingerprint) {
+                cache.clear();
+                fingerprint = currentFingerprint;
+            }
+            const host = ts.createCompilerHost(prepared.compilerOptions);
+            const languageVersion = prepared.compilerOptions.target ?? ts.ScriptTarget.ESNext;
+            // One package.json lookup cache per refresh: a cold refresh parses
+            // every file, and each .ts/.tsx file's format depends on its nearest
+            // package.json "type". Without it, every file re-reads each
+            // package.json up its directory chain.
+            const packageJsonInfoCache = ts.createModuleResolutionCache(prepared.projectRoot, host.getCanonicalFileName.bind(host), prepared.compilerOptions).getPackageJsonInfoCache();
+            const fileWalk = (fileName) => {
+                const path = resolve(fileName);
+                const mtimeMs = mtime(path);
+                if (mtimeMs === undefined)
+                    return undefined;
+                const cached = cache.get(path);
+                if (cached?.mtimeMs === mtimeMs)
+                    return cached.walk;
+                const text = host.readFile(fileName);
+                if (text === undefined)
+                    return undefined;
+                const walk = parseFileForImports(fileName, text, languageVersion, host, prepared.compilerOptionsForFile(fileName), packageJsonInfoCache);
+                cache.set(path, { mtimeMs, walk });
+                return walk;
+            };
+            // No oldProgram, no held host reused as a Program-building host
+            // across calls: this refresh's graph builds its own Program (if
+            // anything asks for `program`/`checker` at all) from scratch, and
+            // that Program is this refresh's own business alone.
+            return buildPreparedGraph(prepared, { host, fileWalk });
+        },
+    };
+}

package/docs/boundary-patterns.md

@@ -0,0 +1,374 @@
+# A survey of existing boundary-checking configurations, and why archstrict does not ship a preset
+
+This records a survey of existing boundary-checking configurations in
+public repositories, done to answer one question: does archstrict need a
+`--preset` flag? The answer is no. The survey's own findings became
+[skills/archstrict/references/patterns.md](../skills/archstrict/references/patterns.md)
+instead - a reference an agent reads before proposing a config, not code
+that runs automatically.
+
+## Method
+
+The survey searched public code for existing boundary-checking
+configuration files and read every one it kept. About 1,090 distinct
+repositories came back across several targeted search queries; each got a
+star count. A repository qualified to keep reading its config at 300 stars
+from a general search query, or 100 stars from a query that already
+selects for a real, chosen tag vocabulary (so the bar could be lower there
+and still surface more than a handful). A tool's own source, its
+documentation, its fixtures, and its tutorials were dropped, along with
+one malformed config. Every kept configuration file was fetched and read
+in full: 113 configuration files, of which 72 carried a real, project-
+specific rule.
+
+**What was counted.** A rule counts once per repository, by which shape it
+expresses (a layer order, a runtime-environment split, a feature isolation
+rule, and so on - fourteen shapes emerged, twelve of them expected going
+in, two found only once the configs were actually read). A single
+repository can count toward more than one shape; most real configurations
+mix two to four of them.
+
+**Two biases, both worth stating plainly.**
+
+- **Most configuration files carry no project decision at all.** Across
+  the sample: a config-generating tool's own tag family, read in the
+  general query, was carrying its own scaffold's no-op rule (a wildcard
+  matching everything, added by the generator and never edited) in three
+  out of every four repositories that had one at all. A dependency-graph
+  tool's own default preset, applied by its own init command and left
+  untouched, accounted for a similar share of that tool's own configs. The
+  mere presence of a boundary tool in a repository is weak evidence of a
+  chosen pattern; the counts below come only from configs that carried a
+  real, hand-written rule.
+- **Search results are ordered by relevance, not by stars, and only the
+  first page is visible.** The counts below are frequencies within this
+  sample, not frequencies in the population of all public repositories.
+  Read a count as "common", "uncommon", or "rare" - not as a percentage.
+- **A third, smaller bias:** several of the richest, most clearly
+  commented configurations in the sample were recent, with self-
+  describing rule names and dated comments, and plausibly written with an
+  agent's help. They still show a real, chosen boundary - a comment
+  explaining a rule is evidence of intent regardless of who wrote the
+  comment.
+
+## Pattern counts
+
+| Pattern | Repositories | Evidence strength |
+|---|---|---|
+| Layered order (downward only) | 34 | strong |
+| Runtime/platform environments | 23 | strong |
+| Feature isolation with a shared kernel | 20 | strong |
+| Public-entry-only (no deep imports) | 17 | strong |
+| Leaf / pure kernel | 16 | strong (not anticipated before the survey) |
+| External package confined to one area | 13 | medium (not anticipated before the survey) |
+| Test code not imported by production code | 9 project-chosen, 10 more inherited from a tool's own default preset | medium; mostly inherited, not chosen |
+| Domain/scope isolation | 9, plus one studied, unsurveyed real config (Prisma) | medium, seen only in one tag-based monorepo tool's own convention |
+| Two tag axes combined | 7, plus the same studied config (three axes) | medium, seen only in that same tool family |
+| App vs lib | 5 | thin as its own explicit rule; often implicit instead |
+| Hexagonal / clean architecture | 5, one more partial | thin; every repository using it had well under 3,000 stars |
+| Barrel-inverse (must not import own barrel) | 5 | thin but consistent in what it says |
+| Type-only exception | 5 | thin; a modifier on another pattern, not a pattern of its own |
+| Host/plugin inversion | 5 | thin |
+
+## What each pattern's vocabulary and rule shape typically look like
+
+Public-entry-only is the strongest single piece of evidence for
+archstrict's own core model - a module as one directory, shown to the rest
+of the codebase through one named surface file. The entry file name varies
+across the sample (`index.ts` most often, then `public.ts`, `facade.ts`,
+`contracts.ts`, one file per subpath export, or the package name itself
+through a build alias) - which is exactly why archstrict's own `surface`
+field is configurable per project and per module, rather than fixed to
+`index.ts`.
+
+A layered order is almost always one entry per layer, naming every layer
+at or below itself as allowed - expressed either as an allow list (a
+monorepo tool's own tag convention) or as a deny list naming everything
+above (a dependency-graph tool, a path-restriction rule). A runtime-
+environment split almost always exempts one directory (`common`,
+`shared`) that every environment may use, and that itself may use
+nothing else. Feature isolation is almost always two rules together: a
+feature may not import a sibling feature, and the shared kernel may not
+import any feature - composition happens one level up, in a router or an
+app shell. A leaf/pure kernel is simpler than a full layer order and is
+often the only rule a small project has at all: one directory that
+imports nothing outside itself. An external-package-confined rule targets
+an npm package or a node built-in by name, not an internal directory - the
+same shape as an internal boundary, aimed outward instead of inward.
+
+Domain isolation and its two-axis combination were both seen only inside
+one tag-based monorepo tool's own tagging convention in this sample (and
+in one further, separately studied real configuration, Prisma's own
+`architecture.config.json`, which combines a domain axis, a layer axis
+scoped per domain, and a third "plane" axis). Evidence for this shape
+outside that one tool family is thin. Hexagonal/clean architecture,
+barrel-inverse, the type-only exception, host/plugin inversion, and app-
+vs-lib-as-an-explicit-rule are each real but thin: five or fewer
+repositories each, and (for hexagonal specifically) every one under 3,000
+stars. A proposal built on one of these five should say plainly that the
+evidence for it is thin.
+
+## A second sample: the 200 most-starred TypeScript repositories
+
+The first survey found repositories through code search for the vocabulary of
+dedicated boundary tools, so it can only measure frequency among repositories
+that already adopted one. A second survey, done on 2026-09-25, instead
+sampled by popularity: the 200 most-starred public TypeScript repositories on
+GitHub, independent of which tool (if any) each one uses. Four of the 200
+already appeared in the first survey's own table (all four enforce a
+boundary); the other 196 were checked by fetching each repository's full file
+tree and reading every file that looked like a boundary-tool config, a
+general lint config, or a hand-written checker script by name (files under
+`scripts/`, `tools/`, or a lint-configuration directory whose name mentions a
+boundary, a layer, a restriction, or an architecture check), plus the root
+package manifest and build config.
+
+**What counted.** A repository counts as enforcing a boundary when at least
+one rule names two areas of the project and forbids or allows an edge
+between them, or confines an external package or capability to one named
+area - the same bar as the first survey. A cycle-detection-only rule, a
+package-hygiene rule with a named single replacement everywhere, a
+deprecation-only rule, or a build system's own per-target dependency
+declarations with no layer table do not count on their own.
+
+**Headline.** 52 of the 200 repositories (26%) enforce a boundary this way;
+47 (24%) after setting aside five repositories whose only rule is a
+load-path rule (see the new LOAD pattern below). About three quarters do
+not.
+
+Enforcement rises sharply with codebase size, counted by `.ts`/`.tsx` file
+count (excluding generated declaration files):
+
+| TypeScript files | Enforces a boundary |
+|---|---|
+| under 100 | 0 of 18 |
+| 100 to 999 | 6 of 82 |
+| 1,000 to 4,999 | 24 of 67 |
+| 5,000 or more | 18 of 29 |
+
+The median enforcing repository has about 3,000 TypeScript files; the median
+non-enforcing repository has about 400. Several very large, popular
+repositories in the sample enforce nothing found by this method at all -
+star count and popularity do not predict enforcement; size does.
+
+**The tool mix inverts.** In the first survey, dedicated tag-and-constraint
+tools (a monorepo tool's own tag graph, a dependency-graph analysis tool, a
+path-restriction rule, a boundary-specific linter plugin) carried almost
+every rule. In this sample, those same tools carry only about an eighth of
+the 48 enforcing repositories combined; a general-purpose linter's built-in
+"forbid importing this path" rule carries about three fifths, and a checker
+the project wrote for itself - its own script, its own rule table, its own
+message text - carries most of the rest. One repository's own hand-written
+checker reimplements a monorepo tool's tag-constraint idea from scratch,
+including a hard-coded tag map and an allow-list per tag, without adopting
+the tool itself.
+
+**Per-pattern counts, both samples side by side.** Sample 1's denominator
+below is 82 repositories, from the first survey's own repository-level
+table. The method section above instead counts 72 configuration files with
+a project-chosen rule, from a per-tool pass over the same
+search results; the two numbers come from two different passes over the
+same underlying search, and the per-pattern counts below use the
+repository-level table's own 82. Sample 2's denominator is 48
+repositories. A repository can count toward more than one pattern in
+either sample.
+
+| Pattern | Sample 1 (of 82) | Sample 2 (of 48) |
+|---|---|---|
+| Public-entry-only | 17 | **22** |
+| Layered order | **34** | 10 |
+| Runtime/platform environments | 23 | 13 |
+| Feature isolation with a shared kernel | 20 | 2 |
+| Leaf / pure kernel | 16 | 7 |
+| External package confined to one area | 13 | 14 |
+| Type-only exception | 5 | 10 |
+| Test code kept out of production | 9 | 4 |
+| Scope/domain isolation | 9 | 2 |
+| Barrel-inverse | 5 | 3 |
+| App vs lib | 5 | 2 |
+| Hexagonal / clean | 5 | 2 |
+| Two tag axes combined | 7 | 1 |
+| Host/plugin inversion | 5 | 4 |
+| Load-path isolation | no category in sample 1 | 8 |
+| Edition split | no category in sample 1 | 2 |
+| Composition root | no category in sample 1 | 2 |
+| Friend list | no category in sample 1 | 1 |
+| Entry-graph budget | no category in sample 1 | 1 |
+
+**What the difference means.** The two samples measure different
+populations, not the same population twice. Sample 1's method can only find
+a repository that already picked a dedicated boundary tool and used its own
+vocabulary: a tag, an element type, a zone. That selection over-represents
+configurations built on a scaffold meant to make a layer ladder or a
+feature-isolation rule cheap to write - those are exactly the shapes a
+dedicated tool's own vocabulary makes easy to write. Sample 2, ordered by
+popularity alone, shows what large, established codebases enforce
+regardless of tooling choice. That turns out to be, overwhelmingly, a
+generic "forbid this import path" rule or a hand-written script, aimed at
+one entry point or one runtime split rather than a whole layer stack. Read
+the layered-order and feature-isolation counts in the first survey as
+evidence about repositories that adopted a layering tool. They are not
+evidence that layering is the most common shape among popular TypeScript
+codebases in general.
+
+Sample 2 also surfaces a reason for a rule that sample 1's own method could
+not have found under its own name: cost. Several repositories forbid a
+statically-imported heavy or side-effecting module purely to keep it off an
+eager load path (bundle size, startup time), not for an architectural
+reason at all. The first survey's own search terms had no way to single
+this reason out from an ordinary external-package rule.
+
+**An independent baseline mechanism.** Three unrelated large repositories in
+the second sample each built their own mechanism, separately, for a rule
+that fails only when the count of known violations grows past a committed
+baseline, or a grow-only list of accepted exceptions that may only get
+longer, never shorter by editing it directly. None of the three call it by
+the same name, and nothing suggests one copied another. This is an
+observation about a real, independently-arrived-at idea for managing
+existing boundary debt over time, not a documented convention any tool
+ships - and it is the same shape, arrived at from a different direction, as
+archstrict's own todo file: a frozen list that can only shrink.
+
+**Tags from sources other than a directory name (observations, not counted
+patterns).** Two repositories in the second sample derive a file's tag from
+something other than its path: one reads a runtime tag off a fixed filename
+suffix (a file whose name ends a certain way is browser-only, another
+ending marks it Node-only, another marks a web-worker file) - archstrict
+already expresses this today, since a `classify` glob can match a literal
+suffix directly. The other reads a tag from a field in a package's own
+manifest, independent of any path at all; archstrict does not read package
+manifests for tags today, so this is noted as an observation, not a
+supported mechanism.
+
+**Limits.** This sample counts declared rules only, not the real import
+graph: it says nothing about how often a rule actually fires, whether the
+codebase's real edges already comply, or whether a project keeps its
+boundary by convention with no rule enforcing it at all (invisible to this
+method either way). A rule living under an unexpected file name, inside a
+CI configuration file, or inside a shared configuration package more than a
+few directories deep could be missed; the "no rule found" count is a lower
+bound, not a proof of absence. Per-package export maps and TypeScript
+project references were not read as a source of boundary evidence in this
+sample. As with the first survey, a count here is a frequency within this
+sample, not a share of all public TypeScript code.
+
+## What real import graphs keep
+
+Both samples above read declared configuration files, not the code itself. A
+third pass, done on 2026-09-25, instead measured the real import graph of the
+50 most-starred public TypeScript repositories (star order; 5 skipped for not
+qualifying as a real codebase, one not measured because analysis ran out of
+memory), independent of whether each one declares any rule at all. Two of the
+50 already appear by name elsewhere in this document (VS Code, in the sample
+below) - every other repository is described only by size and shape, per this
+project's own policy on naming other codebases.
+
+**Method.** Each repository was cloned once, shallow (`--depth 1`); nothing
+from it was installed, built, or run. To make a workspace's own internal
+packages resolvable without running an install, `node_modules/<name>` was
+symlinked to each package directory a repository's own manifest named;
+third-party packages stayed unresolved throughout. A monorepo got one module
+per workspace package; every other repository used archstrict's own init-walk
+(one module per directory holding `.ts` under `src/` or the project root). A
+production graph drops every edge whose importing file is test code, since a
+test file importing a sibling package as a fixture is not the same claim as
+production code doing it; cycles and layering are measured on this production,
+value-import graph, with type-only imports counted as a separate, second
+question rather than folded into the same count.
+
+**Counts, with the declaring subset.**
+
+| Pattern | Kept in the graph (of 50) | Of those, declares a rule |
+|---|---|---|
+| Layered order | 14 | 2 |
+| Runtime/platform environments | 12 | 2 |
+| Feature isolation with a shared kernel | 11 | 3 |
+| Public entry only | 2 | 1 |
+| Leaf / pure kernel | 14 | 3 |
+| External package confined to one area | 43 | 9 |
+| App vs lib | 5 | 0 |
+| Test code kept out of production | 30 | 4 |
+| Host/plugin inversion | 10 | 2 |
+
+About 9 of the 50 declare any internal boundary rule at all, read by hand from
+each repository's own root configuration files.
+
+**The key contrast.** Public-entry-only was the single most-declared pattern
+in the star-ordered sample of declared configs (22 of 48 repositories that
+declare anything). In the real graph, it holds for only 2 of these 50
+repositories - a config declaring it is enforcing something the graph does
+not keep on its own as a byproduct of ordinary code organization. External-
+package confinement (43 of 50) and test separation (30 of 50) are the
+opposite case: the most common shapes the graph already keeps, whether or not
+any config exists to say so.
+
+**Shapes not on the pattern list above.**
+
+- **Test code folds a clean layering into one cycle.** In 15 of the 50
+  repositories, more modules sit inside a value-import cycle once test files
+  count than in the production graph alone - a 329-module repository went
+  from 0 modules in cycles to 46; an 84-module repository went from 0 to 2;
+  VS Code went from 4 to 6 of its 10 modules. A test file importing a sibling
+  package as a fixture is the usual cause; judging layering on the production
+  graph, not the whole-file graph, avoids counting that as a real reverse
+  dependency.
+- **One stray import turns an ordered pair into a mutual cycle.** 17 of the
+  50 repositories have a two-module cycle in production code, and it is
+  usually lopsided rather than balanced: VS Code's own two largest modules
+  pair 951 edges one way against 1 the other; a small repository's
+  configuration file and its library pairing showed 1 edge against 48; a
+  12-module repository showed two directories pairing 1 edge against 9. One
+  direction is the intended dependency; the handful of reverse edges read as
+  the exceptions worth removing, not evidence the pair has no order at all.
+- **Type-only imports add back edges a value-only reading misses.** In 8 of
+  the 50 repositories, counting type-only imports puts more modules inside a
+  cycle than counting value imports alone: an 85-module repository went from
+  4 modules in cycles to 73; a 9-module repository went from 0 to 3; a
+  31-module repository went from 10 to 12.
+- **Nearly disconnected workspaces.** 14 of the 50 repositories with at least
+  5 modules have at most one real production dependency for every two
+  modules: a 10-module repository had 3 dependency pairs; a 12-module
+  repository had 5; a 5-module repository had none at all.
+- **One large cycle instead of a layer order.** 9 of the 50 repositories have
+  a single production value cycle covering at least 30% of their modules (a
+  19-module repository with 12 of them in one cycle; a 9-module repository
+  with 3; a 21-module repository with 8); at this granularity these
+  repositories show no layered order to propose at all.
+
+**Limits.** One commit per repository, from a shallow clone with no history -
+nothing here says whether a kept shape is a real, ongoing decision or a
+snapshot of one moment. Only `.ts` files were parsed at the time of this
+measurement; a repository where `.tsx` outnumbers `.ts` has a graph that
+omits most of its UI code. Third-party imports were never resolved, so
+external-package confinement reads the specifier text a file wrote, and an
+unresolved path alias could be miscounted as a package. Granularity is a
+choice archstrict's own init-walk makes, and a different granularity would
+draw different module boundaries and could shift which patterns are visible
+at all. Every threshold above is this survey's own choice, not a bar drawn by
+any measured project; the per-repository numbers this survey produced allow
+a different threshold to be applied later. Intent is always inferred from
+structure, never confirmed by asking anyone who wrote the code.
+
+## The decision: a reference for agents, not a preset
+
+archstrict does not ship a `--preset` flag, and `init`/`recommend` never
+apply one of these patterns automatically. Instead, this survey's own
+findings became a skill reference
+([skills/archstrict/references/patterns.md](../skills/archstrict/references/patterns.md)):
+recognition cues (directory names, file names, import evidence) and a
+tested, real archstrict config for each pattern, meant for an agent to
+read before proposing a config to a project - never applied without a
+human or an agent looking at the project's own tree first.
+
+The reason is what archstrict itself is: a general tag-and-constraint
+engine over `classify`/`classifyByDirectoryName` and `edges`
+(`allowDeny`/`order`/`point`), not a tool with a fixed vocabulary of
+layers or domains built in. A preset fixes a vocabulary - `type:app`,
+`scope:shared`, `domain:core`, whatever a preset author chose - and a
+project whose own real shape does not match that vocabulary either
+distorts its own directory names to fit the preset, or abandons the
+preset's own rules while keeping its scaffold (exactly the "scaffold, no
+project decision" case this survey measured so often). A pattern an agent
+proposes from a project's own observed layout, in the project's own
+vocabulary, keeps the engine general while still giving every project the
+benefit of a name for the shape it already has.