feat: codebase metrics (METRICS.md) and bootcamp doctor command

[Arthur742Ramos]

Summary

• Adds two new deterministic, well-tested capabilities that follow the existing analyzer pattern, plus supporting docs and exports.
• Codebase Metrics & Hotspots: new src/metrics.ts computes a language breakdown, largest-file and top-directory hotspots, the test:source ratio, a codebase size class, and a 0-100 approachability score (grade A-F) using additive, clamped penalties. It emits a new METRICS.md artifact so a newcomer can size up a repo at a glance.
• Environment Doctor: new bootcamp doctor command (src/doctor.ts + command) diagnoses Node >= 20, git, GitHub CLI + auth, Copilot token env vars, mermaid-cli, and analysis-cache health, giving users a fast way to confirm their machine is ready before running a generation.
• Why: these round out the toolkit with onboarding insight (metrics) and first-run confidence (doctor), both of which were gaps in the current flow.

Approach notes

• Metrics is computed directly in prepareOutputDocuments (pure and instant from scanResult.files, so no extra analysis phase) and threaded through analysis-orchestration and main-command, including a CLI summary line. METRICS.md output is gated behind a new showMetrics style-pack section (on for corporate/startup/oss/academic, off for minimal), so existing fixtures that omit the field stay valid.
• Doctor keeps a pure evaluateDoctor core with injectable gather/log/exit deps so tests never spawn processes or call real process.exit. It supports --json and exits non-zero when a required check fails (useful in CI/scripts).
• Both modules are re-exported from api.ts with new ./metrics and ./doctor subpath exports in package.json.

Type of change

• Bug fix
• New feature
• Refactor
• Documentation
• Test-only change

Testing

• npm run lint
• npm run build
• npm test

Full suite: 1018 passing (985 baseline + 15 metrics + 18 doctor). Also smoke-tested the built CLI end to end: node dist/cli.js doctor and doctor --json both render correctly and return the expected exit codes. The api.ts export-guard test was updated to include the new runtime exports.

Checklist

• I followed the project's coding patterns and conventions
• I added or updated tests for behavior changes
• I updated docs/config where needed
• I verified no unrelated files were changed

Linked issues

N/A

Breaking changes

• No breaking changes
• Breaking changes included (describe below)

Note: StyleConfig.sections gains a required showMetrics field, but getStyleConfig always merges from a base pack that supplies it, and tsconfig.build.json excludes tests, so no consumer or fixture breaks.

[Copilot]

Pull request overview

This PR adds two new deterministic capabilities to repo-bootcamp: a codebase metrics/hotspots report emitted as METRICS.md, and a new bootcamp doctor CLI command to validate a local environment before running analysis/generation.

Changes:

• Add src/metrics.ts to compute codebase metrics (language breakdown, hotspots, directory distribution, test:source ratio, size class, approachability score) and render METRICS.md when styleConfig.sections.showMetrics is enabled.
• Add src/doctor.ts + bootcamp doctor command (with --json) to evaluate environment readiness (Node, git, gh/auth, mermaid-cli, cache).
• Thread metrics through orchestration + CLI summaries, and expose both new modules via src/api.ts and package.json subpath exports.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
test/metrics.test.ts	Adds unit tests for metrics computation and METRICS.md rendering.
test/doctor.test.ts	Adds unit tests for doctor evaluation, formatting, CLI wiring, and JSON output.
test/api.test.ts	Extends export-guard coverage for new public API exports.
src/services/analysis-orchestration.ts	Computes metrics during output prep; conditionally emits METRICS.md; returns metrics in result.
src/plugins.ts	Adds sections.showMetrics to style config and all built-in style packs.
src/metrics.ts	Implements codebase metrics computation and Markdown doc generation.
src/doctor.ts	Implements environment snapshot gathering and deterministic doctor evaluation/report formatting.
src/commands/main-command.ts	Threads metrics through generation and prints an approachability summary line when enabled.
src/commands/doctor-command.ts	Implements bootcamp doctor command with colorized output, JSON mode, and non-zero exit on required failures.
src/cli.ts	Wires the new doctor subcommand into the CLI.
src/api.ts	Re-exports doctor/metrics APIs and types.
README.md	Documents METRICS.md and the new bootcamp doctor command.
package.json	Adds ./metrics and ./doctor subpath exports.
CHANGELOG.md	Documents the new metrics report and doctor command features.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.