@noctcore/lint-meta-rules 0.3.0 → 0.4.0

package/dist/prisma.d.cts

@@ -0,0 +1,174 @@
+import { IMetaRule } from '@noctcore/harness';
+import { TenantRegistry } from '@noctcore/eslint-plugin-prisma';
+export { TenantRegistry } from '@noctcore/eslint-plugin-prisma';
+
+/**
+ * Options for {@link createPrismaMethodSurfaceRule}.
+ *
+ * Every path is relative to the repo root the harness runs in.
+ */
+interface PrismaMethodSurfaceOptions {
+    /** Rule id, for running more than one instance. Default `prisma-method-surface`. */
+    readonly id?: string;
+    /**
+     * Globs of the GENERATED Prisma client files that declare the
+     * `<Model>Delegate` interfaces. Default: the `prisma-client` generator's
+     * per-model files under `generated/prisma/models/`, and the
+     * `prisma-client-js` generator's `node_modules/.prisma/client/index.d.ts`.
+     */
+    readonly clientGlobs?: readonly string[];
+    /**
+     * The methods your rules police as WRITES. Default: `PRISMA_WRITE_METHODS`
+     * from `@noctcore/eslint-plugin-prisma`, which is what its rules read.
+     */
+    readonly writeMethods?: readonly string[];
+    /**
+     * The methods your rules know to be READS. Default: `PRISMA_READ_METHODS`
+     * from `@noctcore/eslint-plugin-prisma`.
+     */
+    readonly readMethods?: readonly string[];
+    /** Whether a violation fails CI. Default `true`. */
+    readonly ciCritical?: boolean;
+}
+/** One `<Model>Delegate` interface: where it was read, and its query methods. */
+interface DelegateSurface {
+    readonly file: string;
+    readonly model: string;
+    readonly methods: readonly string[];
+}
+/**
+ * Every `<Model>Delegate` interface declared in `source`, with its query methods.
+ *
+ * A delegate member is a generic method, `name<T ...>(...)`, declared at the
+ * interface's member indentation, one per line. That holds for both Prisma
+ * generators, so a line scan is enough and needs no TypeScript parse. Anything
+ * that is not a generic method (`fields`, the `[K: symbol]` brand) is not a
+ * query method and is dropped, as is anything `$`-prefixed.
+ */
+declare function parseDelegateSurfaces(source: string, file?: string): DelegateSurface[];
+/**
+ * The model-delegate method surface the rules police must be the surface the
+ * generated Prisma client actually exposes.
+ *
+ * Rules that guard Prisma calls by method name read a hand-written list, and a
+ * list falls behind the client: Prisma adds a method, nobody edits the list, and
+ * the new method is invisible to every fence at once. This reads the GENERATED
+ * client's `<Model>Delegate` interfaces and asserts the configured reads and
+ * writes partition them exactly, so an upgrade that adds a method turns CI red
+ * instead of silently widening an unguarded surface.
+ *
+ * Fails closed: no generated client is a violation, never a vacuous pass, since
+ * a checkout that never ran `prisma generate` is exactly where drift hides.
+ */
+declare function createPrismaMethodSurfaceRule(options?: PrismaMethodSurfaceOptions): IMetaRule;
+
+/** Where the runtime scope map is declared, when it is read from source. */
+interface ScopedModelsSource {
+    /** File declaring the map, e.g. the tenant-scope client extension. */
+    readonly file: string;
+    /** Name of the `const` whose object-literal KEYS are the scoped delegate accessors. */
+    readonly exportName: string;
+}
+/**
+ * The STATIC side: the lint config whose tenant rules must receive the registry.
+ * Read from the RESOLVED config, so it asserts what the rules actually get.
+ */
+interface TenantRegistryEslintOptions {
+    /** Directory whose ESLint config is resolved. Default `.`. */
+    readonly cwd?: string;
+    /** File, relative to `cwd`, the config is resolved for; match your tenant rules' glob. Default `src/__lint_meta_probe__.ts`. */
+    readonly probe?: string;
+    /**
+     * Rules whose `modelsOption` must equal the scoped models. Default the three
+     * `noctcore-prisma` tenant rules.
+     */
+    readonly modelRules?: readonly string[];
+    /** The option those rules take the model list in. Default `tenantModels`. */
+    readonly modelsOption?: string;
+    /**
+     * The rule whose `handScopedOption` must equal `registry.handScopedModels`, or
+     * `null` to skip. Default `noctcore-prisma/tenant-scoped-tables-require-where`.
+     */
+    readonly handScopedRule?: string | null;
+    /** The option that rule takes the hand-scope map in. Default `handScopedModels`. */
+    readonly handScopedOption?: string;
+    /** Path reported for config-side violations. Default: `cwd`. */
+    readonly configFile?: string;
+}
+/**
+ * Options for {@link createTenantModelRegistryParityRule}.
+ *
+ * Every path is relative to the repo root the harness runs in.
+ */
+interface TenantModelRegistryParityOptions {
+    /** Rule id, for running more than one instance. Default `tenant-model-registry-parity`. */
+    readonly id?: string;
+    /**
+     * The Prisma schema: a `.prisma` file, or a folder whose `.prisma` files
+     * (recursively) are read together. Default `prisma/schema.prisma`.
+     */
+    readonly schemaPath?: string;
+    /**
+     * The columns that make a model tenant-bearing: a model carrying ALL of them
+     * must be scoped or exempt. Default `['tenantId']`.
+     */
+    readonly tenantFields?: readonly string[];
+    /**
+     * The project's registry, injected as data (`TenantRegistry` from
+     * `@noctcore/eslint-plugin-prisma`). `scopedModels` is ignored when
+     * `scopedModelsSource` is set. Default: empty.
+     */
+    readonly registry?: TenantRegistry;
+    /**
+     * Read the scoped models from the runtime source instead of
+     * `registry.scopedModels`: the keys of an object literal
+     * (`export const SCOPED = { invoice: [...], ... }`). Prefer this when the
+     * runtime map is the source of truth, so the check reads it rather than a copy.
+     */
+    readonly scopedModelsSource?: ScopedModelsSource;
+    /**
+     * Require every unscoped-by-design model to name its hand-scope columns
+     * (`registry.handScopedModels`) or record why it cannot
+     * (`registry.handScopePending`). Default `true`.
+     */
+    readonly requireHandScope?: boolean;
+    /** The static side, or `false` to check only the registry against the schema. */
+    readonly eslint?: TenantRegistryEslintOptions | false;
+    /**
+     * Path reported for registry-side violations (the hand-scope maps, and the
+     * schema reconciliation when there is no `scopedModelsSource`). Default:
+     * `scopedModelsSource.file`, else `schemaPath`.
+     */
+    readonly registryFile?: string;
+    /** Whether a violation fails CI. Default `true`. */
+    readonly ciCritical?: boolean;
+}
+/**
+ * Top-level keys of the object literal assigned to `exportName`, or `null` when
+ * the declaration cannot be located (reported, never read as an empty map).
+ *
+ * Reads a comment- and string-blanked copy while tracking bracket depth, so a
+ * nested object or an array holding a `:` is never mistaken for an entry.
+ * Quoted keys (`'invoice': [...]`) are blanked with the strings, so a map must
+ * use identifier keys, as a delegate-accessor map does.
+ */
+declare function parseObjectLiteralKeys(source: string, exportName: string): string[] | null;
+/**
+ * The tenant-model registries must mirror each other AND the Prisma schema.
+ *
+ * A multi-tenant Prisma project keeps "which models are tenant-scoped?" in two
+ * hand-maintained places, the runtime scope map and the model list its tenant
+ * lint rules are configured with, and agreement between those two says nothing
+ * about a table neither has heard of. So the SCHEMA is the third input: every
+ * model carrying the tenant columns must be scoped or explicitly exempt with a
+ * reason, and a new tenant-bearing model cannot ship without the guardrails
+ * learning about it.
+ *
+ * The static side is read from the RESOLVED ESLint config, not by parsing the
+ * config file: moving the array, spreading a different preset, or handing one
+ * rule a hand-written list is all caught. Fails closed on an unreadable schema,
+ * runtime map or config. Needs the optional `eslint` peer unless `eslint: false`.
+ */
+declare function createTenantModelRegistryParityRule(options?: TenantModelRegistryParityOptions): IMetaRule;
+
+export { type DelegateSurface, type PrismaMethodSurfaceOptions, type ScopedModelsSource, type TenantModelRegistryParityOptions, type TenantRegistryEslintOptions, createPrismaMethodSurfaceRule, createTenantModelRegistryParityRule, parseDelegateSurfaces, parseObjectLiteralKeys };

