@opensip-cli/checks-universal 0.1.0

package/dist/checks/architecture/no-custom-event-emitter.js

@@ -0,0 +1,123 @@
+/**
+ * @fileoverview No Custom Event Emitter check
+ */
+import { defineCheck } from '@opensip-cli/fitness';
+/**
+ * Creates a pre-compiled RegExp for pattern matching.
+ * These patterns operate on trusted source code files, not user input.
+ * @param pattern - The regex pattern string
+ * @param flags - Optional regex flags
+ * @returns Compiled RegExp object
+ */
+function createPattern(pattern, flags) {
+    // @fitness-ignore-next-line semgrep-scan -- non-literal RegExp is intentional; patterns are hardcoded string constants for code analysis, not user input
+    return new RegExp(pattern, flags);
+}
+// Note: These regex patterns operate on trusted source code files, not user input.
+// The patterns use bounded character classes ([^}]*) instead of .* to prevent ReDoS.
+const EVENT_EMITTER_PATTERNS = [
+    {
+        // Fixed pattern - no backtracking issues
+        pattern: createPattern(String.raw `new\s+EventEmitter\s*\(`, 'g'),
+        type: 'new-event-emitter',
+        suggestion: 'Use a centralized event bus instead of direct EventEmitter instantiation',
+        severity: 'error',
+    },
+    {
+        // Fixed pattern - word boundary prevents issues
+        pattern: createPattern(String.raw `extends\s+EventEmitter\b`, 'g'),
+        type: 'extends-event-emitter',
+        suggestion: 'Implement event handling via a centralized event bus instead of extending EventEmitter',
+        severity: 'error',
+    },
+    {
+        // Use [^}]* (bounded by curly brace) instead of .* to prevent catastrophic backtracking
+        pattern: createPattern(String.raw `import\s+[^}]*\bEventEmitter\b[^}]*from\s+['"]events['"]`, 'g'),
+        type: 'import-event-emitter',
+        suggestion: 'Use a centralized event bus instead of importing EventEmitter directly',
+        severity: 'error',
+    },
+    {
+        // Use [^}]* (bounded by curly brace) instead of .* to prevent catastrophic backtracking
+        pattern: createPattern(String.raw `import\s+[^}]*\bEventEmitter\b[^}]*from\s+['"]node:events['"]`, 'g'),
+        type: 'import-event-emitter',
+        suggestion: 'Use a centralized event bus instead of importing EventEmitter directly',
+        severity: 'error',
+    },
+];
+const EVENT_INFRA_PATTERNS = [
+    /infrastructure\/events\//,
+    /foundation\//,
+    /\/adapters\//,
+    /interfaces\//,
+];
+function analyzeFile(filePath, content) {
+    const issues = [];
+    if (EVENT_INFRA_PATTERNS.some((p) => p.test(filePath))) {
+        return [];
+    }
+    const lines = content.split('\n');
+    for (const [i, line] of lines.entries()) {
+        if (!line)
+            continue;
+        for (const { pattern, type, suggestion, severity } of EVENT_EMITTER_PATTERNS) {
+            pattern.lastIndex = 0;
+            const match = pattern.exec(line);
+            if (match) {
+                issues.push({
+                    file: filePath,
+                    line: i + 1,
+                    type,
+                    match: match[0],
+                    suggestion,
+                    severity,
+                });
+            }
+        }
+    }
+    return issues;
+}
+/**
+ * Check: architecture/no-custom-event-emitter
+ *
+ * Detects direct EventEmitter usage that should use infrastructure/events module.
+ * Ensures consistent event handling patterns across the codebase.
+ */
+export const noCustomEventEmitter = defineCheck({
+    id: '7a36c3b8-fb23-42fc-8f25-336e012aab57',
+    slug: 'no-custom-event-emitter',
+    disabled: true,
+    scope: { languages: ['typescript'], concerns: ['backend', 'server'] },
+    contentFilter: 'strip-strings',
+    confidence: 'medium',
+    description: 'Detects direct EventEmitter usage that should use infrastructure/events',
+    longDescription: `**Purpose:** Prevents direct usage of Node.js \`EventEmitter\` in favor of a centralized event bus.
+
+**Detects:**
+- Direct instantiation of Node.js event emitter
+- Class inheritance from Node.js event emitter
+- Imports of Node.js event emitter from 'events' or 'node:events'
+- Excludes \`infrastructure/events/\`, \`foundation/\`, \`/adapters/\`, and \`interfaces/\` directories
+
+**Why it matters:** Custom event emitters bypass centralized event bus patterns, making event flows untraceable and inconsistent across the platform.
+
+**Scope:** Codebase-specific convention. Analyzes each file individually.`,
+    tags: ['architecture', 'best-practices'],
+    fileTypes: ['ts'],
+    analyze(content, filePath) {
+        // Skip if no EventEmitter usage
+        if (!content.includes('EventEmitter')) {
+            return [];
+        }
+        const issues = analyzeFile(filePath, content);
+        return issues.map((issue) => ({
+            line: issue.line,
+            message: `Custom event emitter: ${issue.type}. ${issue.suggestion}`,
+            severity: issue.severity,
+            suggestion: issue.suggestion,
+            match: issue.match,
+            type: issue.type,
+        }));
+    },
+});
+//# sourceMappingURL=no-custom-event-emitter.js.map

package/dist/checks/architecture/no-custom-event-emitter.js.map

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

