archstrict 0.1.0 → 0.2.0

package/AGENTS.md

@@ -21,7 +21,7 @@ A violation report always carries a rule id, `path:line:col`, the evidence, the
 
 ## Layout
 
-- `src/` is the library and CLI.
+- `src/` is the library and CLI. The root `archstrict.config.ts` checks that tree: `core` is the analysis engine, `rules` and `verbs` are where a new rule or verb lands, and `cli`, `mcp`, and `check-options` sit above them. `archstrict.todo.json` is the ratchet. `skills/archstrict/` is the product skill shipped to consumers, not a second config.
 - `test/` is the Vitest suite; `features/` is the nukadoko (Gherkin) dogfood scenario.
 - `.agents/` is the canonical Claude Code plugin: the manifest, the PreToolUse and PostToolUse hooks, and the MCP server. `.claude-plugin/plugin.json` symlinks to `.agents/plugin.json`, and repo-root `hooks/` and `mcp/` symlink to `.agents/hooks` and `.agents/mcp`. `${CLAUDE_PLUGIN_ROOT}` is the directory that contains `.claude-plugin/`, so those plugin-root paths still resolve. `.claude-plugin/` stays a real directory holding only the manifest symlink: Claude loads `hooks/` from the plugin root, and a directory symlink onto `.agents/` would place `hooks/` and `mcp/` inside `.claude-plugin/`.
 - `skills/archstrict/` (and root `llms.txt`) is the agent-facing skill (`SKILL.md` plus `references/`).
@@ -48,6 +48,7 @@ If you want to cite an internal document, write its substance in place instead.
 For working on archstrict itself:
 
 - `npm run build` — compile `src/` to `dist/`. The CLI's own tests spawn the built `dist/cli.js`, so run this before `npm test` if `dist/` is missing or stale.
+- `node dist/cli.js check` — checks this repository against the root `archstrict.config.ts`. `node dist/cli.js todo` prunes `archstrict.todo.json` after the first run and does not add debt again.
 - `npm run typecheck` — `tsc --noEmit` over the whole project.
 - `npm test` — the Vitest suite.
 - `npm run dogfood:nukadoko` — a nukadoko (Gherkin) scenario that runs the built CLI's full init/check/todo/edit/check round trip against nukadoko's own published `src/` (a real, unrelated codebase with no public-surface convention), copied into a disposable scratch directory. Never modifies the real nukadoko package or a checkout of it.
@@ -56,7 +57,7 @@ For working on archstrict itself:
 
 The CLI itself:
 
