@morriconeluca/eslint-plugin-faf 0.5.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`, `ancestorChainCache`, `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,329 +65,255 @@ export default [
 
 ---
 
-## Anatomy of `faf.config.ts`
+## The Configuration Contract: `fafconfig.ts`
 
-Here is a comprehensive configuration example mapping a typical project structure:
+Every project governed by `eslint-plugin-faf` requires a configuration module named `fafconfig.ts` located at the root of the project.
+
+### 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:
 
-## Configuration Settings Reference
+- **`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.
 
-### `aliases`
+### Native Type-Stripping and Execution Constraints
 
-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.
+`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:
 
-**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`.
+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`.
 
-_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._
+### Configuration Discovery and Automatic Invalidation
 
-### `excludes`
+- **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.
 
-Array of path strings relative to the project root. Any folder matching these paths (or their subfolders) will be completely ignored by the linter.
+---
 
-### `categories`
+## Diagnostic Outcomes & Enforcement Model
 
-Configures taxomonic categories (`_` prefixed directories).
+### Uniform Blocking Severity
 
-- `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`).
+In `eslint-plugin-faf`, all diagnostic outcomes have severity **`error` (2)**. There are no warnings, hints, or demoted diagnostics.
 
-### `localHorizontalHierarchies` / `globalHorizontalHierarchies`
+### The 6 Outcome Families
 
-Determines horizontal import flow (Peer Separation). Each hierarchy is an array of string arrays.
+Diagnostics belong to one of six discriminated outcome families, corresponding to message identifiers in the ESLint rule:
 
-- 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.
+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).
 
----
+### Diagnostic Message Format
 
-## Rules Reference
+Every diagnostic outcome adheres to the canonical structure:
 
-### 1. `faf/naming-conventions`
+```text
+{{constraint}}: {{message}} ({{reference}}).
+```
 
-Verifies pure lexical FAF naming conventions:
+For example:
 
-- Enforces `kebab-case` naming for all folders and files in the logical domain.
-- Requires an underscore prefix for Layers/Categories/Sub-Categories, and forbids it for Fragments/Sub-Fragments/Root Fragments.
-- Validates that a Fractal Branch's name matches its parent scope (`_<Scope>@shared`).
-- Restricts a Logical Node's name to a single Role segment, whether it is a Fragment Node or a loose file inside a Category.
-- For loose files inside a Category: validates the file extension against the category's whitelist, requires a role suffix on code files, and validates that the role matches the Category's configured role.
+```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).
+```
 
-### 2. `faf/logical-domain-placement`
+### Deterministic Outcome Anchoring
 
-Enforces FAF topological placement constraints between Logical Domains:
+Because ESLint can only report diagnostics on files it is currently visiting, the plugin deterministically anchors outcomes to specific files:
 
-- Root Fragments can only reside directly in the Root Container or another Root Fragment.
-- Layers cannot reside inside Fragments, and cannot contain files or Fragments directly, except the terminal Layer of a configured Route Hierarchy.
-- Fragments cannot be placed directly inside other Fragments (they must be nested within a Private Category), Layers (unless terminating a Route Hierarchy), Fractal Branches, or nested Root Fragments.
-- Fractal Branches cannot be nested inside other Fractal Branches, and cannot contain files directly.
+- **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 .`).
 
-### 3. `faf/enforce-access-node`
+---
 
-Enforces Access Node (`index.ts` / `index.js`) integrity:
+## Scope of Verification
 
-- Requires a directory that isn't a Category, Layer, Fractal Branch, or Root Fragment to have an Access Node.
-- Restricts Access Nodes to Fragments: an index file directly inside any other Logical Domain is forbidden.
-- Requires every Fragment to contain at least one Fragment Node (its Master Node).
-- 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.
+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).
 
-### 4. `faf/fragment-master-node`
+The following five properties are explicitly **out of scope** for automated verification:
 
-Enforces Fragment Node identity and Master Node integrity:
+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.
 
-- Validates that internal Fragment files share their parent Fragment's name prefix (e.g. files in folder `button/` must be named `button.<role>.<ext>`).
-- Requires a role suffix on every Fragment Node, and forbids two Fragment Nodes from sharing the same Role.
-- Assures a Fragment placed under a Category (or terminating a Route Hierarchy) contains a Master Node carrying the Role imposed by that Category/Route (e.g. a `.api.ts` file under `_apis`).
-- Assures route terminal Fragments follow the `<method>-<object>` naming pattern (e.g. `get-todo`), with the HTTP method restricted to `routeHierarchies[].httpMethods` or, by default, all standard HTTP methods.
+The plugin emits **no diagnostic outcomes** and applies **no heuristics** for out-of-scope properties or recommendations.
 
-### 5. `faf/no-direct-fragment-import`
+**Conformity Certification**: The absence of diagnostic outcomes certifies architectural conformity for the entire verified scope.
 
-Applies **Fragment Encapsulation**:
+---
 
-- Prevents external files from directly importing a Fragment's internal files. All imports must pass through the Fragment's Access Node (`index.ts`).
+## Operational Boundaries and Limitations
 
-### 6. `faf/no-private-category-leak`
+### Incompatibility with `eslint --cache`
 
-Applies **Private Category Encapsulation**:
+`eslint-plugin-faf` is **fundamentally incompatible with `eslint --cache`**.
 
-- 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'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.
 
-### 7. `faf/no-fractal-branch-leak`
+**Do not run ESLint with `--cache` when validating FAF rules.**
 
-Applies **Fractal Branch Encapsulation**:
+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.
 
-- Fractal Branches named `_<Scope>@shared` are only importable by modules residing inside the parent Scope's subtree.
-- A Fractal Branch itself must never depend, not even indirectly, on the subtree it serves: importing anything from its owner's subtree that isn't part of the branch itself is forbidden.
+### Purely Diagnostic Paradigm — Prohibition of Autofix
 
-### 8. `faf/no-peer-dependency`
+`eslint-plugin-faf` is strictly **diagnostic-only**:
 
-Applies **Peer Isolation** via horizontal hierarchy resolution:
+- 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.
 
-- **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.
+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.
 
-Foreign Domain imports and Root Node dependency direction are handled by dedicated rules (see below).
+### Static Analysis Capabilities
 
-### 9. `faf/foreign-domain-isolation`
+The plugin analyzes codebases using high-performance, deterministic static tooling:
 
-Applies **Foreign Domain 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 Logical Nodes from importing a file from a Foreign Domain (e.g. `src/configs`).
-- Prevents a Foreign Domain file from importing a Logical Node from the FAF tree.
+---
 
-### 10. `faf/root-node-dependency-direction`
+## Migration from 0.5.x (Breaking Changes)
 
-Enforces explicit, non-Role-based dependency direction between **Root Nodes**:
+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.
 
-- 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 (sibling or nested Root Fragments) never fall back to the `roles` scale: any relationship without a matching `rootNodes` entry is denied.
+### What Changed
 
-### 11. `faf/category-mutually-exclusive`
+- **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`.
 
