@noctcore/lint-meta-rules 0.3.0 → 0.4.0

package/docs/rules/eslint-config-no-warn.md

@@ -0,0 +1,71 @@
+# `eslint-config-no-warn`
+
+> Every rule in the RESOLVED ESLint config is `error` or `off`, never `warn`, including severities a
+> spread preset injects.
+
+Import it from the `resolved-config` entry point, which (unlike the main one) loads ESLint:
+
+```ts
+import { createEslintConfigNoWarnRule } from '@noctcore/lint-meta-rules/resolved-config';
+```
+
+## Why
+
+A `warn` neither fails CI nor gets fixed. [`no-warn-severity`](./no-warn-severity.md) scans config
+TEXT for a `'warn'` literal, which misses the common case: a preset spread into the config
+(`...reactHooks.configs['recommended-latest']`) ships rules at `warn`, and no file the project owns
+spells the word. This rule asks ESLint itself. It resolves each package's effective flat config with
+`calculateConfigForFile` and reports every rule that ends up at severity 1, however it got there.
+
+Use both: the text scan is instant and runs anywhere; this one is the one a preset cannot slip past.
+
+## What it flags
+
+For every directory matched by `packages` that holds one of `configFiles`, it resolves the config for
+each of `probes` (glob matching only, so the probe files need not exist) and reports, once per rule
+id, every rule whose resolved severity is `warn` (`1`, `'warn'`, or `['warn', ...]`).
+
+It **fails closed**:
+
+- a config that cannot be loaded (a missing import, an unbuilt workspace package) is a violation;
+- a probe whose resolution THROWS is a violation even when another probe resolves, so a config that
+  breaks for one file shape cannot pass on the shapes that still work;
+- a package whose config ignores every probe is a violation, since nothing was checked.
+
+A probe that is merely ignored is fine while another probe resolves.
+
+Async: it implements the harness's `runAsync` (`@noctcore/harness` 0.3.0 or newer).
+
+## Factory
+
+```ts
+createEslintConfigNoWarnRule(options?: EslintConfigNoWarnOptions): IMetaRule
+```
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `id` | `string` | `'eslint-config-no-warn'` | Rule id, for running more than one instance. |
+| `packages` | `string[]` | `['.', 'apps/*', 'packages/*']` | Directories whose config is resolved: globs, or `.` for the root. A match is checked only when it holds one of `configFiles`. |
+| `configFiles` | `string[]` | `['eslint.config.js', 'eslint.config.mjs', 'eslint.config.cjs']` | File names that mark a directory as owning a flat config. The first one present names the violation's file. |
+| `probes` | `string[]` | `src/__lint_meta_probe__.{ts,tsx,test.ts,test.tsx}` | Files, relative to each package, the config is resolved for. Add one per file shape your config scopes blocks to (`.js`, `.vue`, `e2e/**`). |
+| `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
+
+## Worked example: a pnpm monorepo
+
+Settly-style layout, where every app and package owns a config built from a shared
+`@repo/eslint-config`, and the root config only lints tooling:
+
+```ts
+createEslintConfigNoWarnRule({ packages: ['apps/*', 'packages/*'] });
+```
+
+Deleting the three `react-hooks/*` overrides from the shared React config (so the
+`recommended-latest` preset's `warn` shows through, with no `warn` literal anywhere) reports three
+rules in each of the three packages that spread it.
+
+## Notes
+
+- The rule resolves with the `eslint` that `@noctcore/lint-meta-rules` resolves, which is the
+  consumer's own install when it is hoisted.
+- If a config imports a workspace package that must be built first, build it before lint-meta, or
+  the rule reports that the config could not be resolved.

package/docs/rules/prisma-method-surface.md

@@ -0,0 +1,65 @@
+# `prisma-method-surface`
+
+> The Prisma reads and writes your rules police partition the generated client's `<Model>Delegate`
+> method surface exactly, so a Prisma upgrade cannot add an unguarded method.
+
+Import it from the `prisma` entry point:
+
+```ts
+import { createPrismaMethodSurfaceRule } from '@noctcore/lint-meta-rules/prisma';
+```
+
+## Why
+
+Rules that guard Prisma calls by method name (tenant fences, single-writer fences, transaction
+rules) read a hand-written list of methods. The list falls behind the client: Prisma adds a method
+(`createManyAndReturn` and `updateManyAndReturn` both arrived this way), nobody edits the list, and
+the new method is invisible to every fence at once. It reads like ordinary code, not like evasion,
+which is what makes the gap dangerous.
+
+This reads the GENERATED client, which changes the moment Prisma is upgraded, and asserts the
+configured reads and writes are exactly its delegate surface.
+
+## What it flags
+
+- a delegate method that is neither a configured read nor a configured write (the upgrade case);
+- a configured method the client no longer exposes;
+- a delegate whose method surface differs from the others (the lists are model-agnostic);
+- a method configured as both a read and a write.
+
+It **fails closed**: no generated client under `clientGlobs` is a violation, because a checkout that
+never ran `prisma generate` is exactly where drift hides. Run `prisma generate` before lint-meta.
+
+Members are read line by line: a delegate method is a generic, `name<T ...>(...)`, at the interface's
+member indentation. `fields`, the symbol brand and `$`-prefixed members are not query methods.
+
+## Factory
+
+```ts
+createPrismaMethodSurfaceRule(options?: PrismaMethodSurfaceOptions): IMetaRule
+```
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `id` | `string` | `'prisma-method-surface'` | Rule id. |
+| `clientGlobs` | `string[]` | `['generated/prisma/models/*.ts', 'node_modules/.prisma/client/index.d.ts']` | Generated client files declaring the delegates: the `prisma-client` generator's per-model files, or the `prisma-client-js` generator's single `index.d.ts`. Point it at your generator's `output`. |
+| `writeMethods` | `string[]` | `PRISMA_WRITE_METHODS` from `@noctcore/eslint-plugin-prisma` | The methods your rules police as writes. |
+| `readMethods` | `string[]` | `PRISMA_READ_METHODS` from `@noctcore/eslint-plugin-prisma` | The methods your rules know to be reads. |
+| `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
+
+With the defaults, the rule checks the exact lists `@noctcore/eslint-plugin-prisma`'s rules read.
+If your own rules read their own lists, pass those.
+
+## Worked example: Settly
+
+Settly's schema generates into `packages/database/generated/prisma` with the `prisma-client`
+generator:
+
+```ts
+createPrismaMethodSurfaceRule({
+  clientGlobs: ['packages/database/generated/prisma/models/*.ts'],
+});
+```
+
+Adding a method to every generated delegate reports it as unguarded; adding it to one model only
+reports that delegate as divergent; removing the generated folder reports that no client was found.

package/docs/rules/tenant-model-registry-parity.md

@@ -0,0 +1,117 @@
+# `tenant-model-registry-parity`
+
+> Every tenant-bearing Prisma model is scoped by the runtime tenant extension or exempt with a
+> reason, and the tenant lint rules resolve with exactly that registry.
+
+Import it from the `prisma` entry point:
+
+```ts
+import { createTenantModelRegistryParityRule } from '@noctcore/lint-meta-rules/prisma';
+```
+
+## Why
+
+A multi-tenant Prisma project keeps "which models are tenant-scoped?" in two hand-maintained places:
+the model map of its tenant-scope client extension (the runtime boundary) and the model list its
+tenant lint rules are configured with (the static boundary). Checking those two against each other
+catches a list edited on one side. It cannot catch the expensive case: a migration adds a
+tenant-bearing table and touches neither list, so the table gets no runtime scope and no lint
+coverage while both lists still agree.
+
+So the SCHEMA is the third input. The set of tenant-bearing models is derived from it, and every one
+must be in the runtime map or in an explicit `unscopedByDesign` exemption with a written reason. A
+new tenant-scoped model cannot be added without the guardrails learning about it.
+
+The static side is read from the RESOLVED ESLint config, not by parsing the config file, so it
+asserts what the rules actually receive: moving the array, spreading a different preset, or passing
+one rule a hand-written list is all caught.
+
+## What it flags
+
+1. **Schema vs registry** (via `reconcileTenantRegistry` from `@noctcore/eslint-plugin-prisma`): a
+   model carrying every `tenantFields` column that is neither scoped nor exempt; a model both scoped
+   and exempt; a scoped model or exemption no schema model maps to.
+2. **Hand scope** (when `requireHandScope`): an exemption with no `handScopedModels` columns and no
+   `handScopePending` note; a `handScopedModels` or `handScopePending` entry for a model that is not
+   exempt.
+3. **Registry vs resolved config** (unless `eslint: false`): for each of `modelRules`, a rule that is
+   off or not configured, a rule with no `modelsOption`, a scoped model missing from the option, or
+   an option model that is not scoped; and a `handScopedRule` whose `handScopedOption` does not equal
+   `registry.handScopedModels`.
+
+It **fails closed**: an unreadable runtime map, a missing schema, or a config that cannot be
+resolved is a violation, never an empty registry. Schema findings are still reported when the config
+cannot be resolved.
+
+Async: it implements the harness's `runAsync` (`@noctcore/harness` 0.3.0 or newer).
+
+## Factory
+
+```ts
+createTenantModelRegistryParityRule(options?: TenantModelRegistryParityOptions): IMetaRule
+```
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `id` | `string` | `'tenant-model-registry-parity'` | Rule id. |
+| `schemaPath` | `string` | `'prisma/schema.prisma'` | The schema: a `.prisma` file, or a folder whose `.prisma` files (recursively) are read together. |
+| `tenantFields` | `string[]` | `['tenantId']` | Columns that make a model tenant-bearing; a model must carry ALL of them. |
+| `registry` | `TenantRegistry` | `{ scopedModels: [], unscopedByDesign: {} }` | The project's registry as injected DATA: `scopedModels`, `unscopedByDesign`, `handScopedModels`, `handScopePending` (the `TenantRegistry` type from `@noctcore/eslint-plugin-prisma`). |
+| `scopedModelsSource` | `{ file, exportName }` | none | Read the scoped models from the runtime source instead of `registry.scopedModels`: the top-level keys of the object literal assigned to `exportName` in `file`. |
+| `requireHandScope` | `boolean` | `true` | Require every exemption to name its hand-scope columns or record why it cannot. |
+| `eslint` | `TenantRegistryEslintOptions \| false` | `{}` | The static side (below), or `false` to check only the registry against the schema. |
+| `registryFile` | `string` | `scopedModelsSource.file`, else `schemaPath` | Path reported for registry-side violations. |
+| `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
+
+`eslint` options:
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `cwd` | `string` | `'.'` | Directory whose ESLint config is resolved. |
+| `probe` | `string` | `'src/__lint_meta_probe__.ts'` | File, relative to `cwd`, the config is resolved for. Match the glob your tenant rules are scoped to. |
+| `modelRules` | `string[]` | the `noctcore-prisma` rules `no-cross-tenant-id-in-where`, `tenant-scoped-tables-require-where`, `tenant-write-must-carry-tenant-id` | Rules whose model option must equal the scoped models. |
+| `modelsOption` | `string` | `'tenantModels'` | The option those rules take the model list in. |
+| `handScopedRule` | `string \| null` | `'noctcore-prisma/tenant-scoped-tables-require-where'` | The rule whose hand-scope option must equal `registry.handScopedModels`; `null` skips it. Checked only when the registry has hand-scoped models. |
+| `handScopedOption` | `string` | `'handScopedModels'` | The option that rule takes the map in. |
+| `configFile` | `string` | `cwd` | Path reported for config-side violations: where a maintainer edits the list. |
+
+Keys are Prisma delegate accessors (`invoice` for `model Invoice`).
+
+## Worked example: Settly
+
+Settly scopes on `tenantId`, splits its schema per domain, keeps the runtime map in its API's tenant
+extension and the exemption maps in a registry module its ESLint config also reads:
+
+```ts
+import { createTenantModelRegistryParityRule } from '@noctcore/lint-meta-rules/prisma';
+
+import { HAND_SCOPED_MODELS, HAND_SCOPE_PENDING, UNSCOPED_BY_DESIGN } from './tenant-registry';
+
+createTenantModelRegistryParityRule({
+  schemaPath: 'packages/database/prisma/schema',
+  tenantFields: ['tenantId'],
+  scopedModelsSource: {
+    file: 'apps/api/src/common/database/tenant-scope.extension.ts',
+    exportName: 'TENANT_SCOPED_MODELS',
+  },
+  registry: {
+    scopedModels: [],
+    unscopedByDesign: UNSCOPED_BY_DESIGN,
+    handScopedModels: HAND_SCOPED_MODELS,
+    handScopePending: HAND_SCOPE_PENDING,
+  },
+  eslint: {
+    cwd: 'apps/api',
+    probe: 'src/modules/example/example.service.ts',
+    configFile: 'packages/eslint-config/nestjs.js',
+  },
+});
+```
+
+The registry is data the lint-meta registry imports from wherever the project keeps it; the rule
+never reads a project file by a hardcoded path.
+
+## When not to use it
+
+A project with row-level security as its tenant boundary, or with no client-side scope map, has no
+runtime registry to reconcile: use `eslint: false` and the schema half alone, or skip the rule.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noctcore/lint-meta-rules",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Portable, parameterized lint-meta rules — whole-repo / cross-file invariants ESLint cannot reach — for the @noctcore/harness lint-meta runner.",
   "license": "MIT",
   "type": "module",
@@ -18,6 +18,16 @@
       "import": "./dist/i18n.js",
       "require": "./dist/i18n.cjs"
     },
+    "./prisma": {
+      "types": "./dist/prisma.d.ts",
+      "import": "./dist/prisma.js",
+      "require": "./dist/prisma.cjs"
+    },
+    "./resolved-config": {
+      "types": "./dist/resolved-config.d.ts",
+      "import": "./dist/resolved-config.js",
+      "require": "./dist/resolved-config.cjs"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -46,12 +56,13 @@
   "homepage": "https://github.com/noctcore/eslint-plugins/tree/main/packages/lint-meta-rules",
   "bugs": "https://github.com/noctcore/eslint-plugins/issues",
   "scripts": {
-    "build": "tsup src/index.ts src/i18n.ts --format esm,cjs --dts --clean",
+    "build": "tsup src/index.ts src/i18n.ts src/prisma.ts src/resolved-config.ts --format esm,cjs --dts --clean",
     "typecheck": "tsc --noEmit",
     "test": "bun test"
   },
   "dependencies": {
     "@noctcore/eslint-plugin-contracts": "^0.5.0",
+    "@noctcore/eslint-plugin-prisma": "^0.3.0",
     "@noctcore/harness": "^0.3.0",
     "@typescript-eslint/utils": "^8.61.1"
   },