Architecture Tests in Instatic: Automated Enforcement of Structural Rules

Instatic maintains strict architectural discipline through a comprehensive suite of architecture tests located in src/__tests__/architecture/ that scan source files using Node.js filesystem APIs and regular expressions, failing the CI pipeline immediately when forbidden patterns like Tailwind dependencies or deep barrel imports are detected.

The CoreBunch/Instatic repository relies on automated architecture tests to prevent codebase drift and enforce structural invariants. Unlike traditional unit tests that verify runtime behavior, these tests traverse the source tree to validate import conventions, CSS policies, and database dialect rules. By failing fast during the bun test execution, they ensure that every pull request adheres to the project's documented architectural vision.

How Architecture Tests Scan the Codebase

Each architecture test uses Node’s 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 error message that causes the test runner to fail.

// Example: Running the architecture suite locally
$ bun test src/__tests__/architecture/**/*.test.ts

When a test detects a forbidden pattern, it pushes a violation object and throws an error, immediately blocking the CI pipeline:

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

Dependency Bans and Import Discipline

Prohibiting Tailwind Ecosystem Dependencies

The no-tailwind-deps.test.ts test enforces a strict ban on Tailwind-related packages and utility libraries. The test scans package.json and import statements to block clsx, tailwind-merge, class-variance-authority, and @radix-ui/*. It also prohibits @tailwind and @apply directives in any stylesheet.

Enforcing Barrel-Only Imports

The no-core-barrel-deep-imports.test.ts test ensures all external code imports core engine modules through their public barrels (@core/page-tree, @core/publisher) rather than deep-importing concrete implementation files. The test uses a regular expression to detect violations:

// Example: Enforcing barrel imports (no-core-barrel-deep-imports.test.ts)
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 Dialect and Migration Rules

Banning Postgres-Specific Syntax

The db-postgres-isms.test.ts test blocks Postgres-only SQL constructs in shared database repositories. This ensures the core engine remains portable across different database adapters.

JSON Column Naming Conventions

The db-json-column-naming.test.ts test enforces that all JSON columns follow the *_json naming convention, maintaining consistency in schema definitions.

Migration Parity Between Adapters

The migration-parity.test.ts test verifies that every migration added for PostgreSQL has a matching SQLite counterpart with the same ID. This guarantees feature parity across supported database dialects.

CSS Token Policy and Styling Constraints

Design Token Enforcement

The css-token-policy.test.ts test requires all CSS modules to use design tokens (var(--…)) defined in globals.css. It prohibits hard-coded color values or arbitrary values outside the token system.

No Fallback Values for CSS Variables

The no-css-var-fallbacks.test.ts test disallows fallback values in CSS custom properties. This ensures strict adherence to the design token system and prevents accidental degradation of visual consistency.

Tree Mutation and Schema Integrity

The no-vc-mode-branches-in-mutations.test.ts test guarantees that tree-mutation code remains agnostic to visual-component mode. It forbids conditional checks like kind === 'visualComponent' in mutation logic and verifies that the legacy childNodes field has been removed from core schemas.

Plugin Sandbox Security Invariants

Multiple tests enforce the plugin security model. The plugin-sandbox-invariants.test.ts and plugin-secrets-never-leak.test.ts files verify that plugin VM sandbox permissions, secret handling, and RPC registration follow strict security constraints. These tests prevent plugins from accessing unauthorized APIs or leaking sensitive configuration.

UI and Routing Discipline

Admin Router Usage

The admin-router-usage.test.ts test guarantees that the admin UI uses the custom router located in src/admin/lib/routing/ instead of react-router-dom. This ensures consistent navigation behavior and route guarding across the administrative interface.

UI Primitive Enforcement

The button-primitive-usage.test.ts test enforces that UI components employ shared primitives (Button, Input, etc.) rather than raw HTML elements. This maintains accessibility standards and visual consistency.

Error Boundary Coverage

The error-boundary-coverage.test.ts test confirms that every error-throwing path in the UI is covered by an ErrorBoundary, preventing application crashes from unhandled exceptions.

Asset Route Hygiene

The hole-runtime-asset-route.test.ts validates that dynamic asset routes (e.g., hole runtime) are correctly defined and do not expose raw files directly, maintaining proper abstraction layers for static assets.

Summary

• Architecture tests in src/__tests__/architecture/ use Node.js filesystem APIs to scan source code for structural violations across TypeScript and CSS files.
• Dependency bans prohibit Tailwind-related packages and enforce barrel-only imports for core engine modules like @core/page-tree.
• Database rules enforce dialect portability by blocking Postgres-specific syntax, requiring *_json column naming, and ensuring migration parity between PostgreSQL and SQLite adapters.
• CSS policies mandate design tokens from globals.css while prohibiting fallback values and Tailwind directives.
• Plugin sandbox tests verify VM security constraints, secret handling, and RPC registration integrity.
• UI discipline tests enforce custom admin routing, shared primitive usage, comprehensive error boundary coverage, and safe asset route definitions.

Frequently Asked Questions

Where are the architecture tests located in the Instatic codebase?

All architecture tests reside in the src/__tests__/architecture/ directory according to the CoreBunch/Instatic source code. Each test file targets a specific structural invariant, such as no-tailwind-deps.test.ts for dependency management or migration-parity.test.ts for database consistency.

How do architecture tests differ from unit tests in Instatic?

While unit tests verify functional behavior of individual functions and components, architecture tests inspect file contents and directory structures using regular expressions and string scans. They enforce codebase-wide structural rules—such as banning specific import patterns or enforcing CSS token usage—by failing the build when violations are detected.

What happens when an architecture test detects a violation?

The test aggregates all violations into a descriptive error message and throws an exception, which causes bun test to exit with a failure status. This immediate feedback prevents developers from merging code that violates import conventions, styling policies, or security invariants into the main branch.

Why does Instatic ban Tailwind CSS and related utilities?

The no-tailwind-deps.test.ts test blocks Tailwind CSS and utility libraries like clsx and class-variance-authority to enforce a design-token-first styling approach. By requiring all styles to use CSS custom properties defined in globals.css, Instatic maintains consistent theming and avoids utility-class pollution that can lead to unmaintainable stylesheets.

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