@nielspeter/eess 0.1.0

package/dist/exclusion-comments.d.ts

@@ -0,0 +1,52 @@
+import type { ArchViolation } from './violation.js';
+/**
+ * Exclusion comment parsed from source code.
+ */
+export interface ExclusionComment {
+    /** Rule ID being excluded */
+    ruleId: string;
+    /** Required reason for the exclusion */
+    reason: string;
+    /** File path where the comment was found */
+    file: string;
+    /** Line number of the comment */
+    line: number;
+    /** Whether this is a block exclusion (start/end) */
+    isBlock: boolean;
+    /** End line for block exclusions */
+    endLine?: number;
+}
+/**
+ * Validation warning for exclusion comments.
+ */
+export interface ExclusionWarning {
+    /** Warning message */
+    message: string;
+    /** File path */
+    file: string;
+    /** Line number */
+    line: number;
+}
+/**
+ * Result of parsing exclusion comments from a source file.
+ */
+export interface ParseResult {
+    /** Successfully parsed exclusion comments */
+    exclusions: ExclusionComment[];
+    /** Warnings about malformed comments */
+    warnings: ExclusionWarning[];
+}
+/**
+ * Scan a source file for eess-exclude comments.
+ *
+ * Supported formats:
+ *   // eess-exclude <rule-id>: <reason>
+ *   // eess-exclude-start <rule-id>: <reason>
+ *   // eess-exclude-end
+ *   // eess-exclude <rule-a>, <rule-b>: <reason>
+ *   <!-- eess-exclude <rule-id>: <reason> -->      (markdown / text dialects)
+ *   <!-- eess-exclude-start <rule-id>: <reason> --> / <!-- eess-exclude-end -->
+ */
+export declare function parseExclusionComments(sourceText: string, filePath: string): ParseResult;
+export declare function isExcludedByComment(violation: ArchViolation, comments: ExclusionComment[]): boolean;
+//# sourceMappingURL=exclusion-comments.d.ts.map

package/dist/exclusion-comments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exclusion-comments.d.ts","sourceRoot":"","sources":["../src/exclusion-comments.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAEnD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,6BAA6B;IAC7B,MAAM,EAAE,MAAM,CAAA;IACd,wCAAwC;IACxC,MAAM,EAAE,MAAM,CAAA;IACd,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAA;IACZ,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAA;IACZ,oDAAoD;IACpD,OAAO,EAAE,OAAO,CAAA;IAChB,oCAAoC;IACpC,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,sBAAsB;IACtB,OAAO,EAAE,MAAM,CAAA;IACf,gBAAgB;IAChB,IAAI,EAAE,MAAM,CAAA;IACZ,kBAAkB;IAClB,IAAI,EAAE,MAAM,CAAA;CACb;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,6CAA6C;IAC7C,UAAU,EAAE,gBAAgB,EAAE,CAAA;IAC9B,wCAAwC;IACxC,QAAQ,EAAE,gBAAgB,EAAE,CAAA;CAC7B;AAuJD;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,WAAW,CAyCxF;AAuBD,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,aAAa,EACxB,QAAQ,EAAE,gBAAgB,EAAE,GAC3B,OAAO,CAUT"}

package/dist/exclusion-comments.js

