modular-code-enforcement

Modular Code Architecture — Zero Tolerance Policy

This rule is NON-NEGOTIABLE. Violations BLOCK all further work until resolved.

Rule 1: index files are ENTRY POINTS, NOT dumping grounds

index files (index.ts, __init__.py, index.js, etc.) MUST ONLY contain:

• Re-exports (export { ... } from "./module")
• Factory function calls that compose modules
• Top-level wiring/registration (hook registration, plugin setup)

index files MUST NEVER contain:

• Business logic implementation
• Helper/utility functions
• Type definitions beyond simple re-exports
• Multiple unrelated responsibilities mixed together

If you find mixed logic in an index file: Extract each responsibility into its own dedicated file BEFORE making any other changes. This is not optional.

Rule 2: No Catch-All Files — utils/helpers/service are CODE SMELLS

A single utils, helpers, service, or common file is a gravity well — every unrelated function gets tossed in, and it grows into an untestable, unreviewable blob.

These file names are BANNED as top-level catch-alls. Instead:

Anti-Pattern	Refactor To
utils with formatDate(), slugify(), retry()	date-formatter, slugify, retry
service handling auth + billing + notifications	auth-service, billing-service, notification-service
helpers with 15 unrelated exports	One file per logical domain

Design for reusability from the start. Each module should be:

• Independently importable — no consumer should need to pull in unrelated code
• Self-contained — its dependencies are explicit, not buried in a shared grab-bag
• Nameable by purpose — the filename alone tells you what it does

If you catch yourself typing utils or service, STOP and name the file after what it actually does.

Rule 3: Single Responsibility Principle — ABSOLUTE

Every source file MUST have exactly ONE clear, nameable responsibility.

Self-test: If you cannot describe the file's purpose in ONE short phrase (e.g., "parses YAML frontmatter", "matches rules against file paths"), the file does too much. Split it.