@lifesavertech/archguard-cli 2.0.2 → 2.2.0

package/dist/index.d.ts

@@ -5,7 +5,12 @@ interface CheckOptions {
     baselinePath?: string | null;
     updateBaselinePath?: string | null;
     projectRoot?: string | null;
+    configPath?: string | null;
     verbose?: boolean;
+    diff?: boolean;
+    diffBase?: string | null;
+    /** Test hook: explicit changed files for diff mode without git. */
+    changedFiles?: string[];
 }
 interface CheckSummary {
     mode: "baseline" | "check" | "update-baseline";
@@ -14,6 +19,11 @@ interface CheckSummary {
     violations: Violation[];
     suppressedViolationCount: number;
     baselinePath?: string | null;
+    diff?: {
+        baseRef: string;
+        changedFileCount: number;
+        affectedFileCount: number;
+    };
 }
 interface SourceFileAnalysis {
     filePath: string;
@@ -21,7 +31,10 @@ interface SourceFileAnalysis {
     ast: RuleContext["ast"];
     imports: ImportInfo[];
 }
-export declare function initializeArchguard(preset?: string): void;
+export declare function initializeArchguard(options?: {
+    preset?: string;
+    detect?: boolean;
+}): void;
 export declare function detectReactTypeScript(cwd: string): boolean;
 export declare function runChecks(options?: CheckOptions): CheckSummary;
 export declare function findTypeScriptFiles(dir: string): string[];

package/dist/index.js

@@ -34,9 +34,6 @@ var __importStar = (this && this.__importStar) || (function () {
         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;
@@ -47,26 +44,40 @@ 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 detectStructure_1 = require("./init/detectStructure");
+const generateConfig_1 = require("./init/generateConfig");
+const syncGuidance_1 = require("./sync/syncGuidance");
+const style = __importStar(require("./style"));
+const MIN_NODE_MAJOR = 20;
+const nodeMajor = Number(process.versions.node.split(".")[0] ?? "0");
+if (nodeMajor < MIN_NODE_MAJOR) {
+    console.error(`Error: ArchGuard requires Node.js >=${MIN_NODE_MAJOR}. Current: ${process.versions.node}`);
+    process.exit(1);
+}
 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.1");
+function readCliVersion() {
+    const packageJsonPath = path.join(__dirname, "..", "package.json");
+    const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
+    return packageJson.version ?? "0.0.0";
+}
+program.name("archguard").description("Architecture guard for React + TypeScript projects").version(readCliVersion());
 program
     .command("init")
     .description("Initialize archguard in the current project")
     .option("--preset <preset>", `Architecture preset (${(0, presets_1.formatPresetList)()})`)
+    .option("--no-detect", "Use preset only; skip repository structure detection")
     .action((options) => {
     try {
-        initializeArchguard(options.preset);
-        console.log(chalk_1.default.green("✓ archguard initialized successfully"));
+        initializeArchguard({ preset: options.preset, detect: options.detect });
+        console.log(style.green("✓ archguard initialized successfully"));
     }
     catch (error) {
-        console.error(chalk_1.default.red(`✗ Error: ${error instanceof Error ? error.message : String(error)}`));
+        console.error(style.red(`✗ Error: ${error instanceof Error ? error.message : String(error)}`));
         process.exit(1);
     }
 });
@@ -74,16 +85,21 @@ 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("--config <path>", "Path to architecture.yaml (default: discover from scan root)")
+    .option("--diff", "Only report violations in changed files and their direct import neighbors")
+    .option("--diff-base <ref>", "Git ref for --diff (default: origin/main, main, or HEAD~1)")
+    .option("--format <format>", "Output format (text, json, sarif, github, agent)", "text")
+    .option("--json", "Emit machine-readable JSON (alias for --format json)")
     .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 format = resolveOutputFormat(options);
         const updateBaselinePath = normalizeOptionalPath(options.updateBaseline);
         const projectRoot = normalizeOptionalString(options.root);
+        const configPath = normalizeOptionalString(options.config);
         if (baselinePath && updateBaselinePath) {
             throw new Error("Use either --baseline or --update-baseline, not both.");
         }
@@ -91,7 +107,10 @@ program
             baselinePath,
             updateBaselinePath,
             projectRoot,
+            configPath,
             verbose: Boolean(options.verbose),
+            diff: Boolean(options.diff),
+            diffBase: normalizeOptionalString(options.diffBase),
         });
         printCheckSummary(result, format);
         if (!result.passed) {
@@ -99,14 +118,52 @@ program
         }
     }
     catch (error) {
-        console.error(chalk_1.default.red(`✗ Error: ${error instanceof Error ? error.message : String(error)}`));
+        console.error(style.red(`✗ Error: ${error instanceof Error ? error.message : String(error)}`));
+        process.exit(1);
+    }
+});
+program
+    .command("sync")
+    .description("Regenerate AGENTS.md and .archguard guidance from architecture.yaml")
+    .option("--check", "Exit with error if guidance files are out of date")
+    .option("--config <path>", "Path to architecture.yaml (default: discover from cwd)")
+    .option("--force", "Overwrite existing agent rule files (AGENTS.md, .cursor/rules, copilot instructions)")
+    .option("--targets <list>", "Comma-separated targets: editor,agents,cursor,copilot", "editor,agents,cursor,copilot")
+    .option("--update-agents", "Overwrite AGENTS.md even when it already exists")
+    .action((options) => {
+    try {
+        const result = (0, syncGuidance_1.runGuidanceSync)(process.cwd(), {
+            configPath: normalizeOptionalString(options.config),
+            updateAgents: Boolean(options.updateAgents),
+            checkOnly: Boolean(options.check),
+            targets: (0, syncGuidance_1.parseGuidanceTargets)(options.targets),
+            force: Boolean(options.force),
+        });
+        if (options.check) {
+            if (result.updated.length > 0) {
+                console.error(style.red(`✗ Guidance is stale. Run 'archguard sync' to update:\n${result.updated.map((file) => `  - ${file}`).join("\n")}`));
+                process.exit(1);
+            }
+            console.log(style.green("✓ Guidance is up to date"));
+            return;
+        }
+        if (result.updated.length === 0) {
+            console.log(style.green("✓ Guidance already up to date"));
+            return;
+        }
+        for (const file of result.updated) {
+            console.log(style.green(`✓ Updated ${path.relative(process.cwd(), file) || file}`));
+        }
+    }
+    catch (error) {
+        console.error(style.red(`✗ Error: ${error instanceof Error ? error.message : String(error)}`));
         process.exit(1);
     }
 });
 if (require.main === module) {
     program.parse();
 }