package/dist/checks/architecture/no-kebab-option-indexing.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @fileoverview A command handler must not index its parsed-options object by a
+ * KEBAB-CASE string literal — Commander camelCases long flags, so the kebab key
+ * is always `undefined`.
+ *
+ * WHY (the drift this freezes out):
+ *   Commander stores `--summary-only` under `opts.summaryOnly`, `--report-to`
+ *   under `opts.reportTo`, etc. — it camelCases the long flag when it builds the
+ *   parsed-options object. A handler that reads `opts['summary-only']` therefore
+ *   reads a key Commander NEVER sets: the value is silently `undefined`, the flag
+ *   becomes a permanent no-op, and the bug is invisible (no crash, no warning).
+ *   This is a recurring CLI footgun whenever a multi-word flag is wired by hand.
+ *
+ * DETECTION — regex on RAW content (the kebab string literal IS the signal, so it
+ * must NOT be stripped; comment lines are skipped manually). Flags an index
+ * access on a Commander-convention options identifier (`opts` / `rawOpts` /
+ * `cmdOpts` / `parsedOpts` / `cmdOptions`) whose key is a kebab-case string
+ * literal (`['a-b']`). camelCase keys, numeric keys, and non-options objects
+ * (`headers['content-type']`, `style['font-size']`) do not match.
+ *
+ * SCOPE — TypeScript backend/CLI sources. This is a generic Commander
+ * best-practice (a kebab-indexed parsed-options read is wrong in any
+ * Commander-based CLI), so there is no repo-specific path guard. Test files are
+ * skipped.
+ */
+import { type CheckViolation } from '@opensip-cli/fitness';
+/**
+ * Pure analysis over one source file. Returns a finding for each kebab-indexed
+ * parsed-options read. Exported for unit tests.
+ */
+export declare function analyzeNoKebabOptionIndexing(content: string, filePath: string): CheckViolation[];
+export declare const noKebabOptionIndexing: import("@opensip-cli/fitness").Check;
+//# sourceMappingURL=no-kebab-option-indexing.d.ts.map

package/dist/checks/architecture/no-kebab-option-indexing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"no-kebab-option-indexing.d.ts","sourceRoot":"","sources":["../../../src/checks/architecture/no-kebab-option-indexing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,EAAe,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAcxE;;;GAGG;AACH,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,cAAc,EAAE,CA4BhG;AAED,eAAO,MAAM,qBAAqB,sCAYhC,CAAC"}

package/dist/checks/architecture/no-kebab-option-indexing.js