@@ -0,0 +1,183 @@
+// Single-line: // eess-exclude <rule-id>[, <rule-id>]: <reason>
+// Single-line without reason: // eess-exclude <rule-id>
+const SINGLE_LINE_RE = /\/\/\s*eess-exclude\s+(.+)/;
+// Block start: // eess-exclude-start <rule-id>[, <rule-id>]: <reason>
+const BLOCK_START_RE = /\/\/\s*eess-exclude-start\s+(.+)/;
+// Block end: // eess-exclude-end
+const BLOCK_END_RE = /\/\/\s*eess-exclude-end\b/;
+// HTML-comment forms — the same directives for text dialects whose sources
+// aren't `//`-commented (markdown corpora, and any future text dialect).
+// <!-- eess-exclude <rule-id>[, <rule-id>]: <reason> -->
+const HTML_SINGLE_RE = /<!--\s*eess-exclude\s+(.+?)\s*-->/;
+const HTML_BLOCK_START_RE = /<!--\s*eess-exclude-start\s+(.+?)\s*-->/;
+const HTML_BLOCK_END_RE = /<!--\s*eess-exclude-end\s*-->/;
+/**
+ * Parse rule IDs and reason from the content after the directive keyword.
+ *
+ * Format: `rule-a, rule-b: reason text`
+ * If no colon is present, all content is treated as rule IDs and reason is empty.
+ */
+function parseRuleIdsAndReason(content) {
+    const colonIndex = content.indexOf(':');
+    if (colonIndex < 0) {
+        // No colon — all content is rule IDs, no reason
+        const ruleIds = content
+            .split(',')
+            .map((s) => s.trim())
+            .filter((s) => s.length > 0);
+        return { ruleIds, reason: '' };
+    }
+    const idsPart = content.slice(0, colonIndex);
+    const reason = content.slice(colonIndex + 1).trim();
+    const ruleIds = idsPart
+        .split(',')
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+    return { ruleIds, reason };
+}
+/** Handle a block-end directive line. */
+function handleBlockEnd(openBlocks, exclusions, warnings, filePath, lineNum) {
+    if (openBlocks.size === 0) {
+        warnings.push({
+            message: `eess-exclude-end without matching start`,
+            file: filePath,
+            line: lineNum,
+        });
+        return;
+    }
+    for (const [, comment] of openBlocks) {
+        comment.endLine = lineNum;
+        exclusions.push(comment);
+    }
+    openBlocks.clear();
+}
+/** Emit undocumented-exclusion warnings for each rule ID when no reason is given. */
+function warnUndocumented(warnings, ruleIds, directive, filePath, lineNum) {
+    for (const ruleId of ruleIds) {
+        warnings.push({
+            message: `Undocumented exclusion at ${filePath}:${String(lineNum)} — ` +
+                `// ${directive} ${ruleId}\n` +
+                `  Fix: Add a reason — // ${directive} ${ruleId}: <why>`,
+            file: filePath,
+            line: lineNum,
+        });
+    }
+}
+/** Handle a block-start directive line. */
+function handleBlockStart(content, openBlocks, warnings, filePath, lineNum) {
+    if (openBlocks.size > 0) {
+        warnings.push({
+            message: `Nested eess-exclude-start — close existing block first`,
+            file: filePath,
+            line: lineNum,
+        });
+        return;
+    }
+    const { ruleIds, reason } = parseRuleIdsAndReason(content);
+    if (reason === '') {
+        warnUndocumented(warnings, ruleIds, 'eess-exclude-start', filePath, lineNum);
+    }
+    for (const ruleId of ruleIds) {
+        openBlocks.set(ruleId, {
+            ruleId,
+            reason,
+            file: filePath,
+            line: lineNum,
+            isBlock: true,
+        });
+    }
+}
+/** Handle a single-line exclude directive. */
+function handleSingleLine(content, exclusions, warnings, filePath, lineNum) {
+    // Skip if this was a block start or end (already handled above, but guard)
+    if (content.startsWith('-start') || content.startsWith('-end'))
+        return;
+    const { ruleIds, reason } = parseRuleIdsAndReason(content);
+    if (reason === '') {
+        warnUndocumented(warnings, ruleIds, 'eess-exclude', filePath, lineNum);
+    }
+    for (const ruleId of ruleIds) {
+        exclusions.push({
+            ruleId,
+            reason,
+            file: filePath,
+            line: lineNum,
+            isBlock: false,
+        });
+    }
+}
+/**
+ * Scan a source file for eess-exclude comments.
+ *
+ * Supported formats:
+ *   // eess-exclude <rule-id>: <reason>
+ *   // eess-exclude-start <rule-id>: <reason>
+ *   // eess-exclude-end
+ *   // eess-exclude <rule-a>, <rule-b>: <reason>
+ *   <!-- eess-exclude <rule-id>: <reason> -->      (markdown / text dialects)
+ *   <!-- eess-exclude-start <rule-id>: <reason> --> / <!-- eess-exclude-end -->
+ */
+export function parseExclusionComments(sourceText, filePath) {
+    const lines = sourceText.split('\n');
+    const exclusions = [];
+    const warnings = [];
+    const openBlocks = new Map();
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (line === undefined)
+            continue;
+        const lineNum = i + 1;
+        // Check block end first (before start/single so we don't match -start as single)
+        if (BLOCK_END_RE.test(line) || HTML_BLOCK_END_RE.test(line)) {
+            handleBlockEnd(openBlocks, exclusions, warnings, filePath, lineNum);
+            continue;
+        }
+        // Check block start
+        const startMatch = BLOCK_START_RE.exec(line) ?? HTML_BLOCK_START_RE.exec(line);
+        if (startMatch?.[1]) {
+            handleBlockStart(startMatch[1], openBlocks, warnings, filePath, lineNum);
+            continue;
+        }
+        // Check single-line exclude (must not match block directives)
+        const singleMatch = SINGLE_LINE_RE.exec(line) ?? HTML_SINGLE_RE.exec(line);
+        if (singleMatch?.[1]) {
+            handleSingleLine(singleMatch[1], exclusions, warnings, filePath, lineNum);
+        }
+    }
+    // Any unclosed blocks are errors
+    for (const [, comment] of openBlocks) {
+        warnings.push({
+            message: `eess-exclude-start without matching end for rule '${comment.ruleId}'`,
+            file: filePath,
+            line: comment.line,
+        });
+    }
+    return { exclusions, warnings };
+}
+/**
+ * Check if a violation is covered by an exclusion comment.
+ *
+ * For single-line comments: the violation must be in the same file and
+ * on the line immediately after the comment.
+ *
+ * For block comments: the violation must be in the same file and
+ * within the line range (start line, end line) inclusive.
+ */
+/** Check if a single comment covers the given violation. */
+function commentCoversViolation(comment, violationLine) {
+    if (comment.isBlock) {
+        return (comment.endLine !== undefined &&
+            violationLine >= comment.line &&
+            violationLine <= comment.endLine);
+    }
+    return violationLine === comment.line + 1;
+}
+export function isExcludedByComment(violation, comments) {
+    const ruleId = violation.ruleId;
+    if (!ruleId)
+        return false;
+    return comments.some((comment) => comment.ruleId === ruleId &&
+        comment.file === violation.file &&
+        commentCoversViolation(comment, violation.line));
+}
+//# sourceMappingURL=exclusion-comments.js.map

