coding-standards

Coding Standards

Detected

• Language: TypeScript (292 source files)
• Functions: camelCase (88%, 1049 sampled)
• Classes: PascalCase (55%)
• Files: PascalCase (56%, 297 sampled)
• Imports: relative (72%)
• Indentation: spaces, 2 wide
• Error handling: exceptions (generic)
• UI: Tailwind CSS

Library Rules

• All local imports use .js extensions (import { foo } from "./bar.js"). TypeScript compiles without them but ESM resolution crashes at runtime.
• Use import type for type-only imports, separate from value imports. Prevents runtime imports of pure types.

Rules

• All imports use .js extensions and node: prefix for built-ins. import * as fs from 'node:fs/promises', import { scanProject } from './scan-engine.js'. Omitting .js compiles fine but crashes at runtime — tsup emits ESM.
• Use import type for type-only imports, separate from value imports. Never mix types and values in the same import statement.
• Prefer named exports. No default exports — this is a CLI, no framework requires them.
• Avoid any — use unknown and narrow with type guards. any is acceptable only for untyped third-party boundaries. Define an interface for complex types — don't escape the type system.
• Use | null for fields that were checked and found empty. Reserve ?: (optional) for fields that may not have been checked. EngineResult uses | null for all nullable stack fields — follow the same convention.
• Prefer early returns over nested conditionals. if (!condition) return null; then the main logic flat — not if (condition) { ...long block... }.
• Error handling has two layers. Commands surface errors to the user: chalk.red message + process.exit(1). Engine functions catch internally and return defaults — a detector failure degrades the scan gracefully, it never crashes it.
• Engine files (src/engine/) have zero CLI dependencies — no chalk, no commander, no ora. Engine takes data as input and returns results. All user-facing output belongs in src/commands/.
• Explicit return types on all exported functions. Internal helpers can use inference.
• Avoid disabling lint rules inline. When necessary, add a comment explaining why the disable is required.
• Exported functions require @param and @returns JSDoc tags. The eslint rules enforce this — pre-commit will reject missing tags.
• In JSX text content, use ' for apostrophes. The react/no-unescaped-entities lint rule rejects raw ' characters in JSX — contractions like "don't" must be written as don't.