Static Architectural Linters Specification

Document Status: Living True Specification (Single Source of Truth)
Authority: Tooling, Governance & CI Pipeline
Related Epics: #101 (Capability Governance & Platform Services), #97 (Static Architectural Linters)
Related Documents: docs/CAPABILITY_MANAGEMENT.md, HIGH_LEVEL_DESIGN.md

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 & Fallback Invariants

`require-static-fallback-seeds`

Rule ID: arch/require-static-fallback-seeds
Severity: Error
Description: Asserts that all CMS components and dynamic data-fetching routes define static fallback seed data so client sites never render a 500 error if Cloudflare D1 or KV is temporarily unreachable.

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.