package/dist/exclusion-comments.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exclusion-comments.js","sourceRoot":"","sources":["../src/exclusion-comments.ts"],"names":[],"mappings":"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"}

package/dist/execute-rule.d.ts

@@ -0,0 +1,31 @@
+import type { ArchViolation } from './violation.js';
+import type { CheckOptions } from './check-options.js';
+import type { RuleMetadata } from './rule-metadata.js';
+/**
+ * Context for executing a rule's terminal methods.
+ * Shared across all builder types (RuleBuilder, SliceRuleBuilder,
+ * SchemaRuleBuilder, ResolverRuleBuilder, PairFinalBuilder, SmellBuilder).
+ */
+export interface ExecuteRuleContext {
+    reason?: string;
+    metadata?: RuleMetadata;
+    exclusions?: (string | RegExp)[];
+    silentIndices?: Set<number>;
+}
+/**
+ * Apply exclusion patterns, inline exclusion comments, baseline,
+ * and diff filtering to a set of violations, then execute the
+ * terminal action (throw or warn).
+ *
+ * Extracted to eliminate terminal-method duplication across builders.
+ */
+export declare function applyFilters(violations: ArchViolation[], ctx: ExecuteRuleContext): ArchViolation[];
+/**
+ * Execute the terminal "check" action: apply options, format, throw on violations.
+ */
+export declare function executeCheck(violations: ArchViolation[], ctx: ExecuteRuleContext, options?: CheckOptions): void;
+/**
+ * Execute the terminal "warn" action: apply options, format, log to stderr.
+ */
+export declare function executeWarn(violations: ArchViolation[], ctx: ExecuteRuleContext, options?: CheckOptions): void;
+//# sourceMappingURL=execute-rule.d.ts.map

package/dist/execute-rule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute-rule.d.ts","sourceRoot":"","sources":["../src/execute-rule.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AACnD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAQtD;;;;GAIG;AAEH,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,YAAY,CAAA;IACvB,UAAU,CAAC,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAA;IAChC,aAAa,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;CAC5B;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,UAAU,EAAE,aAAa,EAAE,EAC3B,GAAG,EAAE,kBAAkB,GACtB,aAAa,EAAE,CAsEjB;AAED;;GAEG;AACH,wBAAgB,YAAY,CAC1B,UAAU,EAAE,aAAa,EAAE,EAC3B,GAAG,EAAE,kBAAkB,EACvB,OAAO,CAAC,EAAE,YAAY,GACrB,IAAI,CAeN;AAED;;GAEG;AACH,wBAAgB,WAAW,CACzB,UAAU,EAAE,aAAa,EAAE,EAC3B,GAAG,EAAE,kBAAkB,EACvB,OAAO,CAAC,EAAE,YAAY,GACrB,IAAI,CAmBN"}

