@levironexe/architect 0.1.0

package/dist/utils/interactive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interactive.js","sourceRoot":"","sources":["../../src/utils/interactive.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAO1C,MAAM,UAAU,qBAAqB,CAAC,UAA8B,EAAE;IACpE,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,KAAK,CAAC;IAC7C,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC;IAEhD,OAAO,KAAK,CAAC,KAAK,KAAK,IAAI,IAAI,MAAM,CAAC,KAAK,KAAK,IAAI,CAAC;AACvD,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,OAAO,GAAG,oBAAoB;IACrE,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC;QACzB,OAAO;QACP,OAAO,EAAE,GAAG;QACZ,QAAQ,EAAE,IAAI;KACf,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC,IAAI,EAAE,CAAC;AACvB,CAAC"}

package/dist/utils/path.d.ts

@@ -0,0 +1,5 @@
+export declare function normalizeToAbsolutePath(targetPath: string, cwd?: string): string;
+export declare function ensureDirectoryPath(targetPath: string): string;
+export declare function isPathContained(rootPath: string, candidatePath: string): boolean;
+export declare function resolveContainedRealPath(rootPath: string, candidatePath: string): string | null;
+export declare function toRelativePath(rootPath: string, candidatePath: string): string;

package/dist/utils/path.js

@@ -0,0 +1,31 @@
+import { realpathSync, statSync } from 'node:fs';
+import path from 'node:path';
+export function normalizeToAbsolutePath(targetPath, cwd = process.cwd()) {
+    return path.resolve(cwd, targetPath);
+}
+export function ensureDirectoryPath(targetPath) {
+    const absolutePath = normalizeToAbsolutePath(targetPath);
+    const stats = statSync(absolutePath);
+    if (!stats.isDirectory()) {
+        throw new Error(`Target path is not a directory: ${absolutePath}`);
+    }
+    return absolutePath;
+}
+export function isPathContained(rootPath, candidatePath) {
+    const normalizedRoot = stripTrailingSeparator(path.resolve(rootPath));
+    const normalizedCandidate = stripTrailingSeparator(path.resolve(candidatePath));
+    const relativePath = path.relative(normalizedRoot, normalizedCandidate);
+    return relativePath === '' || (!relativePath.startsWith('..') && !path.isAbsolute(relativePath));
+}
+export function resolveContainedRealPath(rootPath, candidatePath) {
+    const realRootPath = stripTrailingSeparator(realpathSync(rootPath));
+    const realCandidatePath = stripTrailingSeparator(realpathSync(candidatePath));
+    return isPathContained(realRootPath, realCandidatePath) ? realCandidatePath : null;
+}
+export function toRelativePath(rootPath, candidatePath) {
+    return path.relative(stripTrailingSeparator(rootPath), stripTrailingSeparator(candidatePath)) || '.';
+}
+function stripTrailingSeparator(targetPath) {
+    return targetPath.endsWith(path.sep) ? targetPath.slice(0, -1) : targetPath;
+}
+//# sourceMappingURL=path.js.map

package/dist/utils/path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.js","sourceRoot":"","sources":["../../src/utils/path.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACjD,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,MAAM,UAAU,uBAAuB,CAAC,UAAkB,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,EAAE;IAC7E,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;AACvC,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,UAAkB;IACpD,MAAM,YAAY,GAAG,uBAAuB,CAAC,UAAU,CAAC,CAAC;IACzD,MAAM,KAAK,GAAG,QAAQ,CAAC,YAAY,CAAC,CAAC;IAErC,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CAAC,mCAAmC,YAAY,EAAE,CAAC,CAAC;IACrE,CAAC;IAED,OAAO,YAAY,CAAC;AACtB,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,QAAgB,EAAE,aAAqB;IACrE,MAAM,cAAc,GAAG,sBAAsB,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;IACtE,MAAM,mBAAmB,GAAG,sBAAsB,CAAC,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC;IAChF,MAAM,YAAY,GAAG,IAAI,CAAC,QAAQ,CAAC,cAAc,EAAE,mBAAmB,CAAC,CAAC;IAExE,OAAO,YAAY,KAAK,EAAE,IAAI,CAAC,CAAC,YAAY,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC,CAAC;AACnG,CAAC;AAED,MAAM,UAAU,wBAAwB,CAAC,QAAgB,EAAE,aAAqB;IAC9E,MAAM,YAAY,GAAG,sBAAsB,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC;IACpE,MAAM,iBAAiB,GAAG,sBAAsB,CAAC,YAAY,CAAC,aAAa,CAAC,CAAC,CAAC;IAE9E,OAAO,eAAe,CAAC,YAAY,EAAE,iBAAiB,CAAC,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,IAAI,CAAC;AACrF,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,QAAgB,EAAE,aAAqB;IACpE,OAAO,IAAI,CAAC,QAAQ,CAAC,sBAAsB,CAAC,QAAQ,CAAC,EAAE,sBAAsB,CAAC,aAAa,CAAC,CAAC,IAAI,GAAG,CAAC;AACvG,CAAC;AAED,SAAS,sBAAsB,CAAC,UAAkB;IAChD,OAAO,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC;AAC9E,CAAC"}

