aws-samples / aws-samples/sample-autonomous-cloud-coding-agents

feat(ci): mechanical module-boundary enforcement (eslint-plugin-boundaries/dependency-cruiser + madge) (CA-03)

Offen
#254 0 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen
tooling validation-loop
Vorherrschende Sprache
TypeScript
Sterne
143
Forks
46
Ø Merge
3 T. 10 Std.
Gemergte PRs (30 T.)
24

Beschreibung

> **This is a finding from https://github.com/krokoko/cairn** (action item **CA-03**).

### Component

Tooling / CI

### Describe the feature

Add **mechanical module-boundary enforcement** that encodes the `AGENTS.md` routing table as code, using `eslint-plugin-boundaries` or `dependency-cruiser`, plus `madge --circular` for circular-dependency detection. Start the boundary rules in **warn** mode, snapshot the current baseline, then flip to **error** once the baseline is clean.

Boundaries to enforce (from `AGENTS.md`):

- Handler layer (`cdk/src/handlers/`) can't import stack/construct internals (`cdk/src/stacks/`, `cdk/src/constructs/`).
- CLI (`cli/src/`) can't import CDK internals.
- No circular dependencies anywhere.

### Use case

The `AGENTS.md` layering rules are **prose, not mechanically enforced** (AI007 / AI003). Nothing stops an agent — or a human — from introducing an import that violates the intended architecture, and circular dependencies go undetected. A boundary linter turns the routing table into a binding fitness function that catches architectural drift at PR time instead of in review.

### Proposed solution

1. Add `eslint-plugin-boundaries` (or `dependency-cruiser`) to `cdk` / `cli` and encode the `AGENTS.md` routing table as boundary rules.
2. Add `madge --circular` as a fast check (pre-commit + CI).
3. Land the rules in **warn** mode; record the current violation baseline.
4. Once the baseline is clean, flip to **error** and add to the required `build` check.

### Acceptance criteria

- [ ] Boundary rules encode the `AGENTS.md` routing table (handler↛stack/construct internals; CLI↛CDK internals).
- [ ] `madge --circular` runs in pre-commit and CI; zero circular deps in the clean baseline.
- [ ] Rules start in **warn**; baseline violations are documented.
- [ ] A follow-up flips clean rules to **error** in the required `build` check.
- [ ] Remediation text on failures is agent-targeted (what to fix, not just what failed).

### Other information

Source reports: `readiness-roadmap.md`, `verification-strategy.md` (§"Architecture Fitness Functions", maturity 0→3), `ai-smells-gates-report.md` (AI003/AI007). Effort: **S–M**. Calibrate permissively — agents route around hard blockers, so introduce the error line only after the code is behind it. Per ADR-003 this issue needs the `approved` label before work begins.

Beitragsleitfaden

Beitragsleitfaden öffnen

Rechercherichtung

Beginne mit dem Lesen von AGENTS.md und den Architekturabschnitten in readiness-roadmap.md und verification-strategy.md. Untersuche die Imports unter cdk/src/handlers/, cdk/src/stacks/, cdk/src/constructs/ und cli/src/ und führe dann madge --circular aus, um die Ausgangsbasis festzulegen. Als abgeschlossen gilt die Aufgabe, wenn die Grenzregeln und die Prüfung auf zirkuläre Abhängigkeiten in pre-commit und CI ausgeführt werden, mit dokumentierten Warnungen, Text zur Behebung und einem Pfad zur erforderlichen Build-Erzwingung.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Tech-Stack
eslint, typescript
Bereich
build-system, ci-cd, tooling
Issue-Typ
Feature
Schwierigkeit
4/5
Geschätzter Aufwand
3-5 Tage
Aktivitätsstatus
Ruhig
Klarheit
Größtenteils klar
Anfängerfreundlichkeit
48/100

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.