-Ensures category purity:
+### Step-by-Step Migration Guide
 
-- Blocks mixing single files (Logical Nodes) and subfolders (Fragments) in the same category.
-- Blocks direct file placement inside categories configured with `allowSingleFiles: false`.
+1. **Upgrade Dependencies**:
 
----
+   ```bash
+   npm install --save-dev @morriconeluca/eslint-plugin-faf@^0.6.0 eslint@^9.0.0
+   ```
 
-## Migrating from 7 rules to 11
+   Ensure Node.js is `>= 24.0.0`.
 
-Starting with this release, five checks that used to live inside two large rules (`naming-conventions` and `no-peer-dependency`) have moved to dedicated rules with their own `id`. The underlying checks and their error messages are unchanged — only the `ruleId` reporting them is different. This is a breaking change for anyone who doesn't use `configs.recommended` (which picks up the new rules automatically) or who references a specific rule `id` directly, e.g. in `// eslint-disable-next-line faf/<id>` comments or a hand-written `rules` block.
+2. **Create `fafconfig.ts`**:
+   In your repository root, create `fafconfig.ts` implementing `TFAFConfig`:
 
-| Old rule id                                                                                                                          | Check moved to                           |
-| ------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------- |
-| `naming-conventions` — folder/file placement (Root Fragment, Layer, Fragment, Fractal Branch containment)                            | `logical-domain-placement` (new)         |
-| `naming-conventions` — Access Node existence, Master Node existence                                                                  | `enforce-access-node`                    |
-| `naming-conventions` — Fragment Node name prefix, role requirement/uniqueness, Category/Route Master Node role, route naming pattern | `fragment-master-node` (new)             |
-| `naming-conventions` — kebab-case, underscore prefix, Fractal Branch naming, single-Role-segment, Category loose-file naming         | unchanged, stays in `naming-conventions` |
-| `no-peer-dependency` — Foreign Domain imports (both directions)                                                                      | `foreign-domain-isolation` (new)         |
-| `no-peer-dependency` — Root Node dependency direction (`rootFragments.rootNodes`)                                                    | `root-node-dependency-direction` (new)   |
-| `no-peer-dependency` — horizontal hierarchy resolution (Fragment Node roles, sibling folders)                                        | unchanged, stays in `no-peer-dependency` |
+   ```typescript
+   import type { TFAFConfig } from '@morriconeluca/eslint-plugin-faf';
 
-`no-direct-fragment-import`, `no-private-category-leak`, `category-mutually-exclusive` are unaffected. `no-fractal-branch-leak` keeps its `id` and gains one new check: a Fractal Branch depending on the subtree it serves is now reported.
+   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.
-- **Ancestor Chain Cache (`ancestorChainCache`)**: Memoizes the full chain of classified ancestors above a directory, so rules that walk upward from a file (folder taxonomy, topological placement) do so once per directory rather than once per file.
-- **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)