package/dist/utils/progress.d.ts

@@ -0,0 +1,17 @@
+import type { ScanDiagnostic } from '../types/scan-output.js';
+export declare const LARGE_SCAN_FILE_THRESHOLD = 1000;
+export declare const SCAN_PHASES: readonly ["discovery", "parsing", "dependency-analysis", "duplication-analysis", "classification", "scoring", "reporting"];
+export declare function shouldReportProgress(fileCount: number, verbose: boolean, threshold?: number): boolean;
+export interface ProgressRenderOptions {
+    json?: boolean;
+    verbose?: boolean;
+    isInteractive?: boolean;
+    stdoutIsTTY?: boolean;
+    stderrIsTTY?: boolean;
+    fileCount?: number;
+    threshold?: number;
+    force?: boolean;
+}
+export declare function shouldRenderHumanProgress(options: ProgressRenderOptions): boolean;
+export declare function createProgressDiagnostics(fileCount: number, verbose: boolean, threshold?: number): ScanDiagnostic[];
+export declare function createThresholdDiagnostics(locThreshold: number, complexityThreshold: number): ScanDiagnostic[];

package/dist/utils/progress.js

@@ -0,0 +1,48 @@
+export const LARGE_SCAN_FILE_THRESHOLD = 1000;
+export const SCAN_PHASES = [
+    'discovery',
+    'parsing',
+    'dependency-analysis',
+    'duplication-analysis',
+    'classification',
+    'scoring',
+    'reporting'
+];
+export function shouldReportProgress(fileCount, verbose, threshold = LARGE_SCAN_FILE_THRESHOLD) {
+    return verbose && fileCount >= threshold;
+}
+export function shouldRenderHumanProgress(options) {
+    if (options.force === true) {
+        return options.json !== true;
+    }
+    if (options.json === true || options.isInteractive !== true || options.stderrIsTTY !== true) {
+        return false;
+    }
+    return options.verbose === true || shouldReportProgress(options.fileCount ?? 0, true, options.threshold);
+}
+export function createProgressDiagnostics(fileCount, verbose, threshold = LARGE_SCAN_FILE_THRESHOLD) {
+    if (!shouldReportProgress(fileCount, verbose, threshold)) {
+        return [];
+    }
+    return SCAN_PHASES.map((phase) => ({
+        phase,
+        message: `Large scan progress milestone: ${phase}`,
+        details: {
+            fileCount,
+            threshold
+        }
+    }));
+}
+export function createThresholdDiagnostics(locThreshold, complexityThreshold) {
+    return [
+        {
+            phase: 'configuration',
+            message: 'Scan thresholds applied',
+            details: {
+                locThreshold,
+                complexityThreshold
+            }
+        }
+    ];
+}
+//# sourceMappingURL=progress.js.map

