| name | coding-standards |
| description | Invoke when implementing features, writing code, or reviewing code quality. Contains project-specific naming conventions, error handling patterns, import style, and deviations from standard practices. |
Coding Standards
Detected
- Language: TypeScript (281 source files)
- Functions: camelCase (88%, 1015 sampled)
- Classes: PascalCase (55%)
- Files: PascalCase (58%, 286 sampled)
- Imports: relative (71%)
- 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.
Gotchas
- Missing
.js on imports: Every relative import MUST end in .js (e.g., import { foo } from './bar.js'). TypeScript compiles fine without it, but the built CLI crashes at runtime with ERR_MODULE_NOT_FOUND. Standard TypeScript training doesn't include this — it's an ESM-specific requirement.
- "Fixing" empty catch blocks in engine: 57+ catch blocks in engine are intentionally empty — they implement graceful degradation (detector fails, scan continues with partial results). Don't add
console.error or re-throws to engine catch blocks. The error handling belongs in the command layer.
- Adding chalk or ora to engine files: Engine is pure — zero CLI dependencies. A fresh agent adding error formatting or progress output to an engine file breaks the architectural boundary. Engine functions are also called from tests without a TTY. Put all chalk/ora usage in
src/commands/.
Examples
Not yet captured. Add short snippets showing the RIGHT way.
