Cordon Modulith 0.1

.gitattributes

@@ -0,0 +1,12 @@
+* text=auto eol=lf
+
+/.github            export-ignore
+/docs               export-ignore
+/tests              export-ignore
+/.gitattributes     export-ignore
+/.gitignore         export-ignore
+/phpunit.xml        export-ignore
+/phpstan.neon.dist  export-ignore
+/pint.json          export-ignore
+/AGENTS.md          export-ignore
+/docs-site          export-ignore

.github/workflows/docs.yml

@@ -0,0 +1,48 @@
+name: docs
+
+on:
+  push:
+    branches: [main]
+    paths: ['docs-site/**']
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: docs-site
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: docs-site/package-lock.json
+
+      - run: npm ci
+      - run: npm run build
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs-site/.vitepress/dist
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/tests.yml

@@ -0,0 +1,71 @@
+name: tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        php: ['8.3', '8.4']
+        laravel: ['12.*', '13.*']
+        include:
+          - laravel: '12.*'
+            testbench: '10.*'
+          - laravel: '13.*'
+            testbench: '11.*'
+
+    name: PHP ${{ matrix.php }} / Laravel ${{ matrix.laravel }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php }}
+          coverage: none
+
+      - name: Install dependencies
+        run: |
+          composer require "illuminate/support:${{ matrix.laravel }}" "illuminate/console:${{ matrix.laravel }}" "illuminate/contracts:${{ matrix.laravel }}" "orchestra/testbench:${{ matrix.testbench }}" --no-interaction --no-update
+          composer update --prefer-dist --no-interaction
+
+      - name: Tests
+        run: vendor/bin/pest
+
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.4'
+          coverage: none
+
+      - run: composer update --prefer-dist --no-interaction
+
+      - name: Code style
+        run: vendor/bin/pint --test
+
+      - name: Static analysis
+        run: vendor/bin/phpstan analyse
+
+  benchmark:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.4'
+          coverage: none
+
+      - run: composer update --prefer-dist --no-interaction
+
+      - name: 1,000 files in less than 10 seconds
+        run: composer bench

.gitignore

@@ -0,0 +1,7 @@
+/vendor
+composer.lock
+.phpunit.result.cache
+.phpunit.cache
+.idea
+.vscode
+.DS_Store

AGENTS.md

@@ -0,0 +1,23 @@
+# Instructions for AI coding agents
+
+This file is for AI agents (and agent swarms) working on the Cordon Modulith codebase.
+
+## Project in one paragraph
+
+Cordon Modulith is a Laravel dev-dependency that verifies boundaries between modules. It statically parses PHP files (nikic/php-parser, never loading code), maps class references to modules, and runs rules (`internal_access`, `undeclared_dependency`, `cycles`). Entry points: `php artisan cordon:verify` (and `cordon:docs`), the Pest expectation `toRespectBoundaries()` and the PHPStan rule. Pipeline: `ModuleResolver` → `FileCollector` → `DependencyExtractor` → `Analyzer` (cross-module edges) → `Rule`s → `Baseline` → `Reporter`.
+
+## Hard rules
+
+1. **Contracts are frozen.** Do not change interfaces in `src/Contracts`, value objects in `src/Analysis` and `src/Module`, the config shape, the baseline JSON format or command options without an accepted ADR in `docs/adr`. If you believe a change is needed, stop and write the ADR proposal instead.
+2. **Tests first.** Write or update the acceptance test before the implementation. Every detection change needs a fixture in `tests/Fixtures`.
+3. **Never load analysed code.** No `class_exists`, `require`, reflection or autoloading of user code in `src/`.
+4. **Zero false positives.** When unsure whether something is a dependency, don't report it and document the limitation.
+5. **Do not edit `tests/Fixtures` line layout** without updating the tests that assert line numbers.
+6. **Stay in your lane.** Swarms only touch the files listed in their brief (`docs/plan/enjambres/`). Integration across swarms is done by the maintainer.
+7. **Quality gate:** `composer check` (Pint, PHPStan, Pest) must pass before you open a pull request.
+
+## Conventions
+
+- PHP 8.3, `declare(strict_types=1)`, `final` classes, `readonly` value objects.
+- The analysis core (`src/Analysis`, `src/Module`, `src/Rules`, `src/Resolvers`, `src/Reporters`, `src/Baseline`, `src/Support`, `src/Documentation`) must stay framework-agnostic. Only the integration layers (`src/Laravel`, `src/Testing`, `src/PHPStan`) may use Laravel.
+- User-facing messages: one sentence stating the problem plus one stating the fix.

CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to Cordon Modulith are documented here. The project follows [Semantic Versioning](https://semver.org) from 1.0.0; before that, minor versions may contain breaking changes.
+
+## [Unreleased] - 0.1.0
+
+### Added
+- `cordon:verify` command with `text`, `json` and `github` output formats.
+- `cordon:modules` command to inspect the detected modules.
+- Module resolvers for plain namespaces, nwidart/laravel-modules and InterNACHI/modular, with auto-detection.
+- Static dependency extraction with nikic/php-parser (the analysed code is never loaded).
+- Rules: `internal_access`, `undeclared_dependency`, `cycles`.
+- Public API model: public namespaces, `#[PublicApi]`, `#[Internal]`, per-module `public` list and `open` modules.
+- Baseline file for gradual adoption (`--generate-baseline`, `--no-baseline`).
+- Laravel Boost guideline for AI coding agents.
+- `--module` option for `cordon:verify` to report the violations of one or more modules.
+- Pest expectation `toRespectBoundaries()` and `Cordon\Testing\Cordon::modules()`.
+- PHPStan rule `cordon.internalAccess` (`extension.neon`), reading `config/cordon.php` without booting Laravel.
+- Reusable GitHub Action (`action.yml`).
+- `cordon:docs` command: Mermaid dependency diagrams, a canvas per module and an event inventory.
+- `cordon:verify` and `cordon:docs` warn on stderr when Xdebug is active, since it makes the analysis several times slower.
+- Custom rules: classes implementing `Cordon\Contracts\Rule` in the `rules` config.
+- Laravel Boost skill `cordon-fix-violations`.
+- Documentation site (`docs-site/`), benchmark (`composer bench`) and real-project fixtures.
+
+### Fixed
+- Commands read the config through the repository contract (PHPStan level 8).

CONTRIBUTING.md

@@ -0,0 +1,30 @@
+# Contributing
+
+Thanks for helping make module boundaries in Laravel verifiable.
+
+## Setup
+
+```bash
+git clone https://github.com/ChrisAbner/Cordon-Modulith.git cordon-modulith && cd cordon-modulith
+composer install
+composer check   # pint --test, phpstan, pest
+composer bench   # analyses a synthetic project of 1,000 files; fails above 10 s
+```
+
+`php tests/Benchmark/run.php 5000 50` runs a larger benchmark (files, modules, optional time budget in seconds).
+
+## Pull requests
+
+- One topic per pull request, with tests. Bug fixes start with a failing test.
+- New detection behaviour needs a fixture under `tests/Fixtures` that reproduces a real project layout.
+- Run `composer format` before pushing. `tests/Fixtures` is excluded from Pint on purpose, because tests assert line numbers.
+- Changes to anything in `src/Contracts`, the config file shape, the baseline format or command options are public API changes: open a discussion or an ADR in `docs/adr` first.
+- Keep false positives at zero. A rule that reports correct code is a bug.
+
+## Reporting bugs
+
+Please open a pull request with a failing test or fixture, even if you don't have the fix. Pull requests written with the help of a coding agent are welcome; see [AGENTS.md](AGENTS.md).
+
+## Security
+
+Please report security issues privately to the maintainers instead of opening a public issue.

LICENSE.md

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Cordon Modulith contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.