@lifesavertech/archguard-rules-react 2.0.0

package/README.md

@@ -0,0 +1,9 @@
+# @lifesavertech/archguard-rules-react
+
+React-specific ArchGuard rules: layer import boundaries, circular dependencies, and optional UI heuristics.
+
+UI heuristics (`noBusinessLogicInComponents`, `noDataFetchingInUI`) are **opt-in** as of v2.0. Enable them in `architecture.yaml` or use the `react-layered` init preset.
+
+Most users should install `@lifesavertech/archguard-cli` rather than depending on this package directly.
+
+Documentation: [github.com/lindseystead/ArchGuard](https://github.com/lindseystead/ArchGuard)

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+/** React-specific rule implementations. */
+import { Rule } from "@lifesavertech/archguard-core";
+export declare function createLayerImportBoundaryRule(): Rule;
+export declare function createBusinessLogicInComponentsRule(): Rule;
+export declare function createDataFetchingInUIRule(): Rule;
+export declare function createCircularDependencyRule(): Rule;

package/dist/index.js

@@ -0,0 +1,412 @@
+"use strict";
+/** React-specific rule implementations. */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLayerImportBoundaryRule = createLayerImportBoundaryRule;
+exports.createBusinessLogicInComponentsRule = createBusinessLogicInComponentsRule;
+exports.createDataFetchingInUIRule = createDataFetchingInUIRule;
+exports.createCircularDependencyRule = createCircularDependencyRule;
+const ts = __importStar(require("typescript"));
+const path = __importStar(require("path"));
+const archguard_core_1 = require("@lifesavertech/archguard-core");
+const DATA_FETCH_HOOKS = new Set([
+    "useQuery",
+    "useSuspenseQuery",
+    "useInfiniteQuery",
+    "useMutation",
+    "useSWR",
+    "useSWRImmutable",
+    "useSWRInfinite",
+]);
+const DATA_FETCH_AXIOS_METHODS = new Set(["delete", "get", "patch", "post", "put", "request"]);
+function createLayerImportBoundaryRule() {
+    return {
+        name: "layer-import-boundary",
+        description: "Enforces layer import boundaries",
+        execute(context) {
+            const violations = [];
+            if (!(0, archguard_core_1.isLayerBoundaryEnforcementEnabled)(context.architecture.rules)) {
+                return { violations: [], passed: true };
+            }
+            const filePath = context.filePath;
+            const layerName = (0, archguard_core_1.detectLayerFromPath)(filePath, context.architecture.layers);
+            if (!layerName) {
+                return { violations: [], passed: true };
+            }
+            const layerConfig = context.architecture.layers[layerName];
+            if (!layerConfig) {
+                return { violations: [], passed: true };
+            }
+            const allowedLayers = new Set(layerConfig.allowedImports);
+            for (const imp of context.imports) {
+                if (imp.isTypeOnly) {
+                    continue;
+                }
+                const importedLayer = detectLayerFromImport(imp, filePath, context.architecture.layers);
+                if (importedLayer && importedLayer !== layerName) {
+                    if (!allowedLayers.has(importedLayer)) {
+                        const sourceFile = (0, archguard_core_1.parseTypeScript)(context.sourceCode, context.filePath);
+                        const importNode = findImportNode(sourceFile, imp.from);
+                        if (importNode) {
+                            const { line, character } = sourceFile.getLineAndCharacterOfPosition(importNode.getStart());
+                            const allowedList = layerConfig.allowedImports.length > 0
+                                ? layerConfig.allowedImports.join(", ")
+                                : "none";
+                            violations.push({
+                                file: filePath,
+                                line: line + 1,
+                                column: character + 1,
+                                message: `Layer '${layerName}' cannot import from '${importedLayer}'. Import from allowed layers only: ${allowedList}. Move the imported code to an allowed layer or restructure dependencies.`,
+                                rule: "layer-import-boundary",
+                            });
+                        }
+                    }
+                }
+            }
+            return {
+                violations,
+                passed: violations.length === 0,
+            };
+        },
+    };
+}
+function createBusinessLogicInComponentsRule() {
+    return {
+        name: "no-business-logic-in-components",
+        description: "Detects business logic inside React UI layer components",
+        execute(context) {
+            const violations = [];
+            if (!context.architecture.rules.noBusinessLogicInComponents) {
+                return { violations: [], passed: true };
+            }
+            if (!(0, archguard_core_1.fileBelongsToUiLayer)(context.filePath, context.architecture)) {
+                return { violations: [], passed: true };
+            }
+            const sourceFile = (0, archguard_core_1.parseTypeScript)(context.sourceCode, context.filePath);
+            const componentNodes = getComponentNodes(sourceFile);
+            if (componentNodes.length === 0) {
+                return { violations: [], passed: true };
+            }
+            for (const componentNode of componentNodes) {
+                checkForBusinessLogic(componentNode, sourceFile, violations, context.filePath);
+            }
+            return {
+                violations,
+                passed: violations.length === 0,
+            };
+        },
+    };
+}
+function createDataFetchingInUIRule() {
+    return {
+        name: "no-data-fetching-in-ui",
+        description: "Prevents data fetching inside React UI layer components",
+        execute(context) {
+            const violations = [];
+            if (!context.architecture.rules.noDataFetchingInUI) {
+                return { violations: [], passed: true };
+            }
+            if (!(0, archguard_core_1.fileBelongsToUiLayer)(context.filePath, context.architecture)) {
+                return { violations: [], passed: true };
+            }
+            const sourceFile = (0, archguard_core_1.parseTypeScript)(context.sourceCode, context.filePath);
+            const componentNodes = getComponentNodes(sourceFile);
+            if (componentNodes.length === 0) {
+                return { violations: [], passed: true };
+            }
+            const importedSymbols = buildImportedSymbolLayers(context);
+            for (const componentNode of componentNodes) {
+                checkForDataFetching(componentNode, sourceFile, violations, context.filePath, importedSymbols);
+            }
+            return {
+                violations,
+                passed: violations.length === 0,
+            };
+        },
+    };
+}
+function createCircularDependencyRule() {
+    return {
+        name: "no-circular-layer-deps",
+        description: "Detects circular dependencies across layers",
+        execute(context) {
+            const violations = [];
+            if (!context.architecture.rules.noCircularLayerDeps) {
+                return { violations: [], passed: true };
+            }
+            if (!context.importGraph) {
+                return { violations: [], passed: true };
+            }
+            const cycles = detectCycles(context.importGraph);
+            for (const cycle of cycles) {
+                const sortedCycle = [...cycle].sort();
+                const firstFileInCycle = sortedCycle[0];
+                if (context.filePath === firstFileInCycle) {
+                    const cyclePath = cycle
+                        .map((filePath) => formatProjectRelativePath(filePath, context.projectRoot))
+                        .join(" → ");
+                    violations.push({
+                        file: context.filePath,
+                        line: 1,
+                        column: 1,
+                        message: `Circular dependency detected: ${cyclePath}. Break the cycle by extracting shared code to a common layer or using dependency inversion.`,
+                        rule: "no-circular-layer-deps",
+                    });
+                }
+            }
+            return {
+                violations,
+                passed: violations.length === 0,
+            };
+        },
+    };
+}
+function detectCycles(graph) {
+    const cycles = [];
+    const visited = new Set();
+    const recStack = new Set();
+    const pathStack = [];
+    function dfs(node) {
+        visited.add(node);
+        recStack.add(node);
+        pathStack.push(node);
+        const neighbors = graph[node] || [];
+        for (const neighbor of neighbors) {
+            if (!visited.has(neighbor)) {
+                dfs(neighbor);
+            }
+            else if (recStack.has(neighbor)) {
+                const cycleStart = pathStack.indexOf(neighbor);
+                if (cycleStart !== -1) {
+                    const cycle = pathStack.slice(cycleStart).concat([neighbor]);
+                    cycles.push(cycle);
+                }
+            }
+        }
+        recStack.delete(node);
+        pathStack.pop();
+    }
+    for (const node of Object.keys(graph)) {
+        if (!visited.has(node)) {
+            dfs(node);
+        }
+    }
+    return cycles;
+}
+function detectLayerFromImport(importedModule, fromFile, layers) {
+    if (importedModule.resolvedPath) {
+        return (0, archguard_core_1.detectLayerFromPath)(importedModule.resolvedPath, layers);
+    }
+    if (isRelativeImport(importedModule.from)) {
+        return detectLayerFromImportPath(importedModule.from, fromFile, layers);
+    }
+    return null;
+}
+function formatProjectRelativePath(filePath, projectRoot) {
+    if (!projectRoot) {
+        return filePath.replace(/\\/g, "/");
+    }
+    const relativePath = path.relative(projectRoot, filePath);
+    if (relativePath && !relativePath.startsWith("..") && !path.isAbsolute(relativePath)) {
+        return relativePath.replace(/\\/g, "/");
+    }
+    return filePath.replace(/\\/g, "/");
+}
+function detectLayerFromImportPath(importPath, fromFile, layers) {
+    const resolvedPath = path.resolve(path.dirname(fromFile), importPath);
+    return (0, archguard_core_1.detectLayerFromPath)(resolvedPath, layers);
+}
+function isRelativeImport(importPath) {
+    return importPath.startsWith(".") || importPath.startsWith("/");
+}
+function findImportNode(sourceFile, importPath) {
+    let found = null;
+    function visit(node) {
+        if (ts.isImportDeclaration(node)) {
+            const moduleSpecifier = node.moduleSpecifier;
+            if (ts.isStringLiteral(moduleSpecifier) && moduleSpecifier.text === importPath) {
+                found = node;
+                return;
+            }
+        }
+        ts.forEachChild(node, visit);
+    }
+    visit(sourceFile);
+    return found;
+}
+function getComponentNodes(sourceFile) {
+    const components = [];
+    function visit(node) {
+        if (ts.isFunctionDeclaration(node) &&
+            node.name &&
+            isPascalCase(node.name.text) &&
+            functionContainsJsx(node)) {
+            components.push(node);
+        }
+        if (ts.isVariableDeclaration(node) &&
+            ts.isIdentifier(node.name) &&
+            isPascalCase(node.name.text) &&
+            node.initializer &&
+            (ts.isArrowFunction(node.initializer) || ts.isFunctionExpression(node.initializer)) &&
+            functionContainsJsx(node.initializer)) {
+            components.push(node.initializer);
+        }
+        ts.forEachChild(node, visit);
+    }
+    visit(sourceFile);
+    return components;
+}
+function functionContainsJsx(node) {
+    if (!node.body) {
+        return false;
+    }
+    let hasJsx = false;
+    function visit(child) {
+        if (ts.isJsxElement(child) || ts.isJsxSelfClosingElement(child) || ts.isJsxFragment(child)) {
+            hasJsx = true;
+            return;
+        }
+        ts.forEachChild(child, visit);
+    }
+    visit(node.body);
+    return hasJsx;
+}
+function isPascalCase(name) {
+    return /^[A-Z]/.test(name);
+}
+function checkForBusinessLogic(node, sourceFile, violations, filePath) {
+    function visit(n) {
+        if (ts.isForStatement(n) ||
+            ts.isForInStatement(n) ||
+            ts.isForOfStatement(n) ||
+            ts.isWhileStatement(n) ||
+            ts.isDoStatement(n)) {
+            const { line, character } = sourceFile.getLineAndCharacterOfPosition(n.getStart());
+            violations.push({
+                file: filePath,
+                line: line + 1,
+                column: character + 1,
+                message: "Loop detected in UI component. Extract loop logic to a utility function in features/domain layer and pass processed data as props.",
+                rule: "no-business-logic-in-components",
+            });
+        }
+        if (ts.isIfStatement(n) && !isSimpleConditional(n)) {
+            const { line, character } = sourceFile.getLineAndCharacterOfPosition(n.getStart());
+            violations.push({
+                file: filePath,
+                line: line + 1,
+                column: character + 1,
+                message: "Complex conditional in UI component. Extract to a custom hook (e.g. useConditionalLogic) in features layer or move to domain utilities.",
+                rule: "no-business-logic-in-components",
+            });
+        }
+        ts.forEachChild(n, visit);
+    }
+    visit(node);
+}
+function checkForDataFetching(node, sourceFile, violations, filePath, importedSymbols) {
+    function visit(n) {
+        if (ts.isCallExpression(n) && isForbiddenDataFetchCall(n, importedSymbols)) {
+            const { line, character } = sourceFile.getLineAndCharacterOfPosition(n.expression.getStart());
+            violations.push({
+                file: filePath,
+                line: line + 1,
+                column: character + 1,
+                message: "Data fetching in UI component violates architecture. Create a custom hook in the features layer (e.g. useUserData) and call it from the component.",
+                rule: "no-data-fetching-in-ui",
+            });
+        }
+        ts.forEachChild(n, visit);
+    }
+    visit(node);
+}
+function buildImportedSymbolLayers(context) {
+    const importedSymbols = new Map();
+    for (const imp of context.imports) {
+        if (imp.isTypeOnly) {
+            continue;
+        }
+        const importedLayer = detectLayerFromImport(imp, context.filePath, context.architecture.layers);
+        for (const specifier of imp.specifiers) {
+            importedSymbols.set(specifier, importedLayer);
+        }
+    }
+    return importedSymbols;
+}
+function isForbiddenDataFetchCall(node, importedSymbols) {
+    if (ts.isIdentifier(node.expression)) {
+        const callee = node.expression.text;
+        if (callee === "fetch" || callee === "axios" || DATA_FETCH_HOOKS.has(callee)) {
+            return true;
+        }
+        return isImportedDataAccessCall(callee, importedSymbols);
+    }
+    if (ts.isPropertyAccessExpression(node.expression) && ts.isIdentifier(node.expression.expression)) {
+        const receiver = node.expression.expression.text;
+        const method = node.expression.name.text;
+        if (receiver === "axios" && DATA_FETCH_AXIOS_METHODS.has(method)) {
+            return true;
+        }
+        if (receiver === "fetch") {
+            return true;
+        }
+    }
+    return false;
+}
+function isImportedDataAccessCall(callee, importedSymbols) {
+    if (!importedSymbols.has(callee) || isReactHookName(callee)) {
+        return false;
+    }
+    const importedLayer = importedSymbols.get(callee);
+    if (!importedLayer) {
+        return false;
+    }
+    if (importedLayer === "domain") {
+        return true;
+    }
+    return importedLayer === "features" && isLikelyDataAccessFunctionName(callee);
+}
+function isReactHookName(name) {
+    return name.startsWith("use") && name.length > 3 && /[A-Z]/.test(name.charAt(3));
+}
+function isLikelyDataAccessFunctionName(name) {
+    return /^(fetch|load|get|read|request)/i.test(name);
+}
+function isSimpleConditional(node) {
+    const expression = node.expression;
+    return (ts.isIdentifier(expression) ||
+        ts.isPropertyAccessExpression(expression) ||
+        ts.isBinaryExpression(expression));
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@lifesavertech/archguard-rules-react",
+  "version": "2.0.0",
+  "description": "React-specific rules for ArchGuard",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "archguard",
+    "architecture",
+    "react"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc -b --force",
+    "prepack": "npm run build",
+    "build:test": "node -e \"require('fs').rmSync('dist-test',{recursive:true,force:true})\" && tsc -p tsconfig.test.json",
+    "test": "npm run build:test && node --test dist-test/index.test.js"
+  },
+  "dependencies": {
+    "@lifesavertech/archguard-core": "2.0.0",
+    "typescript": "^5.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0"
+  },
+  "author": "Lindsey Stead",
+  "homepage": "https://github.com/lindseystead/ArchGuard#readme",
+  "bugs": {
+    "url": "https://github.com/lindseystead/ArchGuard/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lindseystead/ArchGuard.git",
+    "directory": "packages/rules-react"
+  }
+}