@opensip-cli/checks-universal 0.1.0

package/dist/checks/architecture/docker-version-sync.js

@@ -0,0 +1,193 @@
+// @fitness-ignore-file fitness-check-standards -- Uses fs for package.json reading, not source file content
+// @fitness-ignore-file duplicate-implementation-detection -- similar patterns across diagnostic modules
+/**
+ * @fileoverview Docker version sync fitness check
+ * @invariants
+ * - Node major version in FROM directives must match engines.node from root package.json
+ * - pnpm version should be derived dynamically from package.json packageManager field
+ * - Hardcoded pnpm versions that don't match packageManager are errors
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { defineCheck } from '@opensip-cli/fitness';
+// =============================================================================
+// REGEX PATTERNS
+// =============================================================================
+/** Matches FROM node:XX or FROM node:XX-alpine etc. */
+const FROM_NODE_PATTERN = /^FROM\s+node:(\d+)/i;
+/** Matches corepack prepare pnpm@X.Y.Z or pnpm@X */
+const PNPM_HARDCODED_PATTERN = /corepack\s+prepare\s+pnpm@([\d.]+)/;
+/** Matches the dynamic self-read pattern */
+const PNPM_DYNAMIC_PATTERN = /require\(['"]\.\/package\.json['"]\)\.packageManager/;
+// =============================================================================
+// HELPERS
+// =============================================================================
+/**
+ * Read and parse root package.json.
+ * @throws {Error} When the file exceeds 10MB
+ */
+function readRootPackageJson(cwd) {
+    const pkgPath = path.join(cwd, 'package.json');
+    const stats = fs.statSync(pkgPath);
+    if (stats.size > 10_000_000)
+        throw new Error(`File too large: ${pkgPath}`);
+    const raw = fs.readFileSync(pkgPath, 'utf8');
+    return JSON.parse(raw);
+}
+/**
+ * Extract major Node version from engines.node constraint.
+ * e.g. ">=20.0.0" → 20
+ */
+function extractNodeMajor(constraint) {
+    const match = /(\d+)/.exec(constraint);
+    const digit = match?.[1];
+    // @fitness-ignore-next-line numeric-validation -- regex (\d+) guarantees digit-only string
+    return digit ? Number.parseInt(digit, 10) : null;
+}
+/**
+ * Extract pnpm version from packageManager field.
+ * e.g. "pnpm@10.28.2+sha512.abc..." → "10.28.2"
+ */
+function extractPnpmVersion(packageManager) {
+    const match = /^pnpm@([\d.]+)/.exec(packageManager);
+    /* v8 ignore next -- defensive: regex ([\d.]+) capture is guaranteed when match succeeds */
+    return match?.[1] ?? null;
+}
+/**
+ * Extract major version from a version string.
+ * e.g. "10.28.2" → 10
+ */
+function extractMajor(version) {
+    /* v8 ignore next -- defensive: split always returns at least one element */
+    const major = version.split('.')[0] ?? '0';
+    const parsed = Number.parseInt(major, 10);
+    /* v8 ignore next -- defensive: parseInt on digit-only string is always finite */
+    return Number.isFinite(parsed) ? parsed : 0;
+}
+function checkNodeVersion(line, lineNum, expectedNodeMajor, ctx) {
+    const { filePath, violations } = ctx;
+    const nodeMatch = FROM_NODE_PATTERN.exec(line);
+    const nodeVersion = nodeMatch?.[1];
+    if (!nodeVersion)
+        return;
+    // @fitness-ignore-next-line numeric-validation -- regex (\d+) guarantees digit-only string
+    const dockerNodeMajor = Number.parseInt(nodeVersion, 10);
+    if (dockerNodeMajor !== expectedNodeMajor) {
+        violations.push({
+            line: lineNum,
+            filePath,
+            message: `Node major version mismatch: Dockerfile uses node:${dockerNodeMajor} but package.json engines.node requires ${expectedNodeMajor}`,
+            severity: 'error',
+            suggestion: `Change FROM node:${dockerNodeMajor} to FROM node:${expectedNodeMajor}`,
+            type: 'node-version-mismatch',
+        });
+    }
+}
+function checkPnpmVersion(line, lineNum, expectedPnpmVersion, ctx) {
+    const { filePath, relPath, violations } = ctx;
+    const hardcodedMatch = PNPM_HARDCODED_PATTERN.exec(line);
+    const hardcodedVersion = hardcodedMatch?.[1];
+    if (!hardcodedVersion)
+        return false;
+    if (PNPM_DYNAMIC_PATTERN.test(line)) {
+        // Dynamic pattern is used — this is the preferred approach, no violation
+        return true;
+    }
+    const hardcodedMajor = extractMajor(hardcodedVersion);
+    const expectedMajor = extractMajor(expectedPnpmVersion);
+    const isVersionMismatch = hardcodedMajor !== expectedMajor || hardcodedVersion !== expectedPnpmVersion;
+    if (isVersionMismatch) {
+        violations.push({
+            line: lineNum,
+            filePath,
+            message: `pnpm version mismatch: Dockerfile uses pnpm@${hardcodedVersion} but package.json declares pnpm@${expectedPnpmVersion}`,
+            severity: 'error',
+            suggestion: `Use dynamic version extraction: corepack prepare $(node -e "process.stdout.write(require('./package.json').packageManager.split('+')[0])") --activate`,
+            type: 'pnpm-version-mismatch',
+        });
+    }
+    else {
+        // Version matches but is hardcoded — warn to use dynamic pattern
+        violations.push({
+            line: lineNum,
+            filePath,
+            message: `Hardcoded pnpm version pnpm@${hardcodedVersion} in ${relPath} — prefer dynamic extraction from package.json`,
+            severity: 'warning',
+            suggestion: `Use dynamic version extraction: corepack prepare $(node -e "process.stdout.write(require('./package.json').packageManager.split('+')[0])") --activate`,
+            type: 'pnpm-hardcoded-version',
+        });
+    }
+    return false;
+}
+function analyzeDockerfileLines(lines, expectedNodeMajor, expectedPnpmVersion, ctx) {
+    for (const [i, rawLine] of lines.entries()) {
+        if (!rawLine)
+            continue;
+        const line = rawLine.trim();
+        const lineNum = i + 1;
+        if (expectedNodeMajor !== null) {
+            checkNodeVersion(line, lineNum, expectedNodeMajor, ctx);
+        }
+        if (expectedPnpmVersion !== null) {
+            const shouldSkipLine = checkPnpmVersion(line, lineNum, expectedPnpmVersion, ctx);
+            if (shouldSkipLine)
+                continue;
+        }
+    }
+}
+// =============================================================================
+// CHECK DEFINITION
+// =============================================================================
+/**
+ * Check: architecture/docker-version-sync
+ *
+ * Validates that Dockerfiles keep Node and pnpm versions in sync with package.json:
+ * 1. FROM node:XX major version matches engines.node
+ * 2. pnpm version is either dynamically derived (preferred) or hardcoded consistently
+ */
+export const dockerVersionSync = defineCheck({
+    id: '15680f1a-134d-4247-b4c2-ca6c6ed9c43d',
+    slug: 'docker-version-sync',
+    disabled: true,
+    scope: { languages: ['json', 'typescript', 'yaml'], concerns: ['config'] },
+    contentFilter: 'raw',
+    confidence: 'medium',
+    description: 'Validate Docker Node/pnpm versions match package.json',
+    longDescription: `**Purpose:** Ensures Dockerfiles keep Node.js and pnpm versions synchronized with the root \`package.json\` to prevent version drift.
+
+**Detects:**
+- \`FROM node:XX\` major version mismatches against \`engines.node\` in root \`package.json\`
+- Hardcoded \`corepack prepare pnpm@X.Y.Z\` that differs from \`packageManager\` field
+- Hardcoded pnpm versions even when matching (prefers dynamic extraction via \`require('./package.json').packageManager\`)
+
+**Why it matters:** Version mismatches between Dockerfiles and package.json cause inconsistent runtime behavior and hard-to-diagnose production bugs.
+
+**Scope:** Codebase-specific convention. Cross-file analysis via \`analyzeAll\`.`,
+    tags: ['docker', 'version-sync', 'architecture'],
+    async analyzeAll(files) {
+        const violations = [];
+        // Read root package.json for version truth
+        const rootPkg = readRootPackageJson(process.cwd());
+        const expectedNodeMajor = rootPkg.engines?.node ? extractNodeMajor(rootPkg.engines.node) : null;
+        const expectedPnpmVersion = rootPkg.packageManager
+            ? extractPnpmVersion(rootPkg.packageManager)
+            : null;
+        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 lines = content.split('\n');
+            const relPath = path.relative(process.cwd(), filePath);
+            // Skip non-Node Dockerfiles (e.g. Hasura)
+            const hasNodeFrom = lines.some((line) => FROM_NODE_PATTERN.test(line.trim()));
+            if (!hasNodeFrom)
+                continue;
+            void analyzeDockerfileLines(lines, expectedNodeMajor, expectedPnpmVersion, {
+                filePath,
+                relPath,
+                violations,
+            });
+        }
+        return violations;
+    },
+});
+//# sourceMappingURL=docker-version-sync.js.map

package/dist/checks/architecture/docker-version-sync.js.map

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

package/dist/checks/architecture/env-var-validation.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @fileoverview Environment Variable Validation check
+ */
+/**
+ * Check: architecture/env-var-validation
+ *
+ * Detects environment variable access without validation:
+ * - process.env.X without null check
+ * - Missing default values
+ * - Type coercion issues
+ * - Direct access outside config modules
+ */
+export declare const envVarValidation: import("@opensip-cli/fitness").Check;
+//# sourceMappingURL=env-var-validation.d.ts.map

package/dist/checks/architecture/env-var-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-var-validation.d.ts","sourceRoot":"","sources":["../../../src/checks/architecture/env-var-validation.ts"],"names":[],"mappings":"AACA;;GAEG;AAwUH;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,sCA2C3B,CAAC"}

package/dist/checks/architecture/env-var-validation.js

@@ -0,0 +1,289 @@
+// @fitness-ignore-file semgrep-scan -- non-literal RegExp patterns use envVarName extracted from process.env.\w+ regex match on source code, not user input; regex operates on bounded, trusted codebase files
+/**
+ * @fileoverview Environment Variable Validation check
+ */
+import { createPathMatcher, defineCheck } from '@opensip-cli/fitness';
+// =============================================================================
+// PRE-COMPILED REGEX PATTERNS
+// =============================================================================
+// Excluded path patterns
+const TEST_FILE_PATTERN = /\.test\.[jt]s$/;
+const SPEC_FILE_PATTERN = /\.spec\.[jt]s$/;
+const TESTS_DIR_PATTERN = /__tests__\//;
+const BENCH_FILE_PATTERN = /\.bench\.[jt]s$/;
+const CONFIG_DIR_PATTERN = /config\//;
+const CONFIG_FILE_PATTERN = /\.config\.[jt]s$/;
+// Safe access patterns
+const NULLISH_COALESCING_PATTERN = /process\.env\.\w+\s*\?\?/;
+const LOGICAL_OR_PATTERN = /process\.env\.\w+\s*\|\|/;
+const NON_NULL_ASSERTION_PATTERN = /process\.env\.\w+\s*!\s*[,;)]/;
+const GET_ENV_PATTERN = /getEnv\s*\(/;
+const CONFIG_ACCESS_PATTERN = /config\.\w+/;
+// A validated env-object access (e.g. `env.PORT` from a typed config) is safe —
+// but NOT `process.env.X`, whose own text contains the substring `env.X`. The
+// negative lookbehind stops this pattern from matching the access it's meant to
+// flag (which otherwise made every process.env access "safe" — the check never
+// fired).
+const ENV_ACCESS_PATTERN = /(?<!process\.)\benv\.\w+/;
+const REQUIRE_ENV_PATTERN = /requireEnv\s*\(/;
+const OPTIONAL_ENV_PATTERN = /optionalEnv\s*\(/;
+// Boolean coercion is a safe read: `!!process.env.X` / `Boolean(process.env.X)`
+// can never be `undefined`.
+const BOOLEAN_COERCION_PATTERN = /(?:!!|Boolean\s*\(\s*)process\.env\.\w+/;
+// A comparison is null-safe: `process.env.X === '1'` / `!== ...` evaluates to a
+// boolean regardless of whether the var is set.
+const COMPARISON_PATTERN = /process\.env\.\w+\s*[=!]==?|[=!]==?\s*process\.env\.\w+/;
+// A truthy guard reads the var defensively: `if (process.env.X)` / `if (!process.env.X)`.
+// `(?:!\s*)?` keeps the optional negation unambiguous (no adjacent `\s*` runs).
+const IF_GUARD_PATTERN = /\bif\s*\(\s*(?:!\s*)?process\.env\.\w+/;
+// Captures the variable an env read is assigned to, so a guard on that variable
+// (possibly on a following line) can be recognised as safe. The gap is bounded
+// to a single statement (no `=`, no newline) to keep matching linear.
+// eslint-disable-next-line sonarjs/slow-regex -- gap class [^=\n] excludes the delimiters, so the lazy quantifier is single-pass over a bounded window of trusted source
+const ENV_CAPTURE_PATTERN = /(?:const|let|var)\s+(\w+)\s*=\s*[^=\n]*?process\.env\.\w+/;
+// Env var extraction pattern
+const ENV_VAR_PATTERN = /process\.env\.(\w+)/g;
+const NON_RUNTIME_PATTERNS = [
+    TEST_FILE_PATTERN,
+    SPEC_FILE_PATTERN,
+    TESTS_DIR_PATTERN,
+    BENCH_FILE_PATTERN,
+    CONFIG_DIR_PATTERN,
+    CONFIG_FILE_PATTERN,
+];
+const SAFE_PATTERNS = [
+    NULLISH_COALESCING_PATTERN,
+    LOGICAL_OR_PATTERN,
+    NON_NULL_ASSERTION_PATTERN,
+    GET_ENV_PATTERN,
+    CONFIG_ACCESS_PATTERN,
+    ENV_ACCESS_PATTERN,
+    REQUIRE_ENV_PATTERN,
+    OPTIONAL_ENV_PATTERN,
+    BOOLEAN_COERCION_PATTERN,
+    COMPARISON_PATTERN,
+    IF_GUARD_PATTERN,
+];
+// =============================================================================
+// HELPER FUNCTIONS
+// =============================================================================
+const isExcludedEnvPath = createPathMatcher(NON_RUNTIME_PATTERNS);
+/**
+ * A read captured into a variable is safe when that variable is guarded nearby,
+ * e.g. `const endpoint = process.env.X; if (!endpoint) return;`. Looks within the
+ * provided window (the access line plus a couple of following lines).
+ */
+function isCapturedAndGuarded(window) {
+    const capture = ENV_CAPTURE_PATTERN.exec(window);
+    const varName = capture?.[1];
+    if (!varName) {
+        return false;
+    }
+    // The captured name appears in an if-guard / return-guard, or alongside a
+    // null-ish / boolean / comparison operator.
+    const guard = new RegExp(String.raw `(?:\bif\s*\(|\breturn\b|[!(])[^\n]*\b${varName}\b|\b${varName}\b\s*(?:\?\??|\|\||&&|===|!==|==|!=)`);
+    return guard.test(window);
+}
+function isSafeContext(context) {
+    return SAFE_PATTERNS.some((p) => p.test(context)) || isCapturedAndGuarded(context);
+}
+function hasNullCheck(context) {
+    return context.includes('??') || context.includes('||') || context.includes('?');
+}
+function getMatchContext(line, matchIndex, matchLength) {
+    const start = Math.max(0, matchIndex - 20);
+    const end = Math.min(line.length, matchIndex + matchLength + 50);
+    return line.slice(start, end);
+}
+/**
+ * Check for type coercion issues using dynamic patterns
+ */
+function hasTypeCoercionIssue(context, envVarName) {
+    const numericOpPattern = new RegExp(String.raw `process\.env\.${envVarName}\s*[+\-*/<>]=?\s*\d`);
+    const reverseOpPattern = new RegExp(String.raw `\d\s*[+\-*/<>]=?\s*process\.env\.${envVarName}`);
+    const portPattern = `port`;
+    const timeoutPattern = `timeout`;
+    const envAccess = `process.env.${envVarName}`;
+    if (numericOpPattern.test(context) || reverseOpPattern.test(context)) {
+        return true;
+    }
+    // Check for port/timeout without parseInt
+    if ((context.toLowerCase().includes(portPattern) ||
+        context.toLowerCase().includes(timeoutPattern)) &&
+        context.includes(envAccess) &&
+        !context.includes('parseInt')) {
+        return true;
+    }
+    return false;
+}
+function analyzeMatch(line, match, window) {
+    const envVarName = match[1];
+    if (!envVarName) {
+        return null;
+    }
+    const matchIndex = match.index ?? 0;
+    const context = getMatchContext(line, matchIndex, match[0].length);
+    return { envVarName, context, window, matchIndex };
+}
+/* v8 ignore start -- switch over issue types; only some cases fire in test fixtures */
+function createIssue(filePath, lineNumber, type, envVarName) {
+    switch (type) {
+        case 'direct-access-outside-config': {
+            return {
+                file: filePath,
+                line: lineNumber,
+                type,
+                message: `Direct process.env.${envVarName} access outside config module`,
+                suggestion: 'Access environment variables through config module instead',
+                severity: 'warning',
+                envVarName,
+            };
+        }
+        case 'type-coercion': {
+            return {
+                file: filePath,
+                line: lineNumber,
+                type,
+                message: `process.env.${envVarName} used without type conversion`,
+                suggestion: 'Parse env var: parseInt(process.env.X, 10) or Boolean(process.env.X)',
+                severity: 'warning',
+                envVarName,
+            };
+        }
+        case 'unvalidated-access': {
+            return {
+                file: filePath,
+                line: lineNumber,
+                type,
+                message: `process.env.${envVarName} accessed without null check`,
+                suggestion: 'Add default: process.env.X ?? "default" or validate with requireEnv()',
+                severity: 'warning',
+                envVarName,
+            };
+        }
+        default: {
+            return {
+                file: filePath,
+                line: lineNumber,
+                type,
+                message: `Issue with process.env.${envVarName}`,
+                suggestion: 'Validate environment variable access',
+                severity: 'warning',
+                envVarName,
+            };
+        }
+    }
+}
+/* v8 ignore stop */
+function analyzeMatchForIssues(analysis, filePath, lineNumber, isConfigFile) {
+    const { envVarName, context, window } = analysis;
+    // Skip if in safe context (idiomatic guards may sit on a following line, so
+    // the safe-context test uses the multi-line window, not just the access line).
+    if (isSafeContext(window)) {
+        return null;
+    }
+    // Check for direct access outside config
+    if (!isConfigFile) {
+        return createIssue(filePath, lineNumber, 'direct-access-outside-config', envVarName);
+    }
+    // Check for type coercion issues
+    if (hasTypeCoercionIssue(context, envVarName)) {
+        return createIssue(filePath, lineNumber, 'type-coercion', envVarName);
+    }
+    // Check for missing null check
+    if (!hasNullCheck(window)) {
+        return createIssue(filePath, lineNumber, 'unvalidated-access', envVarName);
+    }
+    return null;
+}
+// How many following lines to include in the guard-detection window.
+const GUARD_WINDOW_LINES = 2;
+function processLine(lines, lineIndex, filePath, isConfigFile) {
+    const line = lines[lineIndex] ?? '';
+    const issues = [];
+    // Guard idioms (`if (!x) return`) may sit just below the access; include a
+    // small forward window so capture-then-guard reads are recognised as safe.
+    const window = lines.slice(lineIndex, lineIndex + 1 + GUARD_WINDOW_LINES).join('\n');
+    // Reset regex lastIndex for global patterns
+    ENV_VAR_PATTERN.lastIndex = 0;
+    const matches = line.matchAll(ENV_VAR_PATTERN);
+    for (const match of matches) {
+        const analysis = analyzeMatch(line, match, window);
+        if (!analysis) {
+            continue;
+        }
+        const issue = analyzeMatchForIssues(analysis, filePath, lineIndex + 1, isConfigFile);
+        if (issue) {
+            issues.push(issue);
+        }
+    }
+    return issues;
+}
+function analyzeFile(filePath, content) {
+    if (isExcludedEnvPath(filePath)) {
+        return [];
+    }
+    const lines = content.split('\n');
+    const isConfigFile = filePath.includes('config');
+    const issues = [];
+    for (let i = 0; i < lines.length; i++) {
+        if (!lines[i]) {
+            continue;
+        }
+        issues.push(...processLine(lines, i, filePath, isConfigFile));
+    }
+    return issues;
+}
+// =============================================================================
+// CHECK DEFINITION
+// =============================================================================
+/**
+ * Check: architecture/env-var-validation
+ *
+ * Detects environment variable access without validation:
+ * - process.env.X without null check
+ * - Missing default values
+ * - Type coercion issues
+ * - Direct access outside config modules
+ */
+export const envVarValidation = defineCheck({
+    id: '47d3e7c7-7dc0-4fd7-bcd6-950837e091df',
+    slug: 'env-var-validation',
+    scope: { languages: ['typescript'], concerns: ['backend', 'server'] },
+    // Strip strings/comments so `process.env.X` appearing inside a string literal,
+    // template literal, or comment (e.g. a detection pattern or doc example in
+    // analyzer source) is not mistaken for a real env access — only live code is
+    // scanned. Real `process.env.X` member access is code and is preserved.
+    contentFilter: 'strip-strings-and-comments',
+    confidence: 'medium',
+    description: 'Detects environment variable access without proper validation',
+    longDescription: `**Purpose:** Enforces safe environment variable access by detecting unvalidated \`process.env\` usage outside config modules.
+
+**Detects:**
+- \`process.env.X\` access without null check (\`??\`, \`||\`, or \`?\`)
+- \`process.env.X\` used in numeric operations without \`parseInt()\` (type coercion)
+- Direct \`process.env.X\` access outside config modules (should use \`getEnv()\`, \`requireEnv()\`, or config objects)
+- Recognizes safe patterns: \`??\`, \`||\`, \`getEnv()\`, \`requireEnv()\`, \`optionalEnv()\`, \`config.*\`
+
+**Why it matters:** Unvalidated env var access causes silent \`undefined\` values and type coercion bugs that surface only at runtime.
+
+**Scope:** General best practice. Analyzes each file individually.`,
+    tags: ['architecture', 'best-practices'],
+    fileTypes: ['ts'],
+    analyze(content, filePath) {
+        // Skip files without process.env
+        if (!content.includes('process.env')) {
+            return [];
+        }
+        const issues = analyzeFile(filePath, content);
+        return issues.map((issue) => ({
+            line: issue.line,
+            message: `${issue.message}. ${issue.suggestion}`,
+            severity: issue.severity,
+            suggestion: issue.suggestion,
+            match: `process.env.${issue.envVarName ?? ''}`,
+            type: issue.type,
+        }));
+    },
+});
+//# sourceMappingURL=env-var-validation.js.map

package/dist/checks/architecture/env-var-validation.js.map

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

package/dist/checks/architecture/heavy-import-detection.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @fileoverview Heavy import detection
+ * @module checks-builtin/checks/architecture/heavy-import-detection
+ *
+ * Detects imports that unnecessarily bloat bundle size:
+ * - Full/namespace imports of tree-shakeable libraries (import * as _ from 'lodash')
+ * - Deprecated library usage (moment -> date-fns/dayjs, aws-sdk v2 -> v3)
+ * - Excessive named imports from a single module (>15 items)
+ */
+export declare const heavyImportDetection: import("@opensip-cli/fitness").Check;
+//# sourceMappingURL=heavy-import-detection.d.ts.map

package/dist/checks/architecture/heavy-import-detection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heavy-import-detection.d.ts","sourceRoot":"","sources":["../../../src/checks/architecture/heavy-import-detection.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAyCH,eAAO,MAAM,oBAAoB,sCA2D/B,CAAC"}

package/dist/checks/architecture/heavy-import-detection.js

@@ -0,0 +1,91 @@
+/**
+ * @fileoverview Heavy import detection
+ * @module checks-builtin/checks/architecture/heavy-import-detection
+ *
+ * Detects imports that unnecessarily bloat bundle size:
+ * - Full/namespace imports of tree-shakeable libraries (import * as _ from 'lodash')
+ * - Deprecated library usage (moment -> date-fns/dayjs, aws-sdk v2 -> v3)
+ * - Excessive named imports from a single module (>15 items)
+ */
+import { defineCheck } from '@opensip-cli/fitness';
+const HEAVY_LIBRARIES = [
+    {
+        pattern: /import\s+\*\s+as\s+\w+\s+from\s+['"]lodash['"]/,
+        message: 'Namespace import of lodash pulls in the entire library (~70KB)',
+        suggestion: "Use named imports: import { debounce } from 'lodash' or import debounce from 'lodash/debounce'",
+    },
+    {
+        pattern: /import\s+(?:\w+|\{[^}]+\})\s+from\s+['"]moment['"]/,
+        message: 'moment.js is deprecated and heavy (~300KB). Use date-fns or dayjs instead',
+        suggestion: "Replace with: import { format } from 'date-fns' or import dayjs from 'dayjs'",
+        deprecated: true,
+    },
+    {
+        pattern: /import\s+(?:\w+|\{[^}]+\})\s+from\s+['"]aws-sdk['"]/,
+        message: 'aws-sdk v2 is deprecated and heavy. Use modular v3 packages',
+        suggestion: "Replace with modular import: import { S3Client } from '@aws-sdk/client-s3'",
+        deprecated: true,
+    },
+    {
+        pattern: /import\s+\*\s+as\s+\w+\s+from\s+['"]rxjs['"]/,
+        message: 'Namespace import of rxjs pulls in the entire library. Use specific imports',
+        suggestion: "Use: import { Observable, map } from 'rxjs' or import { map } from 'rxjs/operators'",
+    },
+];
+const EXCESSIVE_NAMED_IMPORT_THRESHOLD = 15;
+const NAMED_IMPORT_PATTERN = /import\s+\{([^}]+)\}\s+from\s+['"]([^'"]+)['"]/;
+export const heavyImportDetection = defineCheck({
+    id: 'ebd495d1-ae48-478d-a1cc-4823a18cada6',
+    slug: 'heavy-import-detection',
+    scope: { languages: ['typescript', 'javascript'], concerns: ['backend', 'frontend'] },
+    confidence: 'high',
+    description: 'Detects heavy/deprecated library imports and excessive named imports that bloat bundle size',
+    tags: ['architecture', 'performance', 'bundle-size'],
+    fileTypes: ['ts', 'tsx', 'js', 'jsx'],
+    // eslint-disable-next-line sonarjs/cognitive-complexity -- bundler-aware heuristic: each branch detects a distinct heavy-import pattern (deprecated, namespace, deep-path, named-import-explosion)
+    analyze(content, filePath) {
+        if (filePath.includes('.test.') || filePath.includes('__tests__'))
+            return [];
+        const violations = [];
+        const lines = content.split('\n');
+        for (const [i, line] of lines.entries()) {
+            if (!line)
+                continue;
+            const trimmed = line.trim();
+            if (trimmed.startsWith('//') || trimmed.startsWith('*'))
+                continue;
+            // Check heavy library patterns
+            for (const lib of HEAVY_LIBRARIES) {
+                if (lib.pattern.test(line)) {
+                    violations.push({
+                        line: i + 1,
+                        message: lib.message,
+                        severity: lib.deprecated ? 'error' : 'warning',
+                        suggestion: lib.suggestion,
+                        type: lib.deprecated ? 'DEPRECATED_LIBRARY' : 'HEAVY_IMPORT',
+                        match: trimmed,
+                        filePath,
+                    });
+                }
+            }
+            // Check excessive named imports
+            const namedMatch = NAMED_IMPORT_PATTERN.exec(line);
+            if (namedMatch?.[1]) {
+                const names = namedMatch[1].split(',').filter((n) => n.trim().length > 0);
+                if (names.length > EXCESSIVE_NAMED_IMPORT_THRESHOLD) {
+                    violations.push({
+                        line: i + 1,
+                        message: `Excessive named imports: ${names.length} items from '${namedMatch[2]}'. Consider splitting into multiple import groups.`,
+                        severity: 'warning',
+                        suggestion: 'Split into multiple focused imports or evaluate if all imports are needed.',
+                        type: 'EXCESSIVE_NAMED_IMPORTS',
+                        match: `${names.length} imports from ${namedMatch[2]}`,
+                        filePath,
+                    });
+                }
+            }
+        }
+        return violations;
+    },
+});
+//# sourceMappingURL=heavy-import-detection.js.map

package/dist/checks/architecture/heavy-import-detection.js.map

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