What Architecture Tests Enforce Structural Rules in the Instatic Codebase

Instatic maintains strict structural integrity through a comprehensive suite of architecture tests located in src/__tests__/architecture/ that scan source files for forbidden patterns, enforce import conventions, and validate design tokens across the codebase.

The CoreBunch/Instatic repository uses automated architectural guardrails to prevent codebase drift and preserve clean separation of concerns. These tests run on every pull request via bun test, failing the CI pipeline immediately when violations are detected.

Dependency and Import Constraints

Banning Tailwind Ecosystem Dependencies

The src/__tests__/architecture/no-tailwind-deps.test.ts test enforces a strict dependency ban on the entire Tailwind ecosystem. It scans all package.json files and TypeScript imports to block packages including clsx, tailwind-merge, class-variance-authority, and any @radix-ui/* scoped packages. The test also prohibits @tailwind and @apply directives in CSS files, ensuring the codebase maintains its design-token-first styling approach without Tailwind abstractions.

Enforcing Barrel-Only Imports

Deep imports into core engine modules are forbidden by src/__tests__/architecture/no-core-barrel-deep-imports.test.ts. This test guarantees that all external code imports from public barrels like @core/page-tree and @core/publisher rather than reaching into concrete implementation files. It uses a regular expression to detect violations:

const DEEP_IMPORT = new RegExp(
  `(?:from|import\\()\\s*['"]@core/(?:${BARRELLED_MODULES.join('|')})/[^'"]+['"]`,
);
if (DEEP_IMPORT.test(line)) {
  violations.push(`${filePath.replace(ROOT + '/', '')}:${i + 1}  ${line.trim()}`);
}

Database and Migration Standards

SQL Dialect Neutrality

The src/__tests__/architecture/db-postgres-isms.test.ts test bans PostgreSQL-specific syntax in shared repository code, ensuring database portability. This prevents adapter-specific features from leaking into the core data layer, keeping the ORM dialect-agnostic.

JSON Column Naming Conventions

All JSON columns must follow the *_json naming convention, enforced by src/__tests__/architecture/db-json-column-naming.test.ts. This structural rule makes schema inspection predictable and distinguishes JSON-structured data from plain text or relational columns.

Cross-Adapter Migration Parity

The src/__tests__/architecture/migration-parity.test.ts test verifies that every migration added for PostgreSQL has a matching SQLite counterpart with the identical migration ID. This guarantees feature parity across supported database adapters and prevents drift between environments.

UI Component and Styling Rules

CSS Design Token Policy

Two complementary tests enforce the CSS token policy. src/__tests__/architecture/css-token-policy.test.ts requires all CSS modules to use var(--...) references defined in globals.css, while src/__tests__/architecture/no-css-var-fallbacks.test.ts explicitly prohibits fallback values in those variable references. Together, they eliminate hard-coded colors and ensure the design system remains the single source of truth for theming.

Admin Router Enforcement

The admin UI must use the custom routing implementation from src/admin/lib/routing/ instead of react-router-dom, as mandated by src/__tests__/architecture/admin-router-usage.test.ts. This ensures consistent navigation patterns and middleware integration across the administrative interface.

Primitive Component Usage

src/__tests__/architecture/button-primitive-usage.test.ts and related tests enforce that UI components employ shared primitives (Button, Input, etc.) rather than raw HTML elements. This maintains accessibility standards and consistent interaction patterns throughout the application.

Error Boundary Coverage

Every error-throwing path must be covered by an ErrorBoundary in the UI, according to src/__tests__/architecture/error-boundary-coverage.test.ts. This structural rule prevents uncaught exceptions from crashing the user interface.

Security and Plugin Architecture

Sandbox Permission Validation

src/__tests__/architecture/plugin-sandbox-invariants.test.ts validates that plugin VM sandbox permissions follow the documented security model. It checks that RPC registrations and capability grants align with the principle of least privilege.

Secret Handling Verification

The src/__tests__/architecture/plugin-secrets-never-leak.test.ts test ensures that secrets provided to plugins remain confined to the sandbox environment and cannot be exfiltrated through logging or network requests.

Asset Route Hygiene

Dynamic asset routes—such as those used by the hole runtime—are validated by src/__tests__/architecture/hole-runtime-asset-route.test.ts to ensure they do not expose raw files or bypass access controls.

Tree Mutation Integrity

Mutation Purity Constraints

src/__tests__/architecture/no-vc-mode-branches-in-mutations.test.ts enforces that tree mutation code remains agnostic to visual-component mode. It specifically forbids checks like kind === 'visualComponent' in mutation logic and verifies that the legacy childNodes field has been removed from core schemas, ensuring mutations operate purely on the abstract tree structure.

How Architecture Tests Scan Source Files

Each architecture test uses Node.js filesystem APIs (readdirSync, readFileSync) to collect relevant TypeScript, TSX, and CSS files. The tests apply regular-expression scans or string checks to file contents, aggregating violations into an array that causes the test to throw new Error when non-empty:

// Example: Pattern matching from no-tailwind-deps.test.ts
if (banned.pattern.test(src)) {
  violations.push({ file: relative(SRC_ROOT, f), pkg: banned.name })
}

Run the full architecture suite locally with:

bun test src/__tests__/architecture/**/*.test.ts

Because these tests execute as part of the standard test suite, any stray import, disallowed CSS token, or structural violation fails the build immediately, preventing architectural drift from reaching production.

Summary

• Dependency control: Bans Tailwind ecosystem packages and enforces barrel-only imports for core modules via regex scanning in no-tailwind-deps.test.ts and no-core-barrel-deep-imports.test.ts.
• Database integrity: Ensures dialect-agnostic SQL, consistent JSON column naming (*_json), and migration parity between PostgreSQL and SQLite adapters.
• Styling governance: Mandates CSS custom properties from globals.css while prohibiting fallbacks and Tailwind directives.
• Security posture: Validates plugin sandbox invariants and secret isolation through dedicated security tests.
• Structural purity: Enforces tree-mutation agnosticism and removal of deprecated fields like childNodes.

Frequently Asked Questions

How do architecture tests differ from unit tests in Instatic?

Architecture tests validate structural constraints across the entire codebase rather than testing individual function behavior. They scan files using regex and AST-like pattern matching to enforce import disciplines, naming conventions, and dependency bans, whereas unit tests verify specific runtime logic and data transformations.

What happens when an architecture test fails in CI?

When a violation is detected, the test aggregates the offending file paths and patterns into an error message and calls throw new Error, which causes bun test to exit with a non-zero status. This immediately blocks the pull request from merging until the structural violation is remediated.

Why does Instatic enforce barrel-only imports for core modules?

Barrel imports create a clear public API boundary for the @core/* modules, preventing consumers from depending on internal implementation details that may change. This encapsulation allows the CoreBunch team to refactor internal file structures without breaking downstream imports.

How does the CSS token policy maintain design consistency?

By requiring all CSS modules to reference tokens defined in globals.css via var(--...) and prohibiting hard-coded values or fallbacks, the architecture tests ensure that theming, dark mode, and brand colors remain centralized and consistent across the entire application surface.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}