package/dist/execute-rule.js

@@ -0,0 +1,119 @@
+import fs from 'node:fs';
+import { ArchRuleError } from './errors.js';
+import { formatViolations } from './format.js';
+import { formatViolationsJson } from './format-json.js';
+import { formatViolationsGitHub } from './format-github.js';
+import { reportViolations } from './report.js';
+import { parseExclusionComments, isExcludedByComment } from './exclusion-comments.js';
+/**
+ * Apply exclusion patterns, inline exclusion comments, baseline,
+ * and diff filtering to a set of violations, then execute the
+ * terminal action (throw or warn).
+ *
+ * Extracted to eliminate terminal-method duplication across builders.
+ */
+export function applyFilters(violations, ctx) {
+    let result = violations;
+    // Apply .excluding() chain exclusions
+    const exclusions = ctx.exclusions ?? [];
+    if (exclusions.length > 0) {
+        const matchedPatterns = new Set();
+        result = result.filter((v) => {
+            // Match against element, file, or message — so that custom conditions
+            // using createViolation() can be excluded by file path or message content,
+            // not just by element name (which may be a generic AST node kind).
+            const targets = [v.element, v.file, v.message];
+            const matchIndex = exclusions.findIndex((pattern) => typeof pattern === 'string'
+                ? targets.some((t) => t === pattern)
+                : targets.some((t) => pattern.test(t)));
+            if (matchIndex >= 0) {
+                matchedPatterns.add(matchIndex);
+                return false;
+            }
+            return true;
+        });
+        const ruleId = ctx.metadata?.id ?? 'unnamed';
+        const silentIndices = ctx.silentIndices ?? new Set();
+        exclusions.forEach((pattern, index) => {
+            if (!matchedPatterns.has(index) && !silentIndices.has(index)) {
+                console.warn(`[eess] Unused exclusion '${String(pattern)}' in rule '${ruleId}'. ` +
+                    `It matched zero violations — it may be stale after a rename.`);
+            }
+        });
+    }
+    // Scan source files for inline exclusion comments (when rule has an ID)
+    if (ctx.metadata?.id && result.length > 0) {
+        // Tag violations with the rule id so inline exclusion comments (which match
+        // on ruleId) work for every condition — not just the few that stamp it
+        // themselves. The id is a property of the rule, so this is its single
+        // source of truth; conditions that already set it are left untouched.
+        const ruleId = ctx.metadata.id;
+        for (const v of result) {
+            if (v.ruleId === undefined)
+                v.ruleId = ruleId;
+        }
+        const filePaths = new Set(result.map((v) => v.file));
+        const allComments = [...filePaths].flatMap((filePath) => {
+            try {
+                const sourceText = fs.readFileSync(filePath, 'utf-8');
+                const parseResult = parseExclusionComments(sourceText, filePath);
+                for (const warning of parseResult.warnings) {
+                    console.warn(`[eess] ${warning.message}`);
+                }
+                return parseResult.exclusions;
+            }
+            catch (err) {
+                // Deliberate discard: violation paths may be virtual (synthetic
+                // elements, fixtures) — an unreadable file simply has no exclusion
+                // comments; warning here would spam every synthetic-element rule.
+                void err;
+                return [];
+            }
+        });
+        if (allComments.length > 0) {
+            result = result.filter((v) => !isExcludedByComment(v, allComments));
+        }
+    }
+    return result;
+}
+/**
+ * Execute the terminal "check" action: apply options, format, throw on violations.
+ */
+export function executeCheck(violations, ctx, options) {
+    let filtered = applyFilters(violations, ctx);
+    if (options?.baseline) {
+        filtered = options.baseline.filterNew(filtered);
+    }
+    if (options?.diff) {
+        filtered = options.diff.filterToChanged(filtered);
+    }
+    if (filtered.length > 0) {
+        // One emitter for both paths (plan 0070) — text/json/github, then throw.
+        reportViolations(filtered, { format: options?.format, reason: ctx.reason });
+        throw new ArchRuleError(filtered, ctx.reason);
+    }
+}
+/**
+ * Execute the terminal "warn" action: apply options, format, log to stderr.
+ */
+export function executeWarn(violations, ctx, options) {
+    let filtered = applyFilters(violations, ctx);
+    if (options?.baseline) {
+        filtered = options.baseline.filterNew(filtered);
+    }
+    if (options?.diff) {
+        filtered = options.diff.filterToChanged(filtered);
+    }
+    if (filtered.length > 0) {
+        if (options?.format === 'json') {
+            console.warn(formatViolationsJson(filtered, ctx.reason));
+        }
+        else if (options?.format === 'github') {
+            process.stdout.write(formatViolationsGitHub(filtered, 'warning') + '\n');
+        }
+        else {
+            console.warn(formatViolations(filtered, ctx.reason));
+        }
+    }
+}
+//# sourceMappingURL=execute-rule.js.map