-- `archstrict init [dir] [--json]` — on a fresh project, declare one module per top-level directory holding TypeScript source (`.ts`, `.tsx`, `.mts`, `.cts`; default container `src/`, or the project root when it's absent or holds none) and one single-file module per loose top-level source file, so the first `check` covers every analyzed file by construction; write `archstrict.types.ts` (the module-name union type). Re-run any time; it never touches an existing `archstrict.config.ts`, only regenerates `archstrict.types.ts` from its own `declaredModules` names. `--json` prints one object (`configPath`, `typesPath`, `configWritten`, `opened`, `moduleNames`, `hiddenDirs`, `noiseDirs`, `testFileExcludes`, `uncovered`, `notes`, `do`), or `{ "error": "<message>", "do": "<command>" }` on failure, the same convention `check` and `todo` follow.
+- `archstrict init [dir] [--json]` — on a fresh project, declare one module per top-level directory holding TypeScript source (`.ts`, `.tsx`, `.mts`, `.cts`; default container `src/`, or the project root when it's absent or holds none) and one single-file module per loose top-level source file, so the first `check` covers every analyzed file by construction. That map is an inventory: group files that change together (`glob` may be an array of paths in one directory), split a directory that holds almost every file, then add `edges`. `archstrict recommend` names a mega-module and a file-per-module inventory in `mapNotes`. Write `archstrict.types.ts` (the module-name union type). Re-run any time; it never touches an existing `archstrict.config.ts`, only regenerates `archstrict.types.ts` from its own `declaredModules` names. `--json` prints one object (`configPath`, `typesPath`, `configWritten`, `opened`, `moduleNames`, `hiddenDirs`, `noiseDirs`, `testFileExcludes`, `uncovered`, `notes`, `do`), or `{ "error": "<message>", "do": "<command>" }` on failure, the same convention `check` and `todo` follow.
 - `archstrict check [file] [--json] [--rule <id>] [--module <name>] [--frozen]` — analyze the whole project and report violations. With a file argument, analysis still covers the whole project (resolving an edge needs it), but the report is scoped to that file's own violations. Text output prints every violation up to 20; past that it prints grouped counts (by rule, then by the module owning the todo) with one full example per group and a `do:` that reruns just that group, cut at a line-count cap with a count of the groups left out. `--rule`/`--module` are repeatable and filter both the text and `--json` output after analysis; the exit code reflects the filtered set once either is given. An unknown rule id or module name is an error listing the valid ones. `--frozen` includes todo-matched violations too, each marked `frozen: true` and still combinable with `--rule`/`--module`; the exit code ignores a frozen violation, so a project already covered by `archstrict todo` still exits 0. When most public-surface-bypass violations target modules with no surface file at all, the summary says so and offers freezing, naming a surface, or adding surface files as next steps.
 - `archstrict todo [--json]` — on a project's first run, freeze every current freezable violation into one project-root `archstrict.todo.json`, grouped by module name; on every later run, only prune entries that no longer match a current violation. Never adds after the first run. That file's own existence is the "first run happened" signal, replacing an earlier marker file; a project with no debt after its first run still gets the file, with an empty module map, so the ratchet stays visible. The first run refuses instead (exit 1, no file written) while any `uncovered-module` violation exists, since such a file can never be frozen and a later declared-and-covered version of it would then find freezing already closed forever; a later, prune-only run is unaffected. `--json` prints `{ firstRun, added, pruned }`, or `{ "error": "<message>" }` on a config error, the same convention `check` follows.
 
@@ -67,3 +68,14 @@ The CLI itself:
 ## Claude Code plugin
 
 This repository is itself a Claude Code plugin (`.claude-plugin/plugin.json`, a symlink to `.agents/plugin.json`). It ships two hooks around every Edit/Write/MultiEdit, both shelling out to the edited project's own `node_modules/.bin/archstrict`, never to this repository's own build. Its `PreToolUse` hook (`.agents/hooks/pre-tool-use.mjs`, reached as `hooks/pre-tool-use.mjs`) runs before the write happens: it builds the file text the tool call would produce and previews it through that project's `archstrict simulate --json`, returning any added violation into the agent's own context so it can change course before the write lands, or denying the tool call outright when `ARCHSTRICT_PRETOOLUSE=deny` is set. Its `PostToolUse` hook (`.agents/hooks/post-tool-use.mjs`, reached as `hooks/post-tool-use.mjs`) runs the edited project's own installed `archstrict check <file>` right after the write and returns any violation into the agent's own context - the same moment a human editor's red squiggly would appear. Both say nothing when the edited project has no `archstrict` installed at all or the edited file has no violation; see [the hook reference](skills/archstrict/references/hook.md) for the full set of silent cases. The MCP server is `.agents/mcp/server.mjs`, reached as `${CLAUDE_PLUGIN_ROOT}/mcp/server.mjs`. `npm pack` ships `.agents/` and drops the symlinks, so an installed package's hooks are `node_modules/archstrict/.agents/hooks/pre-tool-use.mjs` and `post-tool-use.mjs`.
+
+
+<!-- ARCHSTRICT_START -->
+## archstrict
+
+In projects with an `archstrict.config.ts` (module-boundary/architecture linting), run `archstrict rules <path>` BEFORE creating a file or adding an import - it reports the module, tags, and constraints that would govern that path, even before it exists. Run `archstrict check` after editing to confirm.
+
+The full rule reference (every rule's evidence/because/do shape, the config schema, the pre-edit query) is at `node_modules/archstrict/skills/archstrict/SKILL.md` when installed via npm - read it before configuring `archstrict.config.ts`, or when a violation's `do:` text alone isn't enough.
+
+If there is no `archstrict.config.ts`, skip archstrict entirely - it may not be installed here.
+<!-- ARCHSTRICT_END -->

package/CHANGELOG.md

@@ -3,6 +3,45 @@
 The format follows Keep a Changelog, and the versions follow SemVer. Before 1.0, a minor version
 may change commands, flags, config, or output shape. The version entry will describe each change.
 
+## 0.2.0 (2026-10-01)
+
+### Added
+
+- This repository includes `.claude-plugin/marketplace.json`. Claude Code users can install the plugin with `/plugin marketplace add meganemura/archstrict` and `/plugin install archstrict@archstrict`.
+- `declaredModules[].glob` accepts an array of paths that share one directory, so a flat directory can name a multi-file seam without a directory move. Surface and friends resolve against that directory. The type-leak boundary is each listed file. Paths in two directories, and an empty array, are config errors.
+- `archstrict init` prints that the generated map is an inventory. A container of only files is told to group seams with a glob array. A directory that holds at least four fifths of the files (and at least eight) is named so it can be split before `archstrict todo`.
+- `archstrict recommend` adds `mapNotes` (`mega-module`, `file-per-module`). A surface proposal for the mega-module says to split it before freezing its bypasses.
+- `archstrict check` and `archstrict todo` name the case where one module holds most analyzed files and most public-surface bypasses, including bypasses a todo file already suppresses. The next command is to split that module before freezing more. `check <file>` leaves the note out.
+- While the config has no `edges` rule, a whole-project `check` prints one `summary:` line: the
+  config so far freezes today's import graph, not a target architecture. Its `do:` lines name
+  `archstrict recommend`, `archstrict hotspots`, and the rearchitect reference. `--json` carries
+  the same text as `nextSteps`. `check <file>` leaves it out.
+- A cycle between two modules now names the imports on each side and two moves in its `do:`:
+  extract the shared part into a leaf module both import, or pass the dependency in from the side
+  that owns it, and run `archstrict simulate` on the planned change first. A lopsided pair still
+  names its minority imports first. A cycle of three or more modules keeps the earlier text.
+- A `type-leak` `do:` now tells two cases apart. A type this module owns needs only a name on this
+  surface. A type owned by another module with no surface needs a surface on that module, or the
+  exposing export must leave this surface.
+
+### Changed
+
+- Every verb that walks the project (`init`, `check`, `todo`, `simulate`, `hotspots`, `recommend`)
+  now skips gitignored paths. archstrict reads the root and nested `.gitignore` files, the ones
+  above the project root, and the repository's `info/exclude` with git's own pattern rules, and
+  never runs git. A local scratch directory such as `tmp/` no longer floods `check` with
+  `uncovered-module` violations. A gitignored file stays resolvable as an import target. A config
+  that already declares a module inside a gitignored directory keeps analyzing that module; remove
+  the declaration to drop it.
+
+### Documentation
+
+- The skill, recommend reference, and re-architecture notes tell an adopter to treat `init` as an inventory, to split a mega-module before freezing it, to group a flat directory with a `glob` array, to install the skill once per user, and where a CLI and a graph helper sit.
+- The README (and its Japanese twin) has one Install section per host. Claude Code users add the
+  repository marketplace, then install `archstrict@archstrict` for the skill, edit hooks, and MCP
+  server. Other agents install the skill with `gh skill install`, add the `AGENTS.md` section with
+  `archstrict agents`, and run `archstrict check` in CI, since the edit hooks are Claude Code only.
+
 ## 0.1.0 (2026-09-29)
 
 ### Added

package/README.ja.md

@@ -4,24 +4,104 @@
 
 [![npm version](https://img.shields.io/npm/v/archstrict?logo=npm)](https://www.npmjs.com/package/archstrict)
 
-arch は architecture の略であり、tsc でも eslint でも型チェッカーでもない。module 境界を検査する道具である。
-archetype(アーキタイプ)の略ではない。
+archstrict は TypeScript の module 境界を検査する。ArchUnit(Java)や archspec(Ruby)と同じ考え方に立つ。config で各 module を宣言する。module は 1 個の directory であり、glob が 1 個の file を指すときはその file である。module は codebase の他の部分に対して public-surface file を 1 個だけ見せ、その file が export しないものは private である。
 
-TypeScript の module 境界検査であり、ArchUnit(Java)や archspec(Ruby)と同じ考え方に立つ。module は config で明示的に宣言した 1 個の directory であり、他の module に対しては 1 個の public-surface file だけを見せる。その file が export しないものはすべて private である。
-
-repository の形、rule、command は [AGENTS.md](AGENTS.md) を、実際の workflow は [skills/archstrict/SKILL.md](skills/archstrict/SKILL.md) を参照する。
+tsc と型チェッカーが見るのは型であり、ESLint が見るのは style である。archstrict が見るのは境界である。その public surface を越えて module の内部へ届く import は violation になる。
 
 ## 導入
 
+どの host でも、まずプロジェクトに npm package を入れる。
+
+```sh
+npm install -D archstrict
+```
+
+Node.js 22 以降が要る。
+
+これで、プロジェクトの `node_modules/.bin/archstrict` に実体の `archstrict` binary が置かれる。編集 hook と CI はこの binary を実行し、MCP server は同じ導入済みの package を読み込む。
+
+### 各部品の役割
+
+- **CLI**(`npm install -D archstrict`)は `init`、`check`、`todo` などの verb を実行する。violation を見つけるのはこの部品だけである。
+- **skill**(`skills/archstrict/`)は、violation の報告の読み方と config の変え方を agent に教える。host は `node_modules/` からではなく、host 自身の skill directory から読み込む。
+- **AGENTS.md の節**(`archstrict agents`)は、`AGENTS.md` を読むすべての agent に、file を作る前や import を足す前に `archstrict rules <path>` を実行し、編集の後に `archstrict check` を実行するよう指示する。数行のプロジェクト向け指示であり、skill ではない。
+- **編集 hook**(Claude Code 専用)は編集ごとに動く。PreToolUse hook は変更を事前に確かめ、PostToolUse hook は `archstrict check <file>` を実行して violation を agent の文脈に返す。[hook.md](skills/archstrict/references/hook.md) を参照。
+- **MCP server**(Claude Code の plugin)は、`check`、`rules`、`search`、`simulate` を tool として agent に渡す。
+- **CI** は、どの host が加えた変更にも `archstrict check` を実行する。
+
+### Claude Code
+
+このリポジトリの marketplace から plugin を入れる。plugin は skill、2 個の編集 hook、MCP server を持つ。Claude Code の中で次を実行する。
+
+```text
+/plugin marketplace add meganemura/archstrict
+/plugin install archstrict@archstrict
+```
+
+hook はプロジェクト自身の `node_modules/.bin/archstrict` を実行するので、上の npm install も要る。`node_modules/archstrict/` は plugin として読み込まれない。npm は plugin root に要る symlink(`.claude-plugin/plugin.json`、`hooks/`、`mcp/`)を含めないためである。plugin の file 自体は `node_modules/archstrict/.agents/` に入っている。リリース前の checkout を試すときは、`claude --plugin-dir <clone のパス>` で 1 回の session だけ読み込む。
+
+### その他の agent(Cursor、Codex、cloud agent)
+
+編集 hook は Claude Code 専用である。それ以外の agent では、次の 3 つを使う。
+
+1. GitHub CLI で、公開リポジトリから skill を入れる。`cursor` は、`gh skill install --help` にある自分の agent の値に置き換える。
+
+   ```sh
+   gh skill install meganemura/archstrict archstrict --agent cursor
+   ```
+
+   ユーザーにつき 1 回、`--scope user` で入れる。skill をリポジトリごとにコピーしない。既定の scope はプロジェクトである。Cursor、Codex など複数の agent が `.agents/skills/archstrict/` を共有する。次の `archstrict agents` は、プロジェクトごとの `AGENTS.md` の節である。コマンドを数行書くもので、skill の複製ではない。
+
+2. AGENTS.md の節を足す。
+
+   ```sh
+   npx archstrict agents
+   ```
+
+3. CI で `archstrict check` を実行する。編集 hook が無いので、agent の session で生じた violation は CI で捕まえる。
+
+   ```yaml
+   - run: npm ci
+   - run: npx archstrict check
+   ```
+
+## クイックスタート
+
 ```sh
-npm install --save-dev archstrict
+npm install -D archstrict
+npx archstrict init
+npx archstrict check
 ```
 
-これで、プロジェクトの `node_modules/.bin/archstrict` に実体の `archstrict` binary が置かれる。これは PreToolUse と PostToolUse の 2 個の hook([hook.md](skills/archstrict/references/hook.md) を参照)が、編集の前後で変更を確認するために探す path そのものである。この導入では、agent skill(`skills/archstrict/SKILL.md` と `skills/archstrict/references/`)、`llms.txt`、`.agents/`(plugin manifest、2 個の hook、MCP server)も `node_modules/archstrict/` に入る。npm は checkout 側の symlink(`.claude-plugin/plugin.json`、`hooks/`、`mcp/`)を含めないため、導入後の hook は `node_modules/archstrict/.agents/hooks/pre-tool-use.mjs` と `post-tool-use.mjs` になり、MCP server は `node_modules/archstrict/.agents/mcp/server.mjs` になる。git の checkout では、それらの symlink を通じて Claude Code の plugin として読み込まれる。
+`init` は、`archstrict.config.ts` が無いときその file を書く。あわせて、module 名の union type である `archstrict.types.ts` を書く。初回は、TypeScript source(`.ts`、`.tsx`、`.mts`、`.cts`)を持つ top-level directory ごとに 1 module を宣言し、subdirectory には入っていない top-level の source file ごとに 1 module を宣言する。対象は、開いた container の中と project root の両方である。container は、`src/` が source を持つときは `src/`、`src/` が無い、または source を持たないときは project root である。この map は、解析する file をすべて覆う。成長の seam や import の方向は、まだ検査しない。次に `npx archstrict recommend` を実行し、一緒に変わる file を 1 つの seam にまとめ、`edges` を足す。それが済むまで、この map は完成した architecture ではない。再実行したときは、手で編集した config をそのまま残し、`declaredModules` から `archstrict.types.ts` だけを再生成する。
+
+`check` は project を解析し、各 violation を rule id、`path:line:col`、evidence、`because` の理由、`do:` command とともに表示する。
+
+config は TypeScript の値 1 個である。`init` は歩いた tree から実際の `declaredModules` を書く。下の entry は、directory module と single-file module の例である。下の `exclude` は、`init` が常に書く基本のリストである。`init` は、disk 上で見つけた noise directory と colocated test file の pattern についても、それぞれ entry を足す。
+
+```ts
+import type { Config } from "./archstrict.types.js";
+
+export default {
+  schemaVersion: 1,
+  surface: ["index.ts", "index.tsx", "index.mts", "index.cts"],
+  exclude: ["archstrict.config.ts", "archstrict.types.ts", ".*/**", "**/.*/**"],
+  declaredModules: [
+    { name: "app", glob: "src/app/**" },
+    { name: "shared", glob: "src/shared/**" },
+    { name: "cli.ts", glob: "src/cli.ts", surface: "cli.ts" },
+  ],
+  because: "app and shared are directory modules; cli.ts is one loose file, public as itself",
+} satisfies Config;
+```
+
+`surface` は directory module の public-surface file の名前である。single-file module は、上の `cli.ts` のように、その file 自身を `surface` として書く。`because` は必須である。どの `declaredModules` の glob にも、どの `exclude` の pattern にも一致しない file は `uncovered-module` violation になる。
+
+rule、command、config の全体については、[AGENTS.md](AGENTS.md)、[skills/archstrict/SKILL.md](skills/archstrict/SKILL.md)、[skills/archstrict/references/config.md](skills/archstrict/references/config.md) を参照する。
 
-### local checkout からの導入
+## local checkout からの導入
 
-この repository の未公開の checkout に対して作業するときは、代わりに次のいずれかを使う。
+上の `npm install` は公開済みの package を入れる。この repository の checkout から作業する contributor と agent は、次のいずれかを使う。
 
 1. **同じ machine 上の local checkout からの `npm link`。**
 

package/README.md

@@ -2,24 +2,104 @@
 
 [![npm version](https://img.shields.io/npm/v/archstrict?logo=npm)](https://www.npmjs.com/package/archstrict)
 
-arch is architecture, not tsc, not eslint, not a type checker: module boundary checking.
-Not archetype.
+archstrict checks TypeScript module boundaries, in the sense of ArchUnit (Java) and archspec (Ruby). You declare each module in config: one directory, or one file when its glob names that file. A module shows the rest of the codebase one public-surface file, and anything that file does not export is private.
 
-TypeScript module boundary checking, in the sense of ArchUnit (Java) and archspec (Ruby): a module is one directory declared explicitly in config, it shows the rest of the codebase one public-surface file, and everything else inside it is private.
-
-See [AGENTS.md](AGENTS.md) for the shape, the rules, and the commands, and [skills/archstrict/SKILL.md](skills/archstrict/SKILL.md) for the workflow.
+tsc and type checkers examine types, and ESLint examines style. archstrict examines the boundary: an import that reaches past that public surface into a module's internals is a violation.
 
 ## Install
 
+Every host starts with the npm package in the project:
+
+```sh
+npm install -D archstrict
+```
+
+Requires Node.js 22 or newer.
+
+This puts a real `archstrict` binary at `node_modules/.bin/archstrict`. The edit hooks and CI run this binary, and the MCP server loads the same installed package.
+
+### What each piece does
+
+- **The CLI** (`npm install -D archstrict`) runs `init`, `check`, `todo`, and the other verbs. It is the only piece that finds violations.
+- **The skill** (`skills/archstrict/`) teaches an agent to read a violation report and to change the config. A host loads it from its own skill directory, not from `node_modules/`.
+- **The AGENTS.md section** (`archstrict agents`) tells any agent that reads `AGENTS.md` to run `archstrict rules <path>` before it creates a file or adds an import, and `archstrict check` after it edits. It is a few lines of project instructions, not the skill.
+- **The edit hooks** (Claude Code only) run around each edit. The PreToolUse hook previews the change, and the PostToolUse hook runs `archstrict check <file>` and returns any violation into the agent's context. See [hook.md](skills/archstrict/references/hook.md).
+- **The MCP server** (Claude Code plugin) gives the agent `check`, `rules`, `search`, and `simulate` as tools.
+- **CI** runs `archstrict check` on every change, whichever host made it.
+
+### Claude Code
+
+Install the plugin from this repository's marketplace. The plugin carries the skill, the two edit hooks, and the MCP server. Run these inside Claude Code:
+
+```text
+/plugin marketplace add meganemura/archstrict
+/plugin install archstrict@archstrict
+```
+
+The hooks run the project's own `node_modules/.bin/archstrict`, so the npm install above is still required. The plugin does not load from `node_modules/archstrict/`: npm drops the symlinks that the plugin root needs (`.claude-plugin/plugin.json`, `hooks/`, `mcp/`). The package still carries the plugin's files under `node_modules/archstrict/.agents/`. To try an unreleased checkout, load it for one session with `claude --plugin-dir <path-to-clone>`.
+
+### Other agents (Cursor, Codex, cloud agents)
+
+The edit hooks are Claude Code only. For any other agent, use three pieces:
+
+1. Install the skill from the public repository with the GitHub CLI. Replace `cursor` with your agent's value from `gh skill install --help`:
+
+   ```sh
+   gh skill install meganemura/archstrict archstrict --agent cursor
+   ```
+
+   Install it once for the user, with `--scope user`, so the skill is not copied into every repository. The default scope is the project: Cursor, Codex, and several other agents share `.agents/skills/archstrict/`. `archstrict agents` (the next step) is the per-project `AGENTS.md` section. It is a few lines of commands, and it is not a second copy of the skill.
+
+2. Add the AGENTS.md section:
+
+   ```sh
+   npx archstrict agents
+   ```
+
+3. Run `archstrict check` in CI. With no edit hook, CI is where a violation from an agent session is caught:
+
+   ```yaml
+   - run: npm ci
+   - run: npx archstrict check
+   ```
+
+## Quick start
+
 ```sh
-npm install --save-dev archstrict
+npm install -D archstrict
+npx archstrict init
+npx archstrict check
 ```
 
-This puts a real `archstrict` binary at `node_modules/.bin/archstrict` in your project - the exact path the PreToolUse and PostToolUse hooks (see [hook.md](skills/archstrict/references/hook.md)) check for before previewing and confirming a change on your behalf around an edit. The install also carries the agent skill (`skills/archstrict/SKILL.md` and `skills/archstrict/references/`), `llms.txt`, and `.agents/` (the plugin manifest, the two hooks, and the MCP server) into `node_modules/archstrict/`. npm omits the checkout's symlinks (`.claude-plugin/plugin.json`, `hooks/`, `mcp/`), so the installed hooks are `node_modules/archstrict/.agents/hooks/pre-tool-use.mjs` and `post-tool-use.mjs`, and the installed MCP server is `node_modules/archstrict/.agents/mcp/server.mjs`. A git checkout still loads as a Claude Code plugin through those symlinks.
+`init` writes `archstrict.config.ts` when that file is absent, and writes `archstrict.types.ts`, the module-name union. On a fresh project it declares one module per top-level directory that holds TypeScript source (`.ts`, `.tsx`, `.mts`, `.cts`), and one module per loose top-level source file, both inside the opened container and at the project root. The container is `src/` when that directory holds source, and the project root when `src/` is absent or holds none. That map covers every analyzed file. It does not yet name growth seams or check import direction. Run `npx archstrict recommend` next, group files that change together, and add an `edges` rule before treating the check as a finished architecture. A later run leaves a hand-edited config in place and only regenerates `archstrict.types.ts` from `declaredModules`.
+
+`check` analyzes the project and prints each violation with a rule id, `path:line:col`, the evidence, a `because` reason, and a `do:` command.
+
+A config is one TypeScript value. `init` writes the real `declaredModules` from the tree it walked; the entries below are examples of a directory module and a single-file module. The `exclude` list below is the base that `init` always writes. `init` also adds an entry for each noise directory and colocated test-file pattern it finds on disk.
+
+```ts
+import type { Config } from "./archstrict.types.js";
+
+export default {
+  schemaVersion: 1,
+  surface: ["index.ts", "index.tsx", "index.mts", "index.cts"],
+  exclude: ["archstrict.config.ts", "archstrict.types.ts", ".*/**", "**/.*/**"],
+  declaredModules: [
+    { name: "app", glob: "src/app/**" },
+    { name: "shared", glob: "src/shared/**" },
+    { name: "cli.ts", glob: "src/cli.ts", surface: "cli.ts" },
+  ],
+  because: "app and shared are directory modules; cli.ts is one loose file, public as itself",
+} satisfies Config;
+```
+
+`surface` names the public-surface file of a directory module. A single-file module names that file as its own `surface`, as `cli.ts` does above. `because` is required. A file that matches no `declaredModules` glob and no `exclude` pattern is an `uncovered-module` violation.
+
+Rules, commands, and the full config: [AGENTS.md](AGENTS.md), [skills/archstrict/SKILL.md](skills/archstrict/SKILL.md), and [skills/archstrict/references/config.md](skills/archstrict/references/config.md).
 
-### Installing from a local checkout
+## Installing from a local checkout
 
-Use one of these instead when working against an unpublished checkout of this repository.
+The `npm install` above installs the published package. Contributors and agents working from a checkout of this repository use one of the modes below.
 
 1. **`npm link`, from a local checkout on the same machine.**
 

package/dist/cli.js

@@ -110,7 +110,11 @@ async function runTodo(args) {
     else {
         process.stdout.write(`pruned ${result.pruned} stale entrie(s)\n`);
     }
-    process.stdout.write(`do: archstrict check\n`);
+    for (const note of result.notes ?? [])
+        process.stdout.write(`note: ${note}\n`);
+    process.stdout.write(result.notes !== undefined && result.notes.length > 0
+        ? `do: split the module named above before treating this freeze as done\n`
+        : `do: archstrict check\n`);
     return 0;
 }
 async function runRules(args) {

package/dist/config.js

@@ -156,7 +156,15 @@ export function assertGlobsSupported(config, verb) {
         assertGlobSupported(configPath, `mustBeEmpty[${i}].glob`, entry?.glob, verb);
     }
     for (const [i, mod] of (config.declaredModules ?? []).entries()) {
-        assertGlobSupported(configPath, `declaredModules[${i}].glob`, mod?.glob, verb);
+        const glob = mod?.glob;
+        if (Array.isArray(glob)) {
+            for (const [j, entry] of glob.entries()) {
+                assertGlobSupported(configPath, `declaredModules[${i}].glob[${j}]`, entry, verb);
+            }
+        }
+        else {
+            assertGlobSupported(configPath, `declaredModules[${i}].glob`, glob, verb);
+        }
         const surface = mod?.surface;
         if (Array.isArray(surface)) {
             for (const [j, s] of surface.entries()) {

package/dist/gitignore.js

@@ -0,0 +1,271 @@
+// Responsibility: decide whether a project-relative path is gitignored, by
+// parsing .gitignore files and the repository's info/exclude with git's own
+// pattern rules (negation, directory-only patterns, anchoring, `**`), so the
+// project walk can skip scratch output that was never project source.
+// Boundary: this module reads ignore files only. It never spawns git, never
+// walks a directory tree (module-graph.ts's walk calls in per directory), and
+// never reads the user's global core.excludesFile: that file differs from
+// machine to machine, so honoring it would make a laptop and CI analyze
+// different file sets from the same checkout.
+//
+// Parsing instead of `git ls-files --ignored` keeps the walk independent of
+// git: a copy of a checkout with no .git directory, or a machine with no git
+// binary, still skips what the checkout's own .gitignore files name.
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+function makeLayer(rules, prefix, strip) {
+    const literalAny = new Map();
+    const literalDir = new Map();
+    const patterned = [];
+    rules.forEach((rule, index) => {
+        if (rule.literal === undefined)
+            patterned.push(index);
+        else
+            (rule.dirOnly ? literalDir : literalAny).set(rule.literal, index);
+    });
+    return { rules, prefix, strip, literalAny, literalDir, patterned };
+}
+function escapeRegex(char) {
+    return /[\\^$.*+?()[\]{}|/]/.test(char) ? `\\${char}` : char;
+}
+// One path segment (no "/") of a gitignore pattern, as a regex source.
+function translateSegment(segment) {
+    let out = "";
+    for (let i = 0; i < segment.length; i++) {
+        const char = segment[i];
+        if (char === "\\" && i + 1 < segment.length) {
+            out += escapeRegex(segment[++i]);
+        }
+        else if (char === "*") {
+            // A "**" that is not a whole segment is an ordinary "*" (git's rule).
+            while (segment[i + 1] === "*")
+                i++;
+            out += "[^/]*";
+        }
+        else if (char === "?") {
+            out += "[^/]";
+        }
+        else if (char === "[") {
+            const close = segment.indexOf("]", i + 2);
+            if (close === -1) {
+                out += "\\[";
+                continue;
+            }
+            let body = segment.slice(i + 1, close);
+            let negated = false;
+            if (body.startsWith("!") || body.startsWith("^")) {
+                negated = true;
+                body = body.slice(1);
+            }
+            out += `[${negated ? "^" : ""}${body.replace(/[\\\]^]/g, (c) => `\\${c}`)}]`;
+            i = close;
+        }
+        else {
+            out += escapeRegex(char);
+        }
+    }
+    return out;
+}
+// Exported for the parity test against `git check-ignore`.
+export function parseGitignore(text) {
+    const rules = [];
+    for (const rawLine of text.split("\n")) {
+        let line = rawLine.endsWith("\r") ? rawLine.slice(0, -1) : rawLine;
+        if (line === "" || line.startsWith("#"))
+            continue;
+        // Trailing spaces are dropped unless the last one is escaped.
+        while (line.endsWith(" ") && !line.endsWith("\\ "))
+            line = line.slice(0, -1);
+        let negate = false;
+        if (line.startsWith("!")) {
+            negate = true;
+            line = line.slice(1);
+        }
+        let dirOnly = false;
+        if (line.endsWith("/")) {
+            dirOnly = true;
+            line = line.slice(0, -1);
+        }
+        if (line === "")
+            continue;
+        // A slash at the start or in the middle anchors the pattern to the
+        // ignore file's own directory; otherwise it matches at any depth.
+        const anchored = line.includes("/");
+        if (line.startsWith("/"))
+            line = line.slice(1);
+        const segments = line.split("/");
+        let source = "";
+        segments.forEach((segment, index) => {
+            const last = index === segments.length - 1;
+            if (segment === "**") {
+                source += last ? ".*" : "(?:.*/)?";
+                return;
+            }
+            source += translateSegment(segment) + (last ? "" : "/");
+        });
+        const regex = new RegExp(anchored ? `^${source}$` : `^(?:.*/)?${source}$`);
+        const literal = !anchored && !/[*?[\\]/.test(line) ? line : undefined;
+        rules.push(literal === undefined ? { regex, negate, dirOnly } : { regex, negate, dirOnly, literal });
+    }
+    return rules;
+}
+function toPosix(path) {
+    return sep === "/" ? path : path.split(sep).join("/");
+}
+function readText(path) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+}
+// The repository's common git directory for `projectRoot`, found by walking
+// up to the nearest `.git`. A linked worktree's `.git` is a file that points
+// at its own git directory, whose `commondir` names the shared one where
+// info/exclude lives.
+function findRepository(projectRoot) {
+    let dir = projectRoot;
+    for (;;) {
+        const dotGit = join(dir, ".git");
+        if (existsSync(dotGit)) {
+            let gitDir = dotGit;
+            try {
+                if (statSync(dotGit).isFile()) {
+                    const match = /^gitdir:\s*(.+)$/m.exec(readFileSync(dotGit, "utf8"));
+                    if (match === null)
+                        return undefined;
+                    gitDir = resolve(dir, match[1].trim());
+                }
+            }
+            catch {
+                return undefined;
+            }
+            const commonDirText = readText(join(gitDir, "commondir"));
+            const commonDir = commonDirText === undefined ? gitDir : resolve(gitDir, commonDirText.trim());
+            return { root: dir, commonDir };
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+// Every ignore file that applies above `projectRoot` itself: info/exclude
+// and each .gitignore from the repository root down to the project root's
+// parent. The project root's own .gitignore and every nested one are added
+// by the caller as it reaches each directory (withGitignoreFile). Outside a
+// repository this is empty, and the nested files still apply.
+export function gitignoreStackAbove(projectRoot) {
+    const repository = findRepository(projectRoot);
+    if (repository === undefined)
+        return [];
+    const layers = [];
+    const add = (baseDir, text) => {
+        if (text === undefined)
+            return;
+        const rules = parseGitignore(text);
+        if (rules.length === 0)
+            return;
+        const fromBase = toPosix(relative(baseDir, projectRoot));
+        layers.push(makeLayer(rules, fromBase === "" ? "" : `${fromBase}/`, 0));
+    };
+    add(repository.root, readText(join(repository.commonDir, "info", "exclude")));
+    const between = [];
+    for (let dir = projectRoot; dir !== repository.root; dir = dirname(dir)) {
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        between.unshift(parent);
+    }
+    for (const dir of between)
+        add(dir, readText(join(dir, ".gitignore")));
+    return layers;
+}
+// `stack` plus the .gitignore whose text is `text`, found in the directory
+// at project-relative `dirRel` ("" for the project root).
+export function withGitignoreFile(stack, dirRel, text) {
+    const rules = parseGitignore(text);
+    if (rules.length === 0)
+        return stack;
+    return [...stack, makeLayer(rules, "", dirRel === "" ? 0 : dirRel.length + 1)];
+}
+// The deepest layer's last matching rule decides, the same precedence git
+// uses. No match at all means not ignored.
+export function isIgnoredBy(stack, rel, isDir) {
+    if (stack.length === 0)
+        return false;
+    const basename = rel.slice(rel.lastIndexOf("/") + 1);
+    for (let l = stack.length - 1; l >= 0; l--) {
+        const layer = stack[l];
+        let best = layer.literalAny.get(basename) ?? -1;
+        if (isDir)
+            best = Math.max(best, layer.literalDir.get(basename) ?? -1);
+        const local = layer.prefix + rel.slice(layer.strip);
+        for (let p = layer.patterned.length - 1; p >= 0; p--) {
+            const index = layer.patterned[p];
+            if (index < best)
+                break;
+            const rule = layer.rules[index];
+            if (rule.dirOnly && !isDir)
+                continue;
+            if (rule.regex.test(local)) {
+                best = index;
+                break;
+            }
+        }
+        if (best >= 0)
+            return !layer.rules[best].negate;
+    }
+    return false;
+}
+// The state of the entry at project-relative `rel`, given its parent's
+// state. Git never re-includes a path under an ignored directory, so
+// "ignored" is inherited; only a declared module's base directory (or
+// single file) reverses it, for its whole subtree.
+export function nextIgnoreState(parent, stack, rel, isDir, forcedBases) {
+    if (parent === "forced")
+        return "forced";
+    const ignored = parent === "ignored" || isIgnoredBy(stack, rel, isDir);
+    if (!ignored)
+        return "kept";
+    return forcedBases.has(rel) ? "forced" : "ignored";
+}
+// The walk's own decision for one path that the walk never visited: a file
+// simulate proposes to create. Replays nextIgnoreState down the path's own
+// directories, reading each directory's .gitignore on the way.
+export function isPathGitignored(projectRoot, rel, forcedBases) {
+    let stack = gitignoreStackAbove(projectRoot);
+    const rootText = readText(join(projectRoot, ".gitignore"));
+    if (rootText !== undefined)
+        stack = withGitignoreFile(stack, "", rootText);
+    const parts = rel.split("/");
+    let state = "kept";
+    for (let i = 0; i < parts.length; i++) {
+        const sub = parts.slice(0, i + 1).join("/");
+        const isDir = i < parts.length - 1;
+        state = nextIgnoreState(state, stack, sub, isDir, forcedBases);
+        if (state === "kept" && isDir) {
+            const text = readText(join(projectRoot, sub, ".gitignore"));
+            if (text !== undefined)
+                stack = withGitignoreFile(stack, sub, text);
+        }
+    }
+    return state === "ignored";
+}
+// The project-relative base of every declared module whose glob names a
+// real path (the literal part before the first wildcard). A base of ""
+// (a glob like "**/*.ts") covers the whole project and forces nothing.
+export function forcedBasesOf(bases) {
+    const set = new Set();
+    const ancestors = new Set();
+    for (const base of bases) {
+        if (base === "")
+            continue;
+        set.add(base);
+        const parts = base.split("/");
+        for (let i = 1; i < parts.length; i++)
+            ancestors.add(parts.slice(0, i).join("/"));
+    }
+    return { bases: set, ancestors };
+}