Add BC aliases, feature/wizard commands, architect.json, lint and analyze

Phase A:
- Deprecated Base* aliases (BaseRepository, BaseService, BaseData,
  BaseFormRequest, Action, QueryFilter) extending the Architect* classes
  so pre-1.2 apps survive composer update
- policy, seeder and test patterns with generators and stubs
- architect:feature command (make:module + feature_extras)
- architect:new interactive wizard
- architect.json project-level config overrides (TeamConfig)
- {module} namespace placeholder for domain/modular layouts

Phase B:
- architect:lint with four convention rules (LintRule contract,
  configurable via lint.rules), exit 1 on violations for CI
- architect:analyze layer counts + hotspot report with configurable
  thresholds

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: 2 people

CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.3.0] - 2026-07-22
+
+### Added
+
+- Backwards-compatibility aliases for the classes renamed in 1.2.0: `BaseRepository`, `BaseService`, `BaseData`, `BaseFormRequest`, `Action` and `QueryFilter` still resolve (deprecated, removal planned for 2.0), so existing apps keep working after `composer update`.
+- `policy`, `seeder` and `test` patterns with matching generators and stubs.
+- `architect:feature` command — `make:module` plus the `generation.feature_extras` patterns (policy, seeder, feature test by default).
+- `architect:new` interactive wizard that asks for name, preset, UI, fields and extras, then generates the module.
+- `architect.json` project-level config: a JSON file at the application root that deep-merges over the package config, so teams can version their conventions.
+- `{module}` placeholder in namespace config for domain/modular layouts (e.g. `App\Domain\{module}\Services`).
+- `generation.user_model` config used by generated policies.
+- `architect:lint` command — CI-friendly convention checker (exit code 1 on violations) with four built-in rules: no Eloquent/DB calls in controllers, no repositories injected into controllers, no inline validation in controllers, and models must not depend on the HTTP/service layer. Rules implement `Contracts\LintRule` and are registered in `lint.rules`, so teams can add their own.
+- `architect:analyze` command — read-only report of layer counts (controllers, models, services, repositories, actions, form requests) and hotspots: classes exceeding the configurable `lint.thresholds` for public methods, constructor dependencies and file length.
+
 ## [1.2.0] - 2026-07-22
 
 ### Added
@@ -70,7 +84,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Support for Laravel 11, 12 and 13 (PHP 8.2 – 8.5, per framework requirements).
 - Full test suite (PHPUnit via Orchestra Testbench), PHPStan level 5 (Larastan) and Laravel Pint.
 
-[Unreleased]: https://github.com/gubakareem/lara-architect/compare/v1.2.0...HEAD
+[Unreleased]: https://github.com/gubakareem/lara-architect/compare/v1.3.0...HEAD
+[1.3.0]: https://github.com/gubakareem/lara-architect/releases/tag/v1.3.0
 [1.2.0]: https://github.com/gubakareem/lara-architect/releases/tag/v1.2.0
 [1.1.0]: https://github.com/gubakareem/lara-architect/releases/tag/v1.1.0
 [1.0.0]: https://github.com/gubakareem/lara-architect/releases/tag/v1.0.0

README.md

@@ -1,9 +1,10 @@
 # LaraArchitect
 
-An architecture toolkit for Laravel. It gives you two things:
+An architecture toolkit for Laravel. It gives you three things:
 
 1. **Runtime building blocks** — lean base classes for repositories (with full soft-delete support), CRUD services, single-purpose actions, request-driven query filters, data transfer objects, form requests and JSON responses, so business logic stays out of your controllers.
-2. **A dynamic module generator** — one `make:module` command that scaffolds an entire feature (model, migration, factory, enums, service/actions, filter, requests, resource, controller) using **configurable architecture presets**. Prefer actions over services? Repository pattern? Your own preset? It is all config.
+2. **A dynamic module generator** — one `make:module` command (plus `architect:feature` for policy/seeder/test, and the `architect:new` interactive wizard) that scaffolds an entire feature using **configurable architecture presets**. Prefer actions over services? Repository pattern? Domain layout? Your own preset? It is all config — versionable per team via `architect.json`.
+3. **Architecture guardrails** — `architect:lint` fails CI when conventions are broken (Eloquent in controllers, inline validation, inverted dependencies) and `architect:analyze` reports layer counts and hotspots.
 
 ```bash
 php artisan make:module Product --fields="name:string, price:decimal, sku:string:unique, status:enum, notes:text:nullable"
@@ -53,7 +54,11 @@ Published stubs live in `stubs/lara-architect/` and always win over the package
 php artisan architect:patterns
 ```
 