package/dist/execute-rule.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute-rule.js","sourceRoot":"","sources":["../src/execute-rule.ts"],"names":[],"mappings":"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"}

package/dist/format-github.d.ts

@@ -0,0 +1,25 @@
+import type { ArchViolation } from './violation.js';
+/**
+ * Format violations as GitHub Actions annotation commands.
+ *
+ * Each violation becomes an `::error` or `::warning` command that GitHub
+ * renders as an inline annotation on the PR diff.
+ *
+ * File paths are converted to relative (GitHub needs relative paths from repo root).
+ *
+ * @param violations - The violations to format
+ * @param severity - 'error' for ::error, 'warning' for ::warning
+ *
+ * @example
+ * // In a GitHub Actions workflow step:
+ * // - run: npm run test 2>&1 | tee test-output.txt
+ * // Or directly from the test file:
+ * console.log(formatViolationsGitHub(violations))
+ */
+export declare function formatViolationsGitHub(violations: ArchViolation[], severity?: 'error' | 'warning'): string;
+/**
+ * Escape special characters for GitHub Actions commands.
+ * GitHub uses % encoding for newlines and other control chars.
+ */
+export declare function escapeGitHub(text: string): string;
+//# sourceMappingURL=format-github.d.ts.map

package/dist/format-github.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-github.d.ts","sourceRoot":"","sources":["../src/format-github.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAEnD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,aAAa,EAAE,EAC3B,QAAQ,GAAE,OAAO,GAAG,SAAmB,GACtC,MAAM,CAiBR;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEjD"}

package/dist/format-github.js

@@ -0,0 +1,44 @@
+import path from 'node:path';
+/**
+ * Format violations as GitHub Actions annotation commands.
+ *
+ * Each violation becomes an `::error` or `::warning` command that GitHub
+ * renders as an inline annotation on the PR diff.
+ *
+ * File paths are converted to relative (GitHub needs relative paths from repo root).
+ *
+ * @param violations - The violations to format
+ * @param severity - 'error' for ::error, 'warning' for ::warning
+ *
+ * @example
+ * // In a GitHub Actions workflow step:
+ * // - run: npm run test 2>&1 | tee test-output.txt
+ * // Or directly from the test file:
+ * console.log(formatViolationsGitHub(violations))
+ */
+export function formatViolationsGitHub(violations, severity = 'error') {
+    const cwd = process.cwd();
+    return violations
+        .map((v) => {
+        const relativePath = path.relative(cwd, v.file);
+        const title = v.ruleId
+            ? `Architecture Violation: ${v.ruleId}`
+            : `Architecture Violation: ${v.rule}`;
+        let message = v.because ? `${v.message} (${v.because})` : v.message;
+        if (v.suggestion)
+            message += `. Fix: ${v.suggestion}`;
+        if (v.docs)
+            message += `. Docs: ${v.docs}`;
+        // GitHub annotation format: ::level file=path,line=N,title=T::message
+        return `::${severity} file=${relativePath},line=${String(v.line)},title=${escapeGitHub(title)}::${escapeGitHub(message)}`;
+    })
+        .join('\n');
+}
+/**
+ * Escape special characters for GitHub Actions commands.
+ * GitHub uses % encoding for newlines and other control chars.
+ */
+export function escapeGitHub(text) {
+    return text.replace(/%/g, '%25').replace(/\r/g, '%0D').replace(/\n/g, '%0A');
+}
+//# sourceMappingURL=format-github.js.map

