archstrict 0.0.0 → 0.2.0

package/README.ja.md

@@ -0,0 +1,142 @@
+# 🧱 archstrict
+
+[English](README.md)
+
+[![npm version](https://img.shields.io/npm/v/archstrict?logo=npm)](https://www.npmjs.com/package/archstrict)
+
+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 である。
+
+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 -D archstrict
+npx archstrict init
+npx archstrict check
+```
+
+`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 からの導入
+
+上の `npm install` は公開済みの package を入れる。この repository の checkout から作業する contributor と agent は、次のいずれかを使う。
+
+1. **同じ machine 上の local checkout からの `npm link`。**
+
+   ```sh
+   # この checkout の中で
+   npm run build   # dist/ が無いか古い場合
+   npm link
+
+   # 検査したいプロジェクトの中で
+   npm link archstrict
+   ```
+
+   対象プロジェクトで `npm unlink archstrict` を実行すれば取り除ける。
+
+2. **local checkout への `file:` 依存**。依存関係を global link ではなく、対象側の `package.json` 自体に記録したい場合に使う。
+
+   ```json
+   "archstrict": "file:../archstrict"
+   ```
+
+   `npm install` はこれを `npm link` と同じ symlink に変換し、build 手順は実行しない。対象プロジェクトで `npm install` を実行する前に、checkout 側で `npm run build` を実行する。symlink 化された `file:` 依存は checkout 自身の lifecycle script を実行しないため、`prepare` script は決して build を行わない。build 前に既に install していた場合は、対象プロジェクトで `npm install` をやり直す。これで `dist/` ができた後の binary にリンクし直される。
+
+3. **git 依存**(`"archstrict": "github:<owner>/archstrict#<ref>"`)。この checkout に到達できないが、git 経由で repository を読める machine 向け。`dist/` は commit されていないため、npm は package の devDependencies を install し、clone 後に `prepare` script(`npm run build`)を実行して `dist/` を build する。2 つの条件がある。
+   - install する machine が repository を読めること。access がその repository だけの agent はここで 404 になるため、方法 4 を使う。
+   - lifecycle script が有効であること。npm config で `ignore-scripts=true` の場合、`prepare` は実行されず `dist/` の無い install になり、`node_modules/.bin/archstrict` は存在しない file を指す。この install だけ `--ignore-scripts=false` を渡すか、方法 4 を使う。
+
+4. **`npm pack` が作る tarball** を対象 machine にコピーする方法。この repository に一切 access できない対象(例えば access がその repository だけの agent)でも動く唯一の方法である。
+
+   ```sh
+   # この checkout の中で
+   npm run build
+   npm pack   # archstrict-<version>.tgz を書き出す
+
+   # tarball を対象 machine にコピーしたあと、対象プロジェクトの中で
+   npm install ./archstrict-<version>.tgz
+   ```
+
+   `npm pack` は checkout の working tree を packing する。git 履歴ではないため、`dist/` が既に build 済みであることが要る。実際に実行して確認済み: tarball には `dist/`、`skills/`、`llms.txt`、`.agents/`、`README.md`、`README.ja.md`、`CHANGELOG.md`、`docs/`、`AGENTS.md`、`LICENSE`、`package.json` が入る。これは `npm link` と `file:` の方法が見せる集合と同じで、それに packaging 自体が加わる。

package/README.md

@@ -1,3 +1,144 @@
-# archstrict
+# 🧱 archstrict
 
-Reserved. Nothing is published here yet.
+[![npm version](https://img.shields.io/npm/v/archstrict?logo=npm)](https://www.npmjs.com/package/archstrict)
+
+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.
+
+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 -D archstrict
+npx archstrict init
+npx archstrict check
+```
+
+`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
+
+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.**
+
+   ```sh
+   # in this checkout
+   npm run build   # if dist/ is missing or stale
+   npm link
+
+   # in the project you want to check
+   npm link archstrict
+   ```
+
+   `npm unlink archstrict` in the target project removes it again.
+
+2. **A `file:` dependency on a local checkout**, when you want the dependency recorded in the target's own `package.json` instead of a global link:
+
+   ```json
+   "archstrict": "file:../archstrict"
+   ```
+
+   `npm install` turns this into a symlink to the checkout, the same way `npm link` does, and runs no build step. Run `npm run build` in the checkout before running `npm install` in the target project - a symlinked `file:` dependency does not run the checkout's lifecycle scripts, so its `prepare` script never builds it. If you already installed before building, rerun `npm install` in the target project afterward, so it links the binary now that `dist/` exists.
+
+3. **A git dependency** (`"archstrict": "github:<owner>/archstrict#<ref>"`), for a machine that cannot reach this checkout but can read the repository over git. `dist/` is not committed; npm installs the package's devDependencies and runs its `prepare` script (`npm run build`) after cloning, which builds `dist/`. Two conditions apply:
+   - The installing machine must be able to read the repository. An agent whose access covers only the repository it runs in gets a 404 here; use mode 4 instead.
+   - Lifecycle scripts must be enabled. With `ignore-scripts=true` in the npm config, `prepare` never runs and the install has no `dist/`, so `node_modules/.bin/archstrict` points at a missing file. Pass `--ignore-scripts=false` for this install, or use mode 4.
+
+4. **A tarball from `npm pack`**, copied to the target machine - the mode that works where the target has no access to this repository at all (for example, an agent whose access covers only the repository it runs in):
+
+   ```sh
+   # in this checkout
+   npm run build
+   npm pack   # writes archstrict-<version>.tgz
+
+   # copy the tarball to the target machine, then in the target project
+   npm install ./archstrict-<version>.tgz
+   ```
+
+   `npm pack` packs the checkout's working tree, not its git history, so it needs `dist/` already built. Confirmed by running it: the tarball contains `dist/`, `skills/`, `llms.txt`, `.agents/`, `README.md`, `README.ja.md`, `CHANGELOG.md`, `docs/`, `AGENTS.md`, `LICENSE`, and `package.json` - the same set `npm link` and the `file:` mode expose, plus the packaging itself.
+
+---
+
+[Japanese](README.ja.md)

package/dist/augmentation-cache.js

@@ -0,0 +1,65 @@
+// Responsibility: store the lazy module-augmentation scan for TypeScript
+// files outside analysis. Each absolute file path owns one validated entry.
+// Boundary: this module does not list, read, parse, or resolve project files.
+// The caller supplies scan results and treats every cache failure as a miss.
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { randomUUID } from "node:crypto";
+// An unknown shape is a silent miss. Trying to decode an older shape is
+// refused because a stale negative answer can suppress a required fallback.
+export const AUGMENTATION_CACHE_SCHEMA = 1;
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isMode(value) {
+    return value === undefined || (typeof value === "number" && Number.isInteger(value));
+}
+function isSpecifier(value) {
+    return record(value) && typeof value.specifier === "string" && isMode(value.mode);
+}
+function isEntry(value) {
+    return record(value) && typeof value.mtimeMs === "number" && Number.isFinite(value.mtimeMs) &&
+        typeof value.size === "number" && Number.isFinite(value.size) &&
+        typeof value.optionsHash === "string" && isMode(value.impliedNodeFormat) &&
+        Array.isArray(value.specifiers) && value.specifiers.every(isSpecifier);
+}
+// Invalid content is a cache miss. Reporting cache damage is refused because
+// the scan result remains available from the project files themselves.
+export function readAugmentationCache(path, archstrictVersion) {
+    let value;
+    try {
+        value = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+    if (!record(value) || value.schema !== AUGMENTATION_CACHE_SCHEMA ||
+        value.archstrictVersion !== archstrictVersion || !record(value.files) ||
+        !Object.values(value.files).every(isEntry))
+        return undefined;
+    const entries = value.files;
+    const files = Object.fromEntries(Object.entries(entries).map(([file, entry]) => [file, {
+            ...entry,
+            // JSON omits an undefined mode. Restoring the field is required because
+            // callers use the same exact shape that the syntax scanner returns.
+            specifiers: entry.specifiers.map((item) => ({ specifier: item.specifier, mode: item.mode })),
+        }]));
+    return { schema: AUGMENTATION_CACHE_SCHEMA, archstrictVersion, files };
+}
+// A temporary file keeps a killed writer from leaving partial JSON. Direct
+// writes are refused because a later scoped check must treat the cache atomically.
+export function writeAugmentationCache(path, archstrictVersion, files) {
+    const dir = dirname(path);
+    const temp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(temp, JSON.stringify({ schema: AUGMENTATION_CACHE_SCHEMA, archstrictVersion, files }));
+        renameSync(temp, path);
+    }
+    finally {
+        try {
+            rmSync(temp);
+        }
+        catch { /* A successful rename already removes it. */ }
+    }
+}

package/dist/check-options.js

@@ -0,0 +1,40 @@
+// Responsibility: parse the check verb's command-line options.
+// Boundary: rule and module existence depend on the loaded project and are validated by check().
+import { ReportError } from "./report-error.js";
+export function parseCheckArgv(argv) {
+    const positional = [];
+    const rules = [];
+    const modules = [];
+    let asJson = false;
+    let prove = false;
+    let frozen = false;
+    for (let index = 0; index < argv.length; index++) {
+        const arg = argv[index];
+        if (arg === "--json") {
+            asJson = true;
+        }
+        else if (arg === "--prove") {
+            prove = true;
+        }
+        else if (arg === "--frozen") {
+            frozen = true;
+        }
+        else if (arg === "--rule" || arg === "--module") {
+            const value = argv[++index];
+            if (value === undefined || value.startsWith("--")) {
+                throw new ReportError(`${arg} requires a value`, "archstrict check [file] [--rule <id>] [--module <name>]");
+            }
+            (arg === "--rule" ? rules : modules).push(value);
+        }
+        else if (arg.startsWith("-")) {
+            throw new ReportError(`unknown option '${arg}'`, "archstrict check [file] [--rule <id>] [--module <name>]");
+        }
+        else {
+            positional.push(arg);
+        }
+    }
+    if (positional.length > 1) {
+        throw new ReportError("check takes at most one file", "archstrict check [file] [--rule <id>] [--module <name>]");
+    }
+    return { asJson, prove, frozen, focusFile: positional[0], rules, modules };
+}

package/dist/classify.js

@@ -0,0 +1,148 @@
+// Responsibility: turn a config's `classify` (glob -> tags) and
+// `classifyByDirectoryName` (ambient, name-based) entries into the tag set a
+// given file carries. Boundary: no edge-constraint logic here (that's
+// tickets 4+); this module only answers "what tags does this file have."
+//
+// Precedence for two `classify` entries that both match the same file:
+// most-specific wins, where specificity is (a) the glob's literal prefix
+// length (the text before its first wildcard character), then (b) fewest
+// wildcard characters. This makes config order irrelevant - the property a
+// coding agent depends on when it can't see how a config it's editing was
+// originally ordered. A tie (identical specificity, different tags) is a
+// config error: two equally-specific entries disagreeing about the same
+// file is not something precedence can resolve for you.
+//
+// `classify` and `classifyByDirectoryName` are independent mechanisms whose
+// results union: a file can get tags from an explicit glob AND an ambient
+// directory-name match at once (VS Code's own env:* tags are pure ambient;
+// Prisma's are pure explicit; nothing requires a project pick only one).
+import { sep } from "node:path";
+import { ReportError } from "./report-error.js";
+// Converts one glob into a matcher plus its specificity. Supports `**`
+// (any number of path segments, including zero) and `*` (any characters
+// within one path segment - no `/`). Anything else in the pattern is a
+// literal character, escaped for use in a RegExp. Exported: declared-module
+// membership (module-graph.ts) uses the same precedence rule as tag
+// classification does, and shouldn't reimplement it.
+// Every per-file caller (mostSpecificMatch, for declared-module membership
+// and tag classification; the exclude-glob check and the .d.ts surface
+// check in isEligibleSourceFileWithDtsGlobs) recompiles the same fixed,
+// small set of config globs once per candidate file - O(files * globs)
+// RegExp construction on a large codebase. A glob's own compiled form
+// depends only on its literal text, so caching by that text is exact, not
+// approximate: the same string always compiles to the same matcher.
+const compiledGlobCache = new Map();
+export function compileGlob(glob) {
+    const cached = compiledGlobCache.get(glob);
+    if (cached !== undefined)
+        return cached;
+    const compiled = compileGlobUncached(glob);
+    compiledGlobCache.set(glob, compiled);
+    return compiled;
+}
+function compileGlobUncached(glob) {
+    const firstWildcard = glob.search(/\*/);
+    const literalPrefixLength = firstWildcard === -1 ? glob.length : firstWildcard;
+    const wildcardCount = (glob.match(/\*/g) ?? []).length;
+    let pattern = "";
+    let i = 0;
+    while (i < glob.length) {
+        if (glob.startsWith("/**/", i)) {
+            // `a/**/b.ts` must match `a/b.ts` too (zero segments between the two
+            // literal slashes), not just `a/x/b.ts` - translating `**` to `.*` in
+            // isolation while keeping both surrounding slashes as literals would
+            // require at least one segment. Fold the trailing slash into an
+            // optional group instead: one literal slash, then an optional
+            // "anything, ending in a slash" group.
+            pattern += "/(?:.*/)?";
+            i += 4;
+        }
+        else if (glob.startsWith("**", i)) {
+            pattern += ".*";
+            i += 2;
+        }
+        else if (glob[i] === "*") {
+            pattern += "[^/]*";
+            i += 1;
+        }
+        else {
+            pattern += glob[i].replace(/[.+?^${}()|[\]\\]/g, "\\$&");
+            i += 1;
+        }
+    }
+    const re = new RegExp(`^${pattern}$`);
+    return { test: (path) => re.test(path), literalPrefixLength, wildcardCount };
+}
+// A path is more specific than another when its literal prefix is longer,
+// or (tied) it has fewer wildcards. Returns 0 for a genuine tie: same
+// literal-prefix length AND same wildcard count - the config-error case.
+function compareSpecificity(a, b) {
+    if (a.literalPrefixLength !== b.literalPrefixLength) {
+        return a.literalPrefixLength - b.literalPrefixLength;
+    }
+    return b.wildcardCount - a.wildcardCount; // fewer wildcards = more specific
+}
+export class AmbiguousClassifyError extends ReportError {
+    constructor(path, glob1, glob2) {
+        super(`'${path}' matches two equally-specific entries ('${glob1}' and '${glob2}') with no way to prefer one - narrow one of the globs`, `narrow '${glob1}' or '${glob2}' in archstrict.config.ts, then run archstrict check`);
+        this.name = "AmbiguousClassifyError";
+    }
+}
+// Shared precedence engine: the most-specific of several glob-keyed entries
+// matching `path` wins, config order is irrelevant, and a genuine tie
+// (equal specificity, different `value`s per `sameValue`) throws. Used both
+// for tag classification (`value` is a tag array) and declared-module
+// membership (`value` is a module name) - two different callers, one
+// precedence rule, so they can't quietly drift apart.
+export function mostSpecificMatch(path, entries, sameValue) {
+    let best;
+    for (const entry of entries) {
+        const compiled = compileGlob(entry.glob);
+        if (!compiled.test(path))
+            continue;
+        if (best === undefined) {
+            best = { value: entry.value, glob: entry.glob, ...compiled };
+            continue;
+        }
+        const cmp = compareSpecificity(compiled, best);
+        if (cmp > 0) {
+            best = { value: entry.value, glob: entry.glob, ...compiled };
+        }
+        else if (cmp === 0 && !sameValue(entry.value, best.value)) {
+            throw new AmbiguousClassifyError(path, best.glob, entry.glob);
+        }
+    }
+    return best?.value;
+}
+function sameTags(a, b) {
+    return a.length === b.length && a.every((tag, i) => tag === b[i]);
+}
+// Relative path (project-root-relative, forward-slash-separated) -> the
+// tags its most-specific matching `classify` entry names, or undefined if
+// no entry matches at all.
+export function classifyByGlob(path, entries) {
+    return mostSpecificMatch(path, entries.map((e) => ({ glob: e.glob, value: e.tags })), sameTags);
+}
+// The nearest directory-name segment (innermost first) matching one of
+// `names` becomes `${tagNamespace}:${name}` - VS Code's own code-layering.ts
+// algorithm: walk the path's directory segments from the file outward, stop
+// at the first recognized name.
+export function classifyByDirectoryName(path, config) {
+    if (config === undefined)
+        return [];
+    const segments = path.split(sep === "\\" ? /\\|\// : "/");
+    for (let i = segments.length - 1; i >= 0; i--) {
+        if (config.names.includes(segments[i])) {
+            return [`${config.tagNamespace}:${segments[i]}`];
+        }
+    }
+    return [];
+}
+export function classifyFile(path, config) {
+    const tags = new Set();
+    for (const tag of classifyByGlob(path, config.classify ?? []) ?? [])
+        tags.add(tag);
+    for (const tag of classifyByDirectoryName(path, config.classifyByDirectoryName))
+        tags.add(tag);
+    return tags;
+}