Static Architectural Linters Specification

Document Status: Living True Specification (Single Source of Truth)
Authority: Tooling, Governance & CI Pipeline
Related Epics: #34 (Client App Anatomy & Rendering), #97 (Static Architectural Linters), #101 (Capability Governance), #108 (Automated AST Architectural Linters)
Related Documents: docs/specs/CLIENT_APPLICATION_ANATOMY.md, docs/CAPABILITY_MANAGEMENT.md, HIGH_LEVEL_DESIGN.md, ADR-0003

1. Executive Summary & Objective

In SiteSwarm, standard TypeScript checks (tsc --noEmit) verify variable types, but they are powerless to detect architectural erosion, copy-pasting, or unauthorized re-implementation of platform capabilities.

To maintain fleet cleanliness across dozens of client applications maintained by human developers and autonomous AI agents, we enforce strict architectural constraints at the AST level using the SiteSwarm Architectural Linter Engine (pnpm run lint:arch).

2. Rule Suite Specifications

2.1 Rule Suite 1: Capability Consumption & Anti-Reimplementation Rules

`no-hardcoded-capability-config`

Rule ID: arch/no-hardcoded-capability-config
Severity: Error
Description: Forbids client applications from hardcoding configuration (pricing models, honeypot field names, Turnstile provider choices) directly in Astro components or API routes.
Contract: All runtime capability options must be imported directly from the client’s swarm.config.ts.
Remediation: Import manifest from ../../swarm.config and pass manifest.capabilities['...'].options.

`no-unregistered-capability-target`