@@ -0,0 +1,81 @@
+/**
+ * @fileoverview A command handler must not index its parsed-options object by a
+ * KEBAB-CASE string literal — Commander camelCases long flags, so the kebab key
+ * is always `undefined`.
+ *
+ * WHY (the drift this freezes out):
+ *   Commander stores `--summary-only` under `opts.summaryOnly`, `--report-to`
+ *   under `opts.reportTo`, etc. — it camelCases the long flag when it builds the
+ *   parsed-options object. A handler that reads `opts['summary-only']` therefore
+ *   reads a key Commander NEVER sets: the value is silently `undefined`, the flag
+ *   becomes a permanent no-op, and the bug is invisible (no crash, no warning).
+ *   This is a recurring CLI footgun whenever a multi-word flag is wired by hand.
+ *
+ * DETECTION — regex on RAW content (the kebab string literal IS the signal, so it
+ * must NOT be stripped; comment lines are skipped manually). Flags an index
+ * access on a Commander-convention options identifier (`opts` / `rawOpts` /
+ * `cmdOpts` / `parsedOpts` / `cmdOptions`) whose key is a kebab-case string
+ * literal (`['a-b']`). camelCase keys, numeric keys, and non-options objects
+ * (`headers['content-type']`, `style['font-size']`) do not match.
+ *
+ * SCOPE — TypeScript backend/CLI sources. This is a generic Commander
+ * best-practice (a kebab-indexed parsed-options read is wrong in any
+ * Commander-based CLI), so there is no repo-specific path guard. Test files are
+ * skipped.
+ */
+import { defineCheck } from '@opensip-cli/fitness';
+/** Test-file fragments — skipped. */
+const TEST_PATH = /(?:\.test\.tsx?$|\/__tests__\/)/;
+/**
+ * `<optsVar>['<kebab-case>']` — a parsed-options index by a kebab string literal.
+ * The identifier set is the Commander parsed-options naming convention; the key
+ * must contain at least one `-` (kebab), which a camelCased Commander key never
+ * does.
+ */
+const KEBAB_OPTION_INDEX_RE = /\b(?:opts|rawOpts|cmdOpts|parsedOpts|cmdOptions)\s*\[\s*(['"])([a-z][a-z0-9]*(?:-[a-z0-9]+)+)\1\s*\]/g;
+/**
+ * Pure analysis over one source file. Returns a finding for each kebab-indexed
+ * parsed-options read. Exported for unit tests.
+ */
+export function analyzeNoKebabOptionIndexing(content, filePath) {
+    if (TEST_PATH.test(filePath.replaceAll('\\', '/')))
+        return [];
+    const violations = [];
+    const lines = content.split('\n');
+    for (const [i, rawLine] of lines.entries()) {
+        // Skip comment lines so prose/examples mentioning the pattern don't fire
+        // (content is raw, so the kebab literal survives — we must comment-skip here).
+        const trimmed = rawLine.trimStart();
+        if (trimmed.startsWith('*') || trimmed.startsWith('//'))
+            continue;
+        KEBAB_OPTION_INDEX_RE.lastIndex = 0;
+        let m;
+        while ((m = KEBAB_OPTION_INDEX_RE.exec(rawLine)) !== null) {
+            const kebabKey = m[2];
+            const camel = kebabKey.replaceAll(/-([a-z0-9])/g, (_, c) => c.toUpperCase());
+            violations.push({
+                line: i + 1,
+                message: `Parsed options indexed by the kebab-case key '${kebabKey}'. Commander ` +
+                    `camelCases long flags, so it stores this under '${camel}' — the kebab key is ` +
+                    `always undefined and the flag is a silent no-op.`,
+                severity: 'error',
+                suggestion: `Read the camelCased key Commander actually sets: 'opts.${camel}'.`,
+                type: 'no-kebab-option-indexing',
+            });
+        }
+    }
+    return violations;
+}
+export const noKebabOptionIndexing = defineCheck({
+    id: '64bb7fa7-3e0d-4f4d-a1e6-d7b189df053c',
+    slug: 'no-kebab-option-indexing',
+    description: 'Command handlers must not index parsed options by a kebab-case key — Commander camelCases long flags, so the kebab key is always undefined (silent no-op flag)',
+    scope: { languages: ['typescript'], concerns: ['backend'] },
+    tags: ['architecture'],
+    fileTypes: ['ts'],
+    // raw: the kebab-case string literal IS the signal — strip-strings would blank
+    // it. Comment lines are skipped in the analyzer so prose does not false-fire.
+    contentFilter: 'raw',
+    analyze: (content, filePath) => analyzeNoKebabOptionIndexing(content, filePath),
+});
+//# sourceMappingURL=no-kebab-option-indexing.js.map

package/dist/checks/architecture/no-kebab-option-indexing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"no-kebab-option-indexing.js","sourceRoot":"","sources":["../../../src/checks/architecture/no-kebab-option-indexing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,EAAE,WAAW,EAAuB,MAAM,sBAAsB,CAAC;AAExE,qCAAqC;AACrC,MAAM,SAAS,GAAG,iCAAiC,CAAC;AAEpD;;;;;GAKG;AACH,MAAM,qBAAqB,GACzB,uGAAuG,CAAC;AAE1G;;;GAGG;AACH,MAAM,UAAU,4BAA4B,CAAC,OAAe,EAAE,QAAgB;IAC5E,IAAI,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QAAE,OAAO,EAAE,CAAC;IAE9D,MAAM,UAAU,GAAqB,EAAE,CAAC;IACxC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAClC,KAAK,MAAM,CAAC,CAAC,EAAE,OAAO,CAAC,IAAI,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC;QAC3C,yEAAyE;QACzE,+EAA+E;QAC/E,MAAM,OAAO,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;QACpC,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC;YAAE,SAAS;QAClE,qBAAqB,CAAC,SAAS,GAAG,CAAC,CAAC;QACpC,IAAI,CAAyB,CAAC;QAC9B,OAAO,CAAC,CAAC,GAAG,qBAAqB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;YAC1D,MAAM,QAAQ,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;YACtB,MAAM,KAAK,GAAG,QAAQ,CAAC,UAAU,CAAC,cAAc,EAAE,CAAC,CAAC,EAAE,CAAS,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;YACrF,UAAU,CAAC,IAAI,CAAC;gBACd,IAAI,EAAE,CAAC,GAAG,CAAC;gBACX,OAAO,EACL,iDAAiD,QAAQ,eAAe;oBACxE,mDAAmD,KAAK,uBAAuB;oBAC/E,kDAAkD;gBACpD,QAAQ,EAAE,OAAO;gBACjB,UAAU,EAAE,0DAA0D,KAAK,IAAI;gBAC/E,IAAI,EAAE,0BAA0B;aACjC,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,MAAM,CAAC,MAAM,qBAAqB,GAAG,WAAW,CAAC;IAC/C,EAAE,EAAE,sCAAsC;IAC1C,IAAI,EAAE,0BAA0B;IAChC,WAAW,EACT,gKAAgK;IAClK,KAAK,EAAE,EAAE,SAAS,EAAE,CAAC,YAAY,CAAC,EAAE,QAAQ,EAAE,CAAC,SAAS,CAAC,EAAE;IAC3D,IAAI,EAAE,CAAC,cAAc,CAAC;IACtB,SAAS,EAAE,CAAC,IAAI,CAAC;IACjB,+EAA+E;IAC/E,8EAA8E;IAC9E,aAAa,EAAE,KAAK;IACpB,OAAO,EAAE,CAAC,OAAO,EAAE,QAAQ,EAAE,EAAE,CAAC,4BAA4B,CAAC,OAAO,EAAE,QAAQ,CAAC;CAChF,CAAC,CAAC"}

package/dist/checks/architecture/node-version-consistency.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @fileoverview Node version consistency fitness check
+ * @invariants
+ * - All engines.node fields must match root package.json
+ * - .nvmrc major version must match engines.node
+ * - @types/node major version must match engines.node
+ * - CI workflow node-version must match engines.node
+ * - Dockerfiles are NOT checked (covered by docker-version-sync)
+ */
+/**
+ * Check: architecture/node-version-consistency
+ *
+ * Validates that Node.js version references are consistent across the codebase:
+ * 1. .nvmrc matches root package.json engines.node
+ * 2. All workspace package.json engines.node fields match root
+ * 3. @types/node major version matches engines.node major
+ * 4. CI workflow node-version matches engines.node
+ *
+ * Note: Dockerfile FROM node:XX checks are handled by docker-version-sync.
+ */
+export declare const nodeVersionConsistency: import("@opensip-cli/fitness").Check;
+//# sourceMappingURL=node-version-consistency.d.ts.map

package/dist/checks/architecture/node-version-consistency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-version-consistency.d.ts","sourceRoot":"","sources":["../../../src/checks/architecture/node-version-consistency.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AAkMH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,sBAAsB,sCAqEjC,CAAC"}

package/dist/checks/architecture/node-version-consistency.js

@@ -0,0 +1,225 @@
+// @fitness-ignore-file fitness-check-standards -- Uses fs for package.json reading, not source file content
+// @fitness-ignore-file detached-promises -- helpers (checkNvmrc, checkWorkspaceEngines, checkTypesNode, checkCiWorkflow) are synchronous violation-collectors; heuristic flags them despite returning void
+/**
+ * @fileoverview Node version consistency fitness check
+ * @invariants
+ * - All engines.node fields must match root package.json
+ * - .nvmrc major version must match engines.node
+ * - @types/node major version must match engines.node
+ * - CI workflow node-version must match engines.node
+ * - Dockerfiles are NOT checked (covered by docker-version-sync)
+ */
+import * as path from 'node:path';
+import { defineCheck } from '@opensip-cli/fitness';
+// =============================================================================
+// REGEX PATTERNS
+// =============================================================================
+/** Extract major version from engines.node constraint like ">=24.0.0" -> 24 */
+const ENGINES_NODE_MAJOR = /(\d+)/;
+/** Match @types/node version like "^24.0.0" -> 24 */
+const TYPES_NODE_MAJOR = /\^(\d+)/;
+/** Match node-version in CI workflow YAML */
+const CI_NODE_VERSION = /node-version:\s*['"]?(\d+)['"]?/;
+// =============================================================================
+// HELPERS
+// =============================================================================
+/**
+ * Extract major Node version from engines.node constraint.
+ * e.g. ">=24.0.0" -> 24
+ */
+function extractNodeMajor(constraint) {
+    const match = ENGINES_NODE_MAJOR.exec(constraint);
+    /* v8 ignore next 3 -- defensive: regex (\d+) ensures group [1] is set when match succeeds */
+    const digit = match?.[1];
+    // @fitness-ignore-next-line numeric-validation -- regex guarantees digit-only string; null guard above
+    return digit ? Number.parseInt(digit, 10) : null;
+}
+// =============================================================================
+// PER-FILE ANALYSIS HELPERS
+// =============================================================================
+function checkNvmrc(content, filePath, expectedMajor, violations) {
+    const trimmed = content.trim();
+    const nvmrcMajor = Number.parseInt(trimmed, 10);
+    /* v8 ignore next -- defensive: malformed .nvmrc not exercised in fixtures */
+    if (Number.isNaN(nvmrcMajor))
+        return;
+    if (nvmrcMajor !== expectedMajor) {
+        violations.push({
+            line: 1,
+            filePath,
+            message: `.nvmrc specifies Node ${nvmrcMajor} but root package.json engines.node requires ${expectedMajor}`,
+            severity: 'error',
+            suggestion: `Change .nvmrc from "${trimmed}" to "${expectedMajor}"`,
+            type: 'nvmrc-version-mismatch',
+        });
+    }
+}
+function checkWorkspaceEngines(content, filePath, expectedMajor, rootConstraint, violations) {
+    let pkg;
+    try {
+        pkg = JSON.parse(content);
+    }
+    catch {
+        /* v8 ignore next -- defensive: malformed workspace package.json not exercised in fixtures */
+        // @swallow-ok expected for non-JSON files or malformed package.json
+        return;
+    }
+    const enginesNode = pkg.engines?.node;
+    if (!enginesNode)
+        return;
+    const workspaceMajor = extractNodeMajor(enginesNode);
+    /* v8 ignore next -- defensive: enginesNode already checked, regex match guaranteed */
+    if (workspaceMajor === null)
+        return;
+    if (workspaceMajor !== expectedMajor) {
+        const relPath = path.relative(process.cwd(), filePath);
+        violations.push({
+            line: 1,
+            filePath,
+            message: `${relPath} engines.node is "${enginesNode}" but root package.json has "${rootConstraint}"`,
+            severity: 'error',
+            suggestion: `Change engines.node from "${enginesNode}" to "${rootConstraint}"`,
+            type: 'workspace-engines-mismatch',
+        });
+    }
+}
+function checkTypesNode(content, filePath, expectedMajor, violations) {
+    let pkg;
+    try {
+        pkg = JSON.parse(content);
+    }
+    catch {
+        /* v8 ignore next -- defensive: malformed workspace package.json not exercised in fixtures */
+        // @swallow-ok expected for non-JSON files or malformed package.json
+        return;
+    }
+    /* v8 ignore next -- defensive: pkg.dependencies fallback when devDependencies missing */
+    const typesNodeVersion = pkg.devDependencies?.['@types/node'] ?? pkg.dependencies?.['@types/node'];
+    if (!typesNodeVersion)
+        return;
+    const match = TYPES_NODE_MAJOR.exec(typesNodeVersion);
+    /* v8 ignore next 2 -- defensive: regex ^\d+ ensures group [1] is set when match succeeds */
+    const typesMajor = match?.[1];
+    if (!typesMajor)
+        return;
+    // @fitness-ignore-next-line numeric-validation -- regex ^\d+ guarantees digit-only string
+    const typesMajorNum = Number.parseInt(typesMajor, 10);
+    if (typesMajorNum !== expectedMajor) {
+        const relPath = path.relative(process.cwd(), filePath);
+        violations.push({
+            line: 1,
+            filePath,
+            message: `${relPath} has @types/node "${typesNodeVersion}" but engines.node major is ${expectedMajor}`,
+            severity: 'error',
+            suggestion: `Change @types/node from "${typesNodeVersion}" to "^${expectedMajor}.0.0"`,
+            type: 'types-node-mismatch',
+        });
+    }
+}
+function checkCiWorkflow(content, filePath, expectedMajor, violations) {
+    const lines = content.split('\n');
+    for (const [i, rawLine] of lines.entries()) {
+        /* v8 ignore next -- defensive: lines.entries() never yields undefined */
+        if (!rawLine)
+            continue;
+        const line = rawLine.trim();
+        const match = CI_NODE_VERSION.exec(line);
+        /* v8 ignore next 2 -- defensive: regex (\d+) ensures group [1] is set when match succeeds */
+        const ciVersion = match?.[1];
+        if (!ciVersion)
+            continue;
+        // @fitness-ignore-next-line numeric-validation -- regex (\d+) guarantees digit-only string
+        const ciMajor = Number.parseInt(ciVersion, 10);
+        if (ciMajor !== expectedMajor) {
+            violations.push({
+                line: i + 1,
+                filePath,
+                message: `CI workflow uses node-version: '${ciVersion}' but root package.json engines.node requires ${expectedMajor}`,
+                severity: 'error',
+                suggestion: `Change node-version from '${ciVersion}' to '${expectedMajor}'`,
+                type: 'ci-node-version-mismatch',
+            });
+        }
+    }
+}
+// =============================================================================
+// CHECK DEFINITION
+// =============================================================================
+/**
+ * Check: architecture/node-version-consistency
+ *
+ * Validates that Node.js version references are consistent across the codebase:
+ * 1. .nvmrc matches root package.json engines.node
+ * 2. All workspace package.json engines.node fields match root
+ * 3. @types/node major version matches engines.node major
+ * 4. CI workflow node-version matches engines.node
+ *
+ * Note: Dockerfile FROM node:XX checks are handled by docker-version-sync.
+ */
+export const nodeVersionConsistency = defineCheck({
+    id: 'e32068df-b100-4406-a8ba-caec5d53fa92',
+    slug: 'node-version-consistency',
+    scope: { languages: ['json', 'typescript', 'yaml'], concerns: ['config'] },
+    contentFilter: 'raw',
+    confidence: 'medium',
+    description: 'Validate Node.js version consistency across configs',
+    longDescription: `**Purpose:** Ensures all Node.js version references across the codebase stay in sync with the root \`package.json\` \`engines.node\` field.
+
+**Detects:**
+- \`.nvmrc\` major version mismatches against \`engines.node\`
+- Workspace \`package.json\` \`engines.node\` fields that differ from root
+- \`@types/node\` major version mismatches in any \`package.json\`
+- CI workflow \`node-version:\` lines that don't match
+
+**Why it matters:** Version drift between .nvmrc, CI, and package.json leads to "works on my machine" issues and inconsistent runtime behavior.
+
+**Scope:** Codebase-specific convention. Cross-file analysis via \`analyzeAll\`. Dockerfiles are intentionally excluded (covered by \`docker-version-sync\`).`,
+    tags: ['node', 'version-sync', 'architecture'],
+    async analyzeAll(files) {
+        const violations = [];
+        // Find the root package.json from the scanned file set.
+        // The root is the shortest path (shallowest) package.json in the set.
+        const packageJsonPaths = files.paths.filter((p) => path.basename(p) === 'package.json');
+        if (packageJsonPaths.length === 0)
+            return violations;
+        const rootPkgPath = packageJsonPaths.reduce((shortest, p) => (p.length < shortest.length ? p : shortest), 
+        /* v8 ignore next -- defensive: packageJsonPaths.length checked above */
+        packageJsonPaths[0]);
+        // Read root package.json for version truth
+        const rootContent = await files.read(rootPkgPath);
+        let rootPkg;
+        try {
+            rootPkg = JSON.parse(rootContent);
+        }
+        catch {
+            return violations;
+        }
+        const rootConstraint = rootPkg.engines?.node;
+        if (!rootConstraint)
+            return violations;
+        const expectedMajor = extractNodeMajor(rootConstraint);
+        /* v8 ignore next -- defensive: rootConstraint already checked, regex (\d+) ensures match */
+        if (expectedMajor === null)
+            return violations;
+        for (const filePath of files.paths) {
+            // @fitness-ignore-next-line performance-anti-patterns -- sequential file reading to control memory; FileAccessor is lazy
+            const content = await files.read(filePath);
+            const basename = path.basename(filePath);
+            if (basename === '.nvmrc') {
+                checkNvmrc(content, filePath, expectedMajor, violations);
+            }
+            else if (basename === 'package.json') {
+                // Skip root package.json (it's the source of truth)
+                if (filePath === rootPkgPath)
+                    continue;
+                checkWorkspaceEngines(content, filePath, expectedMajor, rootConstraint, violations);
+                checkTypesNode(content, filePath, expectedMajor, violations);
+            }
+            else if (filePath.includes('.github/workflows/') && basename.endsWith('.yml')) {
+                checkCiWorkflow(content, filePath, expectedMajor, violations);
+            }
+        }
+        return violations;
+    },
+});
+//# sourceMappingURL=node-version-consistency.js.map

package/dist/checks/architecture/node-version-consistency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-version-consistency.js","sourceRoot":"","sources":["../../../src/checks/architecture/node-version-consistency.ts"],"names":[],"mappings":"AAAA,4GAA4G;AAC5G,2MAA2M;AAC3M;;;;;;;;GAQG;AAEH,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC,OAAO,EAAE,WAAW,EAA0C,MAAM,sBAAsB,CAAC;AAsB3F,gFAAgF;AAChF,iBAAiB;AACjB,gFAAgF;AAEhF,+EAA+E;AAC/E,MAAM,kBAAkB,GAAG,OAAO,CAAC;AAEnC,qDAAqD;AACrD,MAAM,gBAAgB,GAAG,SAAS,CAAC;AAEnC,6CAA6C;AAC7C,MAAM,eAAe,GAAG,iCAAiC,CAAC;AAE1D,gFAAgF;AAChF,UAAU;AACV,gFAAgF;AAEhF;;;GAGG;AACH,SAAS,gBAAgB,CAAC,UAAkB;IAC1C,MAAM,KAAK,GAAG,kBAAkB,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAClD,6FAA6F;IAC7F,MAAM,KAAK,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC;IACzB,uGAAuG;IACvG,OAAO,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACnD,CAAC;AAED,gFAAgF;AAChF,4BAA4B;AAC5B,gFAAgF;AAEhF,SAAS,UAAU,CACjB,OAAe,EACf,QAAgB,EAChB,aAAqB,EACrB,UAA4B;IAE5B,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;IAC/B,MAAM,UAAU,GAAG,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IAChD,6EAA6E;IAC7E,IAAI,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC;QAAE,OAAO;IAErC,IAAI,UAAU,KAAK,aAAa,EAAE,CAAC;QACjC,UAAU,CAAC,IAAI,CAAC;YACd,IAAI,EAAE,CAAC;YACP,QAAQ;YACR,OAAO,EAAE,yBAAyB,UAAU,gDAAgD,aAAa,EAAE;YAC3G,QAAQ,EAAE,OAAO;YACjB,UAAU,EAAE,uBAAuB,OAAO,SAAS,aAAa,GAAG;YACnE,IAAI,EAAE,wBAAwB;SAC/B,CAAC,CAAC;IACL,CAAC;AACH,CAAC;AAED,SAAS,qBAAqB,CAC5B,OAAe,EACf,QAAgB,EAChB,aAAqB,EACrB,cAAsB,EACtB,UAA4B;IAE5B,IAAI,GAAyB,CAAC;IAC9B,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAyB,CAAC;IACpD,CAAC;IAAC,MAAM,CAAC;QACP,6FAA6F;QAC7F,oEAAoE;QACpE,OAAO;IACT,CAAC;IAED,MAAM,WAAW,GAAG,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC;IACtC,IAAI,CAAC,WAAW;QAAE,OAAO;IAEzB,MAAM,cAAc,GAAG,gBAAgB,CAAC,WAAW,CAAC,CAAC;IACrD,sFAAsF;IACtF,IAAI,cAAc,KAAK,IAAI;QAAE,OAAO;IAEpC,IAAI,cAAc,KAAK,aAAa,EAAE,CAAC;QACrC,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,QAAQ,CAAC,CAAC;QACvD,UAAU,CAAC,IAAI,CAAC;YACd,IAAI,EAAE,CAAC;YACP,QAAQ;YACR,OAAO,EAAE,GAAG,OAAO,qBAAqB,WAAW,gCAAgC,cAAc,GAAG;YACpG,QAAQ,EAAE,OAAO;YACjB,UAAU,EAAE,6BAA6B,WAAW,SAAS,cAAc,GAAG;YAC9E,IAAI,EAAE,4BAA4B;SACnC,CAAC,CAAC;IACL,CAAC;AACH,CAAC;AAED,SAAS,cAAc,CACrB,OAAe,EACf,QAAgB,EAChB,aAAqB,EACrB,UAA4B;IAE5B,IAAI,GAAyB,CAAC;IAC9B,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAyB,CAAC;IACpD,CAAC;IAAC,MAAM,CAAC;QACP,6FAA6F;QAC7F,oEAAoE;QACpE,OAAO;IACT,CAAC;IAED,yFAAyF;IACzF,MAAM,gBAAgB,GACpB,GAAG,CAAC,eAAe,EAAE,CAAC,aAAa,CAAC,IAAI,GAAG,CAAC,YAAY,EAAE,CAAC,aAAa,CAAC,CAAC;IAC5E,IAAI,CAAC,gBAAgB;QAAE,OAAO;IAE9B,MAAM,KAAK,GAAG,gBAAgB,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;IACtD,4FAA4F;IAC5F,MAAM,UAAU,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC;IAC9B,IAAI,CAAC,UAAU;QAAE,OAAO;IAExB,0FAA0F;IAC1F,MAAM,aAAa,GAAG,MAAM,CAAC,QAAQ,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;IACtD,IAAI,aAAa,KAAK,aAAa,EAAE,CAAC;QACpC,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,QAAQ,CAAC,CAAC;QACvD,UAAU,CAAC,IAAI,CAAC;YACd,IAAI,EAAE,CAAC;YACP,QAAQ;YACR,OAAO,EAAE,GAAG,OAAO,qBAAqB,gBAAgB,+BAA+B,aAAa,EAAE;YACtG,QAAQ,EAAE,OAAO;YACjB,UAAU,EAAE,4BAA4B,gBAAgB,UAAU,aAAa,OAAO;YACtF,IAAI,EAAE,qBAAqB;SAC5B,CAAC,CAAC;IACL,CAAC;AACH,CAAC;AAED,SAAS,eAAe,CACtB,OAAe,EACf,QAAgB,EAChB,aAAqB,EACrB,UAA4B;IAE5B,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAClC,KAAK,MAAM,CAAC,CAAC,EAAE,OAAO,CAAC,IAAI,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC;QAC3C,yEAAyE;QACzE,IAAI,CAAC,OAAO;YAAE,SAAS;QACvB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;QAE5B,MAAM,KAAK,GAAG,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACzC,6FAA6F;QAC7F,MAAM,SAAS,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC;QAC7B,IAAI,CAAC,SAAS;YAAE,SAAS;QAEzB,2FAA2F;QAC3F,MAAM,OAAO,GAAG,MAAM,CAAC,QAAQ,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;QAC/C,IAAI,OAAO,KAAK,aAAa,EAAE,CAAC;YAC9B,UAAU,CAAC,IAAI,CAAC;gBACd,IAAI,EAAE,CAAC,GAAG,CAAC;gBACX,QAAQ;gBACR,OAAO,EAAE,mCAAmC,SAAS,iDAAiD,aAAa,EAAE;gBACrH,QAAQ,EAAE,OAAO;gBACjB,UAAU,EAAE,6BAA6B,SAAS,SAAS,aAAa,GAAG;gBAC3E,IAAI,EAAE,0BAA0B;aACjC,CAAC,CAAC;QACL,CAAC;IACH,CAAC;AACH,CAAC;AAED,gFAAgF;AAChF,mBAAmB;AACnB,gFAAgF;AAEhF;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,WAAW,CAAC;IAChD,EAAE,EAAE,sCAAsC;IAC1C,IAAI,EAAE,0BAA0B;IAChC,KAAK,EAAE,EAAE,SAAS,EAAE,CAAC,MAAM,EAAE,YAAY,EAAE,MAAM,CAAC,EAAE,QAAQ,EAAE,CAAC,QAAQ,CAAC,EAAE;IAC1E,aAAa,EAAE,KAAK;IAEpB,UAAU,EAAE,QAAQ;IACpB,WAAW,EAAE,qDAAqD;IAClE,eAAe,EAAE;;;;;;;;;;8JAU2I;IAC5J,IAAI,EAAE,CAAC,MAAM,EAAE,cAAc,EAAE,cAAc,CAAC;IAE9C,KAAK,CAAC,UAAU,CAAC,KAAmB;QAClC,MAAM,UAAU,GAAqB,EAAE,CAAC;QAExC,wDAAwD;QACxD,sEAAsE;QACtE,MAAM,gBAAgB,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,cAAc,CAAC,CAAC;QACxF,IAAI,gBAAgB,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,UAAU,CAAC;QAErD,MAAM,WAAW,GAAG,gBAAgB,CAAC,MAAM,CACzC,CAAC,QAAQ,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;QAC5D,wEAAwE;QACxE,gBAAgB,CAAC,CAAC,CAAC,CACpB,CAAC;QACF,2CAA2C;QAC3C,MAAM,WAAW,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QAClD,IAAI,OAAwB,CAAC;QAC7B,IAAI,CAAC;YACH,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,WAAW,CAAoB,CAAC;QACvD,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,UAAU,CAAC;QACpB,CAAC;QACD,MAAM,cAAc,GAAG,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC;QAC7C,IAAI,CAAC,cAAc;YAAE,OAAO,UAAU,CAAC;QAEvC,MAAM,aAAa,GAAG,gBAAgB,CAAC,cAAc,CAAC,CAAC;QACvD,4FAA4F;QAC5F,IAAI,aAAa,KAAK,IAAI;YAAE,OAAO,UAAU,CAAC;QAE9C,KAAK,MAAM,QAAQ,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;YACnC,yHAAyH;YACzH,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YAC3C,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;YAEzC,IAAI,QAAQ,KAAK,QAAQ,EAAE,CAAC;gBAC1B,UAAU,CAAC,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,UAAU,CAAC,CAAC;YAC3D,CAAC;iBAAM,IAAI,QAAQ,KAAK,cAAc,EAAE,CAAC;gBACvC,oDAAoD;gBACpD,IAAI,QAAQ,KAAK,WAAW;oBAAE,SAAS;gBAEvC,qBAAqB,CAAC,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,cAAc,EAAE,UAAU,CAAC,CAAC;gBACpF,cAAc,CAAC,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,UAAU,CAAC,CAAC;YAC/D,CAAC;iBAAM,IAAI,QAAQ,CAAC,QAAQ,CAAC,oBAAoB,CAAC,IAAI,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;gBAChF,eAAe,CAAC,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,UAAU,CAAC,CAAC;YAChE,CAAC;QACH,CAAC;QAED,OAAO,UAAU,CAAC;IACpB,CAAC;CACF,CAAC,CAAC"}

package/dist/checks/architecture/project-readme-existence.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @fileoverview Project README existence check
+ *
+ * Ensures every package, app, CLI, and service has a README.md file.
+ */
+/**
+ * Check: architecture/project-readme-existence
+ *
+ * Ensures every package, app, CLI tool, and service has a README.md file
+ * for documentation and discoverability.
+ */
+export declare const projectReadmeExistence: import("@opensip-cli/fitness").Check;
+//# sourceMappingURL=project-readme-existence.d.ts.map

package/dist/checks/architecture/project-readme-existence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-readme-existence.d.ts","sourceRoot":"","sources":["../../../src/checks/architecture/project-readme-existence.ts"],"names":[],"mappings":"AACA;;;;GAIG;AAOH;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,sCA6CjC,CAAC"}

package/dist/checks/architecture/project-readme-existence.js

@@ -0,0 +1,55 @@
+// @fitness-ignore-file fitness-check-standards -- Uses fs for README existence checking, not source file content
+/**
+ * @fileoverview Project README existence check
+ *
+ * Ensures every package, app, CLI, and service has a README.md file.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { defineCheck } from '@opensip-cli/fitness';
+/**
+ * Check: architecture/project-readme-existence
+ *
+ * Ensures every package, app, CLI tool, and service has a README.md file
+ * for documentation and discoverability.
+ */
+export const projectReadmeExistence = defineCheck({
+    id: 'b7c3a2c2-0448-405f-86e3-8b5fca987bc7',
+    slug: 'project-readme-existence',
+    scope: { languages: ['typescript'], concerns: ['backend', 'frontend', 'cli'] },
+    confidence: 'medium',
+    description: 'Ensures every package has a README.md file',
+    longDescription: `**Purpose:** Ensures every package, app, CLI tool, and service has a README.md file for documentation and discoverability.
+
+**Detects:**
+- Missing \`README.md\` files in package directories
+- Checks sibling directory of each \`package.json\`
+- Skips the monorepo root \`package.json\` (via target patterns)
+
+**Why it matters:** README files are essential for onboarding, discoverability, and maintaining documentation standards across the monorepo. Without them, developers must read source code to understand package purpose and usage.
+
+**Scope:** Cross-file analysis via \`analyzeAll\`. Codebase-specific convention.`,
+    tags: ['architecture', 'documentation'],
+    // @fitness-ignore-next-line concurrency-safety -- async keyword required by analyzeAll interface contract; synchronous analysis implementation
+    // eslint-disable-next-line @typescript-eslint/require-await -- AnalyzeAllCheckConfig requires Promise<CheckViolation[]>; this implementation is synchronous
+    async analyzeAll(files) {
+        const violations = [];
+        // Only check directories that contain a package.json (actual packages)
+        const packageJsonPaths = files.paths.filter((fp) => path.basename(fp) === 'package.json');
+        for (const packageJsonPath of packageJsonPaths) {
+            const dirPath = path.dirname(packageJsonPath);
+            const readmePath = path.join(dirPath, 'README.md');
+            if (!fs.existsSync(readmePath)) {
+                violations.push({
+                    filePath: packageJsonPath,
+                    line: 1,
+                    message: `Missing README.md in ${path.basename(dirPath)}`,
+                    severity: 'warning',
+                    suggestion: 'Create a README.md file with package description, usage, and API documentation',
+                });
+            }
+        }
+        return violations;
+    },
+});
+//# sourceMappingURL=project-readme-existence.js.map

package/dist/checks/architecture/project-readme-existence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-readme-existence.js","sourceRoot":"","sources":["../../../src/checks/architecture/project-readme-existence.ts"],"names":[],"mappings":"AAAA,iHAAiH;AACjH;;;;GAIG;AAEH,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC,OAAO,EAAE,WAAW,EAA0C,MAAM,sBAAsB,CAAC;AAE3F;;;;;GAKG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,WAAW,CAAC;IAChD,EAAE,EAAE,sCAAsC;IAC1C,IAAI,EAAE,0BAA0B;IAChC,KAAK,EAAE,EAAE,SAAS,EAAE,CAAC,YAAY,CAAC,EAAE,QAAQ,EAAE,CAAC,SAAS,EAAE,UAAU,EAAE,KAAK,CAAC,EAAE;IAE9E,UAAU,EAAE,QAAQ;IACpB,WAAW,EAAE,4CAA4C;IACzD,eAAe,EAAE;;;;;;;;;iFAS8D;IAC/E,IAAI,EAAE,CAAC,cAAc,EAAE,eAAe,CAAC;IAEvC,+IAA+I;IAC/I,4JAA4J;IAC5J,KAAK,CAAC,UAAU,CAAC,KAAmB;QAClC,MAAM,UAAU,GAAqB,EAAE,CAAC;QAExC,uEAAuE;QACvE,MAAM,gBAAgB,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,KAAK,cAAc,CAAC,CAAC;QAE1F,KAAK,MAAM,eAAe,IAAI,gBAAgB,EAAE,CAAC;YAC/C,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC;YAC9C,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;YAEnD,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;gBAC/B,UAAU,CAAC,IAAI,CAAC;oBACd,QAAQ,EAAE,eAAe;oBACzB,IAAI,EAAE,CAAC;oBACP,OAAO,EAAE,wBAAwB,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE;oBACzD,QAAQ,EAAE,SAAS;oBACnB,UAAU,EACR,gFAAgF;iBACnF,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAED,OAAO,UAAU,CAAC;IACpB,CAAC;CACF,CAAC,CAAC"}

package/dist/checks/architecture/stale-build-artifacts.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @fileoverview Stale build artifact detection
+ * @module checks-builtin/checks/architecture/stale-build-artifacts
+ *
+ * Detects .js, .d.ts, and .js.map files in source directories that should
+ * only exist in dist/. These cause confusing import resolution bugs where
+ * the compiled artifact shadows the source file.
+ */
+export declare const staleBuildArtifacts: import("@opensip-cli/fitness").Check;
+//# sourceMappingURL=stale-build-artifacts.d.ts.map

package/dist/checks/architecture/stale-build-artifacts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stale-build-artifacts.d.ts","sourceRoot":"","sources":["../../../src/checks/architecture/stale-build-artifacts.ts"],"names":[],"mappings":"AACA;;;;;;;GAOG;AA0BH,eAAO,MAAM,mBAAmB,sCA6B9B,CAAC"}