How I Built an Architecture Analyzer with Tree-Sitter AST (and What I Learned About Code Quality Metrics)

The Problem

Every codebase I've worked on in 19 years had the same story: the architecture starts clean, then slowly rots. Someone imports from the wrong layer. A utility class grows into a God Class. Circular dependencies creep in. By the time you notice in code review, refactoring is expensive.

I wanted automated architecture checks — like ESLint for structure, not syntax.

What Architect Genesis Does

Architect Genesis is a CLI tool that analyzes your codebase architecture using Tree-Sitter AST parsing. It works with TypeScript, Python, Go, Java, Rust, Ruby, and PHP.

Install and Run

bashnpm install -g @girardelli/architect

architect analyze ./src

That's it. No config needed to start. It infers your stack, framework, and domain automatically.

What You Get

Architecture Score (0-100) across four weighted dimensions:

Dimension Weight What it measures

Modularity 40% How well-separated are your modules

Coupling 25% Cross-boundary dependency count

Cohesion 20% How related are elements within a module

Layering. 15% Clean layer separation (View/Core/Data/Infra)

Anti-pattern detection: God Classes, Circular Dependencies, Leaky Abstractions, Spaghetti Modules. All derived from AST structure, not heuristics.

Layer detection: Automatically classifies your code into View, Core, Data, and Infrastructure layers based on dependency patterns.

Architecture as Code

The real power is declaring rules in .architect.rules.yml:

yamlquality_gates:

  min_overall_score: 60

  max_critical_anti_patterns: 0

  max_high_anti_patterns: 3



boundaries:

  allow_circular_dependencies: false

  banned_imports:

    - from: "presentation/*"

      to: "infrastructure/*"

    - from: "domain/*"

      to: "framework/*"

Then plug into CI:

basharchitect check ./src

# Exit code 0 = pass, 1 = fail

Architecture violations now break the build.

AI-Assisted Refactoring

When Architect finds problems, it generates a refactoring plan with 5 rule-based transformations:

1. Hub Splitting — breaks up God Classes


2. Barrel Optimization — cleans up index/init files


3. Import Organization — restructures import paths


4. Module Grouping — reorganizes related files


5. Dead Code Detection — finds unreferenced exports

Run architect execute and it applies these using Claude, GPT, or Gemini — with human gating on every step. You approve, skip, retry with a different AI, or rollback. It creates a protective git branch and commits each step individually.

Predicting Architecture Decay

The architect forecast command reads your git history, computes velocity-adjusted scoring, and runs ML-based regression to predict where your score will be in 3-6 months. You can see which modules are trending downward before it becomes a crisis.

Technical Architecture

It's a monorepo with three packages:

architect-core — Tree-Sitter AST parsing, scoring engine, rules engine

architect-agents — AI provider integration, stack/domain detection

architect CLI — reports (HTML/JSON/Markdown), GitHub Actions adapter

Plus a VS Code extension (Architect Intelligence) with CodeLens integration and inline scoring.

What I Learned Building This

Scoring weights are hard. I calibrated 40/25/20/15 against ~30 codebases, but I'm not confident they generalize. A React SPA has different architecture concerns than a Spring Boot microservice. Context-aware weights might be the next step.

AST beats regex. Early versions used pattern matching. Tree-Sitter was a game-changer — it gives you the real dependency graph, not approximations.

Human gating matters. I tried fully autonomous refactoring first. It was terrifying. The approve/skip/rollback model gives you AI speed with human judgment.

Where It's Heading

The roadmap is to evolve from analyzer to intent compiler — describe the architecture you want, and the system generates the code. But that's the future. Today, v8.2.0 does analysis, scoring, validation, and assisted refactoring. And it does them well.

Open source, MIT licensed.

GitHub: https://github.com/camilooscargbaptista/architect