@noctcore/lint-meta-rules 0.6.0 → 0.6.1

package/docs/rules/session-mint-callers.md

@@ -3,6 +3,10 @@
 > The method that mints a session is callable only from an allowlist of files, so a new sign-in
 > entry point cannot skip the gate in front of it.
 
+<!-- begin generated rule header -->
+Runs under `@noctcore/harness`, not ESLint · Factory `createSessionMintCallersRule` from `@noctcore/lint-meta-rules/session` · Category `source-text` · Fails CI by default: yes
+<!-- end generated rule header -->
+
 Import it from the `session` entry point:
 
 ```ts
@@ -23,7 +27,7 @@ session, so this rule fences the door by caller.
 A file matched by `sourceGlobs` that calls `.<mintCall>(` (whitespace before the paren allowed) and is
 not in `allowedCallers`.
 
-## What it leaves alone
+## What it does not flag
 
 - The method's definition (`async establishSession(`): the leading dot is required.
 - `.<mintCall>Something(`: only whitespace may sit between the name and the paren.
@@ -33,7 +37,7 @@ not in `allowedCallers`.
 
 With no `mintCall` the rule is inert.
 
-## Factory
+## Options
 
 ```ts
 createSessionMintCallersRule(options?: SessionMintCallersOptions): IMetaRule
@@ -51,7 +55,11 @@ createSessionMintCallersRule(options?: SessionMintCallersOptions): IMetaRule
 | `hint` | `string` | none | Appended to every message, e.g. a pointer to your auth docs. |
 | `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
 
-## Worked example: Settly
+### Worked example: an app with a gated session mint
+
+`establishSession` mints the session and `beginOrEstablish` is the second-factor gate every sign-in
+must pass through. Only the mint's home, the gate, signup and the two re-issue flows may call the mint
+directly:
 
 ```ts
 const AUTH = 'apps/api/src/modules/auth/services';

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

@@ -3,6 +3,10 @@
 > 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.
 
+<!-- begin generated rule header -->
+Runs under `@noctcore/harness`, not ESLint · Factory `createTenantModelRegistryParityRule` from `@noctcore/lint-meta-rules/prisma` · Category `config` · Fails CI by default: yes
+<!-- end generated rule header -->
+
 Import it from the `prisma` entry point:
 
 ```ts
@@ -45,7 +49,17 @@ cannot be resolved.
 
 Async: it implements the harness's `runAsync` (`@noctcore/harness` 0.3.0 or newer).
 
-## Factory
+## What it does not flag
+
+- A schema model that carries only some of the `tenantFields` columns: a model must carry ALL of them
+  to be tenant-bearing.
+- A tenant-bearing model listed in `unscopedByDesign`, once it names its hand-scope columns in
+  `handScopedModels` or records why it cannot in `handScopePending`.
+- Hand-scope gaps when `requireHandScope` is `false`.
+- The resolved ESLint config when `eslint` is `false`; the hand-scope option when `handScopedRule` is
+  `null` or the registry has no hand-scoped models.
+
+## Options
 
 ```ts
 createTenantModelRegistryParityRule(options?: TenantModelRegistryParityOptions): IMetaRule
@@ -77,10 +91,10 @@ createTenantModelRegistryParityRule(options?: TenantModelRegistryParityOptions):
 
 Keys are Prisma delegate accessors (`invoice` for `model Invoice`).
 
-## Worked example: Settly
+### Worked example: a multi-tenant monorepo
 
-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:
+A project that 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';

package/docs/rules/test-runner-segregation.md

@@ -2,6 +2,10 @@
 
 > Bun-side and foreign-side test runners are never mixed within a package.
 
+<!-- begin generated rule header -->
+Runs under `@noctcore/harness`, not ESLint · Factory `createTestRunnerSegregationRule` from `@noctcore/lint-meta-rules` · Category `testing` · Fails CI by default: yes
+<!-- end generated rule header -->
+
 ## Why
 
 A package that mixes two test runners (e.g. `bun:test` and Vitest) has tests that run under one
@@ -15,10 +19,18 @@ and the **foreign set** (`vitestDirs`). For every `*.test.ts(x)` file:
 
 - **bun-side** — must import the bun runner (`bunRunnerImport`) and must NOT import the foreign runner
   (`foreignRunnerImport`);
-- **foreign-side** — must NOT import the bun runner. (A direct foreign-runner import is not required —
-  it may arrive transitively via shared test-utils.)
+- **foreign-side** — must NOT import the bun runner.
+
+## What it does not flag
 
-## Factory
+- A foreign-side test with no direct foreign-runner import: the runner may arrive transitively via
+  shared test-utils.
+- A bun-side test that imports `bunRunnerImport` and not the foreign runner.
+- Anything in a `vitestDirs` directory for a missing bun import (those dirs leave the bun set).
+- Files that are not `*.test.ts` / `*.test.tsx` (setup files, helpers), and `require()` or dynamic
+  imports: only a `from '<runner>'` import is read.
+
+## Options
 
 ```ts
 createTestRunnerSegregationRule(options?: TestRunnerSegregationOptions): IMetaRule
@@ -33,8 +45,6 @@ createTestRunnerSegregationRule(options?: TestRunnerSegregationOptions): IMetaRu
 | `foreignRunnerImport` | `string` | `'vitest'` | The foreign runner import specifier. |
 | `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
 
-De-projected from nightcore, which hardcoded `bun:test` vs `vitest` and the two dir sets.
-
 ## When not to use it
 
 If your repo uses a single test runner everywhere, this rule has nothing to segregate.

package/docs/rules/test-sibling-enforcement.md

@@ -2,10 +2,14 @@
 
 > Every source file matched by `include` must have a colocated sibling test.
 
+<!-- begin generated rule header -->
+Runs under `@noctcore/harness`, not ESLint · Factory `createTestSiblingEnforcementRule` from `@noctcore/lint-meta-rules` · Category `source-text` · Fails CI by default: yes
+<!-- end generated rule header -->
+
 ## Why
 
 A pure helper with no test is a silent liability — the kind of code that drifts because nothing pins
-its behavior. Requiring a colocated test for a chosen class of files (nightcore's `.utils.ts` sidecars)
+its behavior. Requiring a colocated test for a chosen class of files (`.utils.ts` helper files, say)
 makes "did you test this?" a mechanical check rather than a review-time hope.
 
 ## What it flags
@@ -14,7 +18,13 @@ For each file matched by an `include` glob, the sibling test is the same path wi
 extension replaced by each configured test extension. If none of those siblings exists, the source
 file is flagged. Strict — there is no baseline; the pattern is opt-in via which files `include` selects.
 
-## Factory
+## What it does not flag
+
+- A matched file with a sibling for any one of `testExtensions` (`foo.utils.test.ts` or
+  `foo.utils.test.tsx` for `foo.utils.ts`).
+- Files outside `include` (only `apps/web/src/**/*.utils.ts` by default).
+
+## Options
 
 ```ts
 createTestSiblingEnforcementRule(options?: TestSiblingEnforcementOptions): IMetaRule
@@ -26,9 +36,6 @@ createTestSiblingEnforcementRule(options?: TestSiblingEnforcementOptions): IMeta
 | `testExtensions` | `string[]` | `['.test.ts', '.test.tsx']` | Accepted colocated-test extensions (replace the source extension). |
 | `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
 
-De-projected from nightcore, which hardcoded `apps/web/src/**/*.utils.ts` and the `.utils.test.ts(x)`
-sibling shape.
-
 ## When not to use it
 
 If you colocate tests loosely or centralize them in a `__tests__` tree, retune `include`/`testExtensions`

package/docs/rules/test-workspace-enrollment.md

@@ -2,6 +2,10 @@
 
 > Every tested package must be enumerated in the aggregate test script.
 
+<!-- begin generated rule header -->
+Runs under `@noctcore/harness`, not ESLint · Factory `createTestWorkspaceEnrollmentRule` from `@noctcore/lint-meta-rules` · Category `testing` · Fails CI by default: yes
+<!-- end generated rule header -->
+
 ## Why
 
 When the CI test command is a hardcoded list of workspace paths, a package added without editing that
@@ -13,10 +17,17 @@ cannot silently escape CI.
 
 Reads the root manifest's `scriptName` command. For each candidate directory (from `packageGlobs`
 plus `extraDirs`, minus `excludeDirs`) that contains at least one file matching `testGlobSuffix`, if
-the directory string does not appear in the script command, it is flagged. A missing or invalid
-manifest is a no-op.
+the directory string does not appear in the script command, it is flagged.
+
+## What it does not flag
 
-## Factory
+- A candidate package with no file matching `testGlobSuffix`.
+- Directories in `excludeDirs` (tested by a different runner or script).
+- Anything when the root manifest is missing or is not valid JSON: the rule is a no-op.
+- A directory whose path appears anywhere in the script text: the check is a substring match, not a
+  parse of the command.
+
+## Options
 
 ```ts
 createTestWorkspaceEnrollmentRule(options?: TestWorkspaceEnrollmentOptions): IMetaRule
@@ -32,9 +43,6 @@ createTestWorkspaceEnrollmentRule(options?: TestWorkspaceEnrollmentOptions): IMe
 | `testGlobSuffix` | `string` | `'**/*.test.ts'` | Glob suffix (per dir) that detects the presence of tests. |
 | `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
 
-De-projected from nightcore, which hardcoded the `test:node` script, a `packages/*` + `apps/sidecar`
-dir list, and a vitest exclusion set.
-
 ## When not to use it
 
 If your test runner discovers packages automatically (no hardcoded path list), this rule is

package/docs/rules/translation-dead-keys.md

@@ -3,6 +3,10 @@
 > Every translation catalog key is reachable from the source: named by a translation call, or spelled
 > by some string in the code.
 
+<!-- begin generated rule header -->
+Runs under `@noctcore/harness`, not ESLint · Factory `createTranslationDeadKeysRule` from `@noctcore/lint-meta-rules/i18n` · Category `source-text` · Fails CI by default: yes
+<!-- end generated rule header -->
+
 Import it from the `i18n` entry point, which (unlike the main one) loads ESLint:
 
 ```ts
@@ -21,7 +25,27 @@ This rule resolves call sites with the same visitor and catalog loader as
 two checks never disagree on which key a call means. It then adds the data routes a per-file rule
 cannot see.
 
-## What counts as reached
+## What it flags
+
+Every key in `catalogs` that no scanned source reaches (the routes are listed under
+[What it does not flag](#what-it-does-not-flag)). What is left was named by no call and spelled by no
+string. On a production app with 1,824 keys this reported 55, and every one of them had zero
+references outside the catalogs.
+
+### Blind spots
+
+It is conservative, not complete. It reports a reached key as dead when the key arrives by a route it
+cannot see:
+
+- **Keys that never appear in the scanned source**: server-sent codes, a CMS, another app, JSON
+  config. List them in `allow`, or add the files that spell them to `sourceGlobs`.
+- **A variable key under a `keyPrefix` binding**: `useTranslation('ns', { keyPrefix: 'form' })` then
+  `t(field)` with `field = 'name'` reaches `form.name`, but no string spells `form.name`. (A static key
+  under a `keyPrefix` is resolved correctly.)
+- **Keys built by anything other than `+` or a template literal**: `[a, b].join('.')`,
+  `` `${a}` `` split across variables, `String.prototype.concat`.
+
+## What it does not flag
 
 A key is reached, and never reported, when ANY of these holds:
 
@@ -36,29 +60,13 @@ A key is reached, and never reported, when ANY of these holds:
   `` `nav.${id}.label` `` and `'errors.' + code` are patterns, not just call arguments;
 - it matches an `allow` pattern.
 
-And it reports **no dead key at all** when a scanned file cannot be analysed (a parse error), or when
+It reports **no dead key at all** when a scanned file cannot be analysed (a parse error), or when
 `sourceGlobs` match nothing: in both cases the rule would otherwise call reached keys dead.
 
-What is left was named by no call and spelled by no string. On a production app with 1,824 keys this
-reported 55, and every one of them had zero references outside the catalogs.
-
-## Blind spots
-
-It is conservative, not complete. It reports a reached key as dead when the key arrives by a route it
-cannot see:
-
-- **Keys that never appear in the scanned source**: server-sent codes, a CMS, another app, JSON
-  config. List them in `allow`, or add the files that spell them to `sourceGlobs`.
-- **A variable key under a `keyPrefix` binding**: `useTranslation('ns', { keyPrefix: 'form' })` then
-  `t(field)` with `field = 'name'` reaches `form.name`, but no string spells `form.name`. (A static key
-  under a `keyPrefix` is resolved correctly.)
-- **Keys built by anything other than `+` or a template literal**: `[a, b].join('.')`,
-  `` `${a}` `` split across variables, `String.prototype.concat`.
-
 It also misses some dead keys, by design: any string that happens to equal a key (in any namespace)
 keeps it alive, and a broad pattern such as `` `${x}.title` `` keeps every `*.title` alive.
 
-## Factory
+## Options
 
 ```ts
 createTranslationDeadKeysRule(options?: TranslationDeadKeysOptions): IMetaRule
@@ -92,7 +100,12 @@ createTranslationDeadKeysRule({
 });
 ```
 
-## Requirements
+### Requirements
 
 The `i18n` entry needs the optional peers `eslint` (>= 9) and `@typescript-eslint/parser`. Scanned
 files are parsed as TypeScript with JSX enabled, without type information.
+
+## When not to use it
+
+If most keys reach the app from outside the scanned source (server-sent codes, a CMS, another app),
+`allow` would have to list most of the catalog and the rule proves little, so skip it.

package/docs/rules/ui-primitive-shape.md

@@ -2,6 +2,10 @@
 
 > A folder primitive must ship its proof siblings; a flat primitive must carry none at the ui root.
 
+<!-- begin generated rule header -->
+Runs under `@noctcore/harness`, not ESLint · Factory `createUiPrimitiveShapeRule` from `@noctcore/lint-meta-rules` · Category `source-text` · Fails CI by default: yes
+<!-- end generated rule header -->
+
 ## Why
 
 The primitives root is the one place exempt from folder-per-component: flat single files are fine for
@@ -18,7 +22,15 @@ tested + storied.
   `<Name>.<role><extension>` at the ui root is flagged: those proof files belong inside a `<Name>/`
   folder.
 
-## Factory
+## What it does not flag
+
+- A bare flat primitive (`<uiRoot>/Button.tsx`) with no proof sibling at the ui root.
+- A folder primitive that ships every configured role (`Dialog/Dialog.test.tsx`,
+  `Dialog/Dialog.stories.tsx`).
+- A folder without the `barrelFile`, and flat files whose name does not start with a capital letter.
+- Anything outside `uiRoot`.
+
+## Options
 
 ```ts
 createUiPrimitiveShapeRule(options?: UiPrimitiveShapeOptions): IMetaRule
@@ -32,9 +44,6 @@ createUiPrimitiveShapeRule(options?: UiPrimitiveShapeOptions): IMetaRule
 | `extension` | `string` | `'.tsx'` | Extension of primitive and proof files. |
 | `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
 
-De-projected from nightcore, which hardcoded `apps/web/src/components/ui`, the `test`/`stories` roles,
-and the `.tsx` extension.
-
 ## When not to use it
 
 If you do not maintain a flat-vs-folder primitive convention or do not colocate stories/tests, skip

package/docs/rules/workspace-graph-parity.md

@@ -3,6 +3,10 @@
 > Imported `<scope>/*` specifiers must be declared `workspace:*` deps, and tsconfig `references` must
 > mirror those deps.
 
+<!-- begin generated rule header -->
+Runs under `@noctcore/harness`, not ESLint · Factory `createWorkspaceGraphParityRule` from `@noctcore/lint-meta-rules` · Category `config` · Fails CI by default: yes
+<!-- end generated rule header -->
+
 ## Why
 
 A cross-package edge is real in three places at once: the import in source, the `workspace:*` entry in
@@ -14,13 +18,21 @@ so an edge can never be half-wired.
 
 For each workspace `package.json`:
 
-- **(a) imported ⊆ declared** — every `<scope>/<pkg>` imported under the source dir (test files
-  excluded, self-imports ignored) must appear as a `"<scope>/<pkg>": "workspace:*"` dependency.
+- **(a) imported ⊆ declared** — every `<scope>/<pkg>` imported under the source dir must appear as a
+  `"<scope>/<pkg>": "workspace:*"` dependency.
 - **(b) references mirror deps** — the tsconfig `references` must reference exactly the declared
   workspace deps: a declared dep missing from references, or a referenced package that is not a
   declared dep, is a violation.
 
-## Factory
+## What it does not flag
+
+- A package importing itself by its own `<scope>/<dir>` name.
+- Imports in test files (`.test.ts`, `.test.tsx`) and files outside `srcDir`.
+- Imports without a `from` clause (`import()`, `require()`, a side-effect `import`): only
+  `from '<scope>/<pkg>'` is read.
+- Check (b) for a package with no `tsconfig.json`.
+
+## Options
 
 ```ts
 createWorkspaceGraphParityRule(options?: WorkspaceGraphParityOptions): IMetaRule
@@ -33,8 +45,6 @@ createWorkspaceGraphParityRule(options?: WorkspaceGraphParityOptions): IMetaRule
 | `srcDir` | `string` | `'src'` | Source directory (per package) scanned for imports. |
 | `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
 
-De-projected from nightcore, which hardcoded the `@nightcore` scope and a `src` source directory.
-
 ## When not to use it
 
 If your project does not use the `workspace:*` protocol, or does not use TypeScript project

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noctcore/lint-meta-rules",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "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",
@@ -63,7 +63,7 @@
     "url": "git+https://github.com/noctcore/eslint-plugins.git",
     "directory": "packages/lint-meta-rules"
   },
-  "homepage": "https://github.com/noctcore/eslint-plugins/tree/main/packages/lint-meta-rules",
+  "homepage": "https://noctcore.github.io/eslint-plugins/packages/lint-meta-rules/",
   "bugs": "https://github.com/noctcore/eslint-plugins/issues",
   "scripts": {
     "build": "tsup src/index.ts src/i18n.ts src/prisma.ts src/resolved-config.ts src/session.ts src/trpc.ts --format esm,cjs --dts --clean",
@@ -71,8 +71,8 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@noctcore/eslint-plugin-contracts": "^0.7.0",
-    "@noctcore/eslint-plugin-prisma": "^0.5.0",
+    "@noctcore/eslint-plugin-contracts": "^0.7.1",
+    "@noctcore/eslint-plugin-prisma": "^0.5.1",
     "@noctcore/harness": "^0.3.0",
     "@typescript-eslint/utils": "^8.61.1"
   },