package/dist/format-github.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-github.js","sourceRoot":"","sources":["../src/format-github.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAA;AAG5B;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,sBAAsB,CACpC,UAA2B,EAC3B,WAAgC,OAAO;IAEvC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,EAAE,CAAA;IAEzB,OAAO,UAAU;SACd,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QACT,MAAM,YAAY,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,CAAC,CAAA;QAC/C,MAAM,KAAK,GAAG,CAAC,CAAC,MAAM;YACpB,CAAC,CAAC,2BAA2B,CAAC,CAAC,MAAM,EAAE;YACvC,CAAC,CAAC,2BAA2B,CAAC,CAAC,IAAI,EAAE,CAAA;QACvC,IAAI,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAA;QACnE,IAAI,CAAC,CAAC,UAAU;YAAE,OAAO,IAAI,UAAU,CAAC,CAAC,UAAU,EAAE,CAAA;QACrD,IAAI,CAAC,CAAC,IAAI;YAAE,OAAO,IAAI,WAAW,CAAC,CAAC,IAAI,EAAE,CAAA;QAE1C,sEAAsE;QACtE,OAAO,KAAK,QAAQ,SAAS,YAAY,SAAS,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,YAAY,CAAC,KAAK,CAAC,KAAK,YAAY,CAAC,OAAO,CAAC,EAAE,CAAA;IAC3H,CAAC,CAAC;SACD,IAAI,CAAC,IAAI,CAAC,CAAA;AACf,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,CAAA;AAC9E,CAAC"}

package/dist/format-json.d.ts

@@ -0,0 +1,12 @@
+import type { ArchViolation } from './violation.js';
+/**
+ * Format violations as a JSON string.
+ *
+ * Useful for CI pipelines, custom dashboards, or piping to other tools.
+ *
+ * @example
+ * const violations = collectViolations(rule1, rule2)
+ * console.log(formatViolationsJson(violations))
+ */
+export declare function formatViolationsJson(violations: ArchViolation[], reason?: string): string;
+//# sourceMappingURL=format-json.d.ts.map

package/dist/format-json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-json.d.ts","sourceRoot":"","sources":["../src/format-json.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAEnD;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,aAAa,EAAE,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAmBzF"}

package/dist/format-json.js

@@ -0,0 +1,30 @@
+/**
+ * Format violations as a JSON string.
+ *
+ * Useful for CI pipelines, custom dashboards, or piping to other tools.
+ *
+ * @example
+ * const violations = collectViolations(rule1, rule2)
+ * console.log(formatViolationsJson(violations))
+ */
+export function formatViolationsJson(violations, reason) {
+    const output = {
+        summary: {
+            total: violations.length,
+            reason: reason ?? null,
+        },
+        violations: violations.map((v) => ({
+            rule: v.rule,
+            ruleId: v.ruleId ?? null,
+            element: v.element,
+            file: v.file,
+            line: v.line,
+            message: v.message,
+            because: v.because ?? null,
+            suggestion: v.suggestion ?? null,
+            docs: v.docs ?? null,
+        })),
+    };
+    return JSON.stringify(output, null, 2);
+}
+//# sourceMappingURL=format-json.js.map

package/dist/format-json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-json.js","sourceRoot":"","sources":["../src/format-json.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB,CAAC,UAA2B,EAAE,MAAe;IAC/E,MAAM,MAAM,GAAG;QACb,OAAO,EAAE;YACP,KAAK,EAAE,UAAU,CAAC,MAAM;YACxB,MAAM,EAAE,MAAM,IAAI,IAAI;SACvB;QACD,UAAU,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACjC,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,MAAM,EAAE,CAAC,CAAC,MAAM,IAAI,IAAI;YACxB,OAAO,EAAE,CAAC,CAAC,OAAO;YAClB,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,OAAO,EAAE,CAAC,CAAC,OAAO;YAClB,OAAO,EAAE,CAAC,CAAC,OAAO,IAAI,IAAI;YAC1B,UAAU,EAAE,CAAC,CAAC,UAAU,IAAI,IAAI;YAChC,IAAI,EAAE,CAAC,CAAC,IAAI,IAAI,IAAI;SACrB,CAAC,CAAC;KACJ,CAAA;IACD,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAA;AACxC,CAAC"}

package/dist/format.d.ts

