@lifesavertech/archguard-cli 2.0.0

package/README.md

@@ -0,0 +1,46 @@
+# @lifesavertech/archguard-cli
+
+Command-line interface for ArchGuard — architecture gate for AI-assisted React PRs.
+
+## Install
+
+```bash
+npm install -D @lifesavertech/archguard-cli
+npx archguard --version
+```
+
+Until published to npm, use the [GitHub Action](https://github.com/lindseystead/ArchGuard/blob/main/docs/github-action.md) or [install from source](https://github.com/lindseystead/ArchGuard#install-from-this-repository).
+
+> The legacy scope `@archguard/cli` on npm is an unrelated package. Do not use it.
+
+## Usage
+
+```bash
+archguard init                              # boundaries-only (v2 default)
+archguard init --preset react-layered       # boundaries + UI heuristics
+archguard init --preset feature-sliced-react
+archguard check
+archguard check --root apps/web --verbose
+archguard check --baseline
+archguard check --format json
+```
+
+## Presets
+
+| Preset | UI heuristics | Layers |
+| --- | --- | --- |
+| _(default)_ / `boundaries-only` | Off | domain, features, ui, shared |
+| `react-layered` | On | domain, features, ui, shared |
+| `feature-sliced-react` | On | FSD: app, pages, features, entities, shared |
+
+Preset definitions live in `src/presets/`.
+
+## Documentation
+
+| Doc | Purpose |
+| --- | --- |
+| [ADOPTION.md](https://github.com/lindseystead/ArchGuard/blob/main/docs/ADOPTION.md) | Setup guide |
+| [architecture.example.yaml](https://github.com/lindseystead/ArchGuard/blob/main/docs/architecture.example.yaml) | Config reference |
+| [ENGINEERING_PLAN.md](https://github.com/lindseystead/ArchGuard/blob/main/docs/ENGINEERING_PLAN.md) | v2 roadmap |
+
+Full documentation: [github.com/lindseystead/ArchGuard](https://github.com/lindseystead/ArchGuard)

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+/** CLI entry point. */
+import { ImportInfo, RuleContext, ImportGraph, Violation } from "@lifesavertech/archguard-core";
+interface CheckOptions {
+    baselinePath?: string | null;
+    updateBaselinePath?: string | null;
+    projectRoot?: string | null;
+    verbose?: boolean;
+}
+interface CheckSummary {
+    mode: "baseline" | "check" | "update-baseline";
+    passed: boolean;
+    violationCount: number;
+    violations: Violation[];
+    suppressedViolationCount: number;
+    baselinePath?: string | null;
+}
+interface SourceFileAnalysis {
+    filePath: string;
+    sourceCode: string;
+    ast: RuleContext["ast"];
+    imports: ImportInfo[];
+}
+export declare function initializeArchguard(preset?: string): void;
+export declare function detectReactTypeScript(cwd: string): boolean;
+export declare function runChecks(options?: CheckOptions): CheckSummary;
+export declare function findTypeScriptFiles(dir: string): string[];
+export declare function buildImportGraph(sourceFileAnalyses: SourceFileAnalysis[]): ImportGraph;
+export declare function resolveImportPath(importPath: string, fromFile: string, projectRoot?: string): string | null;
+export {};

package/dist/index.js

@@ -0,0 +1,561 @@
+#!/usr/bin/env node
+"use strict";
+/** CLI entry point. */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initializeArchguard = initializeArchguard;
+exports.detectReactTypeScript = detectReactTypeScript;
+exports.runChecks = runChecks;
+exports.findTypeScriptFiles = findTypeScriptFiles;
+exports.buildImportGraph = buildImportGraph;
+exports.resolveImportPath = resolveImportPath;
+const commander_1 = require("commander");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const chalk_1 = __importDefault(require("chalk"));
+const archguard_core_1 = require("@lifesavertech/archguard-core");
+const archguard_rules_react_1 = require("@lifesavertech/archguard-rules-react");
+const archguard_guidance_1 = require("@lifesavertech/archguard-guidance");
+const presets_1 = require("./presets");
+const program = new commander_1.Command();
+const DEFAULT_BASELINE_PATH = ".archguard-baseline.json";
+const SARIF_SCHEMA_URL = "https://json.schemastore.org/sarif-2.1.0.json";
+program.name("archguard").description("Architecture guard for React + TypeScript projects").version("2.0.0");
+program
+    .command("init")
+    .description("Initialize archguard in the current project")
+    .option("--preset <preset>", `Architecture preset (${(0, presets_1.formatPresetList)()})`)
+    .action((options) => {
+    try {
+        initializeArchguard(options.preset);
+        console.log(chalk_1.default.green("✓ archguard initialized successfully"));
+    }
+    catch (error) {
+        console.error(chalk_1.default.red(`✗ Error: ${error instanceof Error ? error.message : String(error)}`));
+        process.exit(1);
+    }
+});
+program
+    .command("check")
+    .description("Check project against architecture rules")
+    .option("--baseline [path]", "Allow violations already captured in a baseline file")
+    .option("--format <format>", "Output format (text, json, sarif)", "text")
+    .option("--root <path>", "Project subdirectory to scan (for monorepos)")
+    .option("--update-baseline [path]", "Write the current violations to a baseline file and exit")
+    .option("--verbose", "Log unresolved imports and scan diagnostics")
+    .action((options) => {
+    try {
+        const baselinePath = normalizeOptionalPath(options.baseline);
+        const format = normalizeOutputFormat(options.format);
+        const updateBaselinePath = normalizeOptionalPath(options.updateBaseline);
+        const projectRoot = normalizeOptionalString(options.root);
+        if (baselinePath && updateBaselinePath) {
+            throw new Error("Use either --baseline or --update-baseline, not both.");
+        }
+        const result = runChecks({
+            baselinePath,
+            updateBaselinePath,
+            projectRoot,
+            verbose: Boolean(options.verbose),
+        });
+        printCheckSummary(result, format);
+        if (!result.passed) {
+            process.exit(1);
+        }
+    }
+    catch (error) {
+        console.error(chalk_1.default.red(`✗ Error: ${error instanceof Error ? error.message : String(error)}`));
+        process.exit(1);
+    }
+});
+if (require.main === module) {
+    program.parse();
+}
+function initializeArchguard(preset) {
+    const cwd = process.cwd();
+    if (!detectReactTypeScript(cwd)) {
+        throw new Error("React + TypeScript project not detected");
+    }
+    const architectureYamlPath = path.join(cwd, "architecture.yaml");
+    if (fs.existsSync(architectureYamlPath)) {
+        throw new Error("architecture.yaml already exists");
+    }
+    fs.writeFileSync(architectureYamlPath, (0, presets_1.getPresetConfig)(preset));
+    const guidanceDir = path.join(cwd, ".archguard");
+    if (!fs.existsSync(guidanceDir)) {
+        fs.mkdirSync(guidanceDir, { recursive: true });
+    }
+    const editorGuidePath = path.join(guidanceDir, "ARCHITECTURE_RULES.md");
+    const architecture = (0, archguard_core_1.loadArchitectureConfig)(architectureYamlPath);
+    const editorGuide = (0, archguard_guidance_1.generateEditorGuide)(architecture);
+    fs.writeFileSync(editorGuidePath, editorGuide);
+    const agentsPath = path.join(cwd, "AGENTS.md");
+    if (!fs.existsSync(agentsPath)) {
+        fs.writeFileSync(agentsPath, (0, archguard_guidance_1.generateAgentsGuide)(architecture));
+    }
+    installPreCommitHook(cwd);
+}
+function detectReactTypeScript(cwd) {
+    const packageJsonPath = path.join(cwd, "package.json");
+    if (!fs.existsSync(packageJsonPath)) {
+        return false;
+    }
+    const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
+    const deps = { ...packageJson.dependencies, ...packageJson.devDependencies };
+    const hasReact = deps.react || deps["react-dom"];
+    const hasTypeScript = deps.typescript || fs.existsSync(path.join(cwd, "tsconfig.json"));
+    return !!(hasReact && hasTypeScript);
+}
+function runChecks(options = {}) {
+    const cwd = process.cwd();
+    const scanRoot = resolveScanRoot(cwd, options.projectRoot);
+    const { violations: allViolations, scanSummary } = collectViolations(scanRoot, {
+        verbose: options.verbose,
+    });
+    if (options.verbose && scanSummary.unresolvedImports.length > 0) {
+        printUnresolvedImports(scanSummary.unresolvedImports, scanRoot);
+    }
+    if (options.updateBaselinePath) {
+        writeBaseline(options.updateBaselinePath, allViolations, scanRoot);
+        return {
+            mode: "update-baseline",
+            passed: true,
+            violationCount: allViolations.length,
+            violations: allViolations,
+            suppressedViolationCount: 0,
+            baselinePath: options.updateBaselinePath,
+        };
+    }
+    if (options.baselinePath) {
+        const baselineViolations = loadBaseline(options.baselinePath);
+        const { newViolations, suppressedViolationCount } = filterViolationsAgainstBaseline(allViolations, baselineViolations, scanRoot);
+        if (newViolations.length > 0) {
+            return {
+                mode: "baseline",
+                passed: false,
+                violationCount: newViolations.length,
+                violations: newViolations,
+                suppressedViolationCount,
+                baselinePath: options.baselinePath,
+            };
+        }
+        return {
+            mode: "baseline",
+            passed: true,
+            violationCount: 0,
+            violations: [],
+            suppressedViolationCount,
+            baselinePath: options.baselinePath,
+        };
+    }
+    if (allViolations.length > 0) {
+        return {
+            mode: "check",
+            passed: false,
+            violationCount: allViolations.length,
+            violations: allViolations,
+            suppressedViolationCount: 0,
+        };
+    }
+    return {
+        mode: "check",
+        passed: true,
+        violationCount: 0,
+        violations: [],
+        suppressedViolationCount: 0,
+    };
+}
+function findTypeScriptFiles(dir) {
+    const files = [];
+    const ignoreDirs = ["node_modules", "dist", "build", ".git", ".archguard"];
+    function walk(currentDir) {
+        const entries = fs.readdirSync(currentDir, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = path.join(currentDir, entry.name);
+            if (entry.isDirectory()) {
+                if (!ignoreDirs.includes(entry.name)) {
+                    walk(fullPath);
+                }
+            }
+            else if (entry.isFile() && (entry.name.endsWith(".ts") || entry.name.endsWith(".tsx"))) {
+                files.push(fullPath);
+            }
+        }
+    }
+    walk(dir);
+    return files;
+}
+function buildImportGraph(sourceFileAnalyses) {
+    const graph = {};
+    const fileSet = new Set(sourceFileAnalyses.map((analysis) => analysis.filePath));
+    for (const analysis of sourceFileAnalyses) {
+        const resolvedImports = [];
+        for (const importedModule of analysis.imports) {
+            if (importedModule.resolvedPath && fileSet.has(importedModule.resolvedPath)) {
+                resolvedImports.push(importedModule.resolvedPath);
+            }
+        }
+        graph[analysis.filePath] = resolvedImports;
+    }
+    return graph;
+}
+function analyzeSourceFiles(sourceFiles, importResolver, unresolvedImports) {
+    return sourceFiles.map((filePath) => {
+        const sourceCode = fs.readFileSync(filePath, "utf-8");
+        const ast = (0, archguard_core_1.parseTypeScript)(sourceCode, filePath);
+        const imports = (0, archguard_core_1.extractImports)(ast).map((importInfo) => {
+            const resolvedPath = importResolver.resolve(importInfo.from, filePath);
+            if (!resolvedPath &&
+                (importInfo.from.startsWith(".") || importInfo.from.startsWith("@") || importInfo.from.startsWith("/"))) {
+                unresolvedImports.push({
+                    file: filePath,
+                    importPath: importInfo.from,
+                });
+            }
+            return {
+                ...importInfo,
+                resolvedPath,
+            };
+        });
+        return {
+            filePath,
+            sourceCode,
+            ast,
+            imports,
+        };
+    });
+}
+function resolveImportPath(importPath, fromFile, projectRoot = process.cwd()) {
+    return (0, archguard_core_1.createImportResolver)(projectRoot).resolve(importPath, fromFile);
+}
+function installPreCommitHook(cwd) {
+    const gitHooksDir = path.join(cwd, ".git", "hooks");
+    if (!fs.existsSync(gitHooksDir)) {
+        return;
+    }
+    const preCommitPath = path.join(gitHooksDir, "pre-commit");
+    if (fs.existsSync(preCommitPath)) {
+        console.log(chalk_1.default.yellow("! Existing pre-commit hook detected. ArchGuard did not overwrite it; add the check command manually."));
+        return;
+    }
+    // Use the installed CLI name so hooks keep working after npm install or global linking.
+    const preCommitHook = `#!/bin/sh
+# archguard pre-commit hook
+npx archguard check || exit 1
+`;
+    fs.writeFileSync(preCommitPath, preCommitHook);
+    fs.chmodSync(preCommitPath, 0o755);
+}
+function collectViolations(scanRoot, options = {}) {
+    const configPath = (0, archguard_core_1.findArchitectureConfig)(scanRoot);
+    if (!configPath) {
+        throw new Error("architecture.yaml not found. Run 'archguard init' first.");
+    }
+    const architecture = (0, archguard_core_1.loadArchitectureConfig)(configPath);
+    const engine = new archguard_core_1.RuleEngine();
+    const unresolvedImports = [];
+    engine.registerRule((0, archguard_rules_react_1.createLayerImportBoundaryRule)());
+    engine.registerRule((0, archguard_rules_react_1.createBusinessLogicInComponentsRule)());
+    engine.registerRule((0, archguard_rules_react_1.createDataFetchingInUIRule)());
+    engine.registerRule((0, archguard_rules_react_1.createCircularDependencyRule)());
+    const sourceFiles = findTypeScriptFiles(scanRoot);
+    const importResolver = (0, archguard_core_1.createImportResolver)(scanRoot);
+    const sourceFileAnalyses = analyzeSourceFiles(sourceFiles, importResolver, unresolvedImports);
+    const importGraph = buildImportGraph(sourceFileAnalyses);
+    const allViolations = [];
+    for (const analysis of sourceFileAnalyses) {
+        const context = {
+            filePath: analysis.filePath,
+            sourceCode: analysis.sourceCode,
+            ast: analysis.ast,
+            imports: analysis.imports,
+            architecture,
+            importGraph,
+            projectRoot: scanRoot,
+        };
+        const result = engine.executeRules(context);
+        allViolations.push(...result.violations);
+    }
+    if (options.verbose) {
+        console.error(chalk_1.default.gray(`ArchGuard scanned ${sourceFiles.length} file(s) from ${path.relative(scanRoot, scanRoot) || "."} using ${normalizeViolationPath(configPath, scanRoot)}`));
+    }
+    return {
+        violations: sortViolations(allViolations.map((violation) => ({
+            ...violation,
+            file: normalizeViolationPath(violation.file, scanRoot),
+        }))),
+        scanSummary: { unresolvedImports },
+    };
+}
+function printViolations(violations) {
+    for (const violation of violations) {
+        console.log(chalk_1.default.yellow(`${violation.file}:${violation.line}:${violation.column}`) +
+            ` - ${violation.message} (${violation.rule})`);
+    }
+}
+function printCheckSummary(summary, format) {
+    if (format === "json") {
+        console.log(JSON.stringify(buildJsonSummary(summary), null, 2));
+        return;
+    }
+    if (format === "sarif") {
+        console.log(JSON.stringify(buildSarifReport(summary), null, 2));
+        return;
+    }
+    if (summary.mode === "update-baseline") {
+        console.log(chalk_1.default.green(`✓ Wrote ${summary.violations.length} violation(s) to baseline ${summary.baselinePath}`));
+        return;
+    }
+    if (summary.mode === "baseline" && !summary.passed) {
+        console.log(chalk_1.default.red(`\n✗ Found ${summary.violationCount} new violation(s) (${summary.suppressedViolationCount} matched baseline):\n`));
+        printViolations(summary.violations);
+        return;
+    }
+    if (summary.mode === "baseline" && summary.suppressedViolationCount > 0) {
+        console.log(chalk_1.default.green(`✓ No new violations. ${summary.suppressedViolationCount} violation(s) matched baseline ${summary.baselinePath}`));
+        return;
+    }
+    if (!summary.passed) {
+        console.log(chalk_1.default.red(`\n✗ Found ${summary.violationCount} violation(s):\n`));
+        printViolations(summary.violations);
+        return;
+    }
+    console.log(chalk_1.default.green("✓ All checks passed"));
+}
+function normalizeOptionalString(optionValue) {
+    if (optionValue === undefined) {
+        return null;
+    }
+    const trimmedValue = optionValue.trim();
+    return trimmedValue.length > 0 ? trimmedValue : null;
+}
+function resolveScanRoot(cwd, projectRoot) {
+    const scanRoot = projectRoot ? path.resolve(cwd, projectRoot) : cwd;
+    if (!fs.existsSync(scanRoot)) {
+        throw new Error(`Scan root not found: ${projectRoot ?? "."}`);
+    }
+    if (!fs.statSync(scanRoot).isDirectory()) {
+        throw new Error(`Scan root is not a directory: ${projectRoot}`);
+    }
+    return scanRoot;
+}
+function printUnresolvedImports(unresolvedImports, scanRoot) {
+    console.error(chalk_1.default.yellow(`\nUnresolved imports (${unresolvedImports.length}):`));
+    for (const unresolvedImport of unresolvedImports) {
+        console.error(chalk_1.default.yellow(`  ${normalizeViolationPath(unresolvedImport.file, scanRoot)} -> ${unresolvedImport.importPath}`));
+    }
+}
+function normalizeOptionalPath(optionValue) {
+    if (optionValue === undefined || optionValue === false) {
+        return null;
+    }
+    if (optionValue === true) {
+        return DEFAULT_BASELINE_PATH;
+    }
+    const trimmedValue = optionValue.trim();
+    return trimmedValue.length > 0 ? trimmedValue : DEFAULT_BASELINE_PATH;
+}
+function normalizeOutputFormat(format) {
+    const normalizedFormat = (format ?? "text").trim().toLowerCase();
+    if (normalizedFormat === "json" || normalizedFormat === "sarif" || normalizedFormat === "text") {
+        return normalizedFormat;
+    }
+    throw new Error(`Unsupported output format: ${format}. Expected 'text', 'json', or 'sarif'.`);
+}
+function buildJsonSummary(summary) {
+    return {
+        status: summary.passed ? "passed" : "failed",
+        mode: summary.mode,
+        passed: summary.passed,
+        violationCount: summary.violationCount,
+        suppressedViolationCount: summary.suppressedViolationCount,
+        baselinePath: summary.baselinePath ?? null,
+        violations: summary.violations,
+    };
+}
+function buildSarifReport(summary) {
+    const ruleDescriptions = new Map([
+        ["layer-import-boundary", "Import violates a configured layer boundary."],
+        ["no-business-logic-in-components", "Component contains logic that should be moved out of the UI layer."],
+        ["no-data-fetching-in-ui", "Component performs data fetching that should be moved out of the UI layer."],
+        ["no-circular-layer-deps", "Dependency graph contains a circular reference."],
+    ]);
+    const ruleIds = Array.from(new Set(summary.violations.map((violation) => violation.rule))).sort();
+    return {
+        $schema: SARIF_SCHEMA_URL,
+        version: "2.1.0",
+        runs: [
+            {
+                tool: {
+                    driver: {
+                        name: "archguard",
+                        informationUri: "https://github.com/lindseystead/ArchGuard",
+                        rules: ruleIds.map((ruleId) => ({
+                            id: ruleId,
+                            shortDescription: {
+                                text: ruleDescriptions.get(ruleId) ?? "ArchGuard architectural violation.",
+                            },
+                        })),
+                    },
+                },
+                invocations: [
+                    {
+                        executionSuccessful: true,
+                        properties: {
+                            baselinePath: summary.baselinePath ?? null,
+                            mode: summary.mode,
+                            suppressedViolationCount: summary.suppressedViolationCount,
+                            violationCount: summary.violationCount,
+                        },
+                    },
+                ],
+                results: summary.violations.map((violation) => ({
+                    ruleId: violation.rule,
+                    level: "error",
+                    message: { text: violation.message },
+                    locations: [
+                        {
+                            physicalLocation: {
+                                artifactLocation: {
+                                    uri: normalizeViolationPath(violation.file, process.cwd()),
+                                },
+                                region: {
+                                    startColumn: violation.column,
+                                    startLine: violation.line,
+                                },
+                            },
+                        },
+                    ],
+                })),
+            },
+        ],
+    };
+}
+function writeBaseline(baselinePath, violations, cwd) {
+    const resolvedPath = resolveProjectPath(cwd, baselinePath);
+    fs.mkdirSync(path.dirname(resolvedPath), { recursive: true });
+    const baseline = {
+        version: 1,
+        generatedAt: new Date().toISOString(),
+        violations: violations.map((violation) => ({
+            ...violation,
+            file: normalizeViolationPath(violation.file, cwd),
+        })),
+    };
+    fs.writeFileSync(resolvedPath, `${JSON.stringify(baseline, null, 2)}\n`);
+}
+function loadBaseline(baselinePath) {
+    const resolvedPath = resolveProjectPath(process.cwd(), baselinePath);
+    if (!fs.existsSync(resolvedPath)) {
+        throw new Error(`Baseline file not found: ${baselinePath}`);
+    }
+    const rawContent = fs.readFileSync(resolvedPath, "utf-8");
+    const parsed = JSON.parse(rawContent);
+    if (!Array.isArray(parsed.violations)) {
+        throw new Error(`Invalid baseline file: ${baselinePath}`);
+    }
+    return sortViolations(parsed.violations.map((violation) => {
+        if (!isViolation(violation)) {
+            throw new Error(`Invalid baseline file: ${baselinePath}`);
+        }
+        return violation;
+    }));
+}
+function filterViolationsAgainstBaseline(currentViolations, baselineViolations, cwd) {
+    const baselineCounts = new Map();
+    for (const violation of baselineViolations) {
+        const fingerprint = getViolationFingerprint(violation, cwd);
+        baselineCounts.set(fingerprint, (baselineCounts.get(fingerprint) ?? 0) + 1);
+    }
+    const newViolations = [];
+    let suppressedViolationCount = 0;
+    for (const violation of currentViolations) {
+        const fingerprint = getViolationFingerprint(violation, cwd);
+        const remainingMatches = baselineCounts.get(fingerprint) ?? 0;
+        if (remainingMatches > 0) {
+            baselineCounts.set(fingerprint, remainingMatches - 1);
+            suppressedViolationCount += 1;
+            continue;
+        }
+        newViolations.push(violation);
+    }
+    return { newViolations, suppressedViolationCount };
+}
+function sortViolations(violations) {
+    return [...violations].sort((left, right) => {
+        if (left.file !== right.file) {
+            return left.file.localeCompare(right.file);
+        }
+        if (left.rule !== right.rule) {
+            return left.rule.localeCompare(right.rule);
+        }
+        if (left.message !== right.message) {
+            return left.message.localeCompare(right.message);
+        }
+        if (left.line !== right.line) {
+            return left.line - right.line;
+        }
+        return left.column - right.column;
+    });
+}
+function normalizeViolationPath(filePath, cwd) {
+    const absolutePath = path.isAbsolute(filePath) ? filePath : path.resolve(cwd, filePath);
+    const relativePath = path.relative(cwd, absolutePath) || path.basename(absolutePath);
+    return relativePath.replace(/\\/g, "/");
+}
+function getViolationFingerprint(violation, cwd) {
+    return [
+        normalizeViolationPath(violation.file, cwd),
+        violation.rule,
+        violation.message,
+    ].join("::");
+}
+function resolveProjectPath(cwd, filePath) {
+    return path.isAbsolute(filePath) ? filePath : path.resolve(cwd, filePath);
+}
+function isViolation(value) {
+    if (!value || typeof value !== "object") {
+        return false;
+    }
+    const violation = value;
+    return (typeof violation.file === "string" &&
+        typeof violation.line === "number" &&
+        typeof violation.column === "number" &&
+        typeof violation.message === "string" &&
+        typeof violation.rule === "string");
+}

package/dist/presets/index.d.ts

@@ -0,0 +1,10 @@
+/** Architecture.yaml presets for `archguard init`. */
+export declare const PRESET_NAMES: readonly ["boundaries-only", "react-layered", "feature-sliced-react"];
+export type PresetName = (typeof PRESET_NAMES)[number];
+/** Human-readable preset list for CLI errors and help text. */
+export declare function formatPresetList(): string;
+/**
+ * Resolve preset name to architecture.yaml contents.
+ * Omit preset for boundaries-only (v2 default).
+ */
+export declare function getPresetConfig(preset?: string): string;

package/dist/presets/index.js

@@ -0,0 +1,82 @@
+"use strict";
+/** Architecture.yaml presets for `archguard init`. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PRESET_NAMES = void 0;
+exports.formatPresetList = formatPresetList;
+exports.getPresetConfig = getPresetConfig;
+exports.PRESET_NAMES = ["boundaries-only", "react-layered", "feature-sliced-react"];
+const BOUNDARIES_ONLY_CONFIG = `layers:
+  domain:
+    allowedImports: []
+  features:
+    allowedImports: [domain, shared]
+  ui:
+    allowedImports: [features, shared]
+  shared:
+    allowedImports: []
+
+rules:
+  enforceLayerBoundaries: true
+  noCircularLayerDeps: true
+  noBusinessLogicInComponents: false
+  noDataFetchingInUI: false
+`;
+const REACT_LAYERED_CONFIG = `layers:
+  domain:
+    allowedImports: []
+  features:
+    allowedImports: [domain, shared]
+  ui:
+    allowedImports: [features, shared]
+  shared:
+    allowedImports: []
+
+uiLayers: [ui]
+
+rules:
+  enforceLayerBoundaries: true
+  noCircularLayerDeps: true
+  noBusinessLogicInComponents: true
+  noDataFetchingInUI: true
+`;
+const FEATURE_SLICED_REACT_CONFIG = `layers:
+  app:
+    allowedImports: [pages, features, entities, shared]
+  pages:
+    allowedImports: [features, entities, shared]
+  features:
+    allowedImports: [entities, shared]
+  entities:
+    allowedImports: [shared]
+  shared:
+    allowedImports: []
+
+uiLayers: [app, pages]
+
+rules:
+  enforceLayerBoundaries: true
+  noCircularLayerDeps: true
+  noBusinessLogicInComponents: true
+  noDataFetchingInUI: true
+`;
+/** Human-readable preset list for CLI errors and help text. */
+function formatPresetList() {
+    return exports.PRESET_NAMES.join(", ");
+}
+/**
+ * Resolve preset name to architecture.yaml contents.
+ * Omit preset for boundaries-only (v2 default).
+ */
+function getPresetConfig(preset) {
+    if (!preset || preset === "boundaries-only") {
+        return BOUNDARIES_ONLY_CONFIG;
+    }
+    switch (preset) {
+        case "react-layered":
+            return REACT_LAYERED_CONFIG;
+        case "feature-sliced-react":
+            return FEATURE_SLICED_REACT_CONFIG;
+        default:
+            throw new Error(`Unknown preset: ${preset}. Available: ${formatPresetList()}`);
+    }
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@lifesavertech/archguard-cli",
+  "version": "2.0.0",
+  "description": "Command-line interface for ArchGuard",
+  "bin": {
+    "archguard": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "archguard",
+    "architecture",
+    "react",
+    "typescript",
+    "cli"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc -b --force && node -e \"require('fs').chmodSync('dist/index.js', 0o755)\"",
+    "prepack": "npm run build",
+    "build:test": "node -e \"require('fs').rmSync('dist-test',{recursive:true,force:true})\" && tsc -p tsconfig.test.json",
+    "test": "npm run build:test && node --test dist-test/index.test.js dist-test/presets/presets.test.js"
+  },
+  "dependencies": {
+    "@lifesavertech/archguard-guidance": "2.0.0",
+    "@lifesavertech/archguard-core": "2.0.0",
+    "@lifesavertech/archguard-rules-react": "2.0.0",
+    "commander": "^11.0.0",
+    "chalk": "^5.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0"
+  },
+  "author": "Lindsey Stead",
+  "homepage": "https://github.com/lindseystead/ArchGuard#readme",
+  "bugs": {
+    "url": "https://github.com/lindseystead/ArchGuard/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lindseystead/ArchGuard.git",
+    "directory": "packages/cli"
+  }
+}