-**2.** Generate a module (add `--dry-run` first to preview without writing). Default is **API** (JsonResource + `Http\Controllers\Api`). Use `--ui=web` for Blade:
+**2.** Generate a module (add `--dry-run` first to preview without writing). Default is **API** (JsonResource + `Http\Controllers\Api`). Use `--ui=web` for Blade. Not sure which flags you want? Run the interactive wizard instead:
+
+```bash
+php artisan architect:new
+```
 
 ```bash
 # API (default) — controller under App\Http\Controllers\Api + ProductResource
@@ -120,8 +125,16 @@ php artisan make:module Order --architecture=actions --fields="total:decimal, st
 
 # Or hand-pick patterns — no preset needed
 php artisan make:module Tag --patterns=model,migration,resource,controller --fields="name:string:unique"
+
+# Complete feature: preset patterns + policy + seeder + feature test
+php artisan architect:feature Product --fields="name:string, price:decimal"
+
+# Interactive wizard — answers a few questions, then generates
+php artisan architect:new
 ```
 
+`architect:feature` accepts the same flags as `make:module` and appends the patterns listed in `generation.feature_extras` (`policy`, `seeder`, `test` by default), so one command ships a model with a passing test, a seeder wired to the factory, and a policy ready to register.
+
 Other useful flags:
 
 | Flag | Effect |
@@ -193,6 +206,57 @@ Every pattern is a class implementing `KarimAshraf\LaraArchitect\Contracts\Gener
 php artisan make:module Invoice --architecture=my-team-style
 ```
 
+### Team conventions with `architect.json`
+
+Commit an `architect.json` at your project root to version your team's conventions without publishing the package config. Anything under it deep-merges over `config/lara-architect.php` when the generator runs:
+
+```json
+{
+    "generation": {
+        "default_architecture": "actions",
+        "default_ui": "api",
+        "namespaces": {
+            "service": "App\\Domain\\{module}\\Services",
+            "repository": "App\\Domain\\{module}\\Repositories"
+        }
+    }
+}
+```
+
+### Domain / modular layouts
+
+Namespace values support a `{module}` placeholder that is replaced with the model name, so you can generate into a domain-oriented structure:
+
+```php
+'namespaces' => [
+    'service'    => 'App\\Domain\\{module}\\Services',     // App\Domain\Product\Services\ProductService
+    'repository' => 'App\\Domain\\{module}\\Repositories', // App\Domain\Product\Repositories\ProductRepository
+],
+```
+
+## Architecture lint & analysis
+
+Generating a clean structure is half the job — keeping it clean is the other half. Two read-only commands help with that:
+
+```bash
+# Fails (exit code 1) when conventions are broken — wire it into CI
+php artisan architect:lint
+
+# Layer counts + hotspots (long classes, fat constructors, God services)
+php artisan architect:analyze
+```
+
+`architect:lint` ships with four rules, each a class implementing `Contracts\LintRule` (register your own in `lint.rules`):
+
+| Rule | Catches |
+| --- | --- |
+| `no-eloquent-in-controllers` | Controllers calling `Model::create/update/where(...)` or the `DB` facade directly |
+| `no-repositories-in-controllers` | Controllers injecting repositories instead of services/actions |
+| `no-inline-validation-in-controllers` | `$request->validate(...)` / `Validator::make(...)` instead of form requests |
+| `models-do-not-depend-on-http` | Models importing controllers, form requests or services |
+
+`architect:analyze` reports how many controllers/models/services/repositories/actions exist and flags classes above the configurable thresholds (`lint.thresholds`): more than 8 public methods, more than 5 constructor dependencies, or files longer than 300 lines.
+
 ## Runtime building blocks
 
 ### Repository

config/lara-architect.php

@@ -2,6 +2,10 @@
 
 declare(strict_types=1);
 
