Skip to content

Open-source manufacturing ERP, MES and QMS. Quoting, MRP, inventory, shop floor, quality and lot/serial traceability on one Postgres schema, with a REST API and MCP server. Self-host or use Carbon Cloud.

21.8 KB
Raw Blame

@carbon/checks

Conformance checking, clobber detection, invariant queries, and module structure validation for the Carbon monorepo.

Always

  • Run checks against real migrations and module directories — collectFindings(root) scans both SQL migrations and app module structure
  • Use newViolations() for CI — filters findings against the baseline so only new violations fail the build
  • Add new conformance rules to the array that matches the rule's SOURCE — CONFORMANCE_CHECKS (SQL migrations), SERVER_CHECKS (server-only TS), TS_CHECKS (all app + shared-package TS, client and server), EDGE_FUNCTION_CHECKS (one source per edge function, all of its .ts files joined — sources/edge-functions.ts), or STRUCTURE_CHECKS (module layout). Follow the ConformanceCheck / StructureCheck interface
  • Write invariants as .sql files — each returns rows that VIOLATE the rule (empty = healthy); loaded from directory by loadInvariants(dir)

Ask First

  • Regenerating the baseline (pnpm --filter @carbon/checks baseline) — this grandfathers all current violations
  • Adding new OBJECT_PATTERNS to clobber detection (extends what qualifies as a DB object redefinition)
  • Modifying existing conformance checks (may affect CI gates)

Never

  • Ignore clobber warnings — they indicate a view or function is redefined on both your branch and main since the merge-base; rebase first
  • Suppress violations by removing checks — add to the baseline if grandfathering is appropriate

Validation Commands

pnpm --filter @carbon/checks test          # vitest — unit tests
pnpm --filter @carbon/checks clobbers      # check for migration clobber risks
pnpm --filter @carbon/checks invariants    # run SQL invariants against DB
pnpm --filter @carbon/checks baseline      # regenerate baseline (careful!)

