@morriconeluca/eslint-plugin-faf 0.2.0 → 0.4.0

package/README.md

@@ -15,6 +15,15 @@ This plugin is designed for complex TypeScript/JavaScript codebases to ensure **
 
 ---
 
+## 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:
+
+- [`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.
+
+---
+
 ## Installation
 
 Install the plugin along with its peer dependencies:
@@ -213,8 +222,12 @@ export default {
           {
             // 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'],
           },
         ],
       },
@@ -264,8 +277,9 @@ Verifies folders, files, and roles comply with FAF taxonomy:
 
 - 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.
-- Assures route terminal Fragments contain the appropriate Master Node (e.g. a `.api.ts` file under `_apis`).
+- 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.
@@ -289,7 +303,7 @@ Applies **Fragment Encapsulation**:
 
 Applies **Private Category Encapsulation**:
 
-- Restricts consumption of elements inside a Private Category (e.g. `_components/` nested inside a Fragment) to files within the parent Fragment or its sub-fragments.
+- 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).
 
 ### 5. `faf/no-fractal-branch-leak`
 
@@ -303,8 +317,8 @@ Applies **Peer Isolation**:
 
 - 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 by `localHorizontalHierarchies` or `globalHorizontalHierarchies`. If undefined, the linter falls back to mapped roles. Otherwise, peer isolation is strictly enforced.
-  - **Root Nodes**: Flow is governed by the defined index order in `rootFragments.rootNodes`.
+  - **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`
 

package/dist/main.cjs

@@ -39,7 +39,7 @@ module.exports = __toCommonJS(main_exports);
 // package.json
 var package_default = {
   name: "@morriconeluca/eslint-plugin-faf",
-  version: "0.2.0",
+  version: "0.4.0",
   description: "An ESLint plugin for FAF projects.",
   repository: {
     type: "git",
@@ -480,6 +480,17 @@ function getProjectRoot() {
 
 // src/_rules/naming-conventions/naming-conventions.rule.ts
 var KEBAB_CASE_REGEX = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+var DEFAULT_HTTP_METHODS = [
+  "connect",
+  "delete",
+  "get",
+  "head",
+  "options",
+  "patch",
+  "post",
+  "put",
+  "trace"
+];
 var rule3 = {
   create(context) {
     return {
@@ -643,15 +654,6 @@ var rule3 = {
         if (parentType === "invalid-fragment") {
           return;
         }
-        if (fileName === "index.ts" || fileName === "index.js") {
-          if (parentType !== "fragment") {
-            context.report({
-              message: `Access Nodes ("index.ts/index.js") are exclusive to Fragments. Found index file directly inside "${folderName}" (classified as ${parentType}).`,
-              node
-            });
-          }
-          return;
-        }
         const rfConfig = getRootFragmentConfig(relDir, config);
         if (rfConfig) {
           const flatRootNodes = rfConfig.rootNodes.flat();
@@ -667,11 +669,34 @@ var rule3 = {
             return;
           }
         }
+        if (fileName === "index.ts" || fileName === "index.js") {
+          if (parentType !== "fragment") {
+            context.report({
+              message: `Access Nodes ("index.ts/index.js") are exclusive to Fragments. Found index file directly inside "${folderName}" (classified as ${parentType}).`,
+              node
+            });
+          } else {
+            const contents = readDirCached(relDir);
+            const hasFragmentNode = contents.files.some(
+              (f) => f !== "index.ts" && f !== "index.js" && f !== "README.md" && f !== "package.json" && f !== "tsconfig.json"
+            );
+            if (!hasFragmentNode) {
+              context.report({
+                message: `Fragment "${folderName}" has no Master Node. Every Fragment must contain at least one Fragment Node establishing its Role.`,
+                node
+              });
+            }
+          }
+          return;
+        }
         if (fileName === "README.md" || fileName === "package.json" || fileName === "tsconfig.json") {
           return;
         }
         const role = getFileRole(fileName, config);
         const ext = import_path7.default.extname(fileName);
+        const allRoleNames = new Set(config.roles.flat());
+        const roleSegments = fileName.slice(0, fileName.length - ext.length).split(".").slice(1).filter((part) => allRoleNames.has(part));
+        const multiRoleMessage = `File "${fileName}" composes multiple Roles ("${roleSegments.join('", "')}") in its name. A Logical Node may declare only one Role; promote the detail that needs its own Role to an autonomous Sub-Fragment.`;
         if (parentType === "fragment") {
           const matchedRoute = config.routeHierarchies?.find(
             (rh) => rh.paths.some((rp) => relDir === rp || relDir.startsWith(rp + "/"))
@@ -685,6 +710,16 @@ var rule3 = {
                 node
               });
             }
+            const httpMethods = matchedRoute.httpMethods ?? DEFAULT_HTTP_METHODS;
+            const routeNameRegex = new RegExp(
+              `^(${httpMethods.join("|")})-[a-z0-9]+(-[a-z0-9]+)*$`
+            );
+            if (!routeNameRegex.test(folderName)) {
+              context.report({
+                message: `Route terminal Fragment "${folderName}" must follow the "<method>-<object>" pattern with a lowercase HTTP method (${httpMethods.join(", ")}).`,
+                node
+              });
+            }
           }
           let currentParent = import_path7.default.dirname(relDir).replace(/\\/g, "/");
           let categoryConfig = null;
@@ -723,6 +758,19 @@ var rule3 = {
               message: `File "${fileName}" inside Fragment "${folderName}" must have an explicit role suffix (e.g. "${folderName}.style${ext}").`,
               node
             });
+          } else if (roleSegments.length > 1) {
+            context.report({ message: multiRoleMessage, node });
+          } else {
+            const contents = readDirCached(relDir);
+            const duplicate = contents.files.find(
+              (f) => f !== fileName && f !== "index.ts" && f !== "index.js" && getFileRole(f, config) === role
+            );
+            if (duplicate) {
+              context.report({
+                message: `Fragment Node "${fileName}" shares Role "${role}" with sibling "${duplicate}". Each Fragment Node must have a unique Role within its Fragment.`,
+                node
+              });
+            }
           }
         }
         if (parentType === "category") {
@@ -753,6 +801,8 @@ var rule3 = {
                   message: `Role "${role}" for file "${fileName}" does not match the expected Category role "${catConfig.role}".`,
                   node
                 });
+              } else if (roleSegments.length > 1) {
+                context.report({ message: multiRoleMessage, node });
               }
             } else {
               if (role && role !== catConfig.role) {
@@ -760,6 +810,8 @@ var rule3 = {
                   message: `Role "${role}" for asset "${fileName}" does not match the expected Category role "${catConfig.role}".`,
                   node
                 });
+              } else if (role && roleSegments.length > 1) {
+                context.report({ message: multiRoleMessage, node });
               }
             }
           }
