@geonosis/oxlint-plugin-biological-architecture 0.1.1 → 0.2.0

package/README.md

@@ -1,9 +1,9 @@
 # @geonosis/oxlint-plugin-biological-architecture
 
-54 architecture rules as an oxlint JS plugin: which tier a file belongs to, what it may import,
+55 architecture rules as an oxlint JS plugin: which tier a file belongs to, what it may import,
 where state is allowed to live, and the backend invariants that go with them. Nothing is hardcoded
-to a repo — every list of brands, features, tables or paths is an option whose default does nothing
-until it is configured.
+to a repo — every list of brands, features, tables or paths is an option. A rule enabled without the
+options it needs refuses the run rather than passing silently.
 
 ## Install
 
@@ -63,6 +63,7 @@ everything below the organelle is inert. A cell never composes another cell.
 | `backend-d1` | 2 | Cloudflare D1 facts — false on an engine with transactions |
 | `backend-medusa` | 1 | the storefront route surface |
 | `backend-sagaflow-cf` | 1 | durable runs on Cloudflare Workflows — false of an inline saga |
+| `tooling` | 1 | `layer-walls` — a repo's OWN layers, declared as data and walled |
 | `comment-ceiling` | 1 | the comment posture, opt-in (+ oxlint's `capitalized-comments`) |
 
 A rule that is false on another stack gets its own preset rather than riding along in a generic
@@ -72,78 +73,76 @@ one: a preset carrying a repo fact is a repo fact wearing a preset's name.
 
 A repo that already has its own copy of these rules does not delete it because the version numbers
 match. It deletes it when the **findings** match: same tree, same rule ids, two configs, and a diff.
-`geonosis-lint-parity` is that diff.
+[`@geonosis/lint-parity`](https://www.npmjs.com/package/@geonosis/lint-parity) is that diff — a
+separate package, because a parity tool welded to one rule plugin can only ever check that plugin.
+What this package ships towards it is the **evidence**: `corpus/`, the fixture tree its own gates
+run against, one deliberately broken file per rule, plus a `manifest.json` generated from the
+plugin's own rules export naming exactly the rules that corpus speaks for.
 
 ```bash
-geonosis-lint-parity --a <config-a.json> --b <config-b.json> [--oxlint <path>] [--out <dir>] -- <paths…>
+pnpm add -D @geonosis/lint-parity
 ```
 
 ### Step 0 — reach, before parity
 
 Parity between two configs that both do nothing is perfect parity. In one source repo 34 of 51
 configured rules fired nowhere in any corpus it had: 34 rules a consumer would inherit as claims
-nothing could check. So this package ships the **reach corpus** — the fixture tree its own gates run
-against, one deliberately broken file per rule — and answers the question directly:
+nothing could check. Point the tool at the corpus this package installed:
 
 ```bash
-geonosis-lint-parity --corpus --a oxlintrc.fork.json --b oxlintrc.published.json [--out <dir>]
+npx geonosis-lint-parity \
+  --corpus node_modules/@geonosis/oxlint-plugin-biological-architecture/corpus \
+  --a oxlintrc.fork.json --b oxlintrc.published.json --out proofs/reach
 ```
 
-Both configs run over the shipped corpus (copied to a temp root first, so neither a `.gitignore` nor
-oxlint's `node_modules` skip can quietly turn "every rule fired nowhere" into the answer). It prints
-a fired-under-A / fired-under-B row per configured rule and **exits 1 when a rule fires under
-neither**. `--out` writes `CORPUS.md`.
+It prints a fired-under-A / fired-under-B row per in-scope rule and **exits 1 when one fires under
+neither**. A configured `eqeqeq`, `unicorn/*` or `typescript/*` is listed under **outside this
+corpus** and gets no verdict: this tree is no evidence either way about somebody else's rule.
 
 Every rule this package exports has at least one corpus file that fires it, and a test fails if that
 stops being true — so a rule cannot be added without evidence it reaches anything.
 
 ### Then parity
 
-It runs oxlint twice with `--format=unix` over the same paths, strips the working-directory prefix,
-sorts, and prints the two counts, `only in A`, `only in B` and a per-rule tally. **It exits 1 when
-`only in A` is non-empty** — a finding the old config caught and the new one does not. New findings
-are what an upgrade is for; lost ones stop the adoption. `--out` writes `a.txt`, `b.txt`,
-`only-in-a.txt`, `only-in-b.txt` and `SUMMARY.md` for the proof file.
-
 **Fork vs published**, before deleting a vendored copy — two configs identical but for `jsPlugins`:
 
 ```bash
 # oxlintrc.fork.json      → "jsPlugins": ["./packages/eslint-plugin-biological-architecture"]
 # oxlintrc.published.json → "jsPlugins": ["@geonosis/oxlint-plugin-biological-architecture"]
-geonosis-lint-parity \
+npx geonosis-lint-parity \
   --a oxlintrc.fork.json --b oxlintrc.published.json \
   --out proofs/adoption-parity \
   -- apps packages
 ```
 
-**Version vs version**, as the kit's own release check — the same config, pointing first at the
-installed version and then at a local build, by absolute path:
-
-```bash
-geonosis-lint-parity \
-  --a oxlintrc.0.1.0.json --b oxlintrc.0.1.1.json \
-  --out proofs/parity-0.1.0-vs-0.1.1 \
-  -- apps packages
-```
+**Write both configs inside the workspace being linted** — oxlint resolves a `jsPlugins` specifier
+relative to the **config file's** directory, not the working directory. It exits 1 when a finding
+config A reported is missing under config B; a reworded message is reported as **changed** and never
+reaches the exit code. The tool's README has the rest.
 
-`--oxlint` overrides the binary; by default it walks up from the working directory for
-`node_modules/.bin/oxlint`, so the comparison runs under the consumer's own linter rather than one
-`npx` might fetch. Every difference the run reports has to trace to a decision written down in
-`RULES.md`; one that does not is a defect, not a difference.
+Every difference a run reports has to trace to a decision written down in `RULES.md`; one that does
+not is a defect, not a difference.
 
 ### What the two configs must say for the findings to match
 
-A fork usually had its repo's vocabulary compiled in. Here it is configuration, and a config that
-omits it turns the rule off — which reads as a lost finding, correctly. Carry these across:
+A fork usually had its repo's vocabulary compiled in. Here it is configuration — and **a rule
+enabled without the options it needs refuses the run**, naming itself and the missing option, rather
+than quietly finding nothing. That is deliberate: a rule enabled at `"error"` with nothing to
+compare against is indistinguishable from a clean tree, and one consumer shipped exactly that for
+months. Carry these across, or turn the rule off:
 
-| Rule | Option | Without it |
+| Rule | Option | Enabled without it |
 | --- | --- | --- |
-| `no-brand-names` | `{ brands, allowedSubstrings }` | does nothing |
+| `no-brand-names` | `{ brands, allowedSubstrings }` | refuses the run |
 | `organelle-dependency` | `{ sharedFeatures }` | only `shared` crosses a feature boundary |
-| `documents-share-one-table` | `{ perKindTables }` | does nothing |
-| `document-sagas-are-generic` | `{ perKindPrefixes }` | does nothing |
-| `step-opens-its-own-cell` | `{ engine, within, wrapper }` | does nothing |
-| `no-raw-html-atoms` | the positional element→atom map | does nothing |
+| `documents-share-one-table` | `{ perKindTables }` | refuses the run |
+| `document-sagas-are-generic` | `{ perKindPrefixes }` | refuses the run |
+| `step-opens-its-own-cell` | `{ engine, within, wrapper }` | refuses the run |
+| `no-raw-html-atoms` | the positional element→atom map | refuses the run |
+| `layer-walls` | `{ layers: [{ name, paths, mayImport }], externals? }` | refuses the run |
+
+An empty list counts as unconfigured. A rule set to `"off"`, or never named, is untouched — "does
+nothing until configured" survives for a rule nobody enabled, which is oxlint's job, not ours.
 
 Two more facts a fork's config will trip on:
 

package/corpus/.oxlintrc.json

@@ -35,6 +35,39 @@
       }
     ],
     "biological-architecture/effect-hook-naming": "error",
+    "biological-architecture/layer-walls": [
+      "error",
+      {
+        "layers": [
+          {
+            "name": "core",
+            "paths": [
+              "(?:^|/)layers/core/"
+            ],
+            "mayImport": []
+          },
+          {
+            "name": "feature",
+            "paths": [
+              "(?:^|/)layers/feature/"
+            ],
+            "mayImport": [
+              "core"
+            ]
+          },
+          {
+            "name": "shell",
+            "paths": [
+              "(?:^|/)layers/shell/"
+            ],
+            "mayImport": [
+              "core",
+              "feature"
+            ]
+          }
+        ]
+      }
+    ],
     "biological-architecture/max-comment-density": "error",
     "biological-architecture/molecule-atoms-only": "error",
     "biological-architecture/molecule-must-compose": "error",

package/corpus/layers/core/bad-reaches-up.ts

@@ -0,0 +1,3 @@
+import { helper } from '../feature/sibling'
+
+export const reachesUp = () => helper()

package/corpus/layers/core/thing.ts

@@ -0,0 +1 @@
+export const thing = () => 'core'

package/corpus/layers/feature/bad-relative.ts

@@ -0,0 +1,3 @@
+import { boot } from '../shell/boot'
+
+export const crosses = () => boot()

package/corpus/layers/feature/good-downward.ts

@@ -0,0 +1,3 @@
+import { thing } from '../core/thing'
+
+export const downward = () => thing()

package/corpus/layers/feature/good-same-layer.ts

@@ -0,0 +1,3 @@
+import { helper } from './sibling'
+
+export const sameLayer = () => helper()

package/corpus/layers/feature/good-type-only.ts

@@ -0,0 +1,3 @@
+import type { Boot } from '../shell/boot'
+
+export const describeBoot = (boot: Boot): string => boot.name

package/corpus/layers/feature/sibling.ts

@@ -0,0 +1 @@
+export const helper = () => 'feature'

package/corpus/layers/shell/boot.ts

@@ -0,0 +1,3 @@
+export type Boot = { name: string }
+
+export const boot = () => 'shell'

package/corpus/manifest.json

@@ -0,0 +1,60 @@
+{
+  "plugin": "biological-architecture",
+  "rules": [
+    "biological-architecture/atom-no-deps",
+    "biological-architecture/cell-must-be-stateful",
+    "biological-architecture/cell-must-not-compose-cell",
+    "biological-architecture/cell-no-tissues",
+    "biological-architecture/cells-folder-index-is-barrel",
+    "biological-architecture/compound-must-be-stateless",
+    "biological-architecture/compound-no-stores",
+    "biological-architecture/constants-in-constants-file",
+    "biological-architecture/dialect-through-the-seam",
+    "biological-architecture/document-sagas-are-generic",
+    "biological-architecture/documents-share-one-table",
+    "biological-architecture/effect-hook-naming",
+    "biological-architecture/layer-walls",
+    "biological-architecture/max-comment-density",
+    "biological-architecture/molecule-atoms-only",
+    "biological-architecture/molecule-must-compose",
+    "biological-architecture/next-route-segment-is-thin-delegate",
+    "biological-architecture/no-brand-names",
+    "biological-architecture/no-card-shaped-div",
+    "biological-architecture/no-cross-feature-stores",
+    "biological-architecture/no-d1-transaction",
+    "biological-architecture/no-duplicate-jsx-patterns",
+    "biological-architecture/no-hook-in-component-disguise",
+    "biological-architecture/no-inert-hidden-jsx",
+    "biological-architecture/no-inline-data-in-jsx",
+    "biological-architecture/no-invalid-feature-folders",
+    "biological-architecture/no-logic-in-component-files",
+    "biological-architecture/no-orm-outside-db",
+    "biological-architecture/no-raw-html-atoms",
+    "biological-architecture/no-raw-sql-outside-allowed",
+    "biological-architecture/no-react-namespace",
+    "biological-architecture/no-renamed-html-props",
+    "biological-architecture/no-render-prop-reader",
+    "biological-architecture/no-trivial-wrapper-component",
+    "biological-architecture/no-ts-in-bio-folders",
+    "biological-architecture/no-type-definitions-in-components",
+    "biological-architecture/no-void-port",
+    "biological-architecture/organelle-dependency",
+    "biological-architecture/organelle-single-source",
+    "biological-architecture/queries-require-org-scope",
+    "biological-architecture/queue-loop-is-the-library",
+    "biological-architecture/ssot-no-inline-facts",
+    "biological-architecture/ssot-no-process-env",
+    "biological-architecture/step-opens-its-own-cell",
+    "biological-architecture/store-route-scopes-tenant-data",
+    "biological-architecture/tables-declare-their-plane",
+    "biological-architecture/tenant-tables-carry-org-id",
+    "biological-architecture/time-through-the-door",
+    "biological-architecture/tissue-must-compose",
+    "biological-architecture/tissue-no-data-props",
+    "biological-architecture/tissue-no-hooks",
+    "biological-architecture/tissue-no-organelles",
+    "biological-architecture/tissue-no-stores",
+    "biological-architecture/worker-handles-are-scoped",
+    "biological-architecture/zustand-v5-best-practices"
+  ]
+}

package/dist/{chunk-74VWOEPL.js → chunk-HXBZSOIU.js}

@@ -59,6 +59,7 @@ var TENANT_SCOPING = [
   "tables-declare-their-plane",
   "tenant-tables-carry-org-id"
 ];
+var TOOLING = ["layer-walls"];
 var RULE_PREFIX = "biological-architecture";
 var asRules = (names) => Object.fromEntries(names.map((name) => [`${RULE_PREFIX}/${name}`, "error"]));
 var COMMENT_CEILING = {
@@ -75,7 +76,8 @@ var PRESETS = {
   "comment-ceiling": COMMENT_CEILING,
   frontend: { rules: asRules(FRONTEND) },
   recommended: { rules: asRules(FRONTEND) },
-  "tenant-scoping": { rules: asRules(TENANT_SCOPING) }
+  "tenant-scoping": { rules: asRules(TENANT_SCOPING) },
+  tooling: { rules: asRules(TOOLING) }
 };
 var rulesOfPreset = (preset) => Object.keys(PRESETS[preset].rules).filter((id) => id.startsWith(`${RULE_PREFIX}/`)).map((id) => id.slice(RULE_PREFIX.length + 1));
 

package/dist/discover-atoms.d.ts

@@ -0,0 +1,39 @@
+interface AtomMapping {
+    atomFile: string;
+    atomName: string;
+    nativeElement: string;
+}
+interface AtomRestriction {
+    atom: string;
+    element: string;
+    importPath: string;
+}
+interface RestrictedSyntaxEntry {
+    message: string;
+    selector: string;
+}
+/**
+ * Build no-restricted-syntax entries that forbid raw native HTML usage
+ * for every native element wrapped by an atom. Apply these entries to
+ * molecules, compounds, cells, and tissues (NOT atoms themselves).
+ */
+declare function buildAtomRestrictions(atomsDir: string, importPathPrefix?: string): RestrictedSyntaxEntry[];
+/**
+ * Build atom restrictions in the format expected by the no-raw-html-atoms rule.
+ * This replaces no-restricted-syntax for linters that don't support it (e.g. oxlint).
+ */
+declare function buildAtomRuleRestrictions(atomsDir: string, importPathPrefix?: string): AtomRestriction[];
+/**
+ * Scan the atoms directory and build a mapping from native HTML element
+ * to the atom that wraps it. This is used to generate no-restricted-syntax
+ * entries that forbid raw native HTML usage in higher-level components.
+ *
+ * When multiple atoms wrap the same element (e.g. `input.tsx` and
+ * `inline-input.tsx` both wrap `<input>`), the atom whose filename
+ * exactly matches the element name is preferred as the canonical one.
+ * Variants are kept as alternatives in the error message.
+ */
+declare function scanAtomMappings(atomsDir: string): AtomMapping[];
+declare function detectFirstNativeJsxElement(source: string): null | string;
+
+export { buildAtomRestrictions, buildAtomRuleRestrictions, detectFirstNativeJsxElement, scanAtomMappings };

package/dist/index.d.ts

@@ -0,0 +1,54 @@
+import { Preset } from './presets.js';
+export { PRESETS, PresetName, rulesOfPreset } from './presets.js';
+
+type Rule = {
+    create: (context: never) => Record<string, unknown>;
+    fixShape: string;
+    meta: {
+        docs: {
+            description: string;
+        };
+        messages: Record<string, string>;
+        schema: unknown[];
+        type: string;
+    };
+};
+declare const rules: Record<string, Rule>;
+type RuleName = string;
+
+declare const plugin: {
+    configs: {
+        'backend-d1': {
+            rules: Record<string, "error">;
+        };
+        'backend-medusa': {
+            rules: Record<string, "error">;
+        };
+        'backend-sagaflow-cf': {
+            rules: Record<string, "error">;
+        };
+        'backend-workflows': {
+            rules: Record<string, "error">;
+        };
+        'comment-ceiling': Preset;
+        frontend: {
+            rules: Record<string, "error">;
+        };
+        recommended: {
+            rules: Record<string, "error">;
+        };
+        'tenant-scoping': {
+            rules: Record<string, "error">;
+        };
+        tooling: {
+            rules: Record<string, "error">;
+        };
+    };
+    meta: {
+        name: string;
+        version: string;
+    };
+    rules: Record<string, Rule>;
+};
+
+export { Preset, type Rule, type RuleName, plugin as default, rules };