Key Patterns

  • Conformance checks: noNumericPrecision, noLegacyRls, noDerivedPercentColumn, noRequiredColumnWithoutDefault, noViewWithoutInvoker — scan SQL migrations for anti-patterns (noDerivedPercentColumn flags a *Percent/*Rate column GENERATED ALWAYS AS an expression that divides — a percentage is an entered fact, never a lossy echo of a rounded amount; noViewWithoutInvoker fails a CREATE [OR REPLACE] VIEW that does not state security_invoker — CREATE OR REPLACE replaces a view's options, so omitting the clause turns it into an owner-rights view that bypasses RLS for every PostgREST caller, and openJobMaterialLines leaked every company's rows that way. security_invoker = false passes, so an owner-rights view is a visible decision; materialized views are not matched. It reads one file's text, so an EXECUTE format(...) view or a later ALTER VIEW … RESET escapes it — the invariant below is the backstop); noLocalTimezone (in SERVER_CHECKS) scans server TS (sources/server-files.ts) for getLocalTimeZone(), UTC day-slicing, local date-parts of now (new Date().getDay() etc.), and setHours(0,0,0,0) midnights. Scanned files: MES services, packages/jobs, edge functions, packages/database/src, ERP module .service.ts/.server.ts, plus both apps' route trees — route modules are server AND client in one file, so maskClientCode blanks the browser half (default export, clientLoader/clientAction, PascalCase/use* declarations) while keeping loaders, actions, and the module-level helpers they call. A region ends only on a line of closers alone (}, };, });, )): a }: { or }) { line closes a multi-line props signature, and ending there made the rest of a component read as server code
  • Authz ownership (CONFORMANCE_CHECKS via collectFindings): noAuthzDdlInMigrations(functions) fails a migration newer than 20260927000000 that runs CREATE/ALTER POLICY on a public table (storage bucket policies stay allowed), or defines, alters or drops a managed function — policies live in packages/database/src/authz/manifest.ts, RLS helpers in packages/database/src/authz/helpers/<name>.sql, event-system functions in packages/database/src/event-system/functions/<name>.sql (util.<name>.sql outside public; checked from 20261002114954, the migration that took them over), and authz sync applies all of them after migrations. The function list is read from those directories (loadManagedFunctions, one cutoff per directory in MANAGED_FUNCTION_SETS), so it cannot drift from the files. DROP POLICY is allowed (dropping a column a policy uses). Files starting with the authz migration header are exempt; @carbon/database's migration.test.ts verifies their contents. Older migrations are history, so there are no baseline entries
  • Forwarded headers (own source, REQUEST_HANDLING_ROOTS: every app + auth, ee, jobs, lib, utils, edge functions): noRawForwardedHeaders fails a raw read of X-Forwarded-For/-Host/-Proto or X-Real-IP outside packages/utils/src/headers.ts — use getClientIp / getRequestProtocol / getRequestHost / getRequestOrigin. Hand-rolled reads keyed login rate limits and ITAR audit records on the forgeable first X-Forwarded-For entry. No baseline entries
  • Error log messages (same source as forwarded headers, REQUEST_HANDLING_ROOTS): noInterpolatedErrorLog fails logger.error(…${value}) / .fatal — the message is exported as a span attribute and is what errors group by, so values are named ("Failed to upload {fileName}", { fileName }). One baseline entry: the packages/auth/src/utils/result.ts pass-through, whose message is its caller's
  • Numeric-precision checks (in TS_CHECKS, over sources/typescript.ts): noRawRounding flags Math.round/ceil/floor and .toFixed on value-bearing numbers (use round/scrapAllowance/applyRate/deriveRate from @carbon/utils); noInlineFractionDigits flags minimum/maximumFractionDigits at a call site (pick a named kind from @carbon/utils format.ts, and INPUT_FORMAT.* for anything editable); noUnroundedTrackedQuantity flags inline unrounded arithmetic inside a .updateTable("trackedEntity") statement's quantity: set, and a raw ===/!==/< compare against a *[Ee]ntity*.quantity read (use round/settleQuantity at the write, isFullDraw at a split gate — see .claude/rules/traceability-model.md). It is scoped to what one file can prove: a quantity: set from an already-rounded variable is unflaggable either way, and a compare of two locals is presumed rounded where they were defined. It has no baseline entries — the whole tree was fixed in the pass that added it, so any finding is new. sources/typescript.ts walks apps/erp/app/{components,hooks,modules,routes}, apps/mes/app, packages/database/supabase/functions, packages/database/src, packages/{ee,jobs}/src, packages/documents/src/{pdf,utils} and the shared packages packages/{utils,files,form,react,printing}/src — tests (*.test.ts(x), *.spec.ts(x)) and *-test-fixture.ts live-database fixtures excluded; a fixture is test support code, so it is held to the tests' rules, not shipped code's. The shared packages matter: @carbon/utils is where the standard's own helpers live, and form/react own the number inputs whose formatOptions are part of the storage round-trip. See .claude/rules/numeric-precision.md
  • Realtime (in TS_CHECKS): noPostgresChanges fails a postgres_changes subscription — the supabase_realtime publication is empty, so it would never fire. Use a broadcast topic through @carbon/query (.claude/rules/realtime-system.md).
  • Missing audit columns (built in collectFindings, not TS_CHECKS): noMissingAuditColumn(columns) fails a write that names createdBy/updatedBy on a relation that has no such column — PostgREST rejects the whole statement (PGRST204 Could not find the 'createdBy' column of '<table>') and TypeScript does not flag it, because supabase-js widens the insert/upsert argument enough for the excess property to survive. That is how the customerPartToItem upsert in sales-rfq.$rfqId.map-lines.ts shipped with an unchecked result, so every RFQ-line → customer-part mapping silently failed. Roughly a third of Carbon's tables have no audit columns (favourites, link tables, the lean material lookups, companySettings) while golden rule 3 says to include them, so it is an easy assumption to carry into the wrong table. It takes the column map as an ARGUMENT — loadDbTableColumns(root) (sources/db-columns.ts) reads the generated packages/database/src/types.ts Row: blocks, so the I/O stays in sources/ and scan stays pure, the same shape as noAuthzDdlInMigrations(loadManagedFunctions(root)). Scope is the LITERAL argument of the write (.from/insertInto/updateTable + .insert/.upsert/.update/.values/.set); a payload object spread into the row is invisible here. No baseline entries — the one hit was fixed when it was added
  • Function redefinitions (built in collectFindings, cross-file over the migrations): findDroppedFunctionChanges (function-redefinition-keeps-changes) fails a migration from 20261016000000 on whose CREATE OR REPLACE FUNCTION leaves out two or more lines the previous definition added over its own predecessor. A function is its schema, name and input argument types (OUT arguments, argument names, defaults and type modifiers left out; int/int4/integer and the other aliases read as one), so an overload and a util.* function each have their own history. A redefinition must start from the newest definition: 20261014171619_receive-consumed-serial-units forked complete_job_to_inventory from an older migration and silently undid always-post job costing and the production-event lock (restored in 20261015161847_job-receipt-takes-issued-serial-units). A deliberate removal is explained in the migration header and baselined. No baseline entries
  • Stamped identity fields (built in collectFindings, cross-file): findStampColumnMismatches (stamp-matches-columns, sources from loadModuleServerFiles) follows each payload(ctx, value)…for*() chain in a module's <m>.server.ts into the service.<fn>(…) it is passed to, and reads that function's writes in <m>.service.ts whose row is the parameter itself (insert([p]), ...p, sanitize(p), or one local initialized from it). It fails a field payload adds that the table has no column for (PGRST204: createAccount stamped companyId onto the group-scoped account), and createdBy added to a payload that only reaches .update( (it rewrites the row's author: upsertItemCost). It follows payload's own rules: a list gets only createdBy, forUpdate drops createdBy, a nested object is never added to. No baseline entries
  • Tenant-scoped Kysely writes (in TS_CHECKS): noUnscopedKyselyWrite fails any .updateTable(/.deleteFrom( under apps/erp/app/{modules,routes}, apps/mes/app or packages/jobs/src whose statement (up to .execute…(/.compile(/;/, at depth 0, comments blanked) has no .where("companyId", …) / .where("alias.companyId", …). Kysely is the superuser connection, and the public API hands a service's db param that same client, so the statement's own predicate is the only tenant boundary — ten drag-sort services (updateQuoteLineOrder and friends) were a reported cross-tenant write because they keyed on id alone. company is exempt (its id is the tenant); a companyId in .set() does not count; a link table with no companyId column passes by scoping through its parent in a subquery. packages/ee is out of scope (see the file header), and so are writes made through the @carbon/database/rows helpers (updateRows / deleteRows): the check only reads Kysely's own builders. One baseline entry: the companyGroup delete in packages/jobs/.../scheduled/purge-company.ts (a group has no companyId column; its id is the tenant-group key). Every other hit was fixed when it was added
  • Unguarded submit buttons (in TS_CHECKS, .tsx only): noUnguardedSubmit fails a <Button>/<button>/<IconButton> carrying type="submit" whose own opening tag names no in-flight signal (isLoading, isSubmitting, isPending, isSaving, useIsSubmitting, or a *fetcher|navigation|transition*.state read). A live submit button posts again on every click and each POST runs to completion server-side — fetcher.submit aborts the previous BROWSER request, but no route action reads request.signal — which is how one quote finalize emailed the customer the same PDF three times. It parses the real opening tag (brace- and quote-aware), so a guard written after type="submit" still counts and a > inside {a > b} does not end the tag early. The presence of isDisabled is deliberately not enough: the incident's button was isDisabled={loading} where loading was the modal's data-fetch flag, so a check that accepted any isDisabled would have passed the exact line it exists to catch; word boundaries matter too (loading must not satisfy isLoading). Buttons inside a <ValidatedForm> are skipped — ValidatedForm.handleSubmit drops a re-entrant submit, so a second click cannot produce a second POST however the button is written. packages/form/src/components/Submit.tsx is excluded; it IS the guard. The check cannot do dataflow, so a guard held in a differently-named local (disabled={busy}) is baselined rather than rewritten. 32 baseline entries, all reviewed: logout/company-switch/theme/console-toggle (idempotent), delete and rule-unassign (a second delete is a no-op), the two chat composers (guarded by a flushSync clear plus an empty-message return), and ConfiguratorForm (its submit is an onSubmit callback — the in-flight state lives at the caller)
  • Module files (in TS_CHECKS): serviceFnFile (service-fn-file) fails anything in an ERP <module>.server.ts (or .ee.server.ts) other than imports, types, plain constants and exported defineServiceFn consts — a helper function, a class or an exported value is a building block and goes in <module>.service.ts. noServerCodeInClient (no-server-code-in-client) fails a value import of a .service, .server or .pdf file from browser code: components/, hooks/, stores/, a module's ui/, *.models.ts, *.utils.ts and types.ts. Those files are server-only; a function the UI calls lives in <module>.utils.ts. Type-only imports pass. It also scans ERP routes: a route may import a service file for its loader and action, but fails when a name it imports from one is used in its browser half (what maskClientCode blanks, comments removed; a local of the same name is skipped). LOCK_PERIOD_TASK_NAME used in a close-period component put the accounting service, and its @carbon/auth/auth.server import, into the client build, which then failed. No baseline entries for either. See .claude/rules/module-files.md.
  • Side-effect imports (built in collectFindings, cross-file, sources/side-effect-packages.ts): findUndeclaredSideEffectImports (side-effect-import-declared) fails a bare import (import "./x", import "~/x") of a file in its own package when that package's package.json sets "sideEffects": false or does not list the file. The production bundler drops such an import: the ERP's import "./modules/carbon.server" was dropped, so every carbon() call threw in production, and zod.client (z.config({ jitless: true })) never ran in any app. The dev server does not tree-shake, so nothing else shows it. A bare import of another package is left to that package's own sideEffects; .css is ignored. No baseline entries
  • Route writes (in SERVER_CHECKS, ERP routes masked by maskClientCode): routeActionShape (route-action-shape) fails a write made in an ERP route — a .from("…") insert/upsert/update/delete, a Kysely insertInto/updateTable/deleteFrom, or an invokePosting(/invokePostingOrThrow(/invokeCreate( call (a posting body run outside its service function). The write belongs in a defineServiceFn the route calls, so the API and MCP run the same logic (.ai/plans/2026-10-15-service-function-migration.md). It matches those literal patterns only: .rpc( is not matched (it reads as often as it writes), and a route that calls a write building block from a .service.ts (or two write functions) is not detected. 11 baseline entries, all auth routes (_oauth+/authorize, register, token, _public+/unlock, api+/account.security, api+/passkey.*.verify)
  • Edge-function auth (EDGE_FUNCTION_CHECKS): edgeFunctionAuthorizesCaller fails any function under packages/database/supabase/functions/ that never calls requireCaller / requireServiceRole — the gates each self-contained function defines for itself; a declaration alone does not count — because verify_jwt accepts the published anon key
  • License headers (own source, sources/license-files.ts: git-tracked .ts/.tsx/.js/.jsx/.mjs/.cjs/.rs under apps, packages, crates, docs, ci, scripts and the repo root): spdxLicenseHeader fails a file whose first lines are not its SPDX header — AGPL-3.0-only, or LicenseRef-Carbon-Commercial under packages/ee/ and for any .ee. file name. The header text, the classification, the exclusions (each with its reason: generated files a generator would clobber — generate:types, generate:swagger, the workflow catalog, sst-env.d.ts, the notification preview fixtures — and third-party copies) and the insertion rules live in ONE module, src/license-headers.ts, shared with the fixer pnpm --filter @carbon/checks license-headers (--check, --dry-run, --verbose, optional paths; root alias pnpm license:headers), so the check fails exactly the files the fixer would change. The header goes after a shebang and above everything else ("use client", // @ts-nocheck, /// <reference>, biome-ignore-all, deno-lint-ignore-file, Rust //!/#![…] all stay valid after a comment), then one blank line; the other license's header is swapped, CRLF is kept. A file with a third-party notice (foreign SPDX id, @license, copyright) is flagged and never rewritten — add it to PATH_EXCLUSIONS. When the header wording changes, move the old lines to RETIRED_HEADER_LINES. No baseline entries
  • Document sequences (built in collectFindings, cross-file): findUnsyncedDocumentSequences (document-sequence-synced, sources loaded by sources/document-sequences.ts) fails a counter in packages/database/src/seed-data.ts sequences whose table is not both attached to sync_advance_document_sequence in attachments.ts and named in that interceptor's CASE, unless EXEMPT_COUNTERS lists it with the reason no caller ever supplies its number. It also fails a table that is attached but missing from the CASE, or the reverse. Without the interceptor, a number typed by hand or sent through MCP/the API leaves the counter behind and later inserts fail on the unique constraint. COUNTER_TABLES maps counters named differently from their table (journalEntry → journal, creditMemo/debitMemo → memo). No baseline entries
  • Structure checks: moduleShape (module-shape) — each ERP module has types.ts, ui/, one <name>.service.ts and one <name>.models.ts (or their .ee. variants), at most one <name>.server.ts (or .ee.server.ts) and no other .server file, and no barrel (index.ts / index.server.ts). Three baseline entries (an extra backups.service.ts in settings; imports.models.ts and no ui/ in shared)
  • Clobber detection: findClobbers(branch, main) — identifies DB objects redefined on both sides
  • Baseline: src/baseline.ts — grandfathered violations keyed by checkId + file + snippet (no line number, so edits above a baselined hit don't un-baseline it)
  • Invariants: SQL queries loaded from directory, injected Query for testability
  • view-without-security-invoker.sql: every public view runs as its caller (security_invoker true in pg_class.reloptions), whatever put it there — the live-catalog backstop for noViewWithoutInvoker. modules and eventSystemTrigger are excluded by name (no tenant data). Like every invariant it needs a live connection and does not run in CI
  • tracked-entity-zero-available.sql: a lot whose quantity is gone must be Consumed, never a live status. Scrapped/Rejected are excluded — both are quality markers kept as historical record and already excluded from on-hand. Enforcement of the drain rule is per-writer, so this is the net that catches husks from ANY source: rows predating the rule, and any writer that revives a drained lot (unconsume, shipment void, disposition Use As Is / Rework). Run it before deciding whether to promote the rule to a DB CHECK
  • Workflows: two DB-backed drift checks, answering different questions. src/invariants/workflow-trigger-event-drift.sql (via pnpm --filter @carbon/checks invariants) compares each active workflow's workflowTriggerEvent rows against its active version's trigger nodes — a dispatch row that is missing, orphaned, or pinned to a superseded version. src/scripts/check-workflow-events.ts (pnpm --filter @carbon/checks workflow-events) asks whether an event id a live workflow subscribes to still exists in the generated catalog — the shape a catalog rename leaves behind. Neither replaces the other. Neither runs in CI, and neither can as CI stands: both open a live Postgres connection (DATABASE_URL / SUPABASE_DB_URL), and no job in .github/workflows/ has database credentials — check.yml runs only the static check:workflow-catalog, and supabase.yml applies migrations through the Supabase CLI. Run them by hand against staging or production after a catalog change, or give the deploy workflow a connection string first.

Cross-References

  • packages/harness/src/gates.ts — FLOOR_GATES includes @carbon/checks test and clobbers as CI gates
  • packages/database/supabase/migrations/ — SQL files scanned by conformance checks
  • apps/erp/app/modules/ — module directories validated by moduleShape