package/dist/utils/progress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress.js","sourceRoot":"","sources":["../../src/utils/progress.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,yBAAyB,GAAG,IAAI,CAAC;AAE9C,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,WAAW;IACX,SAAS;IACT,qBAAqB;IACrB,sBAAsB;IACtB,gBAAgB;IAChB,SAAS;IACT,WAAW;CACH,CAAC;AAEX,MAAM,UAAU,oBAAoB,CAAC,SAAiB,EAAE,OAAgB,EAAE,SAAS,GAAG,yBAAyB;IAC7G,OAAO,OAAO,IAAI,SAAS,IAAI,SAAS,CAAC;AAC3C,CAAC;AAaD,MAAM,UAAU,yBAAyB,CAAC,OAA8B;IACtE,IAAI,OAAO,CAAC,KAAK,KAAK,IAAI,EAAE,CAAC;QAC3B,OAAO,OAAO,CAAC,IAAI,KAAK,IAAI,CAAC;IAC/B,CAAC;IAED,IAAI,OAAO,CAAC,IAAI,KAAK,IAAI,IAAI,OAAO,CAAC,aAAa,KAAK,IAAI,IAAI,OAAO,CAAC,WAAW,KAAK,IAAI,EAAE,CAAC;QAC5F,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,OAAO,CAAC,OAAO,KAAK,IAAI,IAAI,oBAAoB,CAAC,OAAO,CAAC,SAAS,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;AAC3G,CAAC;AAED,MAAM,UAAU,yBAAyB,CAAC,SAAiB,EAAE,OAAgB,EAAE,SAAS,GAAG,yBAAyB;IAClH,IAAI,CAAC,oBAAoB,CAAC,SAAS,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,CAAC;QACzD,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,OAAO,WAAW,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QACjC,KAAK;QACL,OAAO,EAAE,kCAAkC,KAAK,EAAE;QAClD,OAAO,EAAE;YACP,SAAS;YACT,SAAS;SACV;KACF,CAAC,CAAC,CAAC;AACN,CAAC;AAED,MAAM,UAAU,0BAA0B,CAAC,YAAoB,EAAE,mBAA2B;IAC1F,OAAO;QACL;YACE,KAAK,EAAE,eAAe;YACtB,OAAO,EAAE,yBAAyB;YAClC,OAAO,EAAE;gBACP,YAAY;gBACZ,mBAAmB;aACpB;SACF;KACF,CAAC;AACJ,CAAC"}

package/dist/utils/thresholds.d.ts

@@ -0,0 +1,6 @@
+import type { ThresholdConfiguration } from '../types/scan-output.js';
+export declare const DEFAULT_SCAN_THRESHOLDS: ThresholdConfiguration;
+export declare class ThresholdParseError extends Error {
+    constructor(message: string);
+}
+export declare function parseThresholdOption(value: string | undefined): ThresholdConfiguration;

package/dist/utils/thresholds.js

@@ -0,0 +1,48 @@
+import { DEFAULT_COMPLEXITY_THRESHOLD, DEFAULT_LOC_THRESHOLD } from '../types/analysis.js';
+const THRESHOLD_KEYS = new Set(['loc', 'complexity']);
+export const DEFAULT_SCAN_THRESHOLDS = {
+    locThreshold: DEFAULT_LOC_THRESHOLD,
+    complexityThreshold: DEFAULT_COMPLEXITY_THRESHOLD,
+    source: 'default'
+};
+export class ThresholdParseError extends Error {
+    constructor(message) {
+        super(`${message} Example: --threshold loc=300,complexity=15`);
+        this.name = 'ThresholdParseError';
+    }
+}
+export function parseThresholdOption(value) {
+    if (!value || value.trim().length === 0) {
+        return DEFAULT_SCAN_THRESHOLDS;
+    }
+    const entries = value.split(',').map((entry) => entry.trim()).filter(Boolean);
+    if (entries.length === 0) {
+        throw new ThresholdParseError('Threshold value is empty.');
+    }
+    const thresholds = {
+        ...DEFAULT_SCAN_THRESHOLDS,
+        source: 'cli'
+    };
+    for (const entry of entries) {
+        const [rawKey, rawValue, extra] = entry.split('=');
+        if (!rawKey || rawValue === undefined || extra !== undefined) {
+            throw new ThresholdParseError(`Invalid threshold segment "${entry}".`);
+        }
+        const key = rawKey.trim().toLowerCase();
+        if (!THRESHOLD_KEYS.has(key)) {
+            throw new ThresholdParseError(`Unknown threshold key "${rawKey}". Supported keys: loc, complexity.`);
+        }
+        const parsed = Number(rawValue.trim());
+        if (!Number.isInteger(parsed) || parsed <= 0) {
+            throw new ThresholdParseError(`Threshold "${rawKey}" must be a positive integer.`);
+        }
+        if (key === 'loc') {
+            thresholds.locThreshold = parsed;
+        }
+        else {
+            thresholds.complexityThreshold = parsed;
+        }
+    }
+    return thresholds;
+}
+//# sourceMappingURL=thresholds.js.map

