@geonosis/oxlint-plugin-biological-architecture 1.3.0 → 2.0.0

package/README.md

@@ -62,7 +62,7 @@ everything below the organelle is inert. A cell never composes another cell.
 | `tenant-scoping` | 4 | every row placed, scoped and narrowed to one organisation |
 | `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 |
+| `backend-workflows-cf` | 1 | durable runs on Cloudflare Workflows — false of an inline run |
 | `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`) |
 

package/corpus/.oxlintrc.json

@@ -9,6 +9,18 @@
   },
   "rules": {
     "biological-architecture/atom-no-deps": "error",
+    "biological-architecture/boundary-time-is-primitive": [
+      "error",
+      {
+        "doors": [
+          "(?:__fixtures__|corpus)/time/door\\.ts$"
+        ],
+        "types": [
+          "Date",
+          "Dayjs"
+        ]
+      }
+    ],
     "biological-architecture/cell-must-be-stateful": "error",
     "biological-architecture/cell-must-not-compose-cell": "error",
     "biological-architecture/cell-no-cross-feature-organelles": [
@@ -30,7 +42,8 @@
       {
         "perKindPrefixes": [
           "invoice"
-        ]
+        ],
+        "within": "(?:__fixtures__|corpus)/domains/[^/]+/workflows/"
       }
     ],
     "biological-architecture/documents-share-one-table": [
@@ -42,6 +55,15 @@
         ]
       }
     ],
+    "biological-architecture/durable-body-reads-through-steps": [
+      "error",
+      {
+        "ports": [
+          "store",
+          "billing"
+        ]
+      }
+    ],
     "biological-architecture/effect-hook-naming": "error",
     "biological-architecture/emit-declares-attempts": [
       "error",
@@ -214,17 +236,72 @@
       }
     ],
     "biological-architecture/store-route-scopes-tenant-data": "error",
+    "biological-architecture/subpath-over-barrel": [
+      "error",
+      {
+        "packages": [
+          {
+            "name": "@corpus/domains",
+            "subpaths": {
+              "document": [
+                "Document",
+                "DocumentKind",
+                "documentOf"
+              ],
+              "events": [
+                "DomainEvent",
+                "emit"
+              ]
+            }
+          }
+        ]
+      }
+    ],
     "biological-architecture/subscriber-declares-id": "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/time-through-the-door": [
+      "error",
+      {
+        "door": "(?:__fixtures__|corpus)/time/door\\.ts$",
+        "exempt": [
+          "(?:__fixtures__|corpus)/time/generated/"
+        ]
+      }
+    ],
     "biological-architecture/tissue-must-compose": "error",
+    "biological-architecture/todo-names-its-plan": [
+      "error",
+      {
+        "markers": [
+          "TODO",
+          "FIXME"
+        ]
+      }
+    ],
     "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/unique-query-step-name": "error",
-    "biological-architecture/worker-handles-are-scoped": "error",
+    "biological-architecture/unique-query-step-name": [
+      "error",
+      {
+        "queryStepCalls": [
+          "useQueryGraphStep",
+          "useRemoteQueryStep"
+        ]
+      }
+    ],
+    "biological-architecture/worker-handles-are-scoped": [
+      "error",
+      {
+        "within": "(?:__fixtures__|corpus)/workers/",
+        "wrapper": [
+          "withCells",
+          "withConnection"
+        ]
+      }
+    ],
     "biological-architecture/zustand-v5-best-practices": "error",
     "biological-architecture/font-roles-only": [
       "error",
@@ -250,5 +327,20 @@
         ]
       }
     ]
-  }
+  },
+  "overrides": [
+    {
+      "files": [
+        "**/engine/**"
+      ],
+      "rules": {
+        "biological-architecture/mutating-step-declares-retry": [
+          "error",
+          {
+            "retryKey": "retry"
+          }
+        ]
+      }
+    }
+  ]
 }

package/corpus/domains/document/workflows/bad-per-kind-workflow.ts

@@ -0,0 +1,5 @@
+import { createWorkflow } from '@corpus/workflows'
+
+// BREACH: the same hand-written fork under the other engine's factory. A plain string names ONE
+// entity, which is what the generic base entity replaced.
+export const createInvoice = createWorkflow('invoice.create', async (input) => input)

package/corpus/domains/document/workflows/good-minted-workflow.ts

@@ -0,0 +1,8 @@
+import { createWorkflow } from '@corpus/workflows'
+
+// ACCEPTED: the generic factory. Every entity's create flow comes from one body, and the name is
+// assembled from the entity — a template literal the rule cannot read, which is the point rather
+// than a gap: what is minted is exactly what this rule is asking for.
+export const documentWorkflows = (entity: string) => ({
+  create: createWorkflow(`${entity}.create`, async (input) => input),
+})

package/corpus/engine/bad-durable-free-read.ts

@@ -0,0 +1,20 @@
+import { createStep, createWorkflow } from '@corpus/workflows'
+
+const charge = createStep('charge', async (id: string, { billing }) => billing.charge(id))
+
+const save = createStep('save', async (doc: { id: string }, { store }) => store.updateDocument(doc))
+
+// BREACH: the free read gates a branch. The run crashes after `save` and before it closes; the
+// replay answers `charge` from its record, re-reads, sees the status the FIRST invocation wrote,
+// throws, and unwinds — refunding a charge for an invoice that is still sent. Traced in
+// docs/design-026-document-workflows.md §8 and held as a test in the engine.
+export const send = createWorkflow(
+  'invoice.send',
+  async (id: string, { store }) => {
+    await charge(id)
+    if (store.read(id).status !== 'draft') throw new Error('already sent')
+
+    return await save({ id })
+  },
+  { execution: 'durable' },
+)

package/corpus/engine/bad-no-retry.ts

@@ -0,0 +1,8 @@
+import { createStep } from '@corpus/workflows'
+
+// BREACH: a step that writes and names no budget at all. The engine's default is one attempt, so
+// the first dropped connection reverts the write — the same silence Medusa's `maxRetries: 0` keeps,
+// spelled under this engine's own key.
+export const save = createStep({ name: 'save' }, async (input, { store }) =>
+  store.createDocument(input),
+)

package/corpus/engine/good-durable-other-spelling.ts

@@ -0,0 +1,10 @@
+import { createWorkflow } from '@corpus/workflows'
+
+// ACCEPTED under the DEFAULTS, and the reason the defaults moved (#210): `durable: true` is not a
+// declaration the engine has — `WorkflowOptions` takes `execution`, and a repo whose own factory
+// says it another way names `durableKey`/`durableValue` and gets that instead.
+export const price = createWorkflow(
+  'invoice.price',
+  async (id: string, { store }) => store.read(id),
+  { durable: true },
+)

package/corpus/engine/good-durable-read-is-a-step.ts

@@ -0,0 +1,18 @@
+import { createStep, createWorkflow } from '@corpus/workflows'
+
+const ensureDraft = createStep('ensure-draft', async (id: string, { store }) => store.read(id))
+
+const save = createStep('save', async (doc: { id: string }, { store }) => store.updateDocument(doc))
+
+// ACCEPTED: the decision is a step, so the replay is handed the answer the first invocation got,
+// takes the same branch and closes the same way both times.
+export const send = createWorkflow(
+  'invoice.send',
+  async (id: string) => {
+    const doc = await ensureDraft(id)
+    if (doc.status !== 'draft') throw new Error('already sent')
+
+    return await save({ id })
+  },
+  { durable: true },
+)

package/corpus/engine/good-durable-read-through-helper.ts

@@ -0,0 +1,20 @@
+import { createStep, createWorkflow } from '@corpus/workflows'
+
+const save = createStep('save', async (doc: { id: string }, { store }) => store.updateDocument(doc))
+
+// The port, one function out. THE RULE IS SILENT HERE and #212 says so out loud: it reads a call on
+// a name `ports` lists, and no single-file rule can follow a read through a helper. A repo that
+// reaches the outside world this way names `readStatus` in `ports` — or makes it a step, which is
+// what the run needs anyway.
+const readStatus = (id: string, store: { read: (id: string) => { status: string } }): string =>
+  store.read(id).status
+
+export const send = createWorkflow(
+  'invoice.send.helper',
+  async (id: string, { store }) => {
+    if (readStatus(id, store) !== 'draft') throw new Error('already sent')
+
+    return await save({ id })
+  },
+  { execution: 'durable' },
+)

package/corpus/engine/good-inline-free-read.ts

@@ -0,0 +1,7 @@
+import { createWorkflow } from '@corpus/workflows'
+
+// ACCEPTED: an inline run is invoked once and never replayed, so a free read is read once. The
+// law is about durability, not about ports.
+export const price = createWorkflow('invoice.price', async (id: string, { store }) =>
+  store.read(id),
+)

package/corpus/engine/good-retry-budget.ts

@@ -0,0 +1,9 @@
+import { createStep } from '@corpus/workflows'
+
+// ACCEPTED under `retryKey: 'retry'` — the budget this engine spells — and REPORTED under the
+// default `maxRetries`, which is the whole of the option.
+export const send = createStep(
+  { name: 'send', retry: { backoff: 'exponential', limit: 3 } },
+  async (input, { store }) => store.updateDocument(input),
+  async ({ id }, { store }) => store.deleteDocument(id),
+)

package/corpus/floors/domains/alpha/src/good-downhill.ts

@@ -0,0 +1,3 @@
+import { baseThing } from '@floor/foundation-base'
+
+export const alphaUsesBase = baseThing

package/corpus/floors/domains/alpha/src/index.ts

@@ -0,0 +1 @@
+export const alphaThing = 'alpha'

package/corpus/floors/domains/alpha/src/reaches-own-ui.ts

@@ -0,0 +1,3 @@
+import { AlphaPanel } from './ui/panel'
+
+export const alphaReachesOwnUi = AlphaPanel

package/corpus/floors/domains/alpha/src/reaches-sideways-type.ts

@@ -0,0 +1,3 @@
+import type { BetaShape } from '@floor/domain-beta'
+
+export const alphaReachesSidewaysByType = (shape: BetaShape): BetaShape => shape

package/corpus/floors/domains/alpha/src/reaches-sideways.ts

@@ -0,0 +1,3 @@
+import { betaThing } from '@floor/domain-beta'
+
+export const alphaReachesSideways = betaThing

package/corpus/floors/domains/alpha/src/ui/panel.ts

@@ -0,0 +1,3 @@
+import { alphaThing } from '../index'
+
+export const AlphaPanel = `panel for ${alphaThing}`

package/corpus/floors/domains/beta/src/index.ts

@@ -0,0 +1,3 @@
+export type BetaShape = { id: string }
+
+export const betaThing = 'beta'

package/corpus/floors/foundations/above/src/good-downhill.ts

@@ -0,0 +1,3 @@
+import { baseThing } from '@floor/foundation-base'
+
+export const aboveThing = `above ${baseThing}`

package/corpus/floors/foundations/base/src/good-downhill.ts

@@ -0,0 +1,3 @@
+import { methodThing } from '@floor/method'
+
+export const baseUsesMethod = methodThing

package/corpus/floors/foundations/base/src/index.ts

@@ -0,0 +1 @@
+export const baseThing = 'base'

package/corpus/floors/foundations/base/src/reaches-sideways.ts

@@ -0,0 +1,3 @@
+import { aboveThing } from '@floor/foundation-above'
+
+export const baseReachesSideways = aboveThing

package/corpus/floors/foundations/base/src/reaches-up.ts

@@ -0,0 +1,3 @@
+import { alphaThing } from '@floor/domain-alpha'
+
+export const baseReachesUp = alphaThing

package/corpus/floors/packages/method/src/own.ts

@@ -0,0 +1 @@
+export const methodThing = 'method'

package/corpus/floors/packages/method/src/reaches-up.ts

@@ -0,0 +1,3 @@
+import { baseThing } from '@floor/foundation-base'
+
+export const methodReachesUp = baseThing

package/corpus/floors.oxlintrc.json

@@ -0,0 +1,86 @@
+{
+  "$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/layer-walls": [
+      "error",
+      {
+        "typeOnly": "count",
+        "layers": [
+          {
+            "name": "domain-alpha-ui",
+            "paths": [
+              "(?:^|/)floors/domains/alpha/src/ui/",
+              "^@floor/domain-alpha/ui(/|$)"
+            ],
+            "mayImport": [
+              "domain-alpha",
+              "foundation-above",
+              "foundation-base",
+              "method"
+            ]
+          },
+          {
+            "name": "domain-alpha",
+            "paths": [
+              "(?:^|/)floors/domains/alpha/src/",
+              "^@floor/domain-alpha(/|$)"
+            ],
+            "mayImport": [
+              "foundation-above",
+              "foundation-base",
+              "method"
+            ]
+          },
+          {
+            "name": "domain-beta",
+            "paths": [
+              "(?:^|/)floors/domains/beta/src/",
+              "^@floor/domain-beta(/|$)"
+            ],
+            "mayImport": [
+              "foundation-above",
+              "foundation-base",
+              "method"
+            ]
+          },
+          {
+            "name": "foundation-above",
+            "paths": [
+              "(?:^|/)floors/foundations/above/src/",
+              "^@floor/foundation-above(/|$)"
+            ],
+            "mayImport": [
+              "foundation-base",
+              "method"
+            ]
+          },
+          {
+            "name": "foundation-base",
+            "paths": [
+              "(?:^|/)floors/foundations/base/src/",
+              "^@floor/foundation-base(/|$)"
+            ],
+            "mayImport": [
+              "method"
+            ]
+          },
+          {
+            "name": "method",
+            "paths": [
+              "(?:^|/)floors/packages/[^/]+/src/",
+              "^@floor/method(/|$)"
+            ],
+            "mayImport": []
+          }
+        ]
+      }
+    ]
+  }
+}

package/corpus/manifest.json

@@ -2,6 +2,7 @@
   "plugin": "biological-architecture",
   "rules": [
     "biological-architecture/atom-no-deps",
+    "biological-architecture/boundary-time-is-primitive",
     "biological-architecture/cell-must-be-stateful",
     "biological-architecture/cell-must-not-compose-cell",
     "biological-architecture/cell-no-cross-feature-organelles",
@@ -13,6 +14,7 @@
     "biological-architecture/dialect-through-the-seam",
     "biological-architecture/document-sagas-are-generic",
     "biological-architecture/documents-share-one-table",
+    "biological-architecture/durable-body-reads-through-steps",
     "biological-architecture/effect-hook-naming",
     "biological-architecture/emit-declares-attempts",
     "biological-architecture/font-roles-only",
@@ -60,6 +62,7 @@
     "biological-architecture/step-declares-compensation-or-none",
     "biological-architecture/step-opens-its-own-cell",
     "biological-architecture/store-route-scopes-tenant-data",
+    "biological-architecture/subpath-over-barrel",
     "biological-architecture/subscriber-declares-id",
     "biological-architecture/tables-declare-their-plane",
     "biological-architecture/tenant-tables-carry-org-id",
@@ -69,6 +72,7 @@
     "biological-architecture/tissue-no-hooks",
     "biological-architecture/tissue-no-organelles",
     "biological-architecture/tissue-no-stores",
+    "biological-architecture/todo-names-its-plan",
     "biological-architecture/tokens-only-colors",
     "biological-architecture/unique-query-step-name",
     "biological-architecture/worker-handles-are-scoped",

package/corpus/subpaths/bad-root-barrel.ts

@@ -0,0 +1,5 @@
+import { Document, documentOf } from '@corpus/domains'
+
+// BREACH: every name here lives under one subpath, so this file names the root entry and takes the
+// union of every subpath's module graph to reach one of them.
+export const first = (kind: Document) => documentOf(kind)

package/corpus/subpaths/good-spans-two-subpaths.ts

@@ -0,0 +1,5 @@
+import { Document, emit } from '@corpus/domains'
+
+// ACCEPTED: two subpaths in one import is what the root entry is for. Splitting it is a judgement
+// about how many imports a file should carry, and this rule does not have one.
+export const announce = (doc: Document) => emit(doc)

package/corpus/subpaths/good-subpath.ts

@@ -0,0 +1,4 @@
+import { Document, documentOf } from '@corpus/domains/document'
+
+// ACCEPTED: the subpath the names live under, which is the remedy the diagnostic asks for.
+export const first = (kind: Document) => documentOf(kind)

package/corpus/subpaths/good-type-only.ts

@@ -0,0 +1,4 @@
+import type { Document, DocumentKind } from '@corpus/domains'
+
+// ACCEPTED: a type-only import erases, so the module graph the rule is about never arrives.
+export type Row = { doc: Document; kind: DocumentKind }

package/corpus/time/bad-boundary-type.ts

@@ -0,0 +1,3 @@
+export type InvoiceRow = { id: string; issuedAt: Date }
+
+export const issuedAt = (row: InvoiceRow): Date => row.issuedAt

package/corpus/time/bad-second-door.ts

@@ -0,0 +1,6 @@
+import dayjs from 'dayjs'
+import quarterOfYear from 'dayjs/plugin/quarterOfYear'
+
+dayjs.extend(quarterOfYear)
+
+export const quarterOf = (epochMs: number): number => dayjs(epochMs).quarter()

package/corpus/time/door.ts

@@ -0,0 +1,15 @@
+import dayjs from 'dayjs'
+import utc from 'dayjs/plugin/utc'
+
+dayjs.extend(utc)
+
+const isoDateFormat = 'YYYY-MM-DD'
+
+export const today = (nowMs: number = Date.now()): string => dayjs.utc(nowMs).format(isoDateFormat)
+
+export const addDays = (date: string, days: number): string =>
+  dayjs.utc(date, isoDateFormat, true).add(days, 'day').format(isoDateFormat)
+
+export const epochOf = (timestamp: string): number => Date.parse(timestamp)
+
+export const toDate = (epochMs: number): Date => new Date(epochMs)

package/corpus/time/generated/from-openapi.ts

@@ -0,0 +1 @@
+export const generatedAt = new Date('2026-01-01T00:00:00.000Z').toISOString()

package/corpus/time/good-boundary-primitive.ts

@@ -0,0 +1,3 @@
+export type ReceiptRow = { id: string; issuedAtEpochMs: number; issuedOn: string }
+
+export const issuedAt = (row: ReceiptRow): number => row.issuedAtEpochMs

package/corpus/todos/bad-unplanned.ts

@@ -0,0 +1,2 @@
+// TODO: come back and give this a real cache
+export const cacheKey = (id: string): string => `quote:${id}`

package/corpus/todos/good-planned.ts

@@ -0,0 +1,2 @@
+// TODO(025): the cache lands with the batteries floor
+export const cacheKey = (id: string): string => `quote:${id}`

package/corpus/todos/good-string-not-a-comment.ts

@@ -0,0 +1,2 @@
+export const label = 'TODO: this is copy, not a promise'
+export const helpUrl = 'https://example.test//TODO'

package/corpus/workers/good-with-cells.ts

@@ -0,0 +1,7 @@
+import { withCells } from '@corpus/cells'
+
+// ACCEPTED: the invocation runs inside the wrapper the options name, so the handle it opens is
+// closed when the invocation ends.
+export default {
+  queue: async (): Promise<void> => withCells(async () => undefined),
+}

package/corpus/workers/good-with-connection.ts

@@ -0,0 +1,7 @@
+import { withConnection } from '@corpus/db'
+
+// ACCEPTED: a second wrapper name, from the option. The rule shipped knowing only `withCells`, so a
+// repo whose scope opener is called anything else read as unscoped for ever.
+export default {
+  scheduled: async (): Promise<void> => withConnection(async () => undefined),
+}

package/corpus/workflows/bad-unscoped-host.ts

@@ -0,0 +1,7 @@
+import { createRuntime } from '@geonosis/workflows'
+
+import { journal } from './journal'
+
+// BREACH: a durable host built with no `scope.perStep`. The instance hibernates between steps, so
+// the handle this run opened once is closed by the time the second step reaches for it.
+export const runtime = createRuntime({ journal, tenantId: 'acme' })

package/corpus/workflows/good-host-config-elsewhere.ts

@@ -0,0 +1,6 @@
+import { createRuntime } from '@geonosis/workflows'
+
+import { config } from './config'
+
+// ACCEPTED: the config cannot be read whole, and unreadable is not the same as absent.
+export const runtime = createRuntime(config)

package/corpus/workflows/good-scoped-entrypoint.ts

@@ -0,0 +1,17 @@
+import { entrypointFor } from '@geonosis/workflows'
+
+import { journal } from './journal'
+import { withConnection } from './with-connection'
+
+// ACCEPTED: the adapter's entry declares the scope one closure down, in the runtime it builds per
+// run — which is where it has to be, because the handle belongs to the invocation that opened it.
+export const Durable = entrypointFor({
+  base: WorkflowEntrypoint,
+  runtime: (env, params) =>
+    createRuntime({
+      journal: journal(env),
+      scope: { perStep: () => withConnection(env) },
+      tenantId: params.tenantId,
+    }),
+  workflows: [issue],
+})

package/corpus/workflows/good-scoped-host.ts

@@ -0,0 +1,11 @@
+import { createRuntime } from '@geonosis/workflows'
+
+import { journal } from './journal'
+import { withConnection } from './with-connection'
+
+// ACCEPTED: every step body and every undo is wrapped in a scope of its own.
+export const runtime = createRuntime({
+  journal,
+  scope: { perStep: () => withConnection },
+  tenantId: 'acme',
+})