@morriconeluca/eslint-plugin-faf 0.4.0 → 0.6.0

package/README.md

@@ -1,66 +1,63 @@
 # @morriconeluca/eslint-plugin-faf
 
-An ESLint plugin to deterministically enforce the rules and constraints of the **[Fractal Architecture Framework (FAF)](https://github.com/morriconeluca/fractal-architecture-framework)**.
+Official ESLint plugin for validating codebases against the **Fractal Architecture Framework (FAF)** specification.
 
-This plugin is designed for complex TypeScript/JavaScript codebases to ensure **predictability**, **testability**, and strict **isolation** of dependency flows. It is fully compatible with modern ESLint flat configurations (ESLint v9 and v10).
+`eslint-plugin-faf` enforces strict structural, classification, symbol, dependency, and acyclicity invariants across codebases using deterministic static analysis.
 
 ---
 
-## Features
+## Requirements
 
-- **Strict Enforcing of FAF Taxonomy**: Ensures your folder structure strictly maps to Layers, Categories, Fragments, and Fractal Branches.
-- **Law of Separation between Peers**: Prevents lateral dependency coupling between sibling modules without explicit hierarchy.
-- **Access Node Encapsulation**: Guarantees that internal Fragment files are never imported directly, enforcing consumption solely through the Fragment's barrel file (`index.ts`).
-- **High-Performance Architecture**: Features optimized caching (`dirCache`, `classifyCache`, `rolesCache`) to minimize disk I/O during linting runs.
+- **Node.js**: `>= 24.0.0` (required for native TypeScript type stripping)
+- **ESLint**: `^9.0.0 || ^10.0.0` (flat configuration)
 
 ---
 
-## Companion Tooling
-
-`eslint-plugin-faf` does not detect dependency cycles. FAF requires the dependency graph to be a Directed Acyclic Graph, but enforcing that is intentionally left to dedicated tools, configured separately in your project:
+## Installation
 
-- [`eslint-plugin-import-x`](https://github.com/un-ts/eslint-plugin-import-x)'s `import-x/no-cycle` rule.
-- [`dependency-cruiser`](https://github.com/sverweij/dependency-cruiser), for cycle detection and other custom dependency fitness functions.
+```bash
+npm install --save-dev @morriconeluca/eslint-plugin-faf eslint
+```
 
 ---
 
-## Installation
+## ESLint Flat Configuration
 
-Install the plugin along with its peer dependencies:
+`eslint-plugin-faf` exposes a single, unified, zero-option rule: `faf/conformity`. FAF architectural constraints are non-negotiable and conjunctive: a codebase is either conformant or non-conformant. Granular rule toggles and severity demotions are not supported.
 
-```bash
-npm install @morriconeluca/eslint-plugin-faf --save-dev
-# or
-yarn add @morriconeluca/eslint-plugin-faf --dev
-# or
-pnpm add @morriconeluca/eslint-plugin-faf -D
-```
+### Recommended Setup
 
----
+Add the plugin to your `eslint.config.js` or `eslint.config.ts`:
 
-## Configuration
+```javascript
+import faf from '@morriconeluca/eslint-plugin-faf';
 
-`@morriconeluca/eslint-plugin-faf` is configured via the ESLint flat config file (`eslint.config.ts` or `eslint.config.js`). All architectural settings are loaded from the global `settings.faf` object.
+export default [
+  faf.configs.recommended,
+  // ...your other flat configs
+];
+```
 
-### 1. Integration in `eslint.config.ts`
+The `recommended` configuration automatically:
 
-For a clean setup, we recommend defining your FAF taxonomy settings in a separate file (e.g. `faf.config.ts`) and importing it into your ESLint configuration.
+- Registers the `faf` plugin.
+- Targets all lintable script and module extensions (`.js`, `.jsx`, `.mjs`, `.cjs`, `.ts`, `.tsx`, `.mts`, `.cts`).
+- Enables `faf/conformity` with severity `error` (2).
 
-Since FAF is an **all-or-nothing architectural system**, all rules must be active as blocking errors to prevent architectural drift. The canonical way to integrate it is by extending `fafPlugin.configs.recommended` (which pre-configures all rules as `"error"`) and injecting your settings:
+### Manual Configuration
 
-```typescript
-import fafPlugin from '@morriconeluca/eslint-plugin-faf';
-import fafSettings from './faf.config';
+If you prefer to configure rules manually:
 
-export default [
-  // 1. Extend the recommended FAF configuration (registers the plugin and enables all rules as errors)
-  fafPlugin.configs.recommended,
+```javascript
+import faf from '@morriconeluca/eslint-plugin-faf';
 
-  // 2. Inject FAF taxonomy settings
+export default [
   {
-    files: ['**/*.{js,cjs,ts,cts,tsx}'],
-    settings: {
-      ...fafSettings,
+    plugins: {
+      faf,
+    },
+    rules: {
+      'faf/conformity': 'error',
     },
   },
 ];
@@ -68,280 +65,255 @@ export default [
 
 ---
 
-## Anatomy of `faf.config.ts`
+## The Configuration Contract: `fafconfig.ts`
+
+Every project governed by `eslint-plugin-faf` requires a configuration module named `fafconfig.ts` located at the root of the project.
 
-Here is a comprehensive configuration example mapping a typical project structure:
+### Example Configuration
 
 ```typescript
+import type { TFAFConfig } from '@morriconeluca/eslint-plugin-faf';
+
 export default {
   faf: {
-    // 1. Path aliases mapping (resolves absolute imports)
-    aliases: {
-      '#/_apis@shared': 'src/_src@shared/_network/_apis/_apis@shared',
-      '#/_app@shared': 'src/app/_app@shared',
-      '#/_src@shared': 'src/_src@shared',
-    },
-
-    // 2. Tree configurations
-    trees: [
+    locals: [
       {
-        // Root path to apply these rules to
-        includes: ['src'],
-
-        // Paths to completely exclude from FAF validation (Foreign Domains)
-        excludes: ['src/configs'],
-
-        // Definition of organizational Categories (folders starting with "_")
-        categories: [
-          // name: Name of the folder
-          // role: Associated architectural role
-          // allowSingleFiles: Allow files (Logical Nodes) directly in the folder (defaults to false)
-          // allowedExtensions: Limit file types for static assets (disables role suffix check)
-          { name: '_apis', role: 'api' },
-          { name: '_components', role: 'component' },
-          { name: '_utils', role: 'util' },
-          { name: '_hooks', role: 'hook' },
-          { name: '_layouts', role: 'layout' },
-          { name: '_pages', role: 'page' },
-          { name: '_routes', role: 'route' },
-          { name: '_recipes', role: 'recipe' },
-          { name: '_classes', role: 'class' },
-          { name: '_contexts', role: 'context' },
-          { name: '_stores', role: 'store' },
-          { name: '_factories', role: 'factory' },
-          { name: '_instances', role: 'instance' },
-          { name: '_boundaries', role: 'boundary' },
-
-          // Categories that allow direct logical files (Logical Nodes)
-          { allowSingleFiles: true, name: '_constants', role: 'constant' },
-          { allowSingleFiles: true, name: '_types', role: 'type' },
-          { allowSingleFiles: true, name: '_schemas', role: 'schema' },
-          { allowSingleFiles: true, name: '_mocks', role: 'mock' },
-
-          // Asset-only categories (no logical role required)
-          { allowedExtensions: ['.css'], name: '_styles' },
-          { allowedExtensions: ['.ttf', '.woff', '.woff2'], name: '_fonts' },
-          {
-            allowedExtensions: ['.png', '.jpg', '.jpeg', '.svg'],
-            name: '_images',
-          },
-        ],
-
-        // Global horizontal hierarchies: flow rules for peer imports
-        globalHorizontalHierarchies: [
-          [
-            ['_atoms'],
-            ['_molecules'],
-            ['_organisms'],
-            ['_templates'],
-            ['_pages'],
-          ],
-          [
-            ['_primitives'],
-            ['_compounds'],
-            ['_aggregates'],
-            ['_systems'],
-            ['_ecosystems'],
-          ],
-        ],
-
-        // Local horizontal hierarchies: flow rules restricted to specific paths
-        // Imports flow from left to right (elements on the right can import from the left)
-        localHorizontalHierarchies: [
+        roles: [
           {
-            hierarchies: [['_domain'], ['_network', '_state', '_ui']],
-            paths: ['src/_src@shared'],
+            name: 'constant',
+            category: '_constants',
+            isCategoryNode: true,
+            allowMultipleSymbols: true,
           },
           {
-            hierarchies: [['_enums'], ['_dtos']],
-            paths: ['src/_src@shared/_domain/_schemas'],
+            name: 'type',
+            category: '_types',
+            isCategoryNode: true,
+            allowMultipleSymbols: true,
           },
           {
-            hierarchies: [['_types'], ['_classes'], ['_utils'], ['_apis']],
-            paths: ['src/_src@shared/_network'],
+            name: 'mock',
+            category: '_mocks',
+            isCategoryNode: true,
+            allowMultipleSymbols: true,
           },
           {
-            hierarchies: [
-              ['_constants'],
-              ['_types'],
-              ['_utils'],
-              ['_recipes'],
-              ['_components'],
-              ['_pages'],
-            ],
-            paths: ['src/_src@shared/_ui'],
+            name: 'config',
+            category: '_configs',
+            isCategoryNode: true,
+            allowMultipleSymbols: true,
           },
+          { name: 'util', category: '_utils' },
+          { name: 'service', category: '_services' },
+          { name: 'component', category: '_components' },
         ],
-
-        // Suffix hierarchy role scale for files inside a Fragment.
-        // Files with roles at higher indices can import from roles at lower indices.
-        roles: [
-          ['constant'],
-          ['schema'],
-          ['type'],
-          ['class'],
-          ['config'],
-          ['mock'],
-          ['util'],
-          ['style'],
-          ['recipe'],
-          ['factory'],
-          ['instance'],
-          ['hook'],
+        subGraphRoles: [{ name: 'spec' }],
+        horizontalHierarchies: [
           [
-            'api',
-            'boundary',
-            'component',
-            'context',
-            'layout',
-            'page',
-            'route',
-            'store',
+            ['_constants'],
+            ['_types'],
+            ['_mocks'],
+            ['_configs'],
+            ['_utils'],
+            ['_services'],
+            ['_components'],
           ],
-          ['index', 'spec', 'story'],
-        ],
-
-        // Software entry points (Root Fragments) and their dependency rules
-        rootFragments: [
-          {
-            paths: ['src'],
-            // rootNodes specifies permitted layers of execution:
-            // main.tsx (index 1) can import main.css and app/app.tsx (index 0), but not vice-versa
-            rootNodes: [['main.css', 'app/app.tsx'], ['main.tsx']],
-            subRootFragments: [
-              {
-                paths: ['src/app'],
-                rootNodes: [['app.tsx']],
-              },
-            ],
-          },
-        ],
-
-        // Route-based structure (HTTP APIs or Pages)
-        routeHierarchies: [
-          {
-            // Subtree where intermediate folders are classified as organizational Layers,
-            // and the terminal Fragment must contain a Master Node with the specified role (e.g. '.api.ts')
-            // and a name following the "<method>-<object>" pattern (e.g. 'get-todo')
-            paths: ['src/_src@shared/_network/_apis'],
-            role: 'api',
-            // Optional: restricts which HTTP methods are valid as the Fragment name prefix.
-            // Defaults to all standard HTTP methods (get, post, put, patch, delete, head, options, connect, trace).
-            httpMethods: ['get', 'post', 'put', 'patch', 'delete'],
-          },
         ],
+        rootFragments: [{ path: 'src', rootNodes: [['main.ts']] }],
+        publicRootNodes: ['src/main.ts'],
+        externalDependencies: [{ from: ['src/main.ts'], to: ['package.json'] }],
       },
     ],
   },
-};
+} satisfies TFAFConfig;
 ```
 
+### Configuration Structure: `common` and `locals`
+
+The configuration object defines:
+
+- **`locals`** (_required_, non-empty array): Declarations specific to each Fractal Tree within the workspace. Each element must designate either a `rootFragments` array or a `rootLayers` array defining tree origins.
+- **`common`** (_optional_): Shared declarations (such as roles, sub-graph roles, foreign families, or aliases) inherited by all local trees unless explicitly overridden.
+- **Whole-property replacement**: When a local tree defines a property that also exists in `common`, the local property completely replaces the common definition without shallow or deep merging. Defaults apply strictly after replacement.
+
+### Native Type-Stripping and Execution Constraints
+
+`fafconfig.ts` is evaluated synchronously within an isolated Node.js worker thread leveraging Node's native type stripping. Because native type stripping strips type annotations without full AST transformation, configuration files must adhere to the following rules:
+
+1. **Explicit File Extensions on Relative Value Imports**:
+   Any relative value import inside `fafconfig.ts` or helper modules must specify an explicit extension (for example, `./roles.js` or `./roles.ts`). Type-only imports (`import type ...`) are erased during stripping and are exempt.
+2. **Prohibition of Non-Strippable TypeScript Constructs**:
+   `enum`, runtime `namespace` declarations with executable values, and constructor parameter properties are forbidden in `fafconfig.ts` and its imported dependencies. Use union types and standard property definitions.
+3. **Module Packaging in `package.json`**:
+   The nearest `package.json` must not declare `"type": "commonjs"`. It should specify `"type": "module"` or omit the field.
+4. **Synchronous, Clonable Default Export**:
+   `fafconfig.ts` must export its configuration as a synchronous `export default`. It cannot be a function, cannot return a `Promise` (no top-level asynchronous configuration), and must produce a plain data object serializable via `structuredClone`.
+
+### Configuration Discovery and Automatic Invalidation
+
+- **Discovery**: The plugin inspects `settings.faf.configFile` if provided in ESLint settings. If unset, it searches upward from the linter's current working directory for `fafconfig.ts`. If not found, it reports `configuration/missing-config-file` on all linted files.
+- **Freshness & Invalidation**: During worker evaluation, the loader tracks all local files loaded by `fafconfig.ts`. On subsequent lint passes, the plugin compares `mtimeMs` and `size` for all tracked files. If any file changes, the configuration cache is immediately invalidated and reloaded in a fresh worker without restarting your editor or language server.
+
 ---
 
-## Configuration Settings Reference
+## Diagnostic Outcomes & Enforcement Model
 
-### `aliases`
+### Uniform Blocking Severity
 
-Maps import aliases (e.g., `#/_src@shared`) to relative paths from the project root. This is critical for the linter to trace boundaries and verify import encapsulation.
+In `eslint-plugin-faf`, all diagnostic outcomes have severity **`error` (2)**. There are no warnings, hints, or demoted diagnostics.
 
-**Single Source of Truth**: By default, `eslint-plugin-faf` automatically resolves your path aliases using the `"imports"` field in your `package.json`. If `"imports"` contains any keys mapped to flat path strings, it is treated as the exclusive source of truth, and any `aliases` configured in `faf.config.ts` will be ignored. If `"imports"` is not defined, empty, or consists only of conditional import objects (which are skipped by the linter for simplicity), the plugin falls back to using the `aliases` object defined in `faf.config.ts`.
+### The 6 Outcome Families
 
-_Note: If your codebase uses conditional imports in `package.json` (e.g. mapping aliases to objects for ESM/CJS or types/default targets), you must define their flat equivalents in `faf.config.ts` `aliases` to ensure correct linting._
+Diagnostics belong to one of six discriminated outcome families, corresponding to message identifiers in the ESLint rule:
 
-### `excludes`
+1. **`configuration`**: Errors in `fafconfig.ts` loading, package configuration, schema validation, literal path grammar, foreign glob syntax, or declaration inconsistencies.
+2. **`classification`**: Violations of the FAF classification model, including containment matrix violations, fragment anatomy defects, missing master or access nodes, invalid horizontal hierarchies, and nomenclature non-conformities.
+3. **`symbol`**: Root-scope symbol violations, such as exceeding the single-symbol rule in strict nodes, missing master exports in access nodes, or illegal re-export of imported symbols.
+4. **`dependency`**: Prohibited edges or paths in the Dependency Graph, including peer separation violations, fragment encapsulation bypasses, private category or fractal branch leakage, tree opacity breaches, and unauthorized external or cross-tree dependencies.
+5. **`acyclicity`**: Cycle violations detected in the logical module dependency DAG or across the inter-tree authorization DAG.
+6. **`unverified`**: Incomplete checks that static analysis cannot conclusively prove (such as encountering symbolic links inside trees, unreadable origins or files, non-literal dynamic imports, unsupported syntax, or unexercised reciprocal cyclic authorizations).
 
-Array of path strings relative to the project root. Any folder matching these paths (or their subfolders) will be completely ignored by the linter.
+### Diagnostic Message Format
 
-### `categories`
+Every diagnostic outcome adheres to the canonical structure:
 
-Configures taxomonic categories (`_` prefixed directories).
+```text
+{{constraint}}: {{message}} ({{reference}}).
+```
+
+For example:
 
-- `role`: Maps the folder to an architectural role. It removes language plural heuristics (e.g., mapping `_components` to the `component` role suffix).
-- `allowSingleFiles`: Set to `true` to allow single files (`Logical Nodes`) directly in the category. If `false` or omitted, only subfolder `Fragments` are permitted, except for static assets matching the `allowedExtensions` whitelist.
-- `allowedExtensions`: Whitelists file extensions for asset categories. Matches are treated as static assets, skipping role suffix validation (e.g. `logo.png` inside `_images`).
+```text
+dependency/fragment-encapsulation: 'src/main.ts' imports 'src/_components/button/button.component.ts' through './_components/button/button.component.js': a Fragment is importable from outside only through its index.ts (FAF §6.1.1).
+```
 
-### `localHorizontalHierarchies` / `globalHorizontalHierarchies`
+### Deterministic Outcome Anchoring
 
-Determines horizontal import flow (Peer Separation). Each hierarchy is an array of string arrays.
+Because ESLint can only report diagnostics on files it is currently visiting, the plugin deterministically anchors outcomes to specific files:
 
-- Sub-folders at index `i` can import from sub-folders at index `j` only if `j < i`.
-- Peer folders at the same index (e.g. `['_network', '_state', '_ui']`) cannot import from each other.
+- **Module-Level Outcomes**: Reported directly on the affected TypeScript/JavaScript file at the exact statement or import declaration location.
+- **Domain-Level & Missing-File Outcomes**: If an outcome pertains to an entire directory, a missing mandatory file (such as a missing `index.ts`), or a non-lintable asset, it is deterministically anchored to the first lintable file in lexicographical order among direct children (anchoring to the Master Node if present). If no direct child is lintable, it ascends to the nearest ancestor domain containing a lintable file.
+- **Global Configuration Outcomes**: Global format errors or catalog conflicts are anchored to `fafconfig.ts`.
+- **Missing Configuration File**: If `fafconfig.ts` cannot be discovered, `configuration/missing-config-file` is anchored to every file ESLint visits.
+- **Partial Linting Scope Limitation**: ESLint only presents diagnostics for files included in its current invocation. Linting a single file opened in an editor might not display architectural errors anchored to other files. Comprehensive architectural conformity requires running ESLint across the entire project (e.g., in CI via `eslint .`).
 
 ---
 
-## Rules Reference
+## Scope of Verification
+
+FAF defines both formal structural laws and qualitative design recommendations. Automated static analysis operates exclusively on deterministic source representations (ASTs, file inventories, and resolved import graphs).
 
-### 1. `faf/naming-conventions`
+The following five properties are explicitly **out of scope** for automated verification:
 
-Verifies folders, files, and roles comply with FAF taxonomy:
+1. **Symbol Coherence with Role** (FAF §5): Whether the semantic responsibility of an exported function or constant truthfully matches its declared Role (e.g., distinguishing a pure `util` from a `service` when syntax alone is identical).
+2. **Indivisibility of Symbols and Separation of Concerns** (FAF §6.1.2): Whether multiple Symbols grouped under an allowed multi-symbol catalog exemption are truly indivisible or constitute distinct architectural concerns.
+3. **Semantic Cohesion of a Fragment** (FAF §6.1): Whether all internal files of a Fragment conceptually collaborate toward a single cohesive business responsibility.
+4. **Semantic Fidelity of Mimetic Path Structures to External Addresses** (FAF §6.3.5): Whether declared Path Sub-Categories faithfully mirror real external HTTP routes or resource endpoints beyond syntactic validity.
+5. **Architectural Recommendations Introduced by _"it is recommended"_ / _"è raccomandato"_** (FAF §1.2, §8): Qualitative recommendations such as placing pages next to components, placing private details as close as possible to consumers, or avoiding singleton layers.
 
-- Enforces `kebab-case` naming for all folders and files in the logical domain.
-- Validates that internal Fragment files share their parent Fragment's name prefix (e.g. files in folder `button/` must be named `button.<role>.<ext>`).
-- Enforces role suffix validation on Fragment Nodes and Logical Nodes, restricted to a single Role segment per file name.
-- Requires every Fragment to contain at least one Fragment Node (its Master Node), and forbids two Fragment Nodes from sharing the same Role.
-- Assures route terminal Fragments contain the appropriate Master Node (e.g. a `.api.ts` file under `_apis`) and that the Fragment name follows the `<method>-<object>` pattern (e.g. `get-todo`), with the HTTP method restricted to `routeHierarchies[].httpMethods` or, by default, all standard HTTP methods.
-- Enforces FAF logical domain containment rules:
-  - Root Fragments can only reside directly in the Root Container or another Root Fragment.
-  - Layers cannot reside inside Fragments.
-  - Fragments cannot be placed directly inside other Fragments (they must be nested within a Private Category), Fractal Branches, or nested Root Fragments.
-  - Fractal Branches cannot be nested inside other Fractal Branches.
+The plugin emits **no diagnostic outcomes** and applies **no heuristics** for out-of-scope properties or recommendations.
 
-### 2. `faf/enforce-access-node`
+**Conformity Certification**: The absence of diagnostic outcomes certifies architectural conformity for the entire verified scope.
 
-Enforces Access Node (`index.ts` / `index.js`) integrity:
+---
+
+## Operational Boundaries and Limitations
 
-- Restricts the Access Node to import/export only its own sibling Fragment Nodes.
-- Prevents import of nested Private Categories, Fractal Branches, or unrelated external paths.
+### Incompatibility with `eslint --cache`
 
-### 3. `faf/no-direct-fragment-import`
+`eslint-plugin-faf` is **fundamentally incompatible with `eslint --cache`**.
 
-Applies **Fragment Encapsulation**:
+ESLint's native `--cache` flag operates on per-file timestamps. It assumes that if file `A` has not changed on disk, its lint status remains identical to the previous run. However, architectural invariants are whole-graph properties: if file `B` changes its exports or moves to another directory, file `A` (which imports file `B`) may suddenly become non-conformant even though file `A` was never modified.
 
-- Prevents external files from directly importing a Fragment's internal files. All imports must pass through the Fragment's Access Node (`index.ts`).
+**Do not run ESLint with `--cache` when validating FAF rules.**
 
-### 4. `faf/no-private-category-leak`
+The plugin maintains its own internal, sound caching mechanisms (memoizing module records and dependency graphs based on directory fingerprinting, `package.json`, and `fafconfig.ts`), ensuring high performance on full project runs.
 
-Applies **Private Category Encapsulation**:
+### Purely Diagnostic Paradigm — Prohibition of Autofix
 
-- Restricts consumption of elements inside a Private Category (e.g. `_components/` nested inside a Fragment) to the direct child Fragment Nodes of the owning Fragment/Root Fragment, and to sibling nodes within the same immediate sub-domain of the Private Category. Access does not extend to other sub-domains, nor to a Fractal Branch nested inside the Private Category (governed instead by its own encapsulation rule).
+`eslint-plugin-faf` is strictly **diagnostic-only**:
 
-### 5. `faf/no-fractal-branch-leak`
+- It provides **zero automated fixes** (`fix` functions) and zero automated refactorings.
+- It will never automatically move files, create directories, rewrite imports, or synthesize barrel files.
 
-Applies **Fractal Branch Encapsulation**:
+Architectural corrections require intentional engineering judgment: deciding whether a private helper should be moved into a Private Category, extracted into a Sub-Fragment, or promoted to a Fractal Branch requires domain understanding that automated tools cannot possess.
 
-- Fractal Branches named `_<Scope>@shared` are only importable by modules residing inside the parent Scope's subtree.
+### Static Analysis Capabilities
 
-### 6. `faf/no-peer-dependency`
+The plugin analyzes codebases using high-performance, deterministic static tooling:
 
-Applies **Peer Isolation**:
+- **TypeScript & JavaScript**: Parsed exclusively using `oxc-parser`. The plugin analyzes ESM static imports, dynamic imports with string literals (`import('...')`), CommonJS top-level `require()`, and TypeScript external references (`import x = require('...')`).
+- **CSS Stylesheets**: Scanned with a dedicated parser for `@import` and `url()` references, establishing dependency edges to other stylesheets and static assets.
+- **Binary Assets**: Recognized as terminal leaf nodes (sinks) with incoming edges but zero outgoing edges.
+- **Boundary Resolution (`oxc-resolver`)**: Resolves module specifiers against your project's `tsconfig.json` (`paths`, `baseUrl`) and `package.json` (`imports`, `exports`). Workspace packages inside a monorepo are classified as local codebase files; external `node_modules` packages and Node.js built-ins (`node:*`) act as terminal sinks.
+- **Incomplete Checks (`unverified`)**: Any unanalyzable construct (such as non-literal dynamic imports `import(variable)`, unreadable files, symbolic links inside trees, or unsupported syntax) emits a blocking `unverified/*` outcome. Incomplete checks are never treated as proof of conformity.
 
-- Prevents sibling files and folders from importing each other unless an explicit hierarchy is configured:
-  - **Inside a Fragment**: Flow is governed by the `roles` array order.
-  - **Between folders**: Flow is governed exclusively by `localHorizontalHierarchies` or `globalHorizontalHierarchies`; a sibling pair without a matching entry is denied in both directions.
-  - **Root Nodes**: Flow is governed exclusively by the defined index order in `rootFragments.rootNodes`. Root Nodes are exempt from the Role naming convention, so relationships between them never fall back to the `roles` scale: any relationship without a matching `rootNodes` entry is denied.
+---
 
-### 7. `faf/category-mutually-exclusive`
+## Migration from 0.5.x (Breaking Changes)
 
-Ensures category purity:
+Version `0.6.0` is a **complete ground-up rewrite** of `@morriconeluca/eslint-plugin-faf` centered around the normative Fractal Architecture Framework specification and `fafconfig.ts`. Nothing from version `0.5.x` is compatible.
 
-- Blocks mixing single files (Logical Nodes) and subfolders (Fragments) in the same category.
-- Blocks direct file placement inside categories configured with `allowSingleFiles: false`.
+### What Changed
 
----
+- **Removed `settings.faf.trees`**: Tree origins, catalog roles, and hierarchies are no longer declared inside `eslint.config.js` settings. They are declared in `fafconfig.ts`.
+- **Removed `faf.config.ts`**: Replaced by the standardized `fafconfig.ts` specification module.
+- **Removed Granular Rules**: All legacy individual rules (`faf/no-cross-imports`, `faf/enforce-hierarchy`, `faf/symbol-rules`, etc.) have been removed. The plugin now exposes exactly one rule: `faf/conformity`.
+- **Removed Legacy Configs**: Previous configurations (such as `faf.configs['flat/recommended']`) are replaced by `faf.configs.recommended`.
+
+### Step-by-Step Migration Guide
+
+1. **Upgrade Dependencies**:
+
+   ```bash
+   npm install --save-dev @morriconeluca/eslint-plugin-faf@^0.6.0 eslint@^9.0.0
+   ```
+
+   Ensure Node.js is `>= 24.0.0`.
+
+2. **Create `fafconfig.ts`**:
+   In your repository root, create `fafconfig.ts` implementing `TFAFConfig`:
+
+   ```typescript
+   import type { TFAFConfig } from '@morriconeluca/eslint-plugin-faf';
+
+   export default {
+     faf: {
+       locals: [
+         {
+           roles: [
+             { name: 'util', category: '_utils' },
+             { name: 'component', category: '_components' },
+           ],
+           subGraphRoles: [{ name: 'spec' }],
+           rootLayers: ['src'],
+         },
+       ],
+     },
+   } satisfies TFAFConfig;
+   ```
+
+3. **Update `eslint.config.js`**:
+   Remove any legacy rules and settings. Use the new recommended preset:
 
-## Performance Optimizations
+   ```javascript
+   import faf from '@morriconeluca/eslint-plugin-faf';
 
-To prevent sluggish linting in large codebases, the core engine implements aggressive, state-cached optimizations:
+   export default [faf.configs.recommended];
+   ```
 
-- **Directory Cache (`dirCache`)**: Inspects the physical disk exactly once per folder, storing the contents in-memory. It is optimized to perform exactly one system call on cache misses by removing redundant `fs.existsSync` checks.
-- **Classification Cache (`classifyCache`)**: Memoizes the structural type (`FolderType`) of each directory for the lifetime of the ESLint run.
-- **Role Cache (`rolesCache`)**: Uses a `WeakMap` to cache the allowed roles per tree configuration as a native `Set`, avoiding memory leaks, redundant array flattening allocations, and speeding up role lookup checks to $O(1)$.
-- **Category Configuration Cache (`categoryConfigCache`)**: Memoizes resolved category configurations per folder path to eliminate repetitive directory walks and path parent traversals.
-- **Tree Configuration Cache (`treeConfigCache` / `treeConfigIncludingExcludedCache`)**: Memoizes resolved tree configurations per file path, reducing tree lookup checks to a simple map-lookup.
-- **Resolved Import Path Cache (`resolvedImportPathCache`)**: Caches project-root-relative resolved import paths to avoid repeating expensive path resolutions, alias matching, and package.json parsing on duplicate imports.
+4. **Update CI and Scripts**:
+   Remove `--cache` from your ESLint linting scripts:
+   ```json
+   {
+     "scripts": {
+       "lint": "eslint ."
+     }
+   }
+   ```
 
 ---
 
 ## License
 
-This project is licensed under the terms of the [MIT License](LICENSE).
+MIT © [Luca Morricone](https://github.com/morriconeluca)