-function initializeArchguard(preset) {
+function initializeArchguard(options = {}) {
     const cwd = process.cwd();
     if (!detectReactTypeScript(cwd)) {
         throw new Error("React + TypeScript project not detected");
@@ -115,21 +172,22 @@ function initializeArchguard(preset) {
     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 configContents = resolveInitConfig(cwd, options);
+    fs.writeFileSync(architectureYamlPath, configContents);
     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));
-    }
+    (0, syncGuidance_1.runGuidanceSync)(cwd, { configPath: architectureYamlPath, updateAgents: false });
     installPreCommitHook(cwd);
 }
+function resolveInitConfig(cwd, options) {
+    if (options.detect === false) {
+        return (0, presets_1.getPresetConfig)(options.preset);
+    }
+    const detected = (0, detectStructure_1.detectStructure)(cwd);
+    if (detected) {
+        return (0, generateConfig_1.generateConfigFromStructure)(detected, options.preset);
+    }
+    return (0, presets_1.getPresetConfig)(options.preset);
+}
 function detectReactTypeScript(cwd) {
     const packageJsonPath = path.join(cwd, "package.json");
     if (!fs.existsSync(packageJsonPath)) {
@@ -144,9 +202,16 @@ function detectReactTypeScript(cwd) {
 function runChecks(options = {}) {
     const cwd = process.cwd();
     const scanRoot = resolveScanRoot(cwd, options.projectRoot);
-    const { violations: allViolations, scanSummary } = collectViolations(scanRoot, {
+    const applyDiffFilter = Boolean(options.diff) && !options.updateBaselinePath;
+    const { violations: rawViolations, scanSummary, diffMeta } = collectViolations(scanRoot, {
         verbose: options.verbose,
+        configPath: options.configPath,
+        diff: applyDiffFilter,
+        diffBase: options.diffBase,
+        changedFiles: options.changedFiles,
+        cwd,
     });
+    const allViolations = (0, archguard_core_1.enrichViolations)(rawViolations);
     if (options.verbose && scanSummary.unresolvedImports.length > 0) {
         printUnresolvedImports(scanSummary.unresolvedImports, scanRoot);
     }
@@ -161,44 +226,45 @@ function runChecks(options = {}) {
             baselinePath: options.updateBaselinePath,
         };
     }
+    const withDiff = (summary) => diffMeta ? { ...summary, diff: diffMeta } : summary;
     if (options.baselinePath) {
         const baselineViolations = loadBaseline(options.baselinePath);
         const { newViolations, suppressedViolationCount } = filterViolationsAgainstBaseline(allViolations, baselineViolations, scanRoot);
         if (newViolations.length > 0) {
-            return {
+            return withDiff({
                 mode: "baseline",
                 passed: false,
                 violationCount: newViolations.length,
                 violations: newViolations,
                 suppressedViolationCount,
                 baselinePath: options.baselinePath,
-            };
+            });
         }
-        return {
+        return withDiff({
             mode: "baseline",
             passed: true,
             violationCount: 0,
             violations: [],
             suppressedViolationCount,
             baselinePath: options.baselinePath,
-        };
+        });
     }
     if (allViolations.length > 0) {
-        return {
+        return withDiff({
             mode: "check",
             passed: false,
             violationCount: allViolations.length,
             violations: allViolations,
             suppressedViolationCount: 0,
-        };
+        });
     }
-    return {
+    return withDiff({
         mode: "check",
         passed: true,
         violationCount: 0,
         violations: [],
         suppressedViolationCount: 0,
-    };
+    });
 }
 function findTypeScriptFiles(dir) {
     const files = [];
@@ -270,7 +336,7 @@ function installPreCommitHook(cwd) {
     }
     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."));
+        console.log(style.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.
@@ -281,19 +347,32 @@ 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.");
+function assertLayerCoverage(sourceFiles, architecture, scanRoot) {
+    const layerRulesEnabled = (0, archguard_core_1.isLayerBoundaryEnforcementEnabled)(architecture.rules) ||
+        Boolean(architecture.rules.noCircularLayerDeps);
+    if (!layerRulesEnabled || sourceFiles.length === 0) {
+        return;
     }
+    const matchedFiles = (0, archguard_core_1.countFilesMatchingLayers)(sourceFiles, architecture, scanRoot);
+    if (matchedFiles > 0) {
+        return;
+    }
+    throw new Error(`No scanned files matched any configured layer — boundary rules enforced nothing. ` +
+        `Map your folders with patterns.layers or layers.*.paths in architecture.yaml ` +
+        `or align folder names with layer keys. Scanned ${sourceFiles.length} file(s) under ${scanRoot}.`);
+}
+function collectViolations(scanRoot, options = {}) {
+    const configPath = resolveConfigPath(scanRoot, options.configPath);
     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.createBarrelBoundaryBypassRule)());
     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 sourceFiles = findTypeScriptFiles(scanRoot).filter((filePath) => !(0, archguard_core_1.shouldIgnorePath)(filePath, architecture, scanRoot));
+    assertLayerCoverage(sourceFiles, architecture, scanRoot);
     const importResolver = (0, archguard_core_1.createImportResolver)(scanRoot);
     const sourceFileAnalyses = analyzeSourceFiles(sourceFiles, importResolver, unresolvedImports);
     const importGraph = buildImportGraph(sourceFileAnalyses);
@@ -312,19 +391,40 @@ function collectViolations(scanRoot, options = {}) {
         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)}`));
+        console.error(style.gray(`ArchGuard scanned ${sourceFiles.length} file(s) from ${path.relative(scanRoot, scanRoot) || "."} using ${normalizeViolationPath(configPath, scanRoot)}`));
+    }
+    let violations = sortViolations(allViolations.map((violation) => ({
+        ...violation,
+        file: normalizeViolationPath(violation.file, scanRoot),
+    })));
+    let diffMeta;
+    if (options.diff) {
+        const { changedFiles, affectedFiles } = (0, archguard_core_1.resolveDiffAffectedFiles)({
+            cwd: options.cwd ?? process.cwd(),
+            scanRoot,
+            baseRef: options.diffBase ?? undefined,
+            changedFiles: options.changedFiles,
+        }, importGraph);
+        const normalizedAffected = new Set([...affectedFiles].map((filePath) => normalizeViolationPath(filePath, scanRoot)));
+        violations = (0, archguard_core_1.filterViolationsForDiff)(violations, normalizedAffected);
+        diffMeta = {
+            baseRef: options.diffBase ?? "auto",
+            changedFileCount: changedFiles.length,
+            affectedFileCount: normalizedAffected.size,
+        };
+        if (options.verbose) {
+            console.error(style.gray(`Diff mode: ${changedFiles.length} changed file(s), ${normalizedAffected.size} affected file(s)`));
+        }
     }
     return {
-        violations: sortViolations(allViolations.map((violation) => ({
-            ...violation,
-            file: normalizeViolationPath(violation.file, scanRoot),
-        }))),
+        violations,
         scanSummary: { unresolvedImports },
+        diffMeta,
     };
 }
 function printViolations(violations) {
     for (const violation of violations) {
-        console.log(chalk_1.default.yellow(`${violation.file}:${violation.line}:${violation.column}`) +
+        console.log(style.yellow(`${violation.file}:${violation.line}:${violation.column}`) +
             ` - ${violation.message} (${violation.rule})`);
     }
 }
@@ -333,29 +433,37 @@ function printCheckSummary(summary, format) {
         console.log(JSON.stringify(buildJsonSummary(summary), null, 2));
         return;
     }
+    if (format === "agent") {
+        console.log(JSON.stringify(buildAgentSummary(summary), null, 2));
+        return;
+    }
     if (format === "sarif") {
         console.log(JSON.stringify(buildSarifReport(summary), null, 2));
         return;
     }
+    if (format === "github") {
+        printGithubAnnotations(summary);
+        return;
+    }
     if (summary.mode === "update-baseline") {
-        console.log(chalk_1.default.green(`✓ Wrote ${summary.violations.length} violation(s) to baseline ${summary.baselinePath}`));
+        console.log(style.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`));
+        console.log(style.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}`));
+        console.log(style.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`));
+        console.log(style.red(`\n✗ Found ${summary.violationCount} violation(s):\n`));
         printViolations(summary.violations);
         return;
     }