Rule ID: arch/no-unregistered-capability-target
Severity: Error
Description: Statically asserts that if any file in apps/*/src imports a capability package (e.g., @siteswarm/lead-capture, @siteswarm/quote-estimator, @siteswarm/seo), that file’s relative path must be declared in the app’s swarm.config.ts under the respective capability’s targets: [...] array.
Remediation: Add the target path to swarm.config.ts or remove the unauthorized import.

`no-raw-third-party-security`

Rule ID: arch/no-raw-third-party-security
Severity: Error
Description: Forbids client applications from making raw fetch('https://challenges.cloudflare.com/turnstile/...') calls or authoring custom third-party verification logic (e.g. Turnstile, reCAPTCHA, hCaptcha).
Contract: Mandates encapsulation within an approved platform security / bot-defense capability package (such as @siteswarm/lead-capture, @siteswarm/bot-defense, @siteswarm/security) or platform service binding. Bot defense is decoupled from any single domain capability so that authentication, quote calculators, contact forms, or checkout flows can consume security capabilities independently.
Remediation: Encapsulate verification logic in an approved capability package or route through platform service bindings rather than directly calling third-party verification URLs in client application routes.

`no-raw-schema-jsonld`

Rule ID: arch/no-raw-schema-jsonld
Severity: Error
Description: Forbids hand-rolling raw <script type="application/ld+json"> tags or manual Schema.org JSON objects in client layouts or components.
Contract: Mandates the use of @siteswarm/seo for strongly typed Schema.org generation.
Remediation: Replace manual JSON-LD scripts with @siteswarm/seo generators.

2.2 Rule Suite 2: Client Isolation & Edge Compatibility Rules

`no-cross-tenant-imports`

Rule ID: arch/no-cross-tenant-imports
Severity: Error
Description: Forbids any client application (apps/app-a) from importing code, styles, assets, or configs from another client application (apps/app-b).
Remediation: Promote shared logic into packages/* or keep bespoke implementations isolated.

`no-node-builtins-in-edge-routes`

Rule ID: arch/no-node-builtins-in-edge-routes
Severity: Error
Description: Flags imports of Node.js built-ins (node:fs, node:child_process, node:path) inside edge-rendered (prerender = false) API routes, which will crash in Cloudflare Workers.
Remediation: Use Web Standard APIs (fetch, Request, Response, Crypto) or Cloudflare bindings.

`no-shared-css-classes`

Rule ID: arch/no-shared-css-classes
Severity: Warning
Description: Detects cross-client leakage of branded CSS styles to preserve complete aesthetic divergence between client sites.

2.3 Rule Suite 3: Zero-Lockout & Graceful Degradation Invariants

`require-graceful-degradation`

Rule ID: arch/require-graceful-degradation
Severity: Error
Description: Asserts that all CMS components and dynamic data-fetching routes implement graceful degradation (returning null/empty or handling errors without unhandled exceptions) so client sites never render a 500 error if Cloudflare D1 or platform services are temporarily unreachable, strictly avoiding fabricated mock data.

2.4 Rule Suite 4: Client Application Anatomy & Modularity Rules

Codified per docs/specs/CLIENT_APPLICATION_ANATOMY.md (Epic #34) and ADR-0003:

`require-static-output`

Rule ID: arch/require-static-output
Severity: Error
Description: Statically parses each client application’s astro.config.mjs using TypeScript AST analysis to assert output: "static" is explicitly configured.
Contract: Client marketing frontends must be static-first SSG to guarantee sub-20ms edge TTFB and zero cold starts. Dynamic edge compute is restricted strictly to /api/* endpoints via export const prerender = false;.
Remediation: Declare output: "static" in astro.config.mjs.

`no-client-kv-or-d1`

Rule ID: arch/no-client-kv-or-d1
Severity: Error (for undeclared KV or D1 bindings) / Warning (for legacy declared dedicated storage)
Description: Statically inspects client wrangler.jsonc configs asserting zero kv_namespaces and zero direct d1_databases in client frontend workers (Worker A).
Contract: Public frontends never maintain visitor session KV (preventing preview quota exhaustion) and never hold direct database bindings (shielding D1 from public visitor traffic). Mutations and queries route through Cloudflare Service Bindings to platform microservices (Worker B).
Remediation: Remove kv_namespaces and route database interactions through Service Bindings (env.LEADS_SERVICE, env.CMS_SERVICE).

`warn-monolithic-component`

Rule ID: arch/warn-monolithic-component
Severity: Warning
Description: Audits .astro components in src/components/, warning when single files exceed 200 lines of code without modular directory separation.
Contract: Enforces the Two-Tier Component Modularity Threshold. Simple presentational components stay single-file (< 200 LOC); complex or script-heavy components (> 200 LOC) must be decomposed into a modular directory (index.astro, styles.css, adapter.ts).
Remediation: Extract components exceeding 200 LOC into a dedicated folder src/components/<ComponentName>/ separating styles and script adapters.

`require-vibe-spec`

Rule ID: arch/require-vibe-spec
Severity: Error
Description: Statically verifies that each client application (apps/*) provides an authoritative VIBE.md defining client-specific taste, tone, brand personality, and aesthetic restraint per CLIENT_BUSINESS_INTAKE_AND_SCAFFOLDING.md Section 4.3.
Contract: Every client application must define VIBE.md containing all five required sections: ## Voice & Persona, ## Posture & Aesthetic Restraint, ## Badge Tolerance, ## Banned Patterns & AI Slop Registry, and ## Good vs. Bad Examples.
Remediation: Author apps/<app>/VIBE.md adhering to the required 5-section specification contract.

3. Tooling Integration & CI Pipeline

The architectural linter is consolidated into the @siteswarm/governance suite and wired into the root monorepo toolchain and CI gate:

# Authoritative governance audit (manifest validation + AST architectural rules)
pnpm swarm audit

# Focused AST architectural linter suite
pnpm swarm lint

# Target a specific client application
pnpm swarm audit --app bakery
pnpm swarm lint --app software-agency

# Integrated with monorepo check gate (runs governance audit before package typechecks)
pnpm run check

CI Gate Enforcement

In GitHub Actions (.github/workflows/ci.yml), pnpm swarm audit is executed as an explicit gating step prior to build and functional testing:

Platform Verification: Runs pnpm swarm audit across the entire fleet.
Selective Verification: Runs pnpm swarm audit --app ${{ matrix.app.app }} on impacted apps.
Any violation of an error-level architectural rule immediately fails CI and halts ephemeral preview deployments.