Skip to content

feat: programmatic architectural enforcement via ESLint boundaries #623

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
yanekyuk wants to merge 3 commits into from
Closed

feat: programmatic architectural enforcement via ESLint boundaries #623

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
8e97228
chore(protocol): suppress pre-existing boundary violations with eslin…
yanekyuk Apr 2, 2026
50b3b43
feat(protocol): add eslint-plugin-boundaries for architectural enforc…
yanekyuk Apr 2, 2026
566c3d2
feat: add lint-staged, pre-commit hook, CI workflow, and adapter nami…
yanekyuk Apr 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 55 additions & 0 deletions .github/workflows/lint.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
# Run architectural boundary checks on PRs to dev.
#
# Enforces protocol layering rules (eslint-plugin-boundaries)
# and adapter naming conventions.
#
# NOTE: Only boundary violations fail the check. Pre-existing lint
# errors (no-explicit-any, no-unused-vars) are not gated here yet.
# Full lint enforcement is tracked separately.
name: Lint

on:
pull_request:
branches: [dev]

concurrency:
group: lint-${{ github.head_ref }}
cancel-in-progress: true

jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4

- uses: oven-sh/setup-bun@v2
with:
bun-version: "1.2.20"

- name: Install dependencies
run: |
bun install
cd protocol && bun install

- name: Check architectural boundaries
run: |
cd protocol
bunx eslint src/ --format json 2>/dev/null | bun -e '
const results = JSON.parse(await Bun.stdin.text());
const violations = results
.flatMap(r => r.messages.filter(m => m.ruleId === "boundaries/dependencies"))
.map((m, i, _, r = results.find(r2 => r2.messages.includes(m))) =>
`${r?.filePath}:${m.line} - ${m.message}`
);
if (violations.length > 0) {
console.log("❌ Architectural boundary violations found:\n");
violations.forEach(v => console.log(` ${v}`));
console.log(`\n${violations.length} violation(s) total.`);
process.exit(1);
} else {
console.log("✅ No architectural boundary violations.");
}
'
Comment on lines +34 to +52
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot Apr 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

cat <<'JSON' | bun -e '
const results = JSON.parse(await Bun.stdin.text());
const violations = results
  .flatMap(r => r.messages.filter(m => m.ruleId === "boundaries/dependencies"))
  .map((m, i, _, r = results.find(r2 => r2.messages.includes(m))) =>
    `${r?.filePath}:${m.line} - ${m.message}`
  );
if (violations.length > 0) process.exit(1);
console.log("workflow snippet exits 0");
'
[
  {
    "filePath": "src/broken.ts",
    "messages": [
      { "ruleId": null, "fatal": true, "line": 1, "message": "Parsing error: Unexpected token" }
    ]
  }
]
JSON

Repository: indexnetwork/index

Length of output: 105

🏁 Script executed:

cat -n .github/workflows/lint.yml | sed -n '30,55p'

Repository: indexnetwork/index

Length of output: 1308

🏁 Script executed:

# Search for any tests or documentation about the workflow behavior
fd -t f '*.ts' -o '*.js' -o '*.md' | xargs rg -l 'eslint|lint.yml' | head -20

Repository: indexnetwork/index

Length of output: 1058

🏁 Script executed:

# Look for ESLint configuration in the protocol directory
fd -t f '.eslintrc*' 'eslint.config*' -o '*.json' | rg -B 1 -A 1 'eslint|boundaries'

Repository: indexnetwork/index

Length of output: 193

🏁 Script executed:

# Check if there's eslint configuration in protocol directory
ls -la protocol/ | head -20

Repository: indexnetwork/index

Length of output: 1248

🏁 Script executed:

# Look for ESLint rules configuration, especially boundaries rule
fd -t f . protocol | rg -l 'eslint.*config|boundaries' | head -10

Repository: indexnetwork/index

Length of output: 69

🏁 Script executed:

cat -n protocol/eslint.config.mjs | head -100

Repository: indexnetwork/index

Length of output: 4165

🏁 Script executed:

# Search for boundaries rule configuration
rg -A 5 -B 5 'boundaries' protocol/eslint.config.mjs

Repository: indexnetwork/index

Length of output: 1652

🏁 Script executed:

# Look for any test files that might validate the workflow
fd -t f '.spec.ts' 'test.ts' | xargs rg -l 'fatal|parser.*error' 2>/dev/null | head -10

Repository: indexnetwork/index

Length of output: 610

🏁 Script executed:

# Look for any other workflow files or scripts that might handle eslint output
fd -t f 'workflow' '.yml' '.yaml' | xargs rg -l 'eslint' 2>/dev/null

Repository: indexnetwork/index

Length of output: 1258

🏁 Script executed:

# Search for how eslint fatal errors are typically handled
rg -i 'fatal|parser.*error' protocol/ | head -20

Repository: indexnetwork/index

Length of output: 2439

🏁 Script executed:

# Check if there's any documentation about the architecture check
cat docs/superpowers/specs/2026-04-02-architectural-enforcement-design.md | head -150

Repository: indexnetwork/index

Length of output: 4968

Fail this job on ESLint fatal/parser errors.

The step filters ESLint JSON output to only catch ruleId === "boundaries/dependencies" violations. Parser/fatal errors have ruleId: null and are not caught by this filter, allowing malformed TypeScript to pass the check.

Suggested guard 
           const results = JSON.parse(await Bun.stdin.text());
+          const fatals = results
+            .flatMap(r => r.messages
+              .filter(m => m.fatal)
+              .map(m => `${r.filePath}:${m.line} - ${m.message}`));
           const violations = results
             .flatMap(r => r.messages.filter(m => m.ruleId === "boundaries/dependencies"))
             .map((m, i, _, r = results.find(r2 => r2.messages.includes(m))) =>
               `${r?.filePath}:${m.line} - ${m.message}`
             );
+          if (fatals.length > 0) {
+            console.log("❌ ESLint fatal errors found:\n");
+            fatals.forEach(v => console.log(`  ${v}`));
+            process.exit(1);
+          }
           if (violations.length > 0) {
🧰 Tools
🪛 actionlint (1.7.11)

[error] 35-35: shellcheck reported issue in this script: SC2016:info:2:53: Expressions don't expand in single quotes, use double quotes for that

(shellcheck)

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In @.github/workflows/lint.yml around lines 34 - 52, The current filter only
captures messages where m.ruleId === "boundaries/dependencies" and misses
parser/fatal errors (m.ruleId === null); update the processing of results in the
"Check architectural boundaries" step to also treat messages with m.fatal ===
true as violations (e.g., include m.fatal in the filter alongside the existing
ruleId check), ensure those fatal messages are collected into the violations
array and printed with filePath, line and message, and keep the existing
process.exit(1) when any violations (including fatal/parser errors) are present.


- name: Check adapter naming conventions
run: ./scripts/check-adapter-names.sh
72 changes: 72 additions & 0 deletions bun.lock
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

7 changes: 7 additions & 0 deletions package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,5 +19,12 @@
"worktree:list": "bash scripts/worktree-list.sh",
"worktree:dev": "bash scripts/worktree-dev.sh",
"worktree:build": "bash scripts/worktree-build.sh"
},
"devDependencies": {
"lint-staged": "^16.4.0"
},
"lint-staged": {
"protocol/src/**/*.ts": "eslint --no-warn-ignored",
"frontend/src/**/*.{ts,tsx}": "eslint --no-warn-ignored"
}
}
Loading
Loading