@geonosis/oxlint-plugin-biological-architecture 0.1.0 → 0.1.2

package/README.md

@@ -68,6 +68,113 @@ everything below the organelle is inert. A cell never composes another cell.
 A rule that is false on another stack gets its own preset rather than riding along in a generic
 one: a preset carrying a repo fact is a repo fact wearing a preset's name.
 
+## Adopting
+
+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.
+
+```bash
+geonosis-lint-parity --a <config-a.json> --b <config-b.json> [--oxlint <path>] [--out <dir>] -- <paths…>
+```
+
+**Write both configs inside the workspace being linted** — `<ws>/.oxlintrc.parity-a.json`, deleted
+afterwards — or name the plugin by absolute path in `jsPlugins`. oxlint resolves a `jsPlugins`
+specifier relative to the **config file's** directory, not the working directory, so a config
+written to a temp dir cannot find a plugin installed in the workspace: it fails with
+`Cannot find module '@…/plugin'`, and the tool correctly refuses with
+`config A: oxlint exited 1 without reporting a single finding`.
+
+### 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:
+
+```bash
+geonosis-lint-parity --corpus [<dir>] --a oxlintrc.fork.json --b oxlintrc.published.json [--out <dir>]
+```
+
+Both configs run over the 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 in-scope rule and **exits 1 when one fires under neither**.
+`--out` writes `CORPUS.md`.
+
+**A corpus covers the rules its own `manifest.json` names, and only those.** The one this package
+ships names `biological-architecture/*` — one deliberately broken file per rule, the list generated
+from the plugin's own rules export at build time. 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, and judging one would fail every real config for saying
+nothing. `--corpus <dir>` points the same run at another plugin's corpus; the scope moves with it.
+
+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`, `changed.txt` and `SUMMARY.md` for the proof file.
+
+**A finding is identified by where it is and which rule found it — `path:line:col` plus
+`plugin(rule)`.** The message is not part of it, and neither is the severity. A release that only
+rewords a rule's message would otherwise show as one finding lost and one gained, and stop an
+adoption over a sentence. Those pair up instead under **changed**, reported in full and never
+reaching the exit code; a severity change lands there too, because that is a fact about the config
+rather than a rule that stopped firing.
+
+**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 \
+  --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
+```
+
+`--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.
+
+### 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:
+
+| Rule | Option | Without it |
+| --- | --- | --- |
+| `no-brand-names` | `{ brands, allowedSubstrings }` | does nothing |
+| `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 |
+
+Two more facts a fork's config will trip on:
+
+- **`cell-handles-are-scoped` is `worker-handles-are-scoped` here.** Same rule; it gave up the word
+  "cell" because in this kit a cell is a tier, and a backend rule meaning a D1 database handle by it
+  would teach the wrong vocabulary at every diagnostic. Rename the key in the config.
+- **Rule ids keep the `biological-architecture/` prefix whatever the package is called.** The
+  namespace is the plugin's identity, not the package's, so renaming or re-scoping the package does
+  not rename a single rule id in a single consumer config.
+
 ## Where to read on
 
 - `RULES.md` — every rule, its preset, which source tree it came from, and how each divergence was

package/bin/geonosis-lint-parity.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+// Committed, so `pnpm install` can link the bin on a fresh clone — before `pnpm build` has
+// produced dist/. A bin that only exists after a build is a bin that is missing when you need it.
+import '../dist/parity-cli.js'

package/corpus/.oxlintrc.json