@@ -829,6 +881,16 @@ function _resolveImportPath(importPath, currentFileRelative, settings) {
   }
   return finalizeResolvedPath(relResolved);
 }
+var SCRIPT_EXTENSIONS = /* @__PURE__ */ new Set([
+  "cjs",
+  "cts",
+  "js",
+  "jsx",
+  "mjs",
+  "mts",
+  "ts",
+  "tsx"
+]);
 function finalizeResolvedPath(relResolved) {
   const resolvedDir = import_path8.default.dirname(relResolved).replace(/\\/g, "/");
   const resolvedBase = import_path8.default.basename(relResolved);
@@ -842,9 +904,12 @@ function finalizeResolvedPath(relResolved) {
   const parentContents = readDirCached(resolvedDir);
   const exactMatch = parentContents.files.find((f) => f === resolvedBase);
   if (!exactMatch) {
-    const matchWithExt = parentContents.files.find(
+    const candidates = parentContents.files.filter(
       (f) => f.startsWith(resolvedBase + ".")
     );
+    const matchWithExt = candidates.find(
+      (f) => SCRIPT_EXTENSIONS.has(f.slice(resolvedBase.length + 1))
+    ) ?? candidates[0];
     if (matchWithExt) {
       return (resolvedDir === "." ? "" : resolvedDir + "/") + matchWithExt;
     }
@@ -913,7 +978,7 @@ var rule4 = {
       if (importedFolderType === "fragment") {
         const isAccessNode = importedFile === "index.ts" || importedFile === "index.js";
         if (!isAccessNode) {
-          const isInside = relPath === importedDir || relPath.startsWith(importedDir + "/");
+          const isInside = import_path9.default.dirname(relPath) === importedDir;
           if (!isInside) {
             context.report({
               message: `Direct import of Fragment internal file "${importedFile}" is forbidden. You must import through its Access Node (index file) in "${importedDir}".`,
@@ -1020,19 +1085,19 @@ var rule5 = {
         return;
       }
       const importedDir = import_path12.default.dirname(resolvedRelPath);
-      const owner = getFractalBranchOwner(importedDir);
-      if (owner) {
-        const isDescendant = relPath === owner || relPath.startsWith(owner + "/");
+      const fractalBranchOwner = getFractalBranchOwner(importedDir);
+      if (fractalBranchOwner) {
+        const isDescendant = relPath === fractalBranchOwner || relPath.startsWith(fractalBranchOwner + "/");
         if (!isDescendant) {
           context.report({
-            message: `Importing from Fractal Branch is forbidden. The imported resource is private to "${owner}" and its descendants.`,
+            message: `Importing from Fractal Branch is forbidden. The imported resource is private to "${fractalBranchOwner}" and its descendants.`,
             node
           });
         } else {
           const info = getPrivateCategoryInfo(importedDir, config);
           if (info) {
-            const { owner: owner2, privateCategoryPath } = info;
-            const isPrivateDirectChild = import_path12.default.dirname(relPath) === owner2;
+            const { owner, privateCategoryPath } = info;
+            const isPrivateDirectChild = import_path12.default.dirname(relPath) === owner;
             const importerSubDomain = getImmediateSubDomain(
               relPath,
               privateCategoryPath
@@ -1042,17 +1107,10 @@ var rule5 = {
               privateCategoryPath
             );
             const isInsideSameSubDomain = importerSubDomain !== "" && importerSubDomain === importedSubDomain;
-            let isFractalBranchAllowed = false;
-            const fbOwner = getFractalBranchOwner(importedDir);
-            if (fbOwner) {
-              const isFbInsidePrivateCategory = fbOwner === privateCategoryPath || fbOwner.startsWith(privateCategoryPath + "/");
-              if (isFbInsidePrivateCategory) {
-                isFractalBranchAllowed = relPath === fbOwner || relPath.startsWith(fbOwner + "/");
-              }
-            }
+            const isFractalBranchAllowed = fractalBranchOwner === privateCategoryPath || fractalBranchOwner.startsWith(privateCategoryPath + "/");
             if (!isPrivateDirectChild && !isInsideSameSubDomain && !isFractalBranchAllowed) {
               context.report({
-                message: `Importing from Private Category is forbidden. The imported resource is private to "${owner2}".`,
+                message: `Importing from Private Category is forbidden. The imported resource is private to "${owner}".`,
                 node
               });
             }
@@ -1162,24 +1220,6 @@ function resolveHorizontalHierarchy(lcaPath, subA, subB, config) {
 }
 
 // src/_rules/no-peer-dependency/no-peer-dependency.rule.ts
-function getDirectoryRole(dirPath, config) {
-  const folderName = import_path13.default.basename(dirPath);
-  if (folderName.startsWith("_")) {
-    return getRoleFromFolderName(folderName, config);
-  }
-  const contents = readDirCached(dirPath);
-  for (const file of contents.files) {
-    if (file.startsWith(folderName + ".")) {
-      const role = getFileRole(file, config);
-      if (role) return role;
-    }
-  }
-  return null;
-}
-function getRoleFromFolderName(name, config) {
-  const catConfig = config.categories?.find((c) => c.name === name);
-  return catConfig ? catConfig.role ?? null : null;
-}
 function getRootNodeIndex(relPath, rfConfig, lcaPath) {
   const relToLca = import_path13.default.relative(lcaPath, relPath).replace(/\\/g, "/");
   for (let i = 0; i < rfConfig.rootNodes.length; i++) {
@@ -1283,6 +1323,10 @@ var rule6 = {
         return;
       }
       if (subB === "" && classifyFolder(lca, config) === "fragment") {
+        context.report({
+          message: `Peer separation violation: "${subA}" cannot import directly from the root of Fragment "${lca}". A node nested inside a Private Category or Fractal Branch has no privileged access to its owning Fragment's other direct children; promote the shared resource to a Fractal Branch if the sharing need is genuine.`,
+          node
+        });
         return;
       }
       const rfConfig = getRootFragmentConfig(lca, config);
@@ -1299,6 +1343,15 @@ var rule6 = {
           return;
         }
       }
+      const isSubARootFragment = classifyFolder(import_path13.default.posix.join(lca, subA), config) === "root-fragment";
+      const isSubBRootFragment = classifyFolder(import_path13.default.posix.join(lca, subB), config) === "root-fragment";
+      if (isSubARootFragment || isSubBRootFragment) {
+        context.report({
+          message: `Root Node import violation: "${relPath}" cannot import from "${resolvedRelPath}" because no "rootNodes" relationship is configured under Root Fragment "${lca}". Relationships between Root Nodes must always be explicitly authorized by the architect.`,
+          node
+        });
+        return;
+      }
       const { allowed, defined: hasDefinedHierarchy } = resolveHorizontalHierarchy(lca, subA, subB, config);
       if (hasDefinedHierarchy) {
         if (!allowed) {
@@ -1308,23 +1361,10 @@ var rule6 = {
           });
         }
       } else {
-        const roleA = getDirectoryRole(import_path13.default.posix.join(lca, subA), config);
-        const roleB = getDirectoryRole(import_path13.default.posix.join(lca, subB), config);
-        const idxA = roleA ? getRoleHierarchyIndex(roleA, config) : -1;
-        const idxB = roleB ? getRoleHierarchyIndex(roleB, config) : -1;
-        if (idxA !== -1 && idxB !== -1) {
-          if (idxB >= idxA) {
-            context.report({
-              message: `Horizontal hierarchy violation (fallback to roles): sibling directory "${subA}" (mapped to role "${roleA}", level ${idxA}) cannot import from "${subB}" (mapped to role "${roleB}", level ${idxB}) under parent "${lca}".`,
-              node
-            });
-          }
-        } else {
-          context.report({
-            message: `Peer separation violation: sibling directories "${subA}" and "${subB}" cannot import each other because no horizontal hierarchy is defined under parent "${lca}".`,
-            node
-          });
-        }
+        context.report({
+          message: `Peer separation violation: sibling directories "${subA}" and "${subB}" cannot import each other because no horizontal hierarchy is defined under parent "${lca}".`,
+          node
+        });
       }
     }
     return {
@@ -1378,6 +1418,16 @@ var rule7 = {
       const info = getPrivateCategoryInfo(importedDir, config);
       if (info) {
         const { owner, privateCategoryPath } = info;
+        let isFractalBranchInPrivateCategory = false;
+        let isFractalBranchAllowed = false;
+        const fbOwner = getFractalBranchOwner(importedDir);
+        if (fbOwner) {
+          const isFbInsidePrivateCategory = fbOwner === privateCategoryPath || fbOwner.startsWith(privateCategoryPath + "/");
+          if (isFbInsidePrivateCategory) {
+            isFractalBranchInPrivateCategory = true;
+            isFractalBranchAllowed = relPath === fbOwner || relPath.startsWith(fbOwner + "/");
+          }
+        }
         const isDirectChild = import_path14.default.dirname(relPath) === owner;
         const importerSubDomain = getImmediateSubDomain(
           relPath,
@@ -1388,15 +1438,8 @@ var rule7 = {
           privateCategoryPath
         );
         const isInsideSameSubDomain = importerSubDomain !== "" && importerSubDomain === importedSubDomain;
-        let isFractalBranchAllowed = false;
-        const fbOwner = getFractalBranchOwner(importedDir);
-        if (fbOwner) {
-          const isFbInsidePrivateCategory = fbOwner === privateCategoryPath || fbOwner.startsWith(privateCategoryPath + "/");
-          if (isFbInsidePrivateCategory) {
-            isFractalBranchAllowed = relPath === fbOwner || relPath.startsWith(fbOwner + "/");
-          }
-        }
-        if (!isDirectChild && !isInsideSameSubDomain && !isFractalBranchAllowed) {
+        const isAllowed = isFractalBranchInPrivateCategory ? isFractalBranchAllowed : isDirectChild || isInsideSameSubDomain;
+        if (!isAllowed) {
           context.report({
             message: `Importing from Private Category is forbidden. The imported resource is private to "${owner}".`,
             node