Add Guideline Test Suites (G1-G6)

[maurcarvalho]

Guideline Architecture Test Suites

One spec file per guideline, all static analysis (no runtime infra needed). Run all at once with npm run test:guidelines.

Test Suites

Spec	Guideline	Key Metrics	Tests
g1-modular-boundaries.spec.ts	G1: Enforce Modular Boundaries	C_undecl, C_forbid, C_leak, P_iso	17 (skipped — requires runtime module resolution)
g2-maintainability.spec.ts	G2: Embed Maintainability	ρ_api, G_api, Γ, σ_m, φ_m	7 ✅
g3-scalability.spec.ts	G3: Progressive Scalability	ρ_sync, ω, α, ε_m	5 ✅
g4-migration-readiness.spec.ts	G4: Migration Readiness	Event contracts, ACL patterns, module descriptors	5 ✅
g5-deployment.spec.ts	G5: Deployment Strategy	Nx structure, build independence, path aliases	7 ✅
g6-observability.spec.ts	G6: Observability Patterns	Event correlation, error context, module logging	4 ✅

Metric Symbol Legend

G1 — Boundary Enforcement

Symbol	Name	What it measures
C_undecl	Undeclared Dependency Count	Cross-module references not declared in module descriptor
C_forbid	Forbidden Dependency Count	References to explicitly forbidden modules
C_leak	Encapsulation Leakage Count	Internal symbols (entities, repos) exposed in public API
P_iso	Module Isolation Test Pass Rate	Proportion of modules that pass isolation tests

G2 — Maintainability

Symbol	Name	What it measures
ρ_api	API-Only Dependency Ratio	Proportion of cross-module refs targeting public surfaces (target: ≥ 0.95)
G_api	API Surface Growth Rate	Number of exports per module (detect inflation)
Γ	Module Complexity Concentration	max(API_m) / mean(API_m) — no module should dominate (target: ≤ 3.0)
σ_m	Contract Stability Index	Proportion of public API unchanged between releases (target: ≥ 0.9)
φ_m	Fan-In Concentration	Fraction of modules depending on module m (target: ≤ 0.5 for domain modules)

G3 — Scalability Readiness

Symbol	Name	What it measures
ρ_sync	Synchronous Call Ratio	Proportion of sync vs async inter-module interactions (target: ≤ 0.3)
ω	Data Ownership Clarity Index	Proportion of tables with single-module ownership (target: 1.0)
α	Infrastructure Abstraction Coverage	Proportion of modules free from direct low-level infra imports (target: 1.0)
ε_m	Extraction Readiness Score	Weighted composite: 0.25·b_m + 0.20·(1−ρ_sync) + 0.15·a_m + 0.20·ω_m + 0.20·v_m (target: ≥ 0.8)

npm scripts

Script	What it runs
test:boundary	G1 only
test:maintainability	G2 only
test:scalability	G3 only
test:migration	G4 only
test:deployment	G5 only
test:observability	G6 only
test:guidelines	All G1–G6 at once

Also includes

• G3 exercise violation files in exercises/g3/ (for thesis tutorial demonstrations)
• Renamed module-boundary.spec.ts → g1-modular-boundaries.spec.ts for naming consistency

Current baseline (all modules)

ρ_api  = 1.00    G_api(max) = 20    Γ = 1.57    φ_m = 0.0
ρ_sync = 0.00    ω = 1.00           α = 1.00    ε_m = 0.925