+use KarimAshraf\LaraArchitect\Analysis\Rules\ModelsDoNotDependOnHttpRule;
+use KarimAshraf\LaraArchitect\Analysis\Rules\NoEloquentInControllersRule;
+use KarimAshraf\LaraArchitect\Analysis\Rules\NoInlineValidationInControllersRule;
+use KarimAshraf\LaraArchitect\Analysis\Rules\NoRepositoriesInControllersRule;
 use KarimAshraf\LaraArchitect\Generation\Generators\ActionsGenerator;
 use KarimAshraf\LaraArchitect\Generation\Generators\ControllerGenerator;
 use KarimAshraf\LaraArchitect\Generation\Generators\DtoGenerator;
@@ -10,10 +14,13 @@
 use KarimAshraf\LaraArchitect\Generation\Generators\FilterGenerator;
 use KarimAshraf\LaraArchitect\Generation\Generators\MigrationGenerator;
 use KarimAshraf\LaraArchitect\Generation\Generators\ModelGenerator;
+use KarimAshraf\LaraArchitect\Generation\Generators\PolicyGenerator;
 use KarimAshraf\LaraArchitect\Generation\Generators\RepositoryGenerator;
 use KarimAshraf\LaraArchitect\Generation\Generators\RequestsGenerator;
 use KarimAshraf\LaraArchitect\Generation\Generators\ResourceGenerator;
+use KarimAshraf\LaraArchitect\Generation\Generators\SeederGenerator;
 use KarimAshraf\LaraArchitect\Generation\Generators\ServiceGenerator;
+use KarimAshraf\LaraArchitect\Generation\Generators\TestGenerator;
 use KarimAshraf\LaraArchitect\Generation\Generators\ViewsGenerator;
 
 return [
@@ -81,8 +88,20 @@
             'resource' => ResourceGenerator::class,
             'views' => ViewsGenerator::class,
             'controller' => ControllerGenerator::class,
+            'policy' => PolicyGenerator::class,
+            'seeder' => SeederGenerator::class,
+            'test' => TestGenerator::class,
         ],
 
+        /*
+        | Extra patterns appended by `architect:feature` on top of the chosen
+        | architecture preset, so a feature ships complete in one command.
+        */
+        'feature_extras' => ['policy', 'seeder', 'test'],
+
+        // Model used by generated policies.
+        'user_model' => 'App\\Models\\User',
+
         /*
         | Target namespaces per generated class type. Paths are derived from
         | these namespaces (App\ => app/, Database\ => database/).
@@ -101,6 +120,9 @@
             'request' => 'App\\Http\\Requests',
             'resource' => 'App\\Http\\Resources',
             'factory' => 'Database\\Factories',
+            'policy' => 'App\\Policies',
+            'seeder' => 'Database\\Seeders',
+            'test' => 'Tests\\Feature',
         ],
     ],
 
@@ -169,4 +191,34 @@
             'errors' => 'errors',
         ],
     ],
+
+    /*
+    |--------------------------------------------------------------------------
+    | Architecture Lint & Analysis
+    |--------------------------------------------------------------------------
+    |
+    | `architect:lint` checks the paths below against the registered rules
+    | (each implements Contracts\LintRule — add your own to extend it) and
+    | fails when violations are found, so it can run in CI.
+    | `architect:analyze` reports layer counts and hotspots using the
+    | thresholds below.
+    |
+    */
+
+    'lint' => [
+        'paths' => ['app'],
+
+        'rules' => [
+            NoEloquentInControllersRule::class,
+            NoRepositoriesInControllersRule::class,
+            NoInlineValidationInControllersRule::class,
+            ModelsDoNotDependOnHttpRule::class,
+        ],
+
+        'thresholds' => [
+            'public_methods' => 8,
+            'constructor_dependencies' => 5,
+            'file_lines' => 300,
+        ],
+    ],
 ];

docs/getting-started.md