@@ -0,0 +1,114 @@
+{
+  "$schema": "https://raw.githubusercontent.com/oxc-project/oxc/main/npm/oxlint/configuration_schema.json",
+  "jsPlugins": [
+    "@geonosis/oxlint-plugin-biological-architecture"
+  ],
+  "categories": {
+    "correctness": "off",
+    "suspicious": "off"
+  },
+  "rules": {
+    "biological-architecture/atom-no-deps": "error",
+    "biological-architecture/cell-must-be-stateful": "error",
+    "biological-architecture/cell-must-not-compose-cell": "error",
+    "biological-architecture/cell-no-tissues": "error",
+    "biological-architecture/cells-folder-index-is-barrel": "error",
+    "biological-architecture/compound-must-be-stateless": "error",
+    "biological-architecture/compound-no-stores": "error",
+    "biological-architecture/constants-in-constants-file": "error",
+    "biological-architecture/dialect-through-the-seam": "error",
+    "biological-architecture/document-sagas-are-generic": [
+      "error",
+      {
+        "perKindPrefixes": [
+          "invoice"
+        ]
+      }
+    ],
+    "biological-architecture/documents-share-one-table": [
+      "error",
+      {
+        "perKindTables": [
+          "invoices",
+          "quotes"
+        ]
+      }
+    ],
+    "biological-architecture/effect-hook-naming": "error",
+    "biological-architecture/max-comment-density": "error",
+    "biological-architecture/molecule-atoms-only": "error",
+    "biological-architecture/molecule-must-compose": "error",
+    "biological-architecture/next-route-segment-is-thin-delegate": "error",
+    "biological-architecture/no-brand-names": [
+      "error",
+      {
+        "brands": [
+          "acme"
+        ],
+        "allowedSubstrings": [
+          "media.acme.com"
+        ]
+      }
+    ],
+    "biological-architecture/no-card-shaped-div": "error",
+    "biological-architecture/no-cross-feature-stores": "error",
+    "biological-architecture/no-d1-transaction": "error",
+    "biological-architecture/no-duplicate-jsx-patterns": "error",
+    "biological-architecture/no-hook-in-component-disguise": "error",
+    "biological-architecture/no-inert-hidden-jsx": "error",
+    "biological-architecture/no-inline-data-in-jsx": "error",
+    "biological-architecture/no-invalid-feature-folders": "error",
+    "biological-architecture/no-logic-in-component-files": "error",
+    "biological-architecture/no-orm-outside-db": "error",
+    "biological-architecture/no-raw-html-atoms": [
+      "error",
+      [
+        {
+          "element": "button",
+          "atom": "Button",
+          "importPath": "@kit/ui/atoms/button"
+        }
+      ]
+    ],
+    "biological-architecture/no-raw-sql-outside-allowed": "error",
+    "biological-architecture/no-react-namespace": "error",
+    "biological-architecture/no-renamed-html-props": "error",
+    "biological-architecture/no-render-prop-reader": "error",
+    "biological-architecture/no-trivial-wrapper-component": "error",
+    "biological-architecture/no-ts-in-bio-folders": "error",
+    "biological-architecture/no-type-definitions-in-components": "error",
+    "biological-architecture/no-void-port": "error",
+    "biological-architecture/organelle-dependency": [
+      "error",
+      {
+        "sharedFeatures": [
+          "shared"
+        ]
+      }
+    ],
+    "biological-architecture/organelle-single-source": "error",
+    "biological-architecture/queries-require-org-scope": "error",
+    "biological-architecture/queue-loop-is-the-library": "error",
+    "biological-architecture/ssot-no-inline-facts": "error",
+    "biological-architecture/ssot-no-process-env": "error",
+    "biological-architecture/step-opens-its-own-cell": [
+      "error",
+      {
+        "engine": "sagaflow-js",
+        "within": "(?:__fixtures__|corpus)/workflows/",
+        "wrapper": "(?:__fixtures__|corpus)/workflows/step\\.ts$"
+      }
+    ],
+    "biological-architecture/store-route-scopes-tenant-data": "error",
+    "biological-architecture/tables-declare-their-plane": "error",
+    "biological-architecture/tenant-tables-carry-org-id": "error",
+    "biological-architecture/time-through-the-door": "error",
+    "biological-architecture/tissue-must-compose": "error",
+    "biological-architecture/tissue-no-data-props": "error",
+    "biological-architecture/tissue-no-hooks": "error",
+    "biological-architecture/tissue-no-organelles": "error",
+    "biological-architecture/tissue-no-stores": "error",
+    "biological-architecture/worker-handles-are-scoped": "error",
+    "biological-architecture/zustand-v5-best-practices": "error"
+  }
+}

package/corpus/api/store/catalog/route.ts

@@ -0,0 +1,6 @@
+// ACCEPTED: global catalog data is the same for every caller — must NOT be flagged.
+export async function GET(req: unknown, res: { json: (b: unknown) => void }): Promise<void> {
+  const query = { graph: async (_c: unknown) => ({ data: [] as unknown[] }) }
+  const { data } = await query.graph({ entity: 'product_variant', fields: ['id'] })
+  res.json({ variants: data })
+}

package/corpus/api/store/orders/route.ts

