overengineering-meter

Detect abstraction hell in your codebase. Galaxy Brain score. Are you building a space shuttle to go to the shop?

npm install -g overengineering-meter
# or just
npx overengineering-meter src/

---

What it detects

• AbstractionHell™ — abstract classes with 1 implementation, factories that create 1 type, interfaces with 1 method
• Design pattern overuse — 5+ patterns crammed into a single file
• Barrel files — files that only re-export other modules
• Naming red flags — Manager, Factory, Repository, AbstractBaseEntityManagerRepositoryFactory
• YAGNI violations — "for future use", "when we scale", "someday" comments
• Config overengineering — more config files than source files
• Nesting depth — 4+ directory levels for a 3-file project
• Dead code — functions defined but never called in the same file

---

Usage

npx overengineering-meter             # scan current directory
npx overengineering-meter src/        # specific directory
npx overengineering-meter --roast     # personal commentary mode
npx overengineering-meter --top 10    # show top 10 worst offenders
npx overengineering-meter --ext ts    # TypeScript files only

---

Example output

Here is an over-engineered "Hello World" and what the meter says about it:

src/
  core/
    base/
      abstract/
        interfaces/
          IGreetable.ts          ← interface with 1 method
        AbstractBaseGreeter.ts   ← abstract class, 1 implementation
      GreeterFactory.ts          ← factory that creates 1 type
  strategies/
    EnglishGreetingStrategy.ts  ← strategy for "Hello"
    GreetingContext.ts           ← context class to select strategy
  services/
    GreetingServiceProvider.ts  ← provides the service
    GreetingServiceFactory.ts   ← creates the provider
  adapters/
    ConsoleOutputAdapter.ts     ← adapter for console.log
  main.ts

main.ts (// TODO: add multilingual support when we scale):

const container = new Container();
container.bind<IGreetable>(TYPES.Greeter).to(AbstractBaseGreeter);
const factory = container.get<GreetingServiceFactory>(TYPES.Factory);
const provider = factory.createProvider();
const service = provider.getService();
const adapter = new ConsoleOutputAdapter(service);
adapter.execute();
// Output: "Hello, World"

Running the meter on this:

🔭 Overengineering Meter
──────────────────────────────────────────────────
Scanning: src/ (9 files, 247 lines)

🔭 ENTERPRISE ARCHITECT — Score: 94/100
   congratulations, you've invented Java

Top Offenders:
  core/base/abstract/interfaces/IGreetable.ts        ████ +18 pts
    • Interface with exactly 1 method/property (+5)
    • Abstract class `AbstractBaseGreeter` has 1 implementation (+8)
    • Enterprise name detected: `AbstractBaseGreeter` (+5)
    📄 12 lines | max nesting: 2

  services/GreetingServiceFactory.ts                 ███ +15 pts
    • Factory creates exactly 1 type (GreetingServiceProvider) (+10)
    • Name contains: Service + Factory (+5)
    📄 18 lines | max nesting: 3

Project-Level Issues:
  • 8 directory nesting levels for 9 files (+12)
  • Dependency injection container — are you building a framework? (+7)
  • 1 YAGNI comment — building features for a product you haven't shipped (+3)

Pattern Density (whole project):
  Factory:          4 occurrences (█ MODERATE)
  Abstract:         3 occurrences (█ MODERATE)
  Service:          6 occurrences (██ ELEVATED)
  Strategy:         2 occurrences (█ LOW)

Config Files: 2 | Source Files: 9
Config Ratio: 22% (normal is <10%)

🧮 Would this work as fewer files? Probably yes.
   Estimated simplification: Remove ~56% of abstractions, keep all functionality.

──────────────────────────────────────────────────
Run with --roast for a more personal assessment.

The actual hello world could have been:

console.log("Hello, World");

---

Scoring

Score	Rating	What it means
0–20	✅ SANE	Clean, pragmatic code
21–40	🤔 SUSPICIOUS	Some unnecessary complexity
41–60	🏗️ ARCHITECT BRAIN	You've been reading too many design patterns
61–80	🌌 GALAXY BRAIN	Solving tomorrow's problems today
81–100	🔭 ENTERPRISE ARCHITECT	Congratulations, you've invented Java

---

Why this exists

Over-engineering is the silent killer of software projects. It doesn't show up in test coverage metrics. It passes code review because the individual pieces are "correct". It only reveals itself when:

• Onboarding a new engineer takes 3 weeks
• A one-line business logic change requires touching 8 files
• The PR to add a button has an architecture diagram in the description

This tool won't catch everything, but it will flag the patterns that correlate most strongly with codebases that become unmaintainable.

---

Zero dependencies

Pure Node.js. No install bloat. ES modules. Works on Node 18+.

npx overengineering-meter .

---

MIT License