package/dist/utils/thresholds.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"thresholds.js","sourceRoot":"","sources":["../../src/utils/thresholds.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,4BAA4B,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAG3F,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC;AAEtD,MAAM,CAAC,MAAM,uBAAuB,GAA2B;IAC7D,YAAY,EAAE,qBAAqB;IACnC,mBAAmB,EAAE,4BAA4B;IACjD,MAAM,EAAE,SAAS;CAClB,CAAC;AAEF,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IAC5C,YAAY,OAAe;QACzB,KAAK,CAAC,GAAG,OAAO,6CAA6C,CAAC,CAAC;QAC/D,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACpC,CAAC;CACF;AAED,MAAM,UAAU,oBAAoB,CAAC,KAAyB;IAC5D,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxC,OAAO,uBAAuB,CAAC;IACjC,CAAC;IAED,MAAM,OAAO,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC9E,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,mBAAmB,CAAC,2BAA2B,CAAC,CAAC;IAC7D,CAAC;IAED,MAAM,UAAU,GAA2B;QACzC,GAAG,uBAAuB;QAC1B,MAAM,EAAE,KAAK;KACd,CAAC;IAEF,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACnD,IAAI,CAAC,MAAM,IAAI,QAAQ,KAAK,SAAS,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YAC7D,MAAM,IAAI,mBAAmB,CAAC,8BAA8B,KAAK,IAAI,CAAC,CAAC;QACzE,CAAC;QAED,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QACxC,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YAC7B,MAAM,IAAI,mBAAmB,CAAC,0BAA0B,MAAM,qCAAqC,CAAC,CAAC;QACvG,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;QACvC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,MAAM,IAAI,CAAC,EAAE,CAAC;YAC7C,MAAM,IAAI,mBAAmB,CAAC,cAAc,MAAM,+BAA+B,CAAC,CAAC;QACrF,CAAC;QAED,IAAI,GAAG,KAAK,KAAK,EAAE,CAAC;YAClB,UAAU,CAAC,YAAY,GAAG,MAAM,CAAC;QACnC,CAAC;aAAM,CAAC;YACN,UAAU,CAAC,mBAAmB,GAAG,MAAM,CAAC;QAC1C,CAAC;IACH,CAAC;IAED,OAAO,UAAU,CAAC;AACpB,CAAC"}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@levironexe/architect",
+  "version": "0.1.0",
+  "description": "Structural health scanner for vibe-coded JavaScript and TypeScript projects.",
+  "type": "module",
+  "bin": {
+    "architect": "dist/cli/index.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "templates",
+    "README.md",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/cli/index.ts",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "architecture",
+    "code-quality",
+    "refactoring",
+    "cli",
+    "vibe-coding",
+    "vibe-coded",
+    "typescript",
+    "static-analysis"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@babel/parser": "^7.28.5",
+    "@babel/traverse": "^7.28.5",
+    "@inquirer/prompts": "^8.4.2",
+    "chalk": "^5.6.2",
+    "cli-table3": "^0.6.5",
+    "commander": "^14.0.0",
+    "glob": "^11.0.3",
+    "ignore": "^7.0.5",
+    "js-yaml": "^4.1.1",
+    "jscpd": "^4.0.9",
+    "madge": "^8.0.0",
+    "ora": "^9.4.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.1",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^24.9.1",
+    "eslint": "^9.39.1",
+    "globals": "^16.4.0",
+    "tsx": "^4.20.6",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.46.2",
+    "vitest": "^4.0.7"
+  }
+}

package/skills/meta/general-js.skill.yaml

