archstrict 0.0.0 → 0.2.0

package/dist/cli.js

@@ -0,0 +1,243 @@
+#!/usr/bin/env node
+// Responsibility: parse argv and dispatch to a verb (init, check, todo, rules, agents, recommend, fix, simulate, search, hotspots).
+// Boundary: no rule logic here; verbs live in their own modules.
+import { startArchstrictMcpServer } from "./mcp-server.js";
+import { search, formatSearchText } from "./verbs/search.js";
+import { simulate, formatSimulateText } from "./verbs/simulate.js";
+import { agents, formatAgentsText } from "./verbs/agents.js";
+import { recommend, formatRecommendText } from "./verbs/recommend.js";
+import { fix, formatFixText } from "./verbs/fix.js";
+import { init } from "./verbs/init.js";
+import { check, formatText, hasBlockingViolations } from "./verbs/check.js";
+import { todo } from "./verbs/todo.js";
+import { rules, formatRulesText } from "./verbs/rules.js";
+import { hotspots, formatHotspotsText } from "./verbs/hotspots.js";
+import { ReportError } from "./report-error.js";
+import { parseCheckArgv } from "./check-options.js";
+// Text and JSON share one shape: the message, then the one command to run.
+// A violation already carries `do`; a thrown config or missing-file
+// failure goes through here so it does too.
+function reportFailure(error, verb, asJson) {
+    const message = error instanceof Error ? error.message : String(error);
+    const doText = error instanceof ReportError ? error.do : `archstrict ${verb}`;
+    if (asJson) {
+        process.stdout.write(`${JSON.stringify({ error: message, do: doText })}\n`);
+    }
+    else {
+        process.stderr.write(`archstrict: ${message}\ndo: ${doText}\n`);
+    }
+}
+// `--json` is a flag, never read as a directory, so it's stripped before
+// the positional rules apply. Every other argument is a directory, so any
+// other flag-looking argument ("-" prefix) is rejected outright rather
+// than silently accepted as a directory name. More than one positional
+// means the shell expanded an unquoted glob (`src/*` with more than one
+// match) - archstrict cannot tell that apart from a person genuinely
+// typing two directory names, so both read the same way: init takes
+// exactly one.
+function parseInitArgv(argv) {
+    const positional = argv.filter((arg) => arg !== "--json");
+    for (const arg of positional) {
+        if (arg.startsWith("-"))
+            throw new ReportError(`unknown option '${arg}'`, "archstrict init");
+    }
+    if (positional.length > 1) {
+        throw new ReportError(`init takes one directory; got ${positional.length} arguments (the shell expands an unquoted * or src/*)`, "archstrict init");
+    }
+    return positional[0];
+}
+async function runInit(args) {
+    const asJson = args.includes("--json");
+    const result = await init(process.cwd(), parseInitArgv(args));
+    if (asJson) {
+        // Field names and shapes follow check's and todo's own --json
+        // convention: one object, keys in the same order this prints them.
+        // `typesPath` (not `generatedPath`, InitResult's own internal name)
+        // matches archstrict.types.ts's own file name, which is what an agent
+        // reading this JSON actually needs to find.
+        process.stdout.write(`${JSON.stringify({
+            configPath: result.configPath,
+            typesPath: result.generatedPath,
+            configWritten: result.configWritten,
+            opened: result.opened === "" ? null : result.opened,
+            moduleNames: result.moduleNames,
+            hiddenDirs: result.hiddenDirs,
+            noiseDirs: result.noiseDirs,
+            testFileExcludes: result.testFileExcludes.map((t) => ({ pattern: t.label, exclude: t.exclude, files: t.fileCount })),
+            uncovered: result.uncovered.map((g) => ({
+                path: g.rel,
+                kind: g.kind,
+                files: g.fileCount,
+                declare: g.entry,
+                exclude: g.excludeGlob,
+            })),
+            notes: result.notes,
+            do: result.doText,
+        })}\n`);
+        return 0;
+    }
+    for (const line of result.messageLines)
+        process.stdout.write(`${line}\n`);
+    process.stdout.write(`do: ${result.doText}\n`);
+    return 0;
+}
+async function runCheck(args) {
+    const parsed = parseCheckArgv(args);
+    const result = await check(process.cwd(), parsed.focusFile, {
+        prove: parsed.prove,
+        rules: parsed.rules,
+        modules: parsed.modules,
+        frozen: parsed.frozen,
+    });
+    if (parsed.asJson) {
+        process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+    }
+    else {
+        process.stdout.write(formatText(result));
+    }
+    return hasBlockingViolations(result) ? 1 : 0;
+}
+async function runTodo(args) {
+    const asJson = args.includes("--json");
+    const result = await todo(process.cwd());
+    if (asJson) {
+        process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+        return 0;
+    }
+    if (result.firstRun) {
+        process.stdout.write(`froze ${result.added} violation(s)\n`);
+    }
+    else {
+        process.stdout.write(`pruned ${result.pruned} stale entrie(s)\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) {
+    const asJson = args.includes("--json");
+    const paths = args.filter((arg) => arg !== "--json");
+    if (paths.length !== 1)
+        throw new Error("usage: archstrict rules <path> [--json]");
+    const result = await rules(process.cwd(), paths[0]);
+    process.stdout.write(asJson ? JSON.stringify(result, null, 2) + "\n" : formatRulesText(result));
+    return 0;
+}
+function runAgents(args) {
+    if (args.some((arg) => arg !== "--json" && arg !== "--remove")) {
+        throw new Error("usage: archstrict agents [--remove] [--json]");
+    }
+    const result = agents(process.cwd(), args.includes("--remove"));
+    process.stdout.write(args.includes("--json") ? JSON.stringify(result, null, 2) + "\n" : formatAgentsText(result));
+    return 0;
+}
+async function runRecommend(args) {
+    const paths = args.filter(arg => arg !== "--json");
+    if (paths.length > 1 || paths.some(arg => arg.startsWith("-"))) {
+        throw new Error("usage: archstrict recommend [dir] [--json]");
+    }
+    // Without a config, the directory controls init's own in-memory walk; a
+    // declared config supplies its own scope regardless.
+    const result = await recommend(process.cwd(), paths[0]);
+    process.stdout.write(args.includes("--json") ? JSON.stringify(result, null, 2) + "\n" : formatRecommendText(result));
+    return 0;
+}
+async function runFix(args) {
+    const paths = args.filter(arg => arg !== "--json" && arg !== "--dry-run");
+    if (paths.length > 1 || paths.some(arg => arg.startsWith("-"))) {
+        throw new Error("usage: archstrict fix [file] [--dry-run] [--json]");
+    }
+    const dryRun = args.includes("--dry-run");
+    const result = await fix(process.cwd(), paths[0], dryRun);
+    process.stdout.write(args.includes("--json") ? JSON.stringify(result, null, 2) + "\n" : formatFixText(result));
+    return dryRun || (result.unfixable.length === 0 && result.reverted.length === 0) ? 0 : 1;
+}
+async function runSimulate(args) {
+    if (args.some(arg => arg !== "--json" && arg !== "--whole-project")) {
+        throw new Error("usage: archstrict simulate [--json] [--whole-project]");
+    }
+    let input = "";
+    process.stdin.setEncoding("utf8");
+    for await (const chunk of process.stdin)
+        input += chunk;
+    const body = JSON.parse(input);
+    if (typeof body !== "object" || body === null || !("changes" in body) || !Array.isArray(body.changes)) {
+        throw new Error("stdin must contain a JSON object with a changes array");
+    }
+    const result = await simulate(process.cwd(), body.changes, { wholeProject: args.includes("--whole-project") });
+    process.stdout.write(args.includes("--json") ? JSON.stringify(result, null, 2) + "\n" : formatSimulateText(result));
+    return result.added.length === 0 ? 0 : 1;
+}
+async function runSearch(args) {
+    const query = args.filter(arg => arg !== "--json").join(" ");
+    const result = await search(process.cwd(), query);
+    process.stdout.write(args.includes("--json") ? JSON.stringify(result, null, 2) + "\n" : formatSearchText(result));
+    return 0;
+}
+async function runHotspots(args) {
+    let since;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--json")
+            continue;
+        if (arg === "--since" && since === undefined && args[i + 1] !== undefined && !args[i + 1].startsWith("--")) {
+            since = args[++i];
+            continue;
+        }
+        throw new Error("usage: archstrict hotspots [--since <git ref or date>] [--json]");
+    }
+    const result = await hotspots(process.cwd(), since);
+    process.stdout.write(args.includes("--json") ? JSON.stringify(result, null, 2) + "\n" : formatHotspotsText(result));
+    return 0;
+}
+// The connected transport's stdin listener keeps Node alive after this function returns.
+// A real subprocess stayed alive with stdin open and exited when stdin closed;
+// the host can also terminate it. A separate server-closed promise is unnecessary.
+async function runMcp() {
+    await startArchstrictMcpServer(process.cwd());
+    return 0;
+}
+async function main(argv) {
+    const [verb, ...rest] = argv;
+    if (verb === undefined) {
+        process.stderr.write("usage: archstrict <init|check|todo|rules|agents|recommend|fix|simulate|search|hotspots|mcp> [args]\n");
+        return 1;
+    }
+    try {
+        if (verb === "mcp")
+            return await runMcp();
+        if (verb === "search")
+            return await runSearch(rest);
+        if (verb === "hotspots")
+            return await runHotspots(rest);
+        if (verb === "simulate")
+            return await runSimulate(rest);
+        if (verb === "fix")
+            return await runFix(rest);
+        if (verb === "recommend")
+            return await runRecommend(rest);
+        if (verb === "init")
+            return await runInit(rest);
+        if (verb === "check")
+            return await runCheck(rest);
+        if (verb === "todo")
+            return await runTodo(rest);
+        if (verb === "rules")
+            return await runRules(rest);
+        if (verb === "agents")
+            return runAgents(rest);
+        process.stderr.write(`archstrict: '${verb}' is not implemented yet\ndo: archstrict init\n`);
+        return 1;
+    }
+    catch (error) {
+        // A config or missing-file error throws before any real output.
+        // reportFailure prints the message and a do: line — the same pair
+        // a violation carries — instead of a bare message or stack trace.
+        reportFailure(error, verb, rest.includes("--json"));
+        return 1;
+    }
+}
+process.exitCode = await main(process.argv.slice(2));

package/dist/config-pointer.js

@@ -0,0 +1,251 @@
+// Responsibility: attach structured config locations to raw violations and
+// resolve each config value path against the config's TypeScript source.
+// Boundary: rule evaluation and report formatting stay in their own modules.
+// Rules can supply an exact index when duplicate config entries need distinct
+// locations; this module owns the fallback selection for other findings.
+import { existsSync, readFileSync } from "node:fs";
+import ts from "typescript";
+export const CONFIG_POINTER_SPECS = Symbol("archstrict.config-pointer-specs");
+function pathParts(pointer) {
+    const parts = [];
+    const pattern = /(?:^|\.)([^.\[\]]+)|\[(\d+)\]/g;
+    for (const match of pointer.matchAll(pattern)) {
+        parts.push(match[2] === undefined ? match[1] : Number(match[2]));
+    }
+    return parts;
+}
+function valueAt(config, pointer) {
+    let value = config;
+    for (const part of pathParts(pointer)) {
+        if (typeof part === "number") {
+            value = Array.isArray(value) ? value[part] : undefined;
+        }
+        else {
+            value = typeof value === "object" && value !== null ? value[part] : undefined;
+        }
+    }
+    if (Array.isArray(value) && value.length > 20) {
+        return [...value.slice(0, 20), `... ${value.length - 20} more`];
+    }
+    return value ?? null;
+}
+export function withPointerSpecs(violation, specs) {
+    Object.defineProperty(violation, CONFIG_POINTER_SPECS, { value: specs });
+    return violation;
+}
+function unwrap(expression) {
+    let current = expression;
+    while (ts.isParenthesizedExpression(current) || ts.isAsExpression(current) || ts.isSatisfiesExpression(current)) {
+        current = current.expression;
+    }
+    return current;
+}
+function propertyName(name) {
+    if (ts.isIdentifier(name) || ts.isStringLiteral(name) || ts.isNumericLiteral(name))
+        return name.text;
+    return undefined;
+}
+function isLiteralPosition(node) {
+    return ts.isObjectLiteralExpression(node) || ts.isArrayLiteralExpression(node) || ts.isStringLiteralLike(node) ||
+        ts.isNumericLiteral(node) || node.kind === ts.SyntaxKind.TrueKeyword || node.kind === ts.SyntaxKind.FalseKeyword ||
+        node.kind === ts.SyntaxKind.NullKeyword;
+}
+function configObject(sourceFile) {
+    for (const statement of sourceFile.statements) {
+        if (ts.isExportAssignment(statement))
+            return unwrap(statement.expression);
+    }
+    return undefined;
+}
+function syntaxAt(root, parts) {
+    let current = root;
+    let nearestLiteral = root;
+    for (const part of parts) {
+        const expression = ts.isExpression(current) ? unwrap(current) : current;
+        let next;
+        if (typeof part === "number" && ts.isArrayLiteralExpression(expression)) {
+            // A spread contributes an unknown number of runtime entries. Once one
+            // appears before this index, syntax indices no longer identify values.
+            if (expression.elements.slice(0, part + 1).some(ts.isSpreadElement))
+                break;
+            next = expression.elements[part];
+        }
+        else if (typeof part === "string" && ts.isObjectLiteralExpression(expression)) {
+            let selected;
+            let selectedIndex = -1;
+            let lastUnknownIndex = -1;
+            expression.properties.forEach((candidate, index) => {
+                if (ts.isSpreadAssignment(candidate)) {
+                    lastUnknownIndex = index;
+                    return;
+                }
+                if (!ts.isPropertyAssignment(candidate) && !ts.isShorthandPropertyAssignment(candidate))
+                    return;
+                const name = propertyName(candidate.name);
+                if (name === undefined)
+                    lastUnknownIndex = index;
+                else if (name === part) {
+                    selected = candidate;
+                    selectedIndex = index;
+                }
+            });
+            // A later spread or computed key can replace the selected runtime
+            // value. The containing object is the nearest reliable literal then.
+            if (selected === undefined || selectedIndex < lastUnknownIndex)
+                break;
+            next = ts.isPropertyAssignment(selected) ? selected.initializer : selected.name;
+        }
+        if (next === undefined)
+            break;
+        current = next;
+        const unwrapped = ts.isExpression(next) ? unwrap(next) : next;
+        if (isLiteralPosition(unwrapped))
+            nearestLiteral = unwrapped;
+    }
+    const selected = ts.isExpression(current) ? unwrap(current) : current;
+    return isLiteralPosition(selected) ? selected : nearestLiteral;
+}
+export function createConfigLocator(config, sourceOverride) {
+    let sourceFile;
+    let root;
+    if (sourceOverride !== undefined || existsSync(config.configPath)) {
+        const source = sourceOverride ?? readFileSync(config.configPath, "utf8");
+        sourceFile = ts.createSourceFile(config.configPath, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+        root = configObject(sourceFile);
+    }
+    return {
+        pointer(pointer, role) {
+            let line = 1;
+            let column = 1;
+            if (sourceFile !== undefined && root !== undefined) {
+                const node = syntaxAt(root, pathParts(pointer));
+                const position = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
+                line = position.line + 1;
+                column = position.character + 1;
+            }
+            return { path: config.configPath, pointer, value: valueAt(config, pointer), line, column, role };
+        },
+    };
+}
+export function declaredModulePointerForName(config, name) {
+    const index = config.declaredModules?.findIndex((entry) => entry.name === name) ?? -1;
+    return index < 0 ? "declaredModules" : `declaredModules[${index}]`;
+}
+function edgeIdentifier(kind, entry) {
+    if (kind === "allowDeny")
+        return `${entry.source} -> ${entry.targetNamespace}`;
+    if (kind === "order")
+        return `${entry.tagNamespace}${entry.within === undefined ? "" : ` within ${entry.within}`}`;
+    const from = typeof entry.from === "string" ? entry.from : JSON.stringify(entry.from);
+    const to = typeof entry.to === "string" ? entry.to : JSON.stringify(entry.to);
+    return `${from} -> ${to}`;
+}
+function indexByEvidence(entries, predicate) {
+    return entries?.findIndex(predicate) ?? -1;
+}
+function pointerSpecs(violation, config) {
+    if (violation[CONFIG_POINTER_SPECS] !== undefined)
+        return [...violation[CONFIG_POINTER_SPECS]];
+    switch (violation.rule) {
+        case "public-surface-bypass":
+        case "type-leak":
+            return [{ pointer: declaredModulePointerForName(config, violation.todoModule), role: "governs" }];
+        case "uncovered-module":
+            return [{ pointer: "declaredModules", role: "governs" }];
+        case "cycle":
+            return [
+                { pointer: declaredModulePointerForName(config, violation.todoModule), role: "governs" },
+                { pointer: "ignoredCycles", role: "edit-here" },
+            ];
+        case "stale-cycle-exception": {
+            const index = indexByEvidence(config.ignoredCycles, ([a, b]) => violation.evidence.includes(`['${a}', '${b}']`));
+            return [{ pointer: index < 0 ? "ignoredCycles" : `ignoredCycles[${index}]`, role: "fired" }];
+        }
+        case "must-be-empty": {
+            const index = indexByEvidence(config.mustBeEmpty, (entry) => violation.evidence.includes(`'${entry.glob}'`));
+            return [{ pointer: index < 0 ? "mustBeEmpty" : `mustBeEmpty[${index}]`, role: "fired" }];
+        }
+        case "deprecated-edge-increased": {
+            const index = indexByEvidence(config.deprecated, (entry) => violation.evidence.startsWith(`${entry.from} -> ${entry.to}:`));
+            return [{ pointer: index < 0 ? "deprecated" : `deprecated[${index}].count`, role: "fired" }];
+        }
+        case "tag-boundary": {
+            const rules = config.edges?.allowDeny ?? [];
+            const index = rules.findIndex((entry) => violation.because === entry.because && violation.evidence.includes(`from '${entry.source}'`));
+            if (index < 0)
+                return [{ pointer: "edges.allowDeny", role: "fired" }];
+            const rule = rules[index];
+            if (rule.deny !== undefined) {
+                const deniedIndex = rule.deny.findIndex((value) => violation.evidence.includes(`'${rule.targetNamespace}:${value}'`));
+                if (deniedIndex >= 0)
+                    return [
+                        { pointer: `edges.allowDeny[${index}].deny[${deniedIndex}]`, role: "fired" },
+                        { pointer: `edges.allowDeny[${index}].allow`, role: "edit-here" },
+                    ];
+            }
+            return [{ pointer: `edges.allowDeny[${index}].allow`, role: "fired" }];
+        }
+        case "tag-order": {
+            const rules = config.edges?.order ?? [];
+            const index = rules.findIndex((entry) => violation.because === entry.because && violation.evidence.includes(`(${entry.tagNamespace} sequence:`));
+            return [{ pointer: index < 0 ? "edges.order" : `edges.order[${index}].sequence`, role: "fired" }];
+        }
+        case "point-rule": {
+            const rules = config.edges?.point ?? [];
+            const index = rules.findIndex((entry) => violation.because === entry.because &&
+                violation.do.includes(`'${edgeIdentifier("point", entry)}'`));
+            return [{ pointer: index < 0 ? "edges.point" : `edges.point[${index}]`, role: "fired" }];
+        }
+        case "clean-module-has-todo": {
+            const index = config.strict?.findIndex((name) => violation.evidence.includes(`module '${name}'`)) ?? -1;
+            return [{ pointer: index < 0 ? "strict" : `strict[${index}]`, role: "fired" }];
+        }
+        case "stale-todo":
+            return [{ pointer: "declaredModules", role: "governs" }];
+        case "empty-rule-set": {
+            if (violation.evidence === "no modules declared in declaredModules") {
+                return [{ pointer: "declaredModules", role: "fired" }];
+            }
+            const classifyIndex = indexByEvidence(config.classify, (entry) => violation.evidence.includes(`classify glob '${entry.glob}'`));
+            if (classifyIndex >= 0)
+                return [{ pointer: `classify[${classifyIndex}]`, role: "fired" }];
+            const deprecatedIndex = indexByEvidence(config.deprecated, (entry) => violation.evidence.includes(`'${entry.from} -> ${entry.to}'`));
+            if (deprecatedIndex >= 0)
+                return [{ pointer: `deprecated[${deprecatedIndex}]`, role: "fired" }];
+            for (const kind of ["allowDeny", "order", "point"]) {
+                const rules = config.edges?.[kind] ?? [];
+                const index = rules.findIndex((entry) => violation.evidence.includes(`${kind} rule '${edgeIdentifier(kind, entry)}'`));
+                if (index >= 0)
+                    return [{ pointer: `edges.${kind}[${index}]`, role: "fired" }];
+            }
+            return [{ pointer: "edges", role: "fired" }];
+        }
+        case "exhaustive-allow-list": {
+            const rules = config.edges?.allowDeny ?? [];
+            const index = rules.findIndex((entry) => violation.because === entry.because &&
+                violation.evidence.includes(`'${edgeIdentifier("allowDeny", entry)}'`));
+            return [{ pointer: index < 0 ? "edges.allowDeny" : `edges.allowDeny[${index}].allow`, role: "fired" }];
+        }
+        case "config-meaning": {
+            for (const kind of ["allowDeny", "order", "point"]) {
+                const rules = config.edges?.[kind] ?? [];
+                const index = rules.findIndex((entry) => violation.evidence.includes(`${kind} rule (`) && violation.because === entry.because);
+                if (index >= 0)
+                    return [{ pointer: `edges.${kind}[${index}]`, role: "fired" }];
+            }
+            return [{ pointer: "edges", role: "governs" }];
+        }
+        default:
+            return [{ pointer: "declaredModules", role: "governs" }];
+    }
+}
+export function locateViolation(violation, config, locator, specs = pointerSpecs(violation, config)) {
+    const pointers = specs.map(({ pointer, role }) => locator.pointer(pointer, role));
+    const configPointers = pointers.length === 1 ? pointers[0] : pointers;
+    const primary = pointers[0];
+    const position = violation.path === config.configPath ? { line: primary.line, column: primary.column } : {};
+    return { ...violation, ...position, config: configPointers };
+}
+export function locateViolations(violations, config, locator) {
+    return violations.map((violation) => locateViolation(violation, config, locator));
+}