archstrict 0.0.0 → 0.2.0

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 };
+}

package/dist/mcp-server.js

@@ -0,0 +1,111 @@
+// Responsibility: expose architecture queries through the MCP protocol.
+// Boundary: delegates rule evaluation to verbs and retains one warm graph per server.
+// McpServer's registration helpers typically expect zod input schemas. These inputs
+// are simple enough for manual validation, so Server uses raw JSON Schema instead.
+// This avoids a second direct dependency: zod remains an SDK dependency, not a project import.
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { createWarmGraph } from "./warm-graph.js";
+import { check } from "./verbs/check.js";
+import { rules } from "./verbs/rules.js";
+import { search } from "./verbs/search.js";
+import { simulate } from "./verbs/simulate.js";
+const tools = [
+    { name: "check", description: "Check project architecture, optionally focused on one file.",
+        inputSchema: { type: "object", properties: { file: { type: "string" } }, additionalProperties: false } },
+    { name: "rules", description: "Show the rules that govern a path.",
+        inputSchema: { type: "object", properties: { path: { type: "string" } }, required: ["path"], additionalProperties: false } },
+    { name: "search", description: "Search public exports by name.",
+        inputSchema: { type: "object", properties: { query: { type: "string" } }, required: ["query"], additionalProperties: false } },
+    { name: "simulate", description: "Check a proposed change set in memory. A change to the project's archstrict.config.ts previews a proposed config.",
+        inputSchema: { type: "object", properties: { changes: { type: "array", items: {
+                        type: "object", properties: { path: { type: "string" }, content: { type: ["string", "null"] } },
+                        required: ["path", "content"], additionalProperties: false,
+                    } } }, required: ["changes"], additionalProperties: false } },
+];
+// The declared inputSchema supports client discovery; the low-level SDK does not
+// enforce it before this handler runs. A client can skip validation, so these
+// simple fields need manual checks without another schema library.
+function stringField(args, field) {
+    const value = args[field];
+    if (typeof value !== "string")
+        throw new TypeError(`${field} must be a string`);
+    return value;
+}
+export function createArchstrictMcpServer(projectRoot) {
+    // One server spans many calls in the same process, unlike a one-shot CLI invocation.
+    // Retain each file's import records across refresh calls; a new holder per call would lose that reuse.
+    const warm = createWarmGraph();
+    const server = new Server({ name: "archstrict", version: "0.0.0" }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, () => ({ tools }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        // A failed call must leave the session available for later calls. Convert bad input,
+        // config-load failures, and invalid paths into tool errors the agent can read as data.
+        // Keep rejected promises inside this handler rather than letting them escape through the transport.
+        try {
+            const args = request.params.arguments ?? {};
+            // Discovery lists allowed tools and keys, but clients can send others.
+            // Reject them here rather than trusting the advertised schema.
+            const tool = tools.find(tool => tool.name === request.params.name);
+            if (tool === undefined)
+                throw new TypeError(`Unknown tool: ${request.params.name}`);
+            for (const key of Object.keys(args)) {
+                if (!Object.hasOwn(tool.inputSchema.properties ?? {}, key))
+                    throw new TypeError(`Unexpected argument: ${key}`);
+            }
+            let result;
+            switch (request.params.name) {
+                case "check":
+                    // Agents can check after every edit, as the PostToolUse hook does, so parsed-source reuse matters here.
+                    // Rules already uses a lighter graph builder without a type checker.
+                    // Search keeps its separate cold, one-shot design. Simulate reads
+                    // the disk cache without persisting its in-memory proposal.
+                    result = await check(projectRoot, args.file === undefined ? undefined : stringField(args, "file"), { buildGraph: warm.refresh });
+                    break;
+                case "rules":
+                    result = await rules(projectRoot, stringField(args, "path"));
+                    break;
+                case "search":
+                    result = await search(projectRoot, stringField(args, "query"));
+                    break;
+                case "simulate": {
+                    // Clients can also bypass the nested change schema. Check each entry by hand
+                    // so malformed paths or content cannot reach the simulation as trusted values.
+                    if (!Array.isArray(args.changes))
+                        throw new TypeError("changes must be an array");
+                    const changes = args.changes.map((change) => {
+                        if (typeof change !== "object" || change === null || Array.isArray(change)) {
+                            throw new TypeError("Each change must be an object");
+                        }
+                        const entry = change;
+                        if (Object.keys(entry).some(key => key !== "path" && key !== "content")) {
+                            throw new TypeError("Each change must contain only path and content");
+                        }
+                        const path = stringField(entry, "path");
+                        if (entry.content !== null && typeof entry.content !== "string") {
+                            throw new TypeError("content must be a string or null");
+                        }
+                        return { path, content: entry.content };
+                    });
+                    result = await simulate(projectRoot, changes);
+                    break;
+                }
+                default:
+                    throw new TypeError(`Unknown tool: ${request.params.name}`);
+            }
+            return { content: [{ type: "text", text: JSON.stringify(result) }] };
+        }
+        catch (error) {
+            return { isError: true, content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }] };
+        }
+    });
+    return server;
+}
+// The CLI and plugin wrapper need identical server construction and stdio setup.
+// A shared entry point keeps those callers aligned when startup behavior changes.
+export async function startArchstrictMcpServer(projectRoot) {
+    const server = createArchstrictMcpServer(projectRoot);
+    await server.connect(new StdioServerTransport());
+    return server;
+}