@@ -489,4 +489,22 @@ php artisan vendor:publish --tag=lara-architect-stubs
 # edit stubs/lara-architect/*.stub
 ```
 
-Change target namespaces (e.g. put models in `App\Domain\Models`) under `generation.namespaces` in the config. Add your own pattern by writing a class that implements `KarimAshraf\LaraArchitect\Contracts\Generator`, registering it under `generation.generators`, and adding it to a preset — see [Extending the generator](../README.md#extending-the-generator).
+Change target namespaces (e.g. put models in `App\Domain\Models`) under `generation.namespaces` in the config. Namespace values support a `{module}` placeholder for domain layouts — `App\Domain\{module}\Services` generates `App\Domain\Product\Services\ProductService`. Add your own pattern by writing a class that implements `KarimAshraf\LaraArchitect\Contracts\Generator`, registering it under `generation.generators`, and adding it to a preset — see [Extending the generator](../README.md#extending-the-generator).
+
+## 10. More commands
+
+```bash
+# Interactive wizard — asks for name, preset, UI and fields, then generates
+php artisan architect:new
+
+# make:module + policy + seeder + feature test in one go
+php artisan architect:feature Product --fields="name:string, price:decimal"
+
+# Check the app against the architecture conventions (CI-friendly, exit 1 on violations)
+php artisan architect:lint
+
+# Layer counts and hotspot report (fat controllers, God services, oversized files)
+php artisan architect:analyze
+```
+
+Team conventions can be committed as an `architect.json` file at the project root; it deep-merges over the package config whenever these commands run — see [Team conventions with architect.json](../README.md#team-conventions-with-architectjson).

src/Actions/Action.php

@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KarimAshraf\LaraArchitect\Actions;
+
+/**
+ * Backwards-compatibility alias kept so applications generated before v1.2
+ * keep working after `composer update`.
+ *
+ * @deprecated Use ArchitectAction instead. Will be removed in v2.0.
+ */
+abstract class Action extends ArchitectAction {}

src/Analysis/CodeScanner.php

@@ -0,0 +1,46 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KarimAshraf\LaraArchitect\Analysis;
+
+use Illuminate\Filesystem\Filesystem;
+
+class CodeScanner
+{
+    public function __construct(
+        private readonly Filesystem $files,
+    ) {}
+
+    /**
+     * Scan the given paths (relative to the application root) for PHP files.
+     *
+     * @param  list<string>  $paths
+     * @return list<ScannedFile>
+     */
+    public function scan(array $paths): array
+    {
+        $scanned = [];
+
+        foreach ($paths as $path) {
+            $absolute = base_path($path);
+
+            if (! $this->files->isDirectory($absolute)) {
+                continue;
+            }
+
+            foreach ($this->files->allFiles($absolute) as $file) {
+                if ($file->getExtension() !== 'php') {
+                    continue;
+                }
+
+                $scanned[] = new ScannedFile(
+                    $file->getPathname(),
+                    $this->files->get($file->getPathname()),
+                );
+            }
+        }
+
+        return $scanned;
+    }
+}

src/Analysis/Rules/ModelsDoNotDependOnHttpRule.php

@@ -0,0 +1,50 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KarimAshraf\LaraArchitect\Analysis\Rules;
+
+use KarimAshraf\LaraArchitect\Analysis\ScannedFile;
+use KarimAshraf\LaraArchitect\Analysis\Violation;
+use KarimAshraf\LaraArchitect\Contracts\LintRule;
+
+/**
+ * Dependency direction: the HTTP layer and services may depend on models,
+ * never the other way around. A model importing controllers, requests or
+ * services signals inverted coupling.
+ */
+class ModelsDoNotDependOnHttpRule implements LintRule
+{
+    private const FORBIDDEN_SEGMENTS = ['\\Http\\Controllers\\', '\\Http\\Requests\\', '\\Services\\'];
+
+    public function name(): string
+    {
+        return 'models-do-not-depend-on-http';
+    }
+
+    public function check(ScannedFile $file): array
+    {
+        if (! $file->isModel()) {
+            return [];
+        }
+
+        $violations = [];
+
+        foreach ($file->imports as $import) {
+            foreach (self::FORBIDDEN_SEGMENTS as $segment) {
+                if (str_contains('\\'.$import, $segment)) {
+                    $violations[] = new Violation(
+                        $this->name(),
+                        $file->path,
+                        $file->firstLineOf($import),
+                        sprintf('Model imports [%s]; models must not depend on the HTTP or service layer.', $import),
+                    );
+
+                    break;
+                }
+            }
+        }
+
+        return $violations;
+    }
+}