@@ -0,0 +1,25 @@
+import type { ArchViolation } from './violation.js';
+/**
+ * Format options for violation output.
+ */
+export interface FormatOptions {
+    /** Working directory for relative path display. Default: process.cwd() */
+    cwd?: string;
+    /** Whether to include code frames in output. Default: true */
+    codeFrames?: boolean;
+}
+/**
+ * Format violations into a rich, readable terminal string.
+ *
+ * Groups violations by rule, shows a counter ("Architecture Violation [1 of 3]"),
+ * displays code frames and suggestions, and uses ANSI colors for emphasis.
+ */
+export declare function formatViolations(violations: ArchViolation[], reason?: string, options?: FormatOptions): string;
+/**
+ * Format violations into a plain-text string (no ANSI codes).
+ *
+ * Used by ArchRuleError.message — error messages should be plain text
+ * since they may be captured by test runners, serialized, or logged to files.
+ */
+export declare function formatViolationsPlain(violations: ArchViolation[], reason?: string): string;
+//# sourceMappingURL=format.d.ts.map

package/dist/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAInD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,0EAA0E;IAC1E,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,8DAA8D;IAC9D,UAAU,CAAC,EAAE,OAAO,CAAA;CACrB;AAgCD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,aAAa,EAAE,EAC3B,MAAM,CAAC,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,aAAa,GACtB,MAAM,CAYR;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,aAAa,EAAE,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAkB1F"}

package/dist/format.js

@@ -0,0 +1,66 @@
+import { bold, red, cyan, dim } from './ansi.js';
+import path from 'node:path';
+/** Format a single violation into a rich terminal section. */
+function formatSingleViolation(v, index, total, cwd, showCodeFrames, reason) {
+    const counter = bold(red(`Architecture Violation [${String(index + 1)} of ${String(total)}]`));
+    const ruleLine = `  ${dim('Rule:')} ${v.rule}`;
+    const relativePath = path.relative(cwd, v.file);
+    const locationRef = cyan(relativePath + ':' + String(v.line));
+    const location = `  ${locationRef} ${dim('—')} ${v.element}`;
+    const codeLine = showCodeFrames && v.codeFrame ? `\n${v.codeFrame}` : '';
+    const whyText = v.because ?? reason;
+    const whyLine = whyText ? `  ${dim('Why:')} ${whyText}` : '';
+    const fixLine = v.suggestion ? `  ${dim('Fix:')} ${v.suggestion}` : '';
+    const docsLine = v.docs ? `  ${dim('Docs:')} ${v.docs}` : '';
+    const parts = [counter, '', ruleLine, '', location];
+    if (codeLine)
+        parts.push(codeLine);
+    if (whyLine)
+        parts.push(whyLine);
+    if (fixLine)
+        parts.push(fixLine);
+    if (docsLine)
+        parts.push(docsLine);
+    return parts.join('\n');
+}
+/**
+ * Format violations into a rich, readable terminal string.
+ *
+ * Groups violations by rule, shows a counter ("Architecture Violation [1 of 3]"),
+ * displays code frames and suggestions, and uses ANSI colors for emphasis.
+ */
+export function formatViolations(violations, reason, options) {
+    if (violations.length === 0)
+        return '';
+    const cwd = options?.cwd ?? process.cwd();
+    const showCodeFrames = options?.codeFrames ?? true;
+    const total = violations.length;
+    const sections = violations.map((v, i) => formatSingleViolation(v, i, total, cwd, showCodeFrames, reason));
+    return sections.join('\n\n');
+}
+/**
+ * Format violations into a plain-text string (no ANSI codes).
+ *
+ * Used by ArchRuleError.message — error messages should be plain text
+ * since they may be captured by test runners, serialized, or logged to files.
+ */
+export function formatViolationsPlain(violations, reason) {
+    if (violations.length === 0)
+        return '';
+    const header = `Architecture violation${violations.length === 1 ? '' : 's'} (${String(violations.length)} found)`;
+    const reasonLine = reason ? `\nReason: ${reason}` : '';
+    const details = violations
+        .map((v, i) => {
+        const parts = [
+            `  [${String(i + 1)}/${String(violations.length)}] ${v.element}: ${v.message} (${v.file}:${String(v.line)})`,
+        ];
+        if (v.codeFrame)
+            parts.push(v.codeFrame);
+        if (v.suggestion)
+            parts.push(`  Fix: ${v.suggestion}`);
+        return parts.join('\n');
+    })
+        .join('\n\n');
+    return `${header}${reasonLine}\n\n${details}`;
+}
+//# sourceMappingURL=format.js.map

package/dist/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"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"}