-    console.log(chalk_1.default.green("✓ All checks passed"));
+    console.log(style.green("✓ All checks passed"));
 }
 function normalizeOptionalString(optionValue) {
     if (optionValue === undefined) {
@@ -375,9 +483,9 @@ function resolveScanRoot(cwd, projectRoot) {
     return scanRoot;
 }
 function printUnresolvedImports(unresolvedImports, scanRoot) {
-    console.error(chalk_1.default.yellow(`\nUnresolved imports (${unresolvedImports.length}):`));
+    console.error(style.yellow(`\nUnresolved imports (${unresolvedImports.length}):`));
     for (const unresolvedImport of unresolvedImports) {
-        console.error(chalk_1.default.yellow(`  ${normalizeViolationPath(unresolvedImport.file, scanRoot)} -> ${unresolvedImport.importPath}`));
+        console.error(style.yellow(`  ${normalizeViolationPath(unresolvedImport.file, scanRoot)} -> ${unresolvedImport.importPath}`));
     }
 }
 function normalizeOptionalPath(optionValue) {
@@ -392,13 +500,40 @@ function normalizeOptionalPath(optionValue) {
 }
 function normalizeOutputFormat(format) {
     const normalizedFormat = (format ?? "text").trim().toLowerCase();
-    if (normalizedFormat === "json" || normalizedFormat === "sarif" || normalizedFormat === "text") {
+    if (normalizedFormat === "agent" ||
+        normalizedFormat === "github" ||
+        normalizedFormat === "json" ||
+        normalizedFormat === "sarif" ||
+        normalizedFormat === "text") {
         return normalizedFormat;
     }
-    throw new Error(`Unsupported output format: ${format}. Expected 'text', 'json', or 'sarif'.`);
+    throw new Error(`Unsupported output format: ${format}. Expected 'text', 'json', 'sarif', 'github', or 'agent'.`);
+}
+function resolveOutputFormat(options) {
+    if (options.json) {
+        return "json";
+    }
+    return normalizeOutputFormat(options.format);
+}
+function resolveConfigPath(scanRoot, configPath) {
+    if (configPath) {
+        const resolvedPath = path.isAbsolute(configPath)
+            ? configPath
+            : path.resolve(scanRoot, configPath);
+        if (!fs.existsSync(resolvedPath)) {
+            throw new Error(`Architecture config not found: ${configPath}`);
+        }
+        return resolvedPath;
+    }
+    const discoveredPath = (0, archguard_core_1.findArchitectureConfig)(scanRoot);
+    if (!discoveredPath) {
+        throw new Error("architecture.yaml not found. Run 'archguard init' first.");
+    }
+    return discoveredPath;
 }
 function buildJsonSummary(summary) {
     return {
+        schemaVersion: 2,
         status: summary.passed ? "passed" : "failed",
         mode: summary.mode,
         passed: summary.passed,
@@ -406,8 +541,60 @@ function buildJsonSummary(summary) {
         suppressedViolationCount: summary.suppressedViolationCount,
         baselinePath: summary.baselinePath ?? null,
         violations: summary.violations,
+        diff: summary.diff,
     };
 }
+function buildAgentSummary(summary) {
+    const violations = summary.violations.map((violation) => ({
+        id: violation.id ?? (0, archguard_core_1.createViolationId)(violation),
+        file: violation.file,
+        line: violation.line,
+        column: violation.column,
+        rule: violation.rule,
+        message: truncateAgentText(violation.message, 240),
+        fix: violation.fix ? truncateAgentText(violation.fix, 240) : undefined,
+        context: violation.context,
+    }));
+    return {
+        passed: summary.passed,
+        violationCount: summary.violationCount,
+        summary: summary.passed
+            ? "All architecture checks passed."
+            : `Found ${summary.violationCount} violation(s). Fix layer imports or update architecture.yaml.`,
+        violations,
+    };
+}
+function truncateAgentText(value, maxLength) {
+    if (value.length <= maxLength) {
+        return value;
+    }
+    return `${value.slice(0, maxLength - 3)}...`;
+}
+function printGithubAnnotations(summary) {
+    if (summary.mode === "update-baseline") {
+        console.log(`::notice title=ArchGuard::Wrote ${summary.violations.length} violation(s) to baseline ${summary.baselinePath}`);
+        return;
+    }
+    if (summary.passed) {
+        if (summary.mode === "baseline" && summary.suppressedViolationCount > 0) {
+            console.log(`::notice title=ArchGuard::No new violations (${summary.suppressedViolationCount} matched baseline).`);
+            return;
+        }
+        console.log("::notice title=ArchGuard::All checks passed");
+        return;
+    }
+    for (const violation of summary.violations) {
+        const title = violation.rule;
+        const message = escapeGithubMessage(`${violation.message} (${violation.rule})`);
+        console.log(`::error file=${violation.file},line=${violation.line},col=${violation.column},title=${escapeGithubMessage(title)}::${message}`);
+    }
+}
+function escapeGithubMessage(value) {
+    return value
+        .replace(/%/g, "%25")
+        .replace(/\r/g, "%0D")
+        .replace(/\n/g, "%0A");
+}
 function buildSarifReport(summary) {
     const ruleDescriptions = new Map([
         ["layer-import-boundary", "Import violates a configured layer boundary."],
@@ -557,5 +744,10 @@ function isViolation(value) {
         typeof violation.line === "number" &&
         typeof violation.column === "number" &&
         typeof violation.message === "string" &&
-        typeof violation.rule === "string");
+        typeof violation.rule === "string" &&
+        (violation.id === undefined || typeof violation.id === "string") &&
+        (violation.severity === undefined ||
+            violation.severity === "error" ||
+            violation.severity === "warning") &&
+        (violation.fix === undefined || typeof violation.fix === "string"));
 }

package/dist/init/detectStructure.d.ts

@@ -0,0 +1,12 @@
+/** Scan repository folders to infer layer layout for smart init. */
+export interface DetectedLayer {
+    name: string;
+    include: string[];
+}
+export interface DetectedStructure {
+    sourceRoot: string;
+    layers: DetectedLayer[];
+    uiLayerNames: string[];
+    style: "custom" | "fsd" | "layered";
+}
+export declare function detectStructure(projectRoot: string): DetectedStructure | null;

package/dist/init/detectStructure.js

@@ -0,0 +1,163 @@
+"use strict";
+/** Scan repository folders to infer layer layout for smart init. */
+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;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectStructure = detectStructure;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const SOURCE_ROOT_CANDIDATES = ["src", "app"];
+const FOLDER_LAYER_MAP = {
+    app: "app",
+    common: "shared",
+    components: "ui",
+    database: "db",
+    data: "db",
+    db: "db",
+    domain: "domain",
+    entities: "entities",
+    features: "features",
+    hooks: "features",
+    lib: "shared",
+    libs: "shared",
+    models: "domain",
+    modules: "features",
+    pages: "ui",
+    repositories: "db",
+    services: "domain",
+    shared: "shared",
+    ui: "ui",
+    utils: "shared",
+    views: "ui",
+    widgets: "widgets",
+};
+const UI_LAYER_CANDIDATES = new Set(["ui", "app", "pages", "widgets"]);
+function detectStructure(projectRoot) {
+    const sourceRoot = findSourceRoot(projectRoot);
+    if (!sourceRoot) {
+        return null;
+    }
+    const layerFolders = collectLayerFolders(projectRoot, sourceRoot);
+    if (layerFolders.length < 2) {
+        return null;
+    }
+    const grouped = groupFoldersByLayer(layerFolders);
+    if (Object.keys(grouped).length < 2) {
+        return null;
+    }
+    const layers = Object.entries(grouped).map(([name, folders]) => ({
+        name,
+        include: folders.map((folder) => `${folder}/**`),
+    }));
+    const style = inferStyle(layers.map((layer) => layer.name));
+    const uiLayerNames = layers
+        .map((layer) => layer.name)
+        .filter((name) => UI_LAYER_CANDIDATES.has(name));
+    return {
+        sourceRoot,
+        layers,
+        uiLayerNames,
+        style,
+    };
+}
+function findSourceRoot(projectRoot) {
+    for (const candidate of SOURCE_ROOT_CANDIDATES) {
+        const candidatePath = path.join(projectRoot, candidate);
+        if (fs.existsSync(candidatePath) && fs.statSync(candidatePath).isDirectory()) {
+            return candidate;
+        }
+    }
+    return null;
+}
+function collectLayerFolders(projectRoot, sourceRoot) {
+    const sourcePath = path.join(projectRoot, sourceRoot);
+    const entries = fs.readdirSync(sourcePath, { withFileTypes: true });
+    const layerFolders = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory()) {
+            continue;
+        }
+        const folderName = entry.name;
+        if (!FOLDER_LAYER_MAP[folderName]) {
+            continue;
+        }
+        const folderPath = path.join(sourcePath, folderName);
+        if (containsTypeScriptFiles(folderPath)) {
+            layerFolders.push(`${sourceRoot}/${folderName}`);
+        }
+    }
+    return layerFolders;
+}
+function containsTypeScriptFiles(dir) {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (containsTypeScriptFiles(fullPath)) {
+                return true;
+            }
+            continue;
+        }
+        if (entry.isFile() && (entry.name.endsWith(".ts") || entry.name.endsWith(".tsx"))) {
+            return true;
+        }
+    }
+    return false;
+}
+function groupFoldersByLayer(folders) {
+    const grouped = {};
+    for (const folder of folders) {
+        const segment = folder.split("/").pop();
+        if (!segment) {
+            continue;
+        }
+        const layerName = FOLDER_LAYER_MAP[segment];
+        if (!layerName) {
+            continue;
+        }
+        grouped[layerName] ?? (grouped[layerName] = []);
+        grouped[layerName].push(folder);
+    }
+    return grouped;
+}
+function inferStyle(layerNames) {
+    const names = new Set(layerNames);
+    if (names.has("entities") && names.has("features") && (names.has("pages") || names.has("app"))) {
+        return "fsd";
+    }
+    if (names.has("domain") && names.has("features") && names.has("ui")) {
+        return "layered";
+    }
+    return "custom";
+}

package/dist/init/generateConfig.d.ts

@@ -0,0 +1,3 @@
+/** Build architecture.yaml from detected structure and optional preset rules. */
+import { DetectedStructure } from "./detectStructure";
+export declare function generateConfigFromStructure(structure: DetectedStructure, preset?: string): string;

package/dist/init/generateConfig.js

@@ -0,0 +1,127 @@
+"use strict";
+/** Build architecture.yaml from detected structure and optional preset rules. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateConfigFromStructure = generateConfigFromStructure;
+const PRESET_RULES = {
+    "boundaries-only": {
+        enforceLayerBoundaries: true,
+        noCircularLayerDeps: true,
+        noBusinessLogicInComponents: false,
+        noDataFetchingInUI: false,
+    },
+    "react-layered": {
+        enforceLayerBoundaries: true,
+        noCircularLayerDeps: true,
+        noBusinessLogicInComponents: true,
+        noDataFetchingInUI: true,
+        uiLayers: ["ui"],
+    },
+    "feature-sliced-react": {
+        enforceLayerBoundaries: true,
+        noCircularLayerDeps: true,
+        noBusinessLogicInComponents: true,
+        noDataFetchingInUI: true,
+        uiLayers: ["app", "pages"],
+    },
+};
+function generateConfigFromStructure(structure, preset) {
+    const layerNames = structure.layers.map((layer) => layer.name);
+    const rules = resolveRules(structure, preset);
+    const allowedImports = buildAllowedImports(layerNames, structure.style);
+    const lines = [
+        "patterns:",
+        `  root: ${structure.sourceRoot}`,
+        "  ignore:",
+        '    - "**/*.test.{ts,tsx}"',
+        '    - "**/*.spec.{ts,tsx}"',
+        '    - "**/__tests__/**"',
+        "  layers:",
+    ];
+    for (const layer of structure.layers) {
+        lines.push(`    ${layer.name}:`);
+        lines.push("      include:");
+        for (const include of layer.include) {
+            lines.push(`        - ${include}`);
+        }
+    }
+    lines.push("");
+    lines.push("layers:");
+    for (const layerName of layerNames) {
+        const imports = allowedImports[layerName] ?? [];
+        lines.push(`  ${layerName}:`);
+        if (imports.length > 0) {
+            lines.push(`    allowedImports: [${imports.join(", ")}]`);
+        }
+        else {
+            lines.push("    allowedImports: []");
+        }
+    }
+    if (rules.uiLayers && rules.uiLayers.length > 0) {
+        lines.push("");
+        lines.push(`uiLayers: [${rules.uiLayers.join(", ")}]`);
+    }
+    else if (structure.uiLayerNames.length > 0 && rules.noBusinessLogicInComponents) {
+        lines.push("");
+        lines.push(`uiLayers: [${structure.uiLayerNames.join(", ")}]`);
+    }
+    lines.push("");
+    lines.push("rules:");
+    lines.push(`  enforceLayerBoundaries: ${rules.enforceLayerBoundaries}`);
+    lines.push(`  noCircularLayerDeps: ${rules.noCircularLayerDeps}`);
+    lines.push(`  noBusinessLogicInComponents: ${rules.noBusinessLogicInComponents}`);
+    lines.push(`  noDataFetchingInUI: ${rules.noDataFetchingInUI}`);
+    lines.push("");
+    return lines.join("\n");
+}
+function resolveRules(structure, preset) {
+    if (preset && preset in PRESET_RULES) {
+        return PRESET_RULES[preset];
+    }
+    if (structure.style === "fsd") {
+        return PRESET_RULES["feature-sliced-react"];
+    }
+    if (structure.style === "layered") {
+        return PRESET_RULES["react-layered"];
+    }
+    return PRESET_RULES["boundaries-only"];
+}
+function buildAllowedImports(layerNames, style) {
+    const names = new Set(layerNames);
+    if (style === "fsd") {
+        return {
+            app: pickExisting(names, ["pages", "features", "entities", "shared"]),
+            pages: pickExisting(names, ["features", "entities", "shared"]),
+            features: pickExisting(names, ["entities", "shared"]),
+            entities: pickExisting(names, ["shared"]),
+            shared: [],
+            widgets: pickExisting(names, ["entities", "shared", "features"]),
+            ui: pickExisting(names, ["features", "shared"]),
+            db: [],
+            domain: [],
+        };
+    }
+    if (style === "layered") {
+        return {
+            domain: [],
+            features: pickExisting(names, ["domain", "shared"]),
+            ui: pickExisting(names, ["features", "shared"]),
+            shared: [],
+            db: [],
+            app: pickExisting(names, ["features", "shared"]),
+            pages: pickExisting(names, ["features", "shared"]),
+        };
+    }
+    const imports = {};
+    const lowerLayers = new Set(["domain", "db", "data", "entities", "shared"]);
+    for (const layerName of layerNames) {
+        if (lowerLayers.has(layerName)) {
+            imports[layerName] = layerName === "shared" ? [] : pickExisting(names, ["shared"]);
+            continue;
+        }
+        imports[layerName] = pickExisting(names, ["features", "domain", "db", "shared", "entities"]);
+    }
+    return imports;
+}
+function pickExisting(available, candidates) {
+    return candidates.filter((candidate) => available.has(candidate));
+}

