How vinod-m-1/repo-health works
What this project is (type + purpose)
Repo-Health is a Node.js-based repository analysis tool that:
• Ingests a code repository (likely via local path or remote Git URL),
• Crawls files, builds an AST-based analysis summary (metrics like cyclomatic complexity, LOC, depth),
• Runs code smell detection in two modes:
1) Metadata/threshold checks over precomputed metrics (fast pass),
2) AST structural traversal for smells that require syntax inspection (e.g., empty catch blocks),
• Exposes results either via a web UI (EJS view) and/or a CLI/script entrypoint.
This is not a “full-stack app” in the product sense; it’s primarily an analysis engine with a thin web presentation layer.
What the file tree tells you (architecture clues)
Top-level files imply a small, modular Node.js codebase:
• server.js
Likely an Express server hosting endpoints and rendering views/home.ejs.
• views/home.ejs
A server-rendered UI to submit a repo target and view results.
• crawler.js
A filesystem/repo walker: enumerates files, filters extensions, builds a list of JS/TS files, etc.
• metricsEngine.js
Computes metrics from AST or source (LOC, cyclomatic complexity, nesting depth). Produces the “Summary Object (analysis)” referenced in README.
• codesmel.js
Implements smell detection:
• Threshold check: iterates analysis.Cyclo.funs (precomputed per-function data) and emits events when thresholds exceeded.
• Tree traversal check: AST walk to find patterns like CatchClause with empty body.
• main.js
Likely the orchestrator tying together: clone/prepare repo → crawl → metrics → smells → output.
• temp_repo/
Strong hint there is a “workspace” directory where a target repo is cloned/unzipped for analysis.
• package.json / package-lock.json
The README explicitly describes two internal pipelines:
Metadata Analysis (Threshold Check)
• Input: analysis summary object (already computed)
• Loop: analysis.Cyclo.funs
• Compare: loc, counter (CC), depth against THRESHOLDS
• Output: “event objects” for bulky/complex functions
Tree Traversal (Structural Check)
• Input: AST (per file)
• Search: nodes with type === 'CatchClause'
• Condition: node.body.body.length === 0
• Output: smell event with node.loc.start.line (precise location)
These two checks are important enough to explicitly show as two separate “subsystems” inside the analysis engine.
Web Server Container (server.js)
• Responsibilities: HTTP endpoints, request parsing, calling the analysis orchestration, rendering results via EJS.
• Tech: Node.js + (likely) Express + EJS.
Analysis Engine Container (library-style modules)
• Responsibilities: crawl repo, parse/build AST, compute metrics, detect smells, produce report artifacts.
• Includes modules: main.js, crawler.js, metricsEngine.js, codesmel.js.
Workspace/Storage
• temp_repo/ directory (ephemeral clone workspace)
• Possibly result JSON in-memory or on disk (even if not visible in tree, show the concept if it exists in code).
(Optional) Scheduler/Automation
• README says “daily code for my project”; if there’s a daily run (cron/CI), include a “Scheduler/CI” actor/container even if it’s external.
• Browser → Web Server (submit repo target)
• Web Server → Analysis Engine (invoke run)
• Analysis Engine → Workspace FS (temp_repo/) (clone/read)
• Analysis Engine → Web Server (return report object)
• Web Server → Browser (render home.ejs with results)
Orchestrator
• main.js
• Calls crawler
• Calls metrics engine
• Calls smell detector
• Aggregates final report
Repo Acquisition / Preparation
• If present in code: a “Repo Cloner” step that writes into temp_repo/
• It even if it’s just git clone via child process.
Crawling / File Selection
• crawler.js
• Input: repo root path
• Output: list of files to analyze
Parsing + Metrics
• metricsEngine.js
• Input: file contents (and/or AST)
• Output: analysis summary object
Smell Detection
• codesmel.js
Split it into two subcomponents (because README says they’re distinct):
1. Threshold Rules Engine
• Input: analysis.Cyclo.funs
• Output: smell events (bulky/complex functions)
2. AST Structural Rules
• Input: AST nodes + locations
• Output: smell events (e.g., empty catch blocks)
Report Model
• A conceptual component (even if it’s just a JS object):
• Aggregates events, counts, severities, file/line mapping
• crawler.js → list of paths → metricsEngine.js
• metricsEngine.js → analysis object → codesmel.js (threshold check)
• metricsEngine.js (or parser) → AST → codesmel.js (structural check)
• codesmel.js → smell events → main.js → report → server.js → home.ejs
What to explicitly include
Use these conventions:
Labels
• Name components using file names + responsibility:
• “metricsEngine.js — Metrics + Summary Object Builder”
• “codesmel.js — Smell Rules (Threshold + AST Traversal)”
• “crawler.js — Repo File Walker”
• “server.js — HTTP + EJS Rendering”
• Control flow (invokes/calls)
• Data flow (produces/consumes artifacts)
• “file paths[]”
• “AST”
• “analysis summary”
• “smell events[]”
• “report”
Practical “don’t overthink it” checklist (maximum fidelity fast)
To be very detailed without getting stuck:
two highlighted lanes inside codesmel.js
• “Threshold check (fast, uses summary)”
• “AST traversal (structural checks)”