package/dist/module-candidates.js

@@ -0,0 +1,125 @@
+// Responsibility: turn a list of analyzed files into the groups init
+// declares as modules - one directory group per top-level (or per-container)
+// directory that holds an analyzed file, one file group per loose file -
+// plus the on-disk naming rule for each group and the literal
+// declaredModules-entry text init pastes into the generated config. The
+// same grouping and naming also produces the paste-ready suggestion for a
+// file an EXISTING config doesn't cover yet (rule 3's own `do:`, `archstrict
+// rules <path>`, and init's re-run listing all share `suggestUncovered`
+// below, so the three can never drift into different phrasings of the same
+// entry).
+// Boundary: no I/O, and no opinion about WHICH files are analyzed - the
+// caller (init's own walk, or a config-vs-graph consistency check) already
+// decided that and hands this module the resulting file list, anchor set,
+// and the config's own declaredModules (for the `taken`-name check).
+import { moduleGlobBaseDir, moduleGlobList } from "./module-graph.js";
+const byteSort = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+// Groups analyzed files by their nearest anchor: for a file `f`, the
+// longest anchor that contains it. A file sitting directly in its anchor is
+// its own group (a file group); otherwise the group is the first directory
+// below the anchor on the path to `f` (a directory group) - so a deeply
+// nested file (`src/runtime/db/pool.ts`) still groups under `src/runtime`,
+// one entry per top-level directory, not one per leaf.
+export function groupAnalyzedFiles(files, anchors) {
+    const sortedAnchors = [...anchors].sort((a, b) => b.length - a.length);
+    const groups = new Map();
+    for (const file of files) {
+        // "" is always the last (shortest) anchor tried, and always matches -
+        // every analyzed file is under the project root - so this always finds one.
+        const anchor = sortedAnchors.find((a) => a === "" || file.startsWith(`${a}/`));
+        const rest = anchor === "" ? file : file.slice(anchor.length + 1);
+        const [first, ...more] = rest.split("/");
+        const rel = anchor === "" ? first : `${anchor}/${first}`;
+        const kind = more.length === 0 ? "file" : "dir";
+        const existing = groups.get(rel);
+        if (existing !== undefined) {
+            existing.fileCount++;
+            continue;
+        }
+        groups.set(rel, { kind, rel, anchor, onDiskName: first, fileCount: 1 });
+    }
+    return [...groups.values()].sort((a, b) => byteSort(a.rel, b.rel));
+}
+// Naming, three cases: (1) a group's name is its on-disk name, unless that
+// name collides with another group's own on-disk name at the SAME anchor
+// depth - one directory cannot hold a file and a directory of the same
+// name, so a top-level `cli.ts` and a `src/cli.ts` never collide with each
+// other directly, only through rule 2; (2) a group below the project root
+// whose on-disk name is already `taken` (by an existing config entry, or by
+// another group sharing that name) instead takes its own project-relative
+// path as its name; (3) a project-root group (anchor "") has no deeper
+// path to fall back to - its on-disk name IS its rel - so a root name still
+// `taken` after that takes a "./"-prefixed rel instead (measured: pasting
+// `{ name: "./tools", glob: "tools/**" }` next to an existing "tools" gave
+// 0 violations and tsc passed). This only fires for a re-run's or rule 3's
+// suggestion - a fresh init never has a `taken` set with anything a fresh
+// root group's own on-disk name could collide with.
+export function nameCandidates(groups, taken) {
+    const onDiskCounts = new Map();
+    for (const g of groups)
+        onDiskCounts.set(g.onDiskName, (onDiskCounts.get(g.onDiskName) ?? 0) + 1);
+    return groups.map((g) => {
+        const collides = taken.has(g.onDiskName) || (g.anchor !== "" && (onDiskCounts.get(g.onDiskName) ?? 0) > 1);
+        const name = g.anchor === "" ? (collides ? `./${g.rel}` : g.onDiskName) : collides ? g.rel : g.onDiskName;
+        const glob = g.kind === "dir" ? `${g.rel}/**` : g.rel;
+        const entry = g.kind === "dir" ? { name, glob } : { name, glob, surface: g.onDiskName };
+        return { ...g, entry, excludeGlob: glob };
+    });
+}
+const q = JSON.stringify;
+// The literal declaredModules[] entry text init pastes into the generated
+// config, and the same text a later suggestion (for the root-name-collision
+// case above) would paste for an uncovered path - kept as one function so
+// the two can never drift into two different phrasings of the same entry
+// shape. A directory entry carries no `surface` of its own (the top-level
+// default, or the directory's own package.json exports map, applies
+// instead) - a file
+// entry always does, naming the file itself, since a file with no surface
+// of its own would otherwise be entirely private (nothing else could ever
+// export from it).
+export function declaredModuleEntryText(entry) {
+    return entry.surface === undefined
+        ? `{ name: ${q(entry.name)}, glob: ${q(entry.glob)} }`
+        : `{ name: ${q(entry.name)}, glob: ${q(entry.glob)}, surface: ${q(entry.surface)} }`;
+}
+// The one shared entry point rule 3, `archstrict rules <path>`, and init's
+// re-run all call: given the project-relative paths of files an EXISTING
+// config's declaredModules doesn't cover, group and name them exactly as a
+// fresh init would, with the config's own declaredModules entries counted
+// as `taken` names. Anchors are the project root plus the parent directory
+// of each existing entry's own glob base - the same depth a fresh init
+// itself would have grouped that entry at, computed by string ops alone
+// (moduleGlobBaseDir strips the glob down to its literal prefix; only
+// that prefix's parent directory is the anchor, and a file list
+// contributes one anchor per path).
+export function suggestUncovered(uncoveredRelFiles, declaredModules) {
+    const anchors = new Set([""]);
+    for (const dm of declaredModules) {
+        // The parent of each glob's literal base, the same depth a fresh init
+        // groups at. A directory glob `src/app/**` anchors at `src`, so a
+        // sibling directory is its own group. A file glob `src/sqlite.ts`
+        // anchors at `src`, so the file itself is a file group. A file list
+        // anchors at the shared directory, once per path.
+        for (const glob of moduleGlobList(dm.glob)) {
+            const base = moduleGlobBaseDir(glob);
+            const slash = base.lastIndexOf("/");
+            anchors.add(slash === -1 ? "" : base.slice(0, slash));
+        }
+    }
+    const taken = new Set(declaredModules.map((dm) => dm.name));
+    return nameCandidates(groupAnalyzedFiles(uncoveredRelFiles, [...anchors]), taken);
+}
+// Which of `suggestUncovered`'s own groups a single project-relative file
+// belongs to - a file group's own `rel` IS the file, a directory group's
+// `rel` is its own directory, so the file sits somewhere below it.
+export function groupForRelFile(rel, groups) {
+    return groups.find((g) => g.rel === rel || rel.startsWith(`${g.rel}/`));
+}
+// The one sentence rule 3's `do:` and `archstrict rules <path>` both print
+// for a single uncovered file - the paste-ready entry, with the exclude
+// alternative right beside it so the same suggestion never leads an agent
+// to add a directory entry for a file that turns out not to be module
+// content at all.
+export function suggestionDoText(group) {
+    return `add ${declaredModuleEntryText(group.entry)} to declaredModules in archstrict.config.ts, or add ${q(group.excludeGlob)} to exclude if it is not module content; then run archstrict init`;
+}