package/dist/prisma.d.ts

@@ -0,0 +1,174 @@
+import { IMetaRule } from '@noctcore/harness';
+import { TenantRegistry } from '@noctcore/eslint-plugin-prisma';
+export { TenantRegistry } from '@noctcore/eslint-plugin-prisma';
+
+/**
+ * Options for {@link createPrismaMethodSurfaceRule}.
+ *
+ * Every path is relative to the repo root the harness runs in.
+ */
+interface PrismaMethodSurfaceOptions {
+    /** Rule id, for running more than one instance. Default `prisma-method-surface`. */
+    readonly id?: string;
+    /**
+     * Globs of the GENERATED Prisma client files that declare the
+     * `<Model>Delegate` interfaces. Default: the `prisma-client` generator's
+     * per-model files under `generated/prisma/models/`, and the
+     * `prisma-client-js` generator's `node_modules/.prisma/client/index.d.ts`.
+     */
+    readonly clientGlobs?: readonly string[];
+    /**
+     * The methods your rules police as WRITES. Default: `PRISMA_WRITE_METHODS`
+     * from `@noctcore/eslint-plugin-prisma`, which is what its rules read.
+     */
+    readonly writeMethods?: readonly string[];
+    /**
+     * The methods your rules know to be READS. Default: `PRISMA_READ_METHODS`
+     * from `@noctcore/eslint-plugin-prisma`.
+     */
+    readonly readMethods?: readonly string[];
+    /** Whether a violation fails CI. Default `true`. */
+    readonly ciCritical?: boolean;
+}
+/** One `<Model>Delegate` interface: where it was read, and its query methods. */
+interface DelegateSurface {
+    readonly file: string;
+    readonly model: string;
+    readonly methods: readonly string[];
+}
+/**
+ * Every `<Model>Delegate` interface declared in `source`, with its query methods.
+ *
+ * A delegate member is a generic method, `name<T ...>(...)`, declared at the
+ * interface's member indentation, one per line. That holds for both Prisma
+ * generators, so a line scan is enough and needs no TypeScript parse. Anything
+ * that is not a generic method (`fields`, the `[K: symbol]` brand) is not a
+ * query method and is dropped, as is anything `$`-prefixed.
+ */
+declare function parseDelegateSurfaces(source: string, file?: string): DelegateSurface[];
+/**
+ * The model-delegate method surface the rules police must be the surface the
+ * generated Prisma client actually exposes.
+ *
+ * Rules that guard Prisma calls by method name read a hand-written list, and a
+ * list falls behind the client: Prisma adds a method, nobody edits the list, and
+ * the new method is invisible to every fence at once. This reads the GENERATED
+ * client's `<Model>Delegate` interfaces and asserts the configured reads and
+ * writes partition them exactly, so an upgrade that adds a method turns CI red
+ * instead of silently widening an unguarded surface.
+ *
+ * Fails closed: no generated client is a violation, never a vacuous pass, since
+ * a checkout that never ran `prisma generate` is exactly where drift hides.
+ */
+declare function createPrismaMethodSurfaceRule(options?: PrismaMethodSurfaceOptions): IMetaRule;
+
+/** Where the runtime scope map is declared, when it is read from source. */
+interface ScopedModelsSource {
+    /** File declaring the map, e.g. the tenant-scope client extension. */
+    readonly file: string;
+    /** Name of the `const` whose object-literal KEYS are the scoped delegate accessors. */
+    readonly exportName: string;
+}
+/**
+ * The STATIC side: the lint config whose tenant rules must receive the registry.
+ * Read from the RESOLVED config, so it asserts what the rules actually get.
+ */
+interface TenantRegistryEslintOptions {
+    /** Directory whose ESLint config is resolved. Default `.`. */
+    readonly cwd?: string;
+    /** File, relative to `cwd`, the config is resolved for; match your tenant rules' glob. Default `src/__lint_meta_probe__.ts`. */
+    readonly probe?: string;
+    /**
+     * Rules whose `modelsOption` must equal the scoped models. Default the three
+     * `noctcore-prisma` tenant rules.
+     */
+    readonly modelRules?: readonly string[];
+    /** The option those rules take the model list in. Default `tenantModels`. */
+    readonly modelsOption?: string;
+    /**
+     * The rule whose `handScopedOption` must equal `registry.handScopedModels`, or
+     * `null` to skip. Default `noctcore-prisma/tenant-scoped-tables-require-where`.
+     */
+    readonly handScopedRule?: string | null;
+    /** The option that rule takes the hand-scope map in. Default `handScopedModels`. */
+    readonly handScopedOption?: string;
+    /** Path reported for config-side violations. Default: `cwd`. */
+    readonly configFile?: string;
+}
+/**
+ * Options for {@link createTenantModelRegistryParityRule}.
+ *
+ * Every path is relative to the repo root the harness runs in.
+ */
+interface TenantModelRegistryParityOptions {
+    /** Rule id, for running more than one instance. Default `tenant-model-registry-parity`. */
+    readonly id?: string;
+    /**
+     * The Prisma schema: a `.prisma` file, or a folder whose `.prisma` files
+     * (recursively) are read together. Default `prisma/schema.prisma`.
+     */
+    readonly schemaPath?: string;
+    /**
+     * The columns that make a model tenant-bearing: a model carrying ALL of them
+     * must be scoped or exempt. Default `['tenantId']`.
+     */
+    readonly tenantFields?: readonly string[];
+    /**
+     * The project's registry, injected as data (`TenantRegistry` from
+     * `@noctcore/eslint-plugin-prisma`). `scopedModels` is ignored when
+     * `scopedModelsSource` is set. Default: empty.
+     */
+    readonly registry?: TenantRegistry;
+    /**
+     * Read the scoped models from the runtime source instead of
+     * `registry.scopedModels`: the keys of an object literal
+     * (`export const SCOPED = { invoice: [...], ... }`). Prefer this when the
+     * runtime map is the source of truth, so the check reads it rather than a copy.
+     */
+    readonly scopedModelsSource?: ScopedModelsSource;
+    /**
+     * Require every unscoped-by-design model to name its hand-scope columns
+     * (`registry.handScopedModels`) or record why it cannot
+     * (`registry.handScopePending`). Default `true`.
+     */
+    readonly requireHandScope?: boolean;
+    /** The static side, or `false` to check only the registry against the schema. */
+    readonly eslint?: TenantRegistryEslintOptions | false;
+    /**
+     * Path reported for registry-side violations (the hand-scope maps, and the
+     * schema reconciliation when there is no `scopedModelsSource`). Default:
+     * `scopedModelsSource.file`, else `schemaPath`.
+     */
+    readonly registryFile?: string;
+    /** Whether a violation fails CI. Default `true`. */
+    readonly ciCritical?: boolean;
+}
+/**
+ * Top-level keys of the object literal assigned to `exportName`, or `null` when
+ * the declaration cannot be located (reported, never read as an empty map).
+ *
+ * Reads a comment- and string-blanked copy while tracking bracket depth, so a
+ * nested object or an array holding a `:` is never mistaken for an entry.
+ * Quoted keys (`'invoice': [...]`) are blanked with the strings, so a map must
+ * use identifier keys, as a delegate-accessor map does.
+ */
+declare function parseObjectLiteralKeys(source: string, exportName: string): string[] | null;
+/**
+ * The tenant-model registries must mirror each other AND the Prisma schema.
+ *
+ * A multi-tenant Prisma project keeps "which models are tenant-scoped?" in two
+ * hand-maintained places, the runtime scope map and the model list its tenant
+ * lint rules are configured with, and agreement between those two says nothing
+ * about a table neither has heard of. So the SCHEMA is the third input: every
+ * model carrying the tenant columns must be scoped or explicitly exempt with a
+ * reason, and a new tenant-bearing model cannot ship without the guardrails
+ * learning about it.
+ *
+ * The static side is read from the RESOLVED ESLint config, not by parsing the
+ * config file: moving the array, spreading a different preset, or handing one
+ * rule a hand-written list is all caught. Fails closed on an unreadable schema,
+ * runtime map or config. Needs the optional `eslint` peer unless `eslint: false`.
+ */
+declare function createTenantModelRegistryParityRule(options?: TenantModelRegistryParityOptions): IMetaRule;
+
+export { type DelegateSurface, type PrismaMethodSurfaceOptions, type ScopedModelsSource, type TenantModelRegistryParityOptions, type TenantRegistryEslintOptions, createPrismaMethodSurfaceRule, createTenantModelRegistryParityRule, parseDelegateSurfaces, parseObjectLiteralKeys };