package/dist/presets/index.js

@@ -15,8 +15,17 @@ const BOUNDARIES_ONLY_CONFIG = `layers:
   shared:
     allowedImports: []
 
+# Map custom folder layouts with paths (relative to project root):
+#   ui:
+#     paths: [src/components, src/pages]
+#     allowedImports: [features, db]
+#   db:
+#     paths: [src/db]
+#     allowedImports: []
+
 rules:
   enforceLayerBoundaries: true
+  noBarrelBoundaryBypass: true
   noCircularLayerDeps: true
   noBusinessLogicInComponents: false
   noDataFetchingInUI: false
@@ -35,6 +44,7 @@ uiLayers: [ui]
 
 rules:
   enforceLayerBoundaries: true
+  noBarrelBoundaryBypass: true
   noCircularLayerDeps: true
   noBusinessLogicInComponents: true
   noDataFetchingInUI: true
@@ -55,6 +65,7 @@ uiLayers: [app, pages]
 
 rules:
   enforceLayerBoundaries: true
+  noBarrelBoundaryBypass: true
   noCircularLayerDeps: true
   noBusinessLogicInComponents: true
   noDataFetchingInUI: true

package/dist/style.d.ts

@@ -0,0 +1,5 @@
+/** Terminal styling via Node built-ins (no ESM-only deps in CJS output). */
+export declare function green(text: string): string;
+export declare function red(text: string): string;
+export declare function yellow(text: string): string;
+export declare function gray(text: string): string;

package/dist/style.js

@@ -0,0 +1,20 @@
+"use strict";
+/** Terminal styling via Node built-ins (no ESM-only deps in CJS output). */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.green = green;
+exports.red = red;
+exports.yellow = yellow;
+exports.gray = gray;
+const node_util_1 = require("node:util");
+function green(text) {
+    return (0, node_util_1.styleText)("green", text);
+}
+function red(text) {
+    return (0, node_util_1.styleText)("red", text);
+}
+function yellow(text) {
+    return (0, node_util_1.styleText)("yellow", text);
+}
+function gray(text) {
+    return (0, node_util_1.styleText)("gray", text);
+}

package/dist/sync/syncGuidance.d.ts

@@ -0,0 +1,33 @@
+/** Regenerate guidance files from architecture.yaml. */
+import { ArchitectureConfig } from "@lifesavertech/archguard-core";
+export type GuidanceTarget = "agents" | "copilot" | "cursor" | "editor";
+export declare const DEFAULT_GUIDANCE_TARGETS: GuidanceTarget[];
+export interface SyncTarget {
+    path: string;
+    content: string;
+    name: GuidanceTarget;
+}
+export interface SyncPlan {
+    configPath: string;
+    architecture: ArchitectureConfig;
+    targets: SyncTarget[];
+}
+export interface SyncResult {
+    configPath: string;
+    updated: string[];
+    unchanged: string[];
+}
+export declare function parseGuidanceTargets(value: string | undefined): GuidanceTarget[];
+export declare function planGuidanceSync(cwd: string, options?: {
+    configPath?: string | null;
+    updateAgents?: boolean;
+    targets?: GuidanceTarget[];
+    force?: boolean;
+}): SyncPlan;
+export declare function runGuidanceSync(cwd: string, options?: {
+    configPath?: string | null;
+    updateAgents?: boolean;
+    checkOnly?: boolean;
+    targets?: GuidanceTarget[];
+    force?: boolean;
+}): SyncResult;

package/dist/sync/syncGuidance.js

@@ -0,0 +1,139 @@
+"use strict";
+/** Regenerate guidance files from architecture.yaml. */
+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;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_GUIDANCE_TARGETS = void 0;
+exports.parseGuidanceTargets = parseGuidanceTargets;
+exports.planGuidanceSync = planGuidanceSync;
+exports.runGuidanceSync = runGuidanceSync;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const archguard_core_1 = require("@lifesavertech/archguard-core");
+const archguard_guidance_1 = require("@lifesavertech/archguard-guidance");
+exports.DEFAULT_GUIDANCE_TARGETS = ["editor", "agents", "cursor", "copilot"];
+function parseGuidanceTargets(value) {
+    if (!value || value.trim().length === 0) {
+        return [...exports.DEFAULT_GUIDANCE_TARGETS];
+    }
+    const allowed = new Set(exports.DEFAULT_GUIDANCE_TARGETS);
+    const parsed = value
+        .split(",")
+        .map((part) => part.trim())
+        .filter(Boolean);
+    for (const target of parsed) {
+        if (!allowed.has(target)) {
+            throw new Error(`Unknown sync target "${target}". Use: ${exports.DEFAULT_GUIDANCE_TARGETS.join(", ")}`);
+        }
+    }
+    return parsed;
+}
+function planGuidanceSync(cwd, options = {}) {
+    const configPath = resolveConfigPath(cwd, options.configPath);
+    const architecture = (0, archguard_core_1.loadArchitectureConfig)(configPath);
+    const selectedTargets = options.targets ?? exports.DEFAULT_GUIDANCE_TARGETS;
+    const targets = [];
+    if (selectedTargets.includes("editor")) {
+        targets.push({
+            name: "editor",
+            path: path.join(cwd, ".archguard", "ARCHITECTURE_RULES.md"),
+            content: `${(0, archguard_guidance_1.generateEditorGuide)(architecture)}\n`,
+        });
+    }
+    const agentsPath = path.join(cwd, "AGENTS.md");
+    if (selectedTargets.includes("agents") && (options.force || options.updateAgents || !fs.existsSync(agentsPath))) {
+        targets.push({
+            name: "agents",
+            path: agentsPath,
+            content: `${(0, archguard_guidance_1.generateAgentsGuide)(architecture)}\n`,
+        });
+    }
+    const cursorPath = path.join(cwd, ".cursor", "rules", "archguard.mdc");
+    if (selectedTargets.includes("cursor") && (options.force || !fs.existsSync(cursorPath))) {
+        targets.push({
+            name: "cursor",
+            path: cursorPath,
+            content: `${(0, archguard_guidance_1.generateCursorRules)(architecture)}\n`,
+        });
+    }
+    const copilotPath = path.join(cwd, ".github", "copilot-instructions.md");
+    if (selectedTargets.includes("copilot") && (options.force || !fs.existsSync(copilotPath))) {
+        targets.push({
+            name: "copilot",
+            path: copilotPath,
+            content: `${(0, archguard_guidance_1.generateCopilotInstructions)(architecture)}\n`,
+        });
+    }
+    return { configPath, architecture, targets };
+}
+function runGuidanceSync(cwd, options = {}) {
+    const plan = planGuidanceSync(cwd, options);
+    const updated = [];
+    const unchanged = [];
+    for (const target of plan.targets) {
+        const current = fs.existsSync(target.path) ? fs.readFileSync(target.path, "utf-8") : null;
+        if (current === target.content) {
+            unchanged.push(target.path);
+            continue;
+        }
+        if (options.checkOnly) {
+            updated.push(target.path);
+            continue;
+        }
+        fs.mkdirSync(path.dirname(target.path), { recursive: true });
+        fs.writeFileSync(target.path, target.content);
+        updated.push(target.path);
+    }
+    return {
+        configPath: plan.configPath,
+        updated,
+        unchanged,
+    };
+}
+function resolveConfigPath(cwd, configPath) {
+    if (configPath) {
+        const resolvedPath = path.isAbsolute(configPath)
+            ? configPath
+            : path.resolve(cwd, configPath);
+        if (!fs.existsSync(resolvedPath)) {
+            throw new Error(`Architecture config not found: ${configPath}`);
+        }
+        return resolvedPath;
+    }
+    const discoveredPath = (0, archguard_core_1.findArchitectureConfig)(cwd);
+    if (!discoveredPath) {
+        throw new Error("architecture.yaml not found. Run 'archguard init' first.");
+    }
+    return discoveredPath;
+}

package/package.json

@@ -1,12 +1,15 @@
 {
   "name": "@lifesavertech/archguard-cli",
-  "version": "2.0.2",
+  "version": "2.2.0",
   "description": "Command-line interface for ArchGuard",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "bin": {
     "archguard": "dist/index.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "package.json"
   ],
   "engines": {
     "node": ">=20"
@@ -28,11 +31,10 @@
     "test": "npm run build:test && node --test dist-test/index.test.js dist-test/presets/presets.test.js"
   },
   "dependencies": {
-    "@lifesavertech/archguard-guidance": "2.0.1",
-    "@lifesavertech/archguard-core": "2.0.1",
-    "@lifesavertech/archguard-rules-react": "2.0.1",
-    "commander": "^11.0.0",
-    "chalk": "^5.3.0"
+    "@lifesavertech/archguard-guidance": "2.0.2",
+    "@lifesavertech/archguard-core": "2.2.0",
+    "@lifesavertech/archguard-rules-react": "2.2.0",
+    "commander": "^11.0.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0"