🤖 Automated Architecture Checks

CASCADA provides automated tools to enforce strict architecture rules.

✅ Available Checks

1. Architecture Validator Script

Custom script that checks layer violations

bash

pnpm check:architecture

What it checks:

❌ PLATFORM importing from CORE
❌ PLATFORM importing from GAME
❌ CORE importing from GAME

Example output (violations found):

🔍 Checking architecture rules...

📦 Checking PLATFORM layer (1 files)...
📦 Checking CORE layer (16 files)...
📦 Checking GAME layer (10 files)...

============================================================

❌ Architecture violations found: 1

1. CORE → GAME
   File: src/core/ui/UIManager.ts:15
   Import: @game/scenes/TerritoryScene
   ✗ CORE cannot import from GAME (Core must be game-agnostic)

Fix these violations before committing!
See: docs/technical/strict-architecture.md

Example output (all good):

🔍 Checking architecture rules...

📦 Checking PLATFORM layer (1 files)...
📦 Checking CORE layer (16 files)...
📦 Checking GAME layer (10 files)...

============================================================

✅ Architecture check PASSED!
All layers respect hierarchy rules.

2. ESLint with Import Rules

Uses eslint-plugin-import for static analysis

bash

pnpm lint:eslint

Configuration in eslint.config.js (ESLint 9+):

javascript

export default [
  {
    files: ["src/**/*.{ts,tsx}"],
    rules: {
      // ⚠️ Enforce strict architecture
      "import/no-restricted-paths": [
        "error",
        {
          zones: [
            {
              target: "./src/platform",
              from: "./src/core",
              message: "PLATFORM cannot import from CORE",
            },
            {
              target: "./src/core",
              from: "./src/game",
              message: "CORE cannot import from GAME",
            },
          ],
        },
      ],
    },
  },
];

Catches violations at lint time:

IDE integration (VS Code shows errors)
CI/CD integration
Real-time feedback

3. Combined Lint Check

Runs architecture check + TypeScript check

bash

pnpm lint

This runs:

pnpm check:architecture - layer violations
tsc --noEmit - TypeScript errors

Use before committing!

🪝 Git Pre-Commit Hook

Automatic check on every commit

Husky runs architecture validation automatically:

bash

# Pre-commit hook (.husky/pre-commit)
pnpm check:architecture || exit 1

How it works:

bash

# You commit
git commit -m "Add new feature"

# Hook runs automatically
🔍 Checking architecture rules...
📦 Checking PLATFORM layer...
📦 Checking CORE layer...
📦 Checking GAME layer...

# If violations found:
❌ Architecture violations found!
Commit BLOCKED!

# If all good:
✅ Architecture check passed!
Commit proceeds ✅

You CANNOT commit code that violates architecture!

📋 Manual Checks (No Tools)

Quick Grep Checks

bash

# Check PLATFORM for violations
grep -r "@core\|@game" src/platform/
# Should return: (nothing)

# Check CORE for violations
grep -r "@game" src/core/
# Should return: (nothing)

# If anything found → VIOLATION!

Visual Studio Code

Install Dependency Cruiser extension:

bash

pnpm install -g dependency-cruiser

Create .dependency-cruiser.js:

javascript

module.exports = {
  forbidden: [
    {
      name: "platform-no-core",
      from: { path: "^src/platform" },
      to: { path: "^src/core" },
      comment: "Platform cannot depend on Core",
    },
    {
      name: "platform-no-game",
      from: { path: "^src/platform" },
      to: { path: "^src/game" },
    },
    {
      name: "core-no-game",
      from: { path: "^src/core" },
      to: { path: "^src/game" },
      comment: "Core must be game-agnostic",
    },
  ],
};

Run:

bash

depcruise --validate .dependency-cruiser.js src

🎯 CI/CD Integration

GitHub Actions

yaml

# .github/workflows/check-architecture.yml
name: Architecture Check

on: [push, pull_request]

jobs:
  architecture:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: pnpm/action-setup@v2
      - uses: actions/setup-node@v3
        with:
          node-version: "20"
          cache: "pnpm"

      - run: ppnpm install
      - run: pnpm check:architecture

      - name: Comment on PR if violations
        if: failure()
        uses: actions/github-script@v6
        with:
          script: |
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: '❌ Architecture violations detected! See logs for details.'
            })

📊 What Gets Checked

File Analysis

For each .ts file in src/:

