Readme

Modular Architectural Linters Architecture (docs/architecture/linters/)

1. Executive Summary & Modular Linter Pattern

Standard TypeScript compilation (tsc --noEmit) validates type contracts but cannot detect architectural erosion, cross-tenant leaks, or unauthorized re-implementation of platform capabilities.

Linting is a cornerstone of how SiteSwarm maintains long-term fleet consistency across independent client storefronts (apps/*) and shared platform infrastructure (packages/*, services/*). To prevent linter bloat and rule entanglement, SiteSwarm adheres to a Modular Composable Linter Architecture:

1. Avoid Monolithic Linters: Rather than placing all linting duties into a single giant engine, each distinct architectural concern is implemented as a self-contained, focused linter module.
2. Dedicated Documentation per Linter: Linters evolve dynamically over time. Individual linters are not exhaustively codified into a brittle top-level summary; instead, each linter is documented in its own specification file within docs/architecture/linters/<linter>.md.
3. Composable Wrapper Orchestration: The governance CLI linter (packages/governance/src/cli/lint.ts, invoked via pnpm run lint:arch) composes and executes all discrete linters in a single unified pass, emitting structured diagnostics with consistent severity levels.

flowchart TD
    Wrapper["Governance Architectural Linter\n(pnpm run lint:arch)"] --> L1["Content & Runtime Boundaries\n(content-boundary.ts)"]
    Wrapper --> L2["Documentation Taxonomy\n(docs-taxonomy.ts)"]
    Wrapper --> L3["Phantom Service Bindings\n(phantom-service-bindings.ts)"]
    Wrapper --> L4["Quote Config Synchronization\n(quote-config-sync.ts)"]

---

2. Active Linter Directory

Each active linter is detailed in its dedicated specification:

Linter Module	Specification Document	Primary Architectural Invariant Enforced
Content Boundary	CONTENT_BOUNDARY.md	Prevents cross-tenant imports between apps/*, blocks Node.js built-ins in edge routes, stops unmanaged process.env secret reads, and enforces component modularity.
Docs Taxonomy	DOCS_TAXONOMY.md	Enforces the strict 4-pillar documentation whitelist, relative link integrity, write-up YAML frontmatter contracts, and the one-way citation guard.
Phantom Service Bindings	PHANTOM_SERVICE_BINDINGS.md	Verifies that declared Worker service bindings match real deployable services and detects unconfigured binding references.
Quote Config Sync	QUOTE_CONFIG_SYNC.md	Validates synchronization between vertical client manifest configurations and platform quote estimation schemas.

---

3. Standard Linter Contract & Authoring Guide

All discrete linters live under packages/governance/src/cli/linters/ and implement the standardized ArchLintViolation interface:

export interface ArchLintViolation {
  ruleId: string;       // e.g. "arch/no-cross-tenant-imports", "docs/whitelist"
  severity: "error" | "warn";
  appId?: string;       // Application or package slug
  file: string;         // Relative path to offending file
  line?: number;        // 1-indexed line number
  message: string;      // Human-readable explanation and remediation hint
}

Authoring Rules for New Linters:

1. Isolated Responsibilities: A linter must focus on one coherent architectural domain. If a new rule introduces unrelated checks, author a new linter rather than extending an existing one.
2. Dedicated Documentation: Every new linter must include a companion specification in docs/architecture/linters/<NAME>.md detailing its intent, defect signals, and remediation steps.
3. Wrapper Registration: Register the linter in packages/governance/src/cli/lint.ts so it is automatically included in pnpm run lint:arch and CI change detection.

---

Decisions Intentionally Deferred

• Automated auto-fixing (--fix) for architectural violations is intentionally deferred; architectural repairs require intentional developer or agent refactoring.