@@ -0,0 +1,6 @@
+// BREACH: reads a customer-owned entity with no caller scoping at all.
+export async function GET(req: unknown, res: { json: (b: unknown) => void }): Promise<void> {
+  const query = { graph: async (_c: unknown) => ({ data: [] as unknown[] }) }
+  const { data } = await query.graph({ entity: 'order', fields: ['id'] })
+  res.json({ orders: data })
+}

package/corpus/api/store/orders/scoped.route.ts

@@ -0,0 +1,13 @@
+// ACCEPTED: the same read, narrowed to the authenticated caller.
+export async function GET(
+  req: { auth_context?: { actor_id?: string } },
+  res: { json: (b: unknown) => void },
+): Promise<void> {
+  const query = { graph: async (_c: unknown) => ({ data: [] as unknown[] }) }
+  const { data } = await query.graph({
+    entity: 'order',
+    fields: ['id'],
+    filters: { customer_id: req.auth_context?.actor_id },
+  })
+  res.json({ orders: data })
+}

package/corpus/app/bad-route/page.tsx

@@ -0,0 +1,3 @@
+export default function Page() {
+  return <div>inline markup instead of a tissue</div>
+}

package/corpus/apps/api/src/bad-unscoped-worker.ts

@@ -0,0 +1,3 @@
+export default {
+  fetch: async (): Promise<Response> => new Response('ok'),
+}

package/corpus/atoms/bad-import.tsx

@@ -0,0 +1,5 @@
+// Breaches atom-no-deps: atoms are the lowest tier — they must not import from a
+// higher level (molecules/compounds/cells/...). Atoms are dependency-free leaves.
+import { Field } from '../molecules/field'
+
+export const BadAtom = Field

package/corpus/atoms/good-atom.tsx

@@ -0,0 +1,4 @@
+// A clean atom: the lowest tier, no higher-level imports.
+export function GoodAtom() {
+  return <button type="button">x</button>
+}

package/corpus/brand/bad-brand.tsx

@@ -0,0 +1,2 @@
+// A bare brand name in kit source — no-brand-names must FIRE.
+export const FOOTER_NOTE = 'Powered by Acme'

package/corpus/brand/good-media-url.tsx

@@ -0,0 +1,2 @@
+// Only an allowed media.acme.com demo URL — no-brand-names must NOT fire.
+export const HERO = 'https://media.acme.com/2023/06/hero.jpg'

package/corpus/cells/bad-cross-cell.tsx

@@ -0,0 +1,4 @@
+import { OtherCell } from './other-cell'
+export function BadCrossCell() {
+  return <OtherCell />
+}

package/corpus/cells/bad-logic.ts

@@ -0,0 +1,3 @@
+// A pure-logic .ts file inside a bio folder (cells/) — no-ts-in-bio-folders must
+// FIRE. Pure logic belongs in lib/.
+export const computeThing = (n: number) => n * 2

package/corpus/cells/bad-stateless-display.tsx

@@ -0,0 +1,6 @@
+// A stateless props-in/JSX-out display with no hook, no organelle, no store, and
+// no state-bearing sibling. It is "inert chemistry" filed in the cell tier —
+// cell-must-be-stateful must fire and push it down to compounds/.
+export function BadStatelessDisplay({ label }: { label: string }) {
+  return <div className="badge">{label}</div>
+}

package/corpus/cells/bad-tissue-import.tsx

@@ -0,0 +1,5 @@
+// Breaches cell-no-tissues: a cell must not import a higher-level tissue.
+// Direction is wrong — tissues compose cells, not the reverse.
+import { SiteHeader } from '../tissues/site-header'
+
+export const BadTissueImport = SiteHeader

package/corpus/cells/bad-triplicate.tsx

@@ -0,0 +1,9 @@
+export function BadTriplicate() {
+  return (
+    <div>
+      <p className="mb-[4px] text-[12px] leading-[16px] font-bold">a</p>
+      <p className="mb-[4px] text-[12px] leading-[16px] font-bold">b</p>
+      <p className="mb-[4px] text-[12px] leading-[16px] font-bold">c</p>
+    </div>
+  )
+}

package/corpus/cells/bad-two-exports.tsx

@@ -0,0 +1,6 @@
+export function FirstWidget() {
+  return <div data-testid="1"><span>a</span><span>b</span></div>
+}
+export function SecondWidget() {
+  return <section data-testid="2"><p>x</p><p>y</p></section>
+}

package/corpus/cells/bad-type-def.tsx