Extract layer (platform/core/game)
Parse imports (from statements)
Check violations:
- Platform file imports @core/* → ❌ ERROR
- Platform file imports @game/* → ❌ ERROR
- Core file imports @game/* → ❌ ERROR
- Game file imports anything → ✅ OK

Import Patterns Detected

typescript

// All these patterns are checked:
import { X } from "@core/ui/UIManager";
import { Y } from "@game/scenes/MyScene";
import { Z } from "../core/systems/GameModeManager";
import { A } from "../../game/config/game.config";

// Even relative imports are caught!

🛠️ How the Script Works

Source: scripts/check-architecture.cjs

javascript

// 1. Find all .ts files in src/platform, src/core, src/game
const platformFiles = findTsFiles("src/platform");
const coreFiles = findTsFiles("src/core");
const gameFiles = findTsFiles("src/game");

// 2. For each file, extract layer
function getLayer(filePath) {
  if (filePath.includes("/platform/")) return "platform";
  if (filePath.includes("/core/")) return "core";
  if (filePath.includes("/game/")) return "game";
}

// 3. Check import statements
lines.forEach((line) => {
  const importMatch = line.match(/import.*from ["']([^"']+)["']/);

  if (layer === "platform" && importPath.includes("@core/")) {
    violations.push({
      message: "PLATFORM cannot import from CORE",
    });
  }

  // ... similar checks
});

// 4. Report violations or success
if (violations.length > 0) {
  console.log("❌ Architecture violations found");
  process.exit(1); // Blocks commit!
} else {
  console.log("✅ All good");
  process.exit(0);
}

🎓 Usage Examples

Before Committing

bash

# Manual check
pnpm check:architecture

# Full lint (includes architecture)
pnpm lint

# If violations → fix them!
# If passed → safe to commit

During Development

bash

# Watch mode (manual)
pnpm check:architecture

# Re-run after fixing imports
pnpm check:architecture

In CI/CD

bash

# In your CI pipeline
ppnpm install
pnpm check:architecture # Fails pipeline if violations
pnpm lint              # Includes architecture check
pnpm build

🚨 Common Violations & Fixes

Violation 1: Config in Wrong Layer

❌ Found:
File: src/platform/game.config.ts
Import: @game/scenes/BootScene
✗ PLATFORM cannot import from GAME

Fix:

bash

# Move game.config.ts to game layer
mv src/platform/game.config.ts src/game/config/phaser.config.ts

# Update imports in main.ts
# Before: import { gameConfig } from "@platform/game.config";
# After:  import { gameConfig } from "@game/config/phaser.config";

Why: Game config with scene imports = game-specific → belongs in GAME layer.

Violation 2: Core Using Game Types

❌ Found:
File: src/core/systems/EntityRegistry.ts
Import: @game/types
✗ CORE cannot import from GAME

Fix:

bash

# Move shared types to Core
mv src/game/types/Entity.ts src/core/types/Entity.ts

# Or create Core version
# core/types/Entity.ts (generic)
# game/types/Player.ts extends Entity (specific)

Violation 3: Utility in Wrong Place

❌ Found:
File: src/platform/utils/math.ts
Import: @core/config/constants
✗ PLATFORM cannot import from CORE

Fix:

bash

# Math utilities are universal → move to Core
mv src/platform/utils/math.ts src/core/utils/math.ts

📖 Integration with Documentation

All architecture rules documented in:

Automated checks enforce what documentation teaches.

🎯 Benefits

For Developers

✅ Catch violations early - before code review
✅ Learn architecture - errors teach correct patterns
✅ Confidence - know your code won't break architecture
✅ Fast feedback - check runs in <1 second

For Projects

✅ Enforce standards - automation never forgets
✅ Prevent regressions - can't accidentally break architecture
✅ Team alignment - everyone follows same rules
✅ Documentation stays accurate - code matches docs

For CI/CD

✅ Block bad PRs - violations fail CI
✅ Automatic checks - no manual review needed
✅ Fast pipeline - architecture check is quick
✅ Clear feedback - exact file and line numbers

🔧 Commands Reference

bash

# Check architecture only
pnpm check:architecture

# Full lint (architecture + TypeScript)
pnpm lint

# ESLint check
pnpm lint:eslint

# Install git hooks
pnpm prepare

# Test pre-commit hook
git commit -m "test" --dry-run

🚀 Summary

Architecture validation is AUTOMATED:

✅ Custom script (check-architecture.cjs)
✅ ESLint rules (.eslintrc.json)
✅ Pre-commit hook (.husky/pre-commit)
✅ Integrated in pnpm lint
✅ Ready for CI/CD

You can't break architecture by accident anymore! 🎯

Back to Architecture Rules • Project Structure

🤖 Automated Architecture Checks ​

✅ Available Checks ​

1. Architecture Validator Script ​

2. ESLint with Import Rules ​

3. Combined Lint Check ​

🪝 Git Pre-Commit Hook ​

📋 Manual Checks (No Tools) ​

Quick Grep Checks ​

Visual Studio Code ​

🎯 CI/CD Integration ​

GitHub Actions ​

📊 What Gets Checked ​

File Analysis ​

Import Patterns Detected ​

🛠️ How the Script Works ​

🎓 Usage Examples ​

Before Committing ​

During Development ​

In CI/CD ​

🚨 Common Violations & Fixes ​

Violation 1: Config in Wrong Layer ​

Violation 2: Core Using Game Types ​

Violation 3: Utility in Wrong Place ​

📖 Integration with Documentation ​

🎯 Benefits ​

For Developers ​

For Projects ​

For CI/CD ​

🔧 Commands Reference ​

🚀 Summary ​

🤖 Automated Architecture Checks

✅ Available Checks

1. Architecture Validator Script

2. ESLint with Import Rules

3. Combined Lint Check

🪝 Git Pre-Commit Hook

📋 Manual Checks (No Tools)

Quick Grep Checks

Visual Studio Code

🎯 CI/CD Integration

GitHub Actions

📊 What Gets Checked

File Analysis

Import Patterns Detected

🛠️ How the Script Works

🎓 Usage Examples

Before Committing

During Development

In CI/CD

🚨 Common Violations & Fixes

Violation 1: Config in Wrong Layer

Violation 2: Core Using Game Types

Violation 3: Utility in Wrong Place

📖 Integration with Documentation

🎯 Benefits

For Developers

For Projects

For CI/CD

🔧 Commands Reference

🚀 Summary