@@ -0,0 +1,131 @@
+schema_version: "2.0.0"
+id: general-js
+name: "General JavaScript/TypeScript"
+version: "1.1.0"
+description: "Language-level JavaScript and TypeScript hygiene for naming, imports, errors, and environment handling."
+category: meta
+language: javascript
+frameworks: []
+detection:
+  source_indicators:
+    - "import "
+    - "export "
+structure:
+  required_dirs: []
+  recommended_dirs:
+    - path: src
+      purpose: "All application source code. Every module the app ships is rooted here. Consumers import from src/ paths, not from the project root."
+    - path: tests
+      purpose: "All automated test files. Mirrors src/ directory structure with *.test.ts or *.spec.ts suffixes."
+separation:
+  rules:
+    - concern: configuration
+      belongs_in: src/config
+      rule_text: "Environment and runtime configuration must be centralized in src/config so the rest of the codebase consumes validated config values instead of raw process.env reads scattered across modules. Fail fast at startup when required variables are missing."
+      example: |
+        // src/config/index.ts
+        import { z } from 'zod';
+        const envSchema = z.object({
+          API_BASE_URL: z.string().url(),
+          PORT: z.coerce.number().default(3000),
+          DATABASE_URL: z.string().min(1),
+        });
+        export const config = envSchema.parse(process.env);
+      indicators:
+        - "process.env"
+    - concern: utility
+      belongs_in: src/utils
+      rule_text: "Generic helper functions with no domain or framework coupling belong in src/utils so they can be reused across all feature modules without creating circular dependencies. A utility must not import from domain or service modules."
+      example: |
+        // src/utils/array.ts
+        export function chunk<T>(items: T[], size: number): T[][] {
+          return items.reduce<T[][]>((groups, item, index) => {
+            const groupIndex = Math.floor(index / size);
+            groups[groupIndex] ??= [];
+            groups[groupIndex].push(item);
+            return groups;
+          }, []);
+        }
+      anti_indicators:
+        - "import.*services"
+        - "import.*controllers"
+        - "import.*repositories"
+    - concern: error_handler
+      belongs_in: src/errors
+      rule_text: "Custom error classes that extend the built-in Error must live in src/errors so all modules throw typed, structured errors instead of raw strings or plain objects. Typed errors enable central error middleware to map errors to correct HTTP status codes."
+      example: |
+        // src/errors/app-error.ts
+        export class AppError extends Error {
+          constructor(
+            message: string,
+            public readonly code: string,
+            public readonly statusCode = 500,
+            public readonly isOperational = true,
+          ) {
+            super(message);
+            this.name = 'AppError';
+          }
+        }
+      indicators:
+        - "extends Error"
+        - "new Error("
+patterns:
+  naming:
+    files: "Use kebab-case for all filenames (user-service.ts, auth-middleware.ts). Use *.test.ts or *.spec.ts suffixes for test files. Never use spaces or underscores in filenames."
+    variables: "Use lowerCamelCase for local variables and functions (userId, fetchUser). Use UpperCamelCase for classes and type aliases (UserService, ApiResponse). Use UPPER_SNAKE_CASE for true module-level constants (MAX_RETRIES, DEFAULT_TIMEOUT)."
+    functions: "Name all functions, including callbacks and inline arrow functions. Anonymous functions appear as '<anonymous>' in stack traces and profiling tools, making debugging significantly harder."
+  error_handling:
+    recommended: "Always 'return await' when returning promises to preserve full stack traces. Register process.on('unhandledRejection', handler) as a global safety net. Subscribe to EventEmitter 'error' events when working with streams or event-driven code."
+  data_flow:
+    direction: "node: built-ins -> external packages -> src/config -> src/errors -> src/utils -> domain modules -> route handlers"
+    rules:
+      - "Group imports: node: built-ins first, then external packages, then internal src/ path aliases, then relative paths. Use a consistent blank line between groups."
+      - "Keep all process.env access inside src/config. No module outside src/config reads process.env directly."
+      - "Avoid barrel re-export index.ts files that re-export across feature boundaries — they create circular import graphs that cause runtime errors and slow bundlers."
+anti_patterns:
+  - id: empty_catch
+    severity: warning
+    description: "Errors are swallowed without handling or logging, making failures invisible to monitoring, on-call engineers, and automated alerting. Silent failures in production are the hardest class of bug to diagnose."
+    bad_example: |
+      try {
+        await saveUser(user);
+      } catch (error) {}
+    good_example: |
+      try {
+        await saveUser(user);
+      } catch (error) {
+        logger.error('Failed to save user', { userId: user.id, error });
+        throw error;
+      }
+  - id: hardcoded_env_values
+    severity: critical
+    description: "Environment-specific values (hostnames, secrets, feature flags, API keys) are hardcoded in source files. This prevents running the app in multiple environments, leaks production config into version control, and requires code changes for every environment switch."
+    bad_example: |
+      // Hardcoded deep inside a feature file
+      const db = new Client({
+        host: 'prod-db.us-east-1.internal',
+        password: 'super_secret_prod_password',
+      });
+    good_example: |
+      // Read once at startup in src/config/index.ts; consumed everywhere else
+      import { config } from '@/config';
+      const db = new Client({
+        host: config.DB_HOST,
+        password: config.DB_PASSWORD,
+      });
+  - id: unsafe_any
+    severity: warning
+    description: "Using the 'any' type disables TypeScript's type checker for that value and everything downstream that touches it. Values typed as 'any' propagate unsafely through the call chain, turning TypeScript into JavaScript with extra syntax overhead."
+    bad_example: |
+      async function getUser(id: string): Promise<any> {
+        const data: any = await fetchJson(`/users/${id}`);
+        return data.profile.email; // crashes at runtime if shape is wrong; no IDE help
+      }
+    good_example: |
+      interface UserResponse {
+        profile: { email: string; name: string };
+      }
+      async function getUser(id: string): Promise<UserResponse> {
+        const data = await fetchJson<UserResponse>(`/users/${id}`);
+        return data; // fully type-checked; IDE autocomplete and refactoring work
+      }