@morriconeluca/eslint-plugin-faf 0.5.0 → 0.6.1

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,265 @@ 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`
 
-## Configuration Settings Reference
+The configuration object defines:
 
-### `aliases`
+- **`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.
 
-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.
+### Native Type-Stripping and Execution Constraints
 
-**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`.
+`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:
 
-_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._
+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`.
 
-### `excludes`
+### Configuration Discovery and Automatic Invalidation
 
-Array of path strings relative to the project root. Any folder matching these paths (or their subfolders) will be completely ignored by the linter.
+- **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.
 
-### `categories`
+---
 
-Configures taxomonic categories (`_` prefixed directories).
+## Diagnostic Outcomes & Enforcement Model
 
-- `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`).
+### Uniform Blocking Severity
 
-### `localHorizontalHierarchies` / `globalHorizontalHierarchies`
+In `eslint-plugin-faf`, all diagnostic outcomes have severity **`error` (2)**. There are no warnings, hints, or demoted diagnostics.
 
-Determines horizontal import flow (Peer Separation). Each hierarchy is an array of string arrays.
+### The 6 Outcome Families
 
-- 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.
+Diagnostics belong to one of six discriminated outcome families, corresponding to message identifiers in the ESLint rule:
 
----
+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).
 
-## Rules Reference
+### Diagnostic Message Format
 
-### 1. `faf/naming-conventions`
+Every diagnostic outcome adheres to the canonical structure:
 
-Verifies pure lexical FAF naming conventions:
+```text
+{{constraint}}: {{message}} ({{reference}}).
+```
 
-- 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.
+For example:
 
-### 2. `faf/logical-domain-placement`
+```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).
+```
 
-Enforces FAF topological placement constraints between Logical Domains:
+### Deterministic Outcome Anchoring
 
-- 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.
+Because ESLint can only report diagnostics on files it is currently visiting, the plugin deterministically anchors outcomes to specific files:
 
-### 3. `faf/enforce-access-node`
+- **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 .`).
 
-Enforces Access Node (`index.ts` / `index.js`) integrity:
+---
 
-- 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.
+## Scope of Verification
 
-### 4. `faf/fragment-master-node`
+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).
 
-Enforces Fragment Node identity and Master Node integrity:
+The following five properties are explicitly **out of scope** for automated verification:
 
-- 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.
+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.
 
-### 5. `faf/no-direct-fragment-import`
+The plugin emits **no diagnostic outcomes** and applies **no heuristics** for out-of-scope properties or recommendations.
 
-Applies **Fragment Encapsulation**:
+**Conformity Certification**: The absence of diagnostic outcomes certifies architectural conformity for the entire verified scope.
 
-- Prevents external files from directly importing a Fragment's internal files. All imports must pass through the Fragment's Access Node (`index.ts`).
+---
 
-### 6. `faf/no-private-category-leak`
+## Operational Boundaries and Limitations
 
-Applies **Private Category Encapsulation**:
+### Incompatibility 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-plugin-faf` is **fundamentally incompatible with `eslint --cache`**.
 
-### 7. `faf/no-fractal-branch-leak`
+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.
 
-Applies **Fractal Branch Encapsulation**:
+**Do not run ESLint with `--cache` when validating FAF rules.**
 
-- 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.
+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.
 
-### 8. `faf/no-peer-dependency`
+### Purely Diagnostic Paradigm — Prohibition of Autofix
 
-Applies **Peer Isolation** via horizontal hierarchy resolution:
+`eslint-plugin-faf` is strictly **diagnostic-only**:
 
-- **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.
+- 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.
 
-Foreign Domain imports and Root Node dependency direction are handled by dedicated rules (see below).
+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.
 
-### 9. `faf/foreign-domain-isolation`
+### Static Analysis Capabilities
 
-Applies **Foreign Domain isolation**:
+The plugin analyzes codebases using high-performance, deterministic static tooling:
 
-- 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.
+- **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, or symbolic links inside trees) emits a blocking `unverified/*` outcome. Non-literal `require(...)` calls, TypeScript `export =` assignments, and CommonJS `module.exports` / `exports.*` assignments are unsupported constructs that emit `unverified/unsupported-syntax`. Incomplete checks are never treated as proof of conformity.
 
-### 10. `faf/root-node-dependency-direction`
+### Nominal Kebab-Case Grammar
 
-Enforces explicit, non-Role-based dependency direction between **Root Nodes**:
+The lexical policy enforced by the plugin requires standard architectural element names to match the ASCII regular expression `^[a-z0-9]+(?:-[a-z0-9]+)*$`:
 
-- 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.
+- **Permitted Characters**: Lowercase ASCII letters `a-z` and digits `0-9` separated by single hyphens.
+- **Initial Digits**: Permitted, such as `2fa-service` or `v2-parser`.
+- **Acronyms**: Must be lowercase, such as `http-client`.
+- **Rejected Forms**: Uppercase letters (e.g. `HTTPClient`), consecutive, leading, or trailing hyphens, non-prefix underscores, and non-ASCII Unicode characters (e.g. `café-parser`).
+- **Free Naming**: Free naming applies to designated Tree origins, Root Fragments, Root Nodes, Foreign Domains, and Foreign Nodes.
 
-### 11. `faf/category-mutually-exclusive`
+---
 
-Ensures category purity:
+## Migration from 0.5.x (Breaking Changes)
 
-- Blocks mixing single files (Logical Nodes) and subfolders (Fragments) in the same category.
-- Blocks direct file placement inside categories configured with `allowSingleFiles: false`.
+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.
 
----
+### What Changed
 
-## Migrating from 7 rules to 11
+- **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`.
 
-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.
+### Step-by-Step Migration Guide
 
-| 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` |
+1. **Upgrade Dependencies**:
 
-`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.
+   ```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.
-- **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)