@geonosis/oxlint-plugin-biological-architecture 2.7.0 → 2.8.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # @geonosis/oxlint-plugin-biological-architecture
 
+## 2.8.0
+
+### Minor Changes
+
+- e880a6c: The tiers have no dead ends a consumer can reach (#1, #2). Three shapes from one migration had no
+  legal expression, because two rules together forbade every place the file could live:
+  
+  - **`tissue-no-data-props`** accepts layout configuration: a `number` or `boolean` prop the tissue
+    gives a literal default (`initialCount = 10`, `wrap = false`). A stateless adapter between two
+    cells is a tissue, and now it can be one. A string, a default that is not a literal of the prop's
+    type, and a primitive with no default are still data.
+  - **`no-hook-in-component-disguise`** accepts the client-boundary beacon: a file whose directive
+    prologue says `'use client'`, whose component calls a hook and returns only `null`. Its parent — a
+    Server Component, or a tissue under `tissue-no-hooks` — cannot call the hook, so there was no
+    real component to move it into. A `'use client'` component that returns its `children`, or calls
+    no hook, is still reported. The no-hook message now tells a layout about metadata
+    (`passthroughLayout`) and tells any other component nothing of the kind.
+  - **`no-invalid-feature-folders`** takes `roots` (default: none). Directly under each declared
+    directory, a folder that is not a tier is a finding per file, so an unmigrated pile
+    (`src/components/organisms/`) is debt the ratchet counts and moving a file into it grows the
+    count, instead of silently clearing every tier rule.
+  
+  `cell-must-not-compose-cell` keeps no exception; its fix now names the stateful host: two cells
+  side by side, coordinating through the store, arranged by a tissue.
+
 ## 2.7.0
 
 ### Minor Changes

package/RULES.md

@@ -867,7 +867,7 @@ option not named here is one no rule reads.
 | `no-index-count-as-exact` | `estimateFields`, `labelKey` |
 | `no-inert-hidden-jsx` | — |
 | `no-inline-data-in-jsx` | — |
-| `no-invalid-feature-folders` | — |
+| `no-invalid-feature-folders` | `roots` |
 | `no-loader-side-effect-in-index-file` | `directories`, `resourceFactories` |
 | `no-logic-in-component-files` | — |
 | `no-mock-db-in-integration` | `dbModules`, `integrationDirs`, `mockNames` |

package/dist/index.js

@@ -538,7 +538,12 @@ var cellMustNotComposeCell = directionRule({
   description: "Cells must not import from any other cell anywhere in the repo. No same-feature exception, no shared/document/charts exception. Cells compose only atoms, molecules, compounds, and organelles. Type-only imports are allowed.",
   fixShape: `A cell never composes another cell \u2014 not same-feature, not \`shared/\`, no exception. If you want to,
 one of the two is misclassified: arrangement goes up to a \`tissues/\` file, a stateless display goes
-down to \`compounds/\`, a store adapter goes sideways to \`organelles/\`. Private siblings of the SAME
+down to \`compounds/\`, a store adapter goes sideways to \`organelles/\`. A parent that holds state AND
+hosts a cell (a summary card that opens a modal-hosted form) is two cells side by side: the child
+hosts its own modal and reads whether it is open from the store, the parent writes it, and a
+\`tissues/\` file arranges both. Cells coordinate through a store, never through props from one to
+the other. A stateless adapter between cells is a tissue \u2014 it may take number and boolean layout
+configuration with a literal default (\`step = 10\`). Private siblings of the SAME
 component (\`invoice-editor.parts.tsx\` from \`invoice-editor.tsx\`) are one cell and are fine. The
 barrels \`cells/index.ts\`, \`cells/dynamic.ts\` and \`cells/dynamic.tsx\` are exempt \u2014 re-exporting
 siblings is the shape \`cells-folder-index-is-barrel\` requires of them.`,
@@ -2621,6 +2626,7 @@ var EXPLICIT_SIDE_EFFECT_HOOKS = /* @__PURE__ */ new Set([
 ]);
 var CUSTOM_EFFECT_HOOK_PATTERN = /^use[A-Z][A-Za-z0-9]*Effect$/;
 var STORE_HOOK_PATTERN = /^use[A-Z][A-Za-z0-9]*Store$/;
+var ANY_HOOK_PATTERN = /^use[A-Z]/;
 function isSideEffectHook(name) {
   if (EXPLICIT_SIDE_EFFECT_HOOKS.has(name)) return true;
   if (CUSTOM_EFFECT_HOOK_PATTERN.test(name)) return true;
@@ -2634,6 +2640,7 @@ var ROUTE_FALLBACK_BASENAMES = /* @__PURE__ */ new Set([
   "loading.tsx",
   "not-found.tsx"
 ]);
+var LAYOUT_BASENAMES = /* @__PURE__ */ new Set(["layout.tsx", "template.tsx"]);
 var R3F_PACKAGES = /* @__PURE__ */ new Set(["@react-three/drei", "@react-three/fiber"]);
 function isPascalCase(name) {
   return /^[A-Z]/.test(name);
@@ -2666,11 +2673,21 @@ function isIdentityFragment(n) {
   return false;
 }
 function classifyReturnShape(arg) {
-  if (isNullLiteral(arg)) return "identity";
-  if (isChildrenIdentifier(arg)) return "identity";
-  if (isIdentityFragment(arg)) return "identity";
+  if (isNullLiteral(arg)) return "null";
+  if (isChildrenIdentifier(arg)) return "passthrough";
+  if (isIdentityFragment(arg)) return "passthrough";
   return "real";
 }
+function recordReturn(scope, arg) {
+  if (!scope) return;
+  const shape = classifyReturnShape(arg);
+  if (shape === "real") {
+    scope.hasNonIdentityReturn = true;
+    return;
+  }
+  scope.hasIdentityReturn = true;
+  if (shape === "passthrough") scope.hasPassthroughReturn = true;
+}
 function suggestedHookName(componentName) {
   const trimmed = componentName.replace(/(Provider|Sync|Listener|Hydration)$/, "");
   const kebab = trimmed.replaceAll(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
@@ -2684,6 +2701,7 @@ var noHookInComponentDisguise = {
     const basename = normalized.split("/").pop() ?? "";
     if (ROUTE_FALLBACK_BASENAMES.has(basename)) return {};
     let fileUsesR3F = false;
+    let fileIsClientBoundary = false;
     const scopeStack = [];
     let pendingName = null;
     function currentScope() {
@@ -2691,9 +2709,11 @@ var noHookInComponentDisguise = {
     }
     function enterFunction(name, node) {
       scopeStack.push({
+        calledAnyHook: false,
         calledHooks: /* @__PURE__ */ new Set(),
         hasIdentityReturn: false,
         hasNonIdentityReturn: false,
+        hasPassthroughReturn: false,
         name,
         node
       });
@@ -2706,14 +2726,16 @@ var noHookInComponentDisguise = {
       if (scope.hasNonIdentityReturn) return;
       if (!scope.hasIdentityReturn) return;
       if (basename === "page.tsx" && scope.calledHooks.size === 0) return;
+      if (fileIsClientBoundary && scope.calledAnyHook && !scope.hasPassthroughReturn) return;
       const hasHooks = scope.calledHooks.size > 0;
+      const passthrough = LAYOUT_BASENAMES.has(basename) ? "passthroughLayout" : "passthroughComponent";
       context.report({
         data: {
           hooks: hasHooks ? [...scope.calledHooks].toSorted((a, b) => a.localeCompare(b)).join(", ") : "",
           name: scope.name,
           suggested: suggestedHookName(scope.name)
         },
-        messageId: hasHooks ? "hookInDisguise" : "passthroughComponent",
+        messageId: hasHooks ? "hookInDisguise" : passthrough,
         node: scope.node
       });
     }
@@ -2723,12 +2745,7 @@ var noHookInComponentDisguise = {
         pendingName = null;
         enterFunction(name, node);
         if (node.body && node.body.type !== "BlockStatement") {
-          const shape = classifyReturnShape(node.body);
-          const scope = currentScope();
-          if (scope) {
-            if (shape === "identity") scope.hasIdentityReturn = true;
-            else scope.hasNonIdentityReturn = true;
-          }
+          recordReturn(currentScope(), node.body);
         }
       },
       "ArrowFunctionExpression:exit"() {
@@ -2740,6 +2757,7 @@ var noHookInComponentDisguise = {
         if (!scope) return;
         const name = node.callee.name;
         if (!name) return;
+        if (ANY_HOOK_PATTERN.test(name)) scope.calledAnyHook = true;
         if (isSideEffectHook(name)) {
           scope.calledHooks.add(name);
         }
@@ -2765,12 +2783,16 @@ var noHookInComponentDisguise = {
           fileUsesR3F = true;
         }
       },
+      // Only the prologue is a directive: the same string after an import is an expression
+      // statement, and React reads it as nothing.
+      Program(node) {
+        for (const statement2 of node.body ?? []) {
+          if (typeof statement2.directive !== "string") break;
+          if (statement2.directive === "use client") fileIsClientBoundary = true;
+        }
+      },
       ReturnStatement(node) {
-        const scope = currentScope();
-        if (!scope) return;
-        const shape = classifyReturnShape(node.argument);
-        if (shape === "identity") scope.hasIdentityReturn = true;
-        else scope.hasNonIdentityReturn = true;
+        recordReturn(currentScope(), node.argument);
       },
       VariableDeclarator(node) {
         if (node.id?.type === "Identifier" && node.init && (node.init.type === "ArrowFunctionExpression" || node.init.type === "FunctionExpression")) {
@@ -2781,14 +2803,19 @@ var noHookInComponentDisguise = {
   },
   fixShape: `A component that calls hooks, renders nothing, and exists only to run an effect is a hook wearing
 \`.tsx\`. Move it to \`organelles/use-<thing>.ts\`, export it as \`use<Thing>\`, and let the cell call it.
-A component returns UI; a hook returns state.`,
+A component returns UI; a hook returns state. The one exception is the client-boundary beacon, for a
+parent that cannot call hooks \u2014 a Server Component, or a tissue: \`'use client'\` as the file's first
+statement, a hook call, and \`return null\`. Render it beside the children, never around them \u2014 a
+component that returns its \`children\` is still a disguise. A component that calls no hook and
+returns nothing is not a beacon either; delete it.`,
   meta: {
     docs: {
-      description: "Forbid components whose body calls side-effect hooks (useEffect/useLayoutEffect/useInsertionEffect/useRef) but whose every return is identity (null, bare `children`, `<></>`, `<>{children}</>`). Such a component renders no real UI \u2014 it's a hook masquerading as a component. Move to organelles/use-*-effect.ts and call the hook from a real component. Exempt: route fallback files (default/not-found/loading/error/global-error.tsx) and files importing from @react-three/fiber or @react-three/drei. That is lint-theater."
+      description: "Forbid components whose body calls side-effect hooks (useEffect/useLayoutEffect/useInsertionEffect/useRef) but whose every return is identity (null, bare `children`, `<></>`, `<>{children}</>`). Such a component renders no real UI \u2014 it's a hook masquerading as a component. Move to organelles/use-*-effect.ts and call the hook from a real component. Exempt: route fallback files (default/not-found/loading/error/global-error.tsx), files importing from @react-three/fiber or @react-three/drei, and the client-boundary beacon \u2014 a 'use client' file whose component calls a hook and returns only null. That is lint-theater."
     },
     messages: {
-      hookInDisguise: "Component '{{name}}' has side-effect hooks ({{hooks}}) but renders only identity/null. It's a hook in disguise \u2014 move to organelles/use-{{suggested}}-effect.ts and call the hook from a real component.",
-      passthroughComponent: "Component '{{name}}' renders only identity/null with no effects. It serves no architectural purpose. If this is a metadata-only layout, move `metadata`/`generateMetadata` to the sibling page.tsx and delete this file. If it's structural, give it real content."
+      hookInDisguise: "Component '{{name}}' has side-effect hooks ({{hooks}}) but renders only identity/null. It's a hook in disguise \u2014 move to organelles/use-{{suggested}}-effect.ts and call the hook from a real component. If its parent cannot call hooks (a Server Component, a tissue), make it the client boundary instead: 'use client' first, and return null \u2014 rendered beside the children, not around them.",
+      passthroughComponent: "Component '{{name}}' renders only identity/null and calls no hook. It serves no architectural purpose: delete it and render its children where it is used, or give it real content.",
+      passthroughLayout: "Component '{{name}}' renders only identity/null with no effects. It serves no architectural purpose. If this is a metadata-only layout, move `metadata`/`generateMetadata` to the sibling page.tsx and delete this file. If it's structural, give it real content."
     },
     schema: [],
     type: "problem"
@@ -3017,10 +3044,31 @@ var VALID_FOLDERS = /* @__PURE__ */ new Set([
   "tissues"
 ]);
 var FEATURE_PATH_PATTERN = /features\/([^/]+)\/([^/]+)\//;
+var folderUnderRoot = (normalized, roots) => {
+  const path2 = `/${normalized}`;
+  for (const declared of roots) {
+    const root = declared.replaceAll(/^\/+|\/+$/g, "");
+    const at = path2.indexOf(`/${root}/`);
+    if (root === "" || at === -1) continue;
+    const rest = path2.slice(at + root.length + 2);
+    const slash = rest.indexOf("/");
+    if (slash !== -1) return { folder: rest.slice(0, slash), root };
+  }
+  return void 0;
+};
 var noInvalidFeatureFolders = {
   create(context) {
     const normalized = normalise(context.filename);
     const match = normalized.match(FEATURE_PATH_PATTERN);
+    const { roots = [] } = context.options?.[0] ?? {};
+    const underRoot = match ? void 0 : folderUnderRoot(normalized, roots);
+    if (underRoot && underRoot.folder !== "features" && !VALID_FOLDERS.has(underRoot.folder)) {
+      return {
+        Program(node) {
+          context.report({ data: underRoot, messageId: "untiered", node });
+        }
+      };
+    }
     if (!match) return {};
     const feature = match[1] ?? "";
     const folder = match[2] ?? "";
@@ -3050,16 +3098,28 @@ var noInvalidFeatureFolders = {
   fixShape: `A feature folder holds only the tiers and their two neighbours: \`atoms\`, \`molecules\`, \`compounds\`,
 \`organelles\`, \`cells\`, \`tissues\`, \`stores\`, \`lib\`. Anything else (\`components\`, \`utils\`, \`helpers\`,
 \`types\`) is an unclassified pile \u2014 put the file in the tier that describes what it does, and pure
-logic in \`lib/\`.`,
+logic in \`lib/\`. A repo whose components live outside \`features/\` names those directories in
+\`roots\` (default: none), and the same holds directly under each one. An unmigrated folder there
+(\`organisms/\`) is a finding per file \u2014 debt the ratchet counts, never a place to park a file whose
+tier would not accept it.`,
   meta: {
     docs: {
-      description: 'Files inside features/*/ must be in a valid biological hierarchy folder. Hooks (use-*) must be in organelles/, not lib/. Folders like "dynamic", "utils", "helpers", "components", "hooks" are forbidden.'
+      description: 'Files inside features/*/ \u2014 and directly under each directory the `roots` option declares \u2014 must be in a valid biological hierarchy folder. Hooks (use-*) must be in organelles/, not lib/. Folders like "dynamic", "utils", "helpers", "components", "hooks" are forbidden.'
     },
     messages: {
       hookInLib: 'Hook file "{{file}}" is in features/{{feature}}/lib/ but hooks must be in features/{{feature}}/organelles/. lib/ is for pure logic only \u2014 no hooks, no state.',
-      invalid: 'File is in "features/{{feature}}/{{folder}}/" which is not a valid biological hierarchy folder. Valid folders: compounds, organelles, cells, tissues, stores, lib.'
+      invalid: 'File is in "features/{{feature}}/{{folder}}/" which is not a valid biological hierarchy folder. Valid folders: compounds, organelles, cells, tissues, stores, lib.',
+      untiered: 'File is in "{{root}}/{{folder}}/", which is not a tier, so no tier rule inspects it. Move it to the tier that describes what it does: atoms, molecules, compounds, organelles, cells, tissues, stores or lib.'
     },
-    schema: [],
+    schema: [
+      {
+        additionalProperties: false,
+        properties: {
+          roots: { items: { type: "string" }, type: "array" }
+        },
+        type: "object"
+      }
+    ],
     type: "problem"
   }
 };
@@ -6297,6 +6357,12 @@ function isAllowedType(t) {
       return true;
   }
 }
+var literalDefaultsOf = (param) => new Map(
+  (param.properties ?? []).flatMap(
+    (property) => property.type === "Property" && property.key?.type === "Identifier" && property.value?.type === "AssignmentPattern" && property.value.right?.type === "Literal" ? [[property.key.name ?? "", property.value.right.value]] : []
+  )
+);
+var isLayoutConfiguration = (t, defaults, prop) => t.type === "TSNumberKeyword" && typeof defaults.get(prop) === "number" || t.type === "TSBooleanKeyword" && typeof defaults.get(prop) === "boolean";
 var tissueNoDataProps = {
   create(context) {
     const normalized = normalise(context.filename);
@@ -6312,6 +6378,7 @@ var tissueNoDataProps = {
       const typeLiteral = firstParam.typeAnnotation?.typeAnnotation;
       if (!typeLiteral || typeLiteral.type !== "TSTypeLiteral") return;
       const members = typeLiteral.members ?? [];
+      const defaults = literalDefaultsOf(firstParam);
       for (const member of members) {
         if (member.key?.type !== "Identifier") continue;
         const propName = member.key.name ?? "";
@@ -6320,6 +6387,7 @@ var tissueNoDataProps = {
         const t = member.typeAnnotation?.typeAnnotation;
         if (!t) continue;
         if (isAllowedType(t)) continue;
+        if (isLayoutConfiguration(t, defaults, propName)) continue;
         context.report({
           data: { prop: propName, type: describeTypeAnnotation(t) },
           messageId: "dataProp",
@@ -6359,13 +6427,14 @@ var tissueNoDataProps = {
   fixShape: `A tissue takes \`children\`, ReactNode slot props, layout variants, \`params\` and \`searchParams\` \u2014 and
 nothing else. A prop typed \`string\`, \`number\`, an array or a domain type (\`id\`, \`initialData\`,
 \`documents\`) means the file owns data, which makes it a CELL: move it to \`cells/\`. A tissue gets its
-content as slots, never as data.`,
+content as slots, never as data. Layout configuration is not data: a \`number\` or \`boolean\` prop the
+tissue gives a literal default (\`{ step = 10, wrap = false }\`) is allowed.`,
   meta: {
     docs: {
       description: "Tissues must not own data. Props on a tissue must be limited to `children`, ReactNode slot props, `params`, `searchParams`, icon types, or layout-variant literal unions. Any primitive (`string`/`number`/`boolean`), array type, or arbitrary domain type reference means the file is actually a cell \u2014 move it to cells/. That is lint-theater.2 (Tissue self-sufficiency rule)."
     },
     messages: {
-      dataProp: "Tissue prop '{{prop}}' has type '{{type}}' which is not allowed on a tissue. Tissues arrange children without owning data. Move the file from features/*/tissues/ to features/*/cells/ \u2014 cells own data. Allowed tissue props: children, params, searchParams, ReactNode slots, literal-union variants, icon types."
+      dataProp: "Tissue prop '{{prop}}' has type '{{type}}' which is not allowed on a tissue. Tissues arrange children without owning data. Move the file from features/*/tissues/ to features/*/cells/ \u2014 cells own data. Allowed tissue props: children, params, searchParams, ReactNode slots, literal-union variants, icon types, and number/boolean layout configuration with a literal default."
     },
     schema: [],
     type: "problem"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geonosis/oxlint-plugin-biological-architecture",
-  "version": "2.7.0",
+  "version": "2.8.0",
   "types": "./dist/index.d.ts",
   "description": "Biological tier architecture as lint — the union of the dielime and during.day rule sets, shipped as presets.",
   "keywords": [
@@ -45,7 +45,7 @@
     "oxlint": ">=1.77"
   },
   "devDependencies": {
-    "@geonosis/lint-parity": "2.7.0"
+    "@geonosis/lint-parity": "2.8.0"
   },
   "engines": {
     "node": ">=22"