@@ -0,0 +1,8 @@
+// Breaches no-type-definitions-in-components: a component .tsx must not declare a
+// type/interface — inline the props in the signature, or move shared types to
+// features/*/lib/types.ts.
+type Label = string
+
+export function BadTypeDef({ label }: { label: Label }) {
+  return <button type="button">{label}</button>
+}

package/corpus/cells/dynamic.tsx

@@ -0,0 +1 @@
+export const LazyBadge = () => <span data-testid="lazy">lazy</span>

package/corpus/cells/good-iterated.tsx

@@ -0,0 +1,9 @@
+export function GoodIterated({ items }: { items: string[] }) {
+  return (
+    <ul>
+      {items.map((i) => (
+        <li key={i} className="font-primary text-[12px] leading-[16px] font-bold">{i}</li>
+      ))}
+    </ul>
+  )
+}

package/corpus/cells/good-one-export.tsx

@@ -0,0 +1,10 @@
+const COLOR_MAP = { a: 'x', b: 'y' }
+function privateHelper(n: number) {
+  return n * 2
+}
+export function GoodOneExport() {
+  return <div data-testid="g">{privateHelper(COLOR_MAP.a.length)}</div>
+}
+export function GoodOneExportRed() {
+  return <GoodOneExport />
+}

package/corpus/cells/good-own-sibling.sections.tsx

@@ -0,0 +1,3 @@
+export function GoodOwnSiblingSection() {
+  return <div data-testid="section">section</div>
+}

package/corpus/cells/good-own-sibling.tsx

@@ -0,0 +1,4 @@
+import { GoodOwnSiblingSection } from './good-own-sibling.sections'
+export function GoodOwnSibling() {
+  return <GoodOwnSiblingSection />
+}

package/corpus/cells/good-shape.types.ts

@@ -0,0 +1,3 @@
+// Co-located <component>.types.ts — the kit's allowed convention.
+// no-ts-in-bio-folders must NOT fire.
+export type GoodShape = { id: string }

package/corpus/cells/good-stateful.tsx

@@ -0,0 +1,12 @@
+import { useState } from 'react'
+
+// A genuine cell: it OWNS state (a useState hook). cell-must-be-stateful must
+// stay silent here — this is the living unit the cell tier is for.
+export function GoodStateful() {
+  const [open, setOpen] = useState(false)
+  return (
+    <button onClick={() => setOpen(!open)} type="button">
+      {open ? 'on' : 'off'}
+    </button>
+  )
+}

package/corpus/cells/index.ts

@@ -0,0 +1,2 @@
+export { GoodStateful } from './good-stateful'
+export { OtherCell } from './other-cell'

package/corpus/cells/other-cell.tsx

@@ -0,0 +1,3 @@
+export function OtherCell() {
+  return <div data-testid="other">other</div>
+}

package/corpus/comments/bad-comment-density.ts

@@ -0,0 +1,5 @@
+// this file is mostly commentary
+// which is the thing the rule measures
+// four lines of it, in a row
+// so the block ceiling is passed too
+export const one = 1

package/corpus/compounds/bad-card-div.tsx

@@ -0,0 +1,3 @@
+export function BadCardDiv() {
+  return <div className="border bg-white">card</div>
+}

package/corpus/compounds/bad-inline-data.tsx

@@ -0,0 +1,5 @@
+import { Picker } from './good-compound'
+
+export function BadInlineData() {
+  return <Picker options={[{ id: 'a' }, { id: 'b' }, { id: 'c' }]} />
+}

package/corpus/compounds/bad-stateful.tsx

@@ -0,0 +1,8 @@
+// Breaches compound-must-be-stateless: a compound is pure props-in / JSX-out —
+// no hooks. If you need state, this is a cell or an organelle.
+import { useState } from 'react'
+
+export function BadStateful() {
+  const [open] = useState(false)
+  return open ? 'a' : 'b'
+}

package/corpus/compounds/bad-store-import.tsx

@@ -0,0 +1,5 @@
+// Breaches compound-no-stores: a compound (level 3) may import only atoms /
+// molecules / other compounds — never a store (or any higher-level tier).
+import { useCartStore } from '../stores/cart'
+
+export const BadStoreImport = useCartStore

package/corpus/compounds/good-compound.tsx

@@ -0,0 +1,6 @@
+import { Button } from '../atoms/button'
+
+// A clean compound: composes a lower-level atom, no store / higher-level import.
+export function GoodCompound() {
+  return <Button />
+}

package/corpus/config/bad-process-env.ts

@@ -0,0 +1 @@
+export const apiUrl = process.env.API_URL ?? ''

package/corpus/data/bad-d1-transaction.ts

@@ -0,0 +1,5 @@
+export const move = async (db: { transaction: (fn: () => Promise<void>) => Promise<void> }) => {
+  await db.transaction(async () => {
+    return undefined
+  })
+}

package/corpus/data/bad-dialect-leak.ts

@@ -0,0 +1,3 @@
+import { pgTable } from 'drizzle-orm/pg-core'
+
+export const table = pgTable

package/corpus/data/bad-orm-outside-db.ts

@@ -0,0 +1,3 @@
+import { eq } from 'drizzle-orm'
+
+export const where = eq

package/corpus/data/bad-raw-sql.ts

@@ -0,0 +1,3 @@
+import { sql } from './fake-sql'
+
+export const all = sql`select id from documents`

package/corpus/features/invoice/cells/bad-cross-feature-store.tsx

@@ -0,0 +1,6 @@
+import { useBillingStore } from '@/features/billing/stores/billing-store'
+
+export function BadCrossFeatureStore() {
+  const total = useBillingStore((state) => state.total)
+  return <span>{total}</span>
+}

package/corpus/features/invoice/widgets/bad-folder.ts

@@ -0,0 +1 @@
+export const widget = 'widgets/ is not a tier'

package/corpus/inline/uses-engine-step.ts

@@ -0,0 +1,5 @@
+import { step } from 'sagaflow-js'
+
+// ACCEPTED: outside the configured `within`. An inline run shares the request's connection and
+// never hibernates, so nothing here needs a per-step handle.
+export const price = step('price', async () => ({ ok: true }))

package/corpus/manifest.json

@@ -0,0 +1,59 @@
+{
+  "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/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/corpus/molecules/bad-cell-import.tsx

@@ -0,0 +1,7 @@
+// Breaches molecule-atoms-only: a molecule is an inert combination of ATOMS —
+// importing a higher-level cell makes it stateful (that's a cell, not a molecule).
+import { ProductCell } from '../cells/product'
+
+export function BadCellImport() {
+  return <ProductCell />
+}

package/corpus/molecules/bad-passthrough.tsx

@@ -0,0 +1,8 @@
+import { Button } from '../atoms/button'
+
+// Breaches molecule-must-compose: imports an atom but NEVER renders it (fake
+// composition / lint-theater) — renders only a raw <div>. A molecule is by
+// definition a combination; it must actually render an atom/molecule.
+export function BadPassthrough() {
+  return <div>nothing composed</div>
+}

package/corpus/molecules/bad-renamed-props.tsx

@@ -0,0 +1,9 @@
+import { Button } from '../atoms/good-atom'
+
+interface BadRenamedProps {
+  ariaLabel: string
+}
+
+export function BadRenamed({ ariaLabel }: BadRenamedProps) {
+  return <Button aria-label={ariaLabel} />
+}

package/corpus/molecules/good-molecule.tsx

@@ -0,0 +1,6 @@
+import { Button } from '../atoms/button'
+
+// A clean molecule: composes only lower-level atoms.
+export function GoodMolecule() {
+  return <Button />
+}

package/corpus/organelles/bad-imports-cell.tsx

@@ -0,0 +1,7 @@
+// An organelle importing a CELL — direction is inverted (cells contain
+// organelles, not the reverse). organelle-dependency must FIRE on the flat path.
+import { SomeCell } from '../cells/some-cell'
+
+export function BadOrganelle() {
+  return <SomeCell />
+}

package/corpus/organelles/bad-two-sources.tsx

@@ -0,0 +1,9 @@
+import { useForm } from 'react-hook-form'
+
+import { useInvoiceStore } from '../stores/invoice-store'
+
+export function BadTwoSources() {
+  const total = useInvoiceStore((state) => state.total)
+  const { register } = useForm()
+  return <input {...register('total')} defaultValue={total} />
+}

package/corpus/organelles/good-imports-atom.tsx

@@ -0,0 +1,6 @@
+// An organelle importing an ATOM — allowed. organelle-dependency must NOT fire.
+import { Button } from '../atoms/button'
+
+export function GoodOrganelle() {
+  return <Button />
+}