@noctcore/lint-meta-rules 0.5.0 → 0.6.1

package/dist/session.js

@@ -0,0 +1,244 @@
+import {
+  DEFAULT_SKIP_DIRS,
+  escapeRegExp,
+  globFiles,
+  readSourceText
+} from "./chunk-OYFQKSJN.js";
+
+// src/session/scan.ts
+var DEFAULT_EXCLUDE_SUFFIXES = [
+  ".spec.ts",
+  ".spec.tsx",
+  ".test.ts",
+  ".test.tsx"
+];
+function scopedSources(ctx, options) {
+  const skipDirs = options.skipDirs ?? DEFAULT_SKIP_DIRS;
+  const excludeSuffixes = options.excludeSuffixes ?? DEFAULT_EXCLUDE_SUFFIXES;
+  const matched = globFiles(ctx.glob, options.sourceGlobs ?? [], skipDirs).map(toPosix);
+  const sources = [];
+  for (const file of matched) {
+    if (excludeSuffixes.some((suffix) => file.endsWith(suffix))) continue;
+    const text = readSourceText(ctx.read, file);
+    if (text !== null) sources.push({ file, text });
+  }
+  return { matched: new Set(matched), sources };
+}
+function toPosix(file) {
+  return file.replace(/\\/gu, "/").replace(/^\.\//u, "");
+}
+function pathSet(files) {
+  return new Set((files ?? []).map(toPosix));
+}
+function callsMethod(source, method) {
+  return new RegExp(`\\.${escapeRegExp(method)}\\s*\\(`, "u").test(source);
+}
+function callArguments(source, method) {
+  const needle = `.${method}`;
+  const calls = [];
+  let from = 0;
+  for (; ; ) {
+    const hit = source.indexOf(needle, from);
+    if (hit === -1) break;
+    from = hit + needle.length;
+    const open = source.indexOf("(", from);
+    if (open === -1) break;
+    if (source.slice(from, open).trim() !== "") continue;
+    let depth = 0;
+    let end = open;
+    for (; end < source.length; end += 1) {
+      const char = source[end];
+      if (char === "(") depth += 1;
+      else if (char === ")") {
+        depth -= 1;
+        if (depth === 0) break;
+      }
+    }
+    calls.push(source.slice(open + 1, end));
+    from = end;
+  }
+  return calls;
+}
+function mentionsIdentifier(text, identifier) {
+  return new RegExp(`\\b${escapeRegExp(identifier)}\\b`, "u").test(text);
+}
+function withHint(message, hint) {
+  return hint === void 0 || hint === "" ? message : `${message} ${hint}`;
+}
+
+// src/session/session-epoch-captured.ts
+var DEFAULT_ID = "session-epoch-captured";
+var DEFAULT_FIELD = "epoch";
+function createSessionEpochCapturedRule(options = {}) {
+  const id = options.id ?? DEFAULT_ID;
+  const call = options.call ?? "";
+  const field = options.field ?? DEFAULT_FIELD;
+  const exempt = pathSet(options.exempt);
+  return {
+    id,
+    category: "source-text",
+    ciCritical: options.ciCritical ?? true,
+    description: "Every call into the sign-in seam must pass the session epoch captured before the credential was read, or a revocation landing during the credential check loses the race.",
+    run(ctx) {
+      if (call === "") return [];
+      const violations = [];
+      for (const { file, text } of scopedSources(ctx, options).sources) {
+        if (exempt.has(file)) continue;
+        for (const args of callArguments(text, call)) {
+          if (mentionsIdentifier(args, field)) continue;
+          violations.push({
+            file,
+            rule: id,
+            message: withHint(
+              `${call}() must be passed \`${field}\`, captured${options.captureCall === void 0 ? "" : ` with ${options.captureCall}`} BEFORE this flow reads the credential it authenticates on. Without it the epoch fence starts at the session write, so a revocation landing during the credential check loses the race.`,
+              options.hint
+            )
+          });
+        }
+      }
+      return violations;
+    }
+  };
+}
+
+// src/session/session-kind-stamped.ts
+var DEFAULT_ID2 = "session-kind-stamped";
+var DEFAULT_FIELD2 = "kind";
+function createSessionKindStampedRule(options = {}) {
+  const id = options.id ?? DEFAULT_ID2;
+  const mintCall = options.mintCall ?? "";
+  const field = options.field ?? DEFAULT_FIELD2;
+  const allowUnstamped = pathSet(options.allowUnstamped);
+  return {
+    id,
+    category: "source-text",
+    ciCritical: options.ciCritical ?? true,
+    description: "Every call that mints a session must stamp the principal kind onto it, or sit in an allowlisted, provably single-kind flow; a session read without the kind falls back to a default and can silently promote one kind of account into another.",
+    run(ctx) {
+      if (mintCall === "") return [];
+      const violations = [];
+      for (const { file, text } of scopedSources(ctx, options).sources) {
+        if (allowUnstamped.has(file)) continue;
+        const calls = callArguments(text, mintCall);
+        if (calls.length === 0) continue;
+        const fileStamps = mentionsIdentifier(text, field);
+        for (const args of calls) {
+          const stamped = args.includes("{") ? mentionsIdentifier(args, field) : fileStamps;
+          if (stamped) continue;
+          violations.push({
+            file,
+            rule: id,
+            message: withHint(
+              `${mintCall}() must stamp \`${field}\` onto the session it mints${options.stampExample === void 0 ? "" : `: add \`${options.stampExample}\` to the options`}. A session read without \`${field}\` falls back to the reader's default, so an unstamped mint can silently promote one kind of account into another. If this flow provably can never mint for an account that needs the field, add the file to \`allowUnstamped\` with the proof.`,
+              options.hint
+            )
+          });
+        }
+      }
+      return violations;
+    }
+  };
+}
+
+// src/session/session-landing-declared.ts
+var DEFAULT_ID3 = "session-landing-declared";
+function createSessionLandingDeclaredRule(options = {}) {
+  const id = options.id ?? DEFAULT_ID3;
+  const doorCalls = (options.doorCalls ?? []).filter((name) => name !== "");
+  const doors = (options.doors ?? []).map((door) => ({ ...door, file: toPosix(door.file) }));
+  const landings = options.landings ?? {};
+  const landingNames = Object.keys(landings);
+  const callList = doorCalls.join(" or ");
+  return {
+    id,
+    category: "source-text",
+    ciCritical: options.ciCritical ?? true,
+    description: "Every file that opens a door into a session must declare where it leaves the caller, and a door whose landing demands a return shape (the one that carries the principal kind to the client) must have it.",
+    run(ctx) {
+      if (doorCalls.length === 0) return [];
+      const violations = [];
+      const report = (file, message) => {
+        violations.push({ file, rule: id, message: withHint(message, options.hint) });
+      };
+      for (const door of doors) {
+        if (!Object.hasOwn(landings, door.landing)) {
+          report(
+            door.file,
+            `\`doors\` declares this file with landing \`${door.landing}\`, which is not one of the configured landings (${landingNames.join(", ") || "none"}).`
+          );
+        }
+        if (door.because.trim() === "") {
+          report(door.file, "`doors` declares this file with an empty `because`. Write down why its landing is the right one.");
+        }
+      }
+      const { matched, sources } = scopedSources(ctx, options);
+      for (const { file, text } of sources) {
+        if (!doorCalls.some((name) => callsMethod(text, name))) continue;
+        const declared = doors.find((door) => door.file === file);
+        if (declared === void 0) {
+          report(
+            file,
+            `This file opens a door into a session (${callList}) and does not declare where it leaves the caller. Add it to \`doors\` with one of the landings (${landingNames.join(", ") || "none"}) and a \`because\`: can this door end a sign-in for an account the client must route by kind? Then declare the landing that returns the kind. Does the caller already hold a session? Or can such an account provably never reach it? Say so in \`because\`.`
+          );
+          continue;
+        }
+        const required = landings[declared.landing];
+        if (typeof required === "string" && required !== "" && !text.includes(required)) {
+          report(
+            file,
+            `This door is declared \`${declared.landing}\` but its source never contains \`${required}\`, so the sign-in it completes hands the client nothing to route the account by. Return it, or reclassify the door in \`doors\` with the proof that it cannot end such a sign-in.`
+          );
+        }
+      }
+      for (const door of doors) {
+        if (!matched.has(door.file)) {
+          report(
+            door.file,
+            "`doors` names a file that no longer exists, or that `sourceGlobs` do not reach. Remove the entry, or point it at the file the door moved to."
+          );
+        }
+      }
+      return violations;
+    }
+  };
+}
+
+// src/session/session-mint-callers.ts
+var DEFAULT_ID4 = "session-mint-callers";
+function createSessionMintCallersRule(options = {}) {
+  const id = options.id ?? DEFAULT_ID4;
+  const mintCall = options.mintCall ?? "";
+  const allowed = pathSet(options.allowedCallers);
+  const gate = options.gateCall;
+  return {
+    id,
+    category: "source-text",
+    ciCritical: options.ciCritical ?? true,
+    description: "The method that mints a session may only be called from allowlisted files; a new sign-in entry point must route through the gate in front of it so the gate cannot be bypassed.",
+    run(ctx) {
+      if (mintCall === "") return [];
+      const violations = [];
+      const allowedList = [...allowed].join(", ") || "none";
+      for (const { file, text } of scopedSources(ctx, options).sources) {
+        if (allowed.has(file)) continue;
+        if (!callsMethod(text, mintCall)) continue;
+        violations.push({
+          file,
+          rule: id,
+          message: withHint(
+            `${mintCall}() may only be called from the allowlisted files (${allowedList}).${gate === void 0 ? "" : ` A sign-in or OAuth entry point must call ${gate}() instead, so the checks it runs before minting are not bypassed.`} If this is a genuine mint that passes no gate (a signup, or a re-issue to a caller who already holds a session), add the file to \`allowedCallers\` with a justification.`,
+            options.hint
+          )
+        });
+      }
+      return violations;
+    }
+  };
+}
+export {
+  callArguments,
+  createSessionEpochCapturedRule,
+  createSessionKindStampedRule,
+  createSessionLandingDeclaredRule,
+  createSessionMintCallersRule
+};

package/dist/trpc.cjs

@@ -0,0 +1,122 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/trpc.ts
+var trpc_exports = {};
+__export(trpc_exports, {
+  createIdempotencyKeyParityRule: () => createIdempotencyKeyParityRule
+});
+module.exports = __toCommonJS(trpc_exports);
+
+// src/rules/shared.ts
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+var DEFAULT_SKIP_DIRS = [
+  "node_modules",
+  ".git",
+  "dist",
+  ".turbo",
+  "coverage"
+];
+function globFiles(glob, globs, skipDirs = []) {
+  const skip = new Set(skipDirs);
+  const found = /* @__PURE__ */ new Set();
+  for (const pattern of globs) {
+    for (const rel of glob(pattern)) {
+      if (!rel.split("/").some((segment) => skip.has(segment))) found.add(rel);
+    }
+  }
+  return [...found].sort();
+}
+function readSourceText(read, rel) {
+  try {
+    return read(rel);
+  } catch {
+    return null;
+  }
+}
+
+// src/trpc/idempotency-key-parity.ts
+var DEFAULT_ID = "idempotency-key-parity";
+function routerAlias(source, names) {
+  return names.alias.exec(source)?.[2] ?? null;
+}
+function guardedMethods(source, names) {
+  const methods = [];
+  const decorator = new RegExp(names.decorator.source, "gu");
+  let match;
+  while ((match = decorator.exec(source)) !== null) {
+    if (!names.middleware.test(match[1] ?? "")) continue;
+    const rest = source.slice(match.index + match[0].length);
+    const method = /\basync\s+([A-Za-z_$][\w$]*)\s*\(/u.exec(rest)?.[1];
+    if (method !== void 0) methods.push(method);
+  }
+  return methods;
+}
+function createIdempotencyKeyParityRule(options = {}) {
+  const id = options.id ?? DEFAULT_ID;
+  const middleware = options.middleware ?? "";
+  const keyToken = options.keyToken ?? "idempotencyKey";
+  const clientPrefix = options.clientPrefix ?? "trpc.";
+  const skipDirs = options.skipDirs ?? DEFAULT_SKIP_DIRS;
+  const exempt = new Set(options.exempt ?? []);
+  const names = {
+    alias: new RegExp(
+      `@${escapeRegExp(options.routerDecorator ?? "Router")}\\(\\{[^}]*\\b${escapeRegExp(options.aliasKey ?? "alias")}:\\s*(['"])([^'"]+)\\1`,
+      "u"
+    ),
+    decorator: new RegExp(`@${escapeRegExp(options.middlewareDecorator ?? "UseMiddlewares")}\\(([^)]*)\\)`, "u"),
+    middleware: new RegExp(`\\b${escapeRegExp(middleware)}\\b`, "u")
+  };
+  return {
+    id,
+    category: "source-text",
+    ciCritical: options.ciCritical ?? true,
+    description: "Procedures carrying the idempotency middleware must have a client caller that sends an idempotency key, or no client caller at all.",
+    run(ctx) {
+      if (middleware === "") return [];
+      const clientSources = globFiles(ctx.glob, options.clientGlobs ?? [], skipDirs).map((file) => readSourceText(ctx.read, file)).filter((text) => text !== null);
+      const violations = [];
+      for (const file of globFiles(ctx.glob, options.routerGlobs ?? [], skipDirs)) {
+        const source = readSourceText(ctx.read, file);
+        if (source === null || !names.middleware.test(source)) continue;
+        const alias = routerAlias(source, names);
+        if (alias === null) continue;
+        for (const method of guardedMethods(source, names)) {
+          const path = `${alias}.${method}`;
+          if (exempt.has(path)) continue;
+          const callers = clientSources.filter((text) => text.includes(`${clientPrefix}${path}`));
+          if (callers.length === 0) continue;
+          if (callers.some((text) => text.includes(keyToken))) continue;
+          violations.push({
+            file,
+            rule: id,
+            message: `\`${path}\` carries ${middleware} but its client callers never send \`${keyToken}\`, so the guard is inert. Send the key from the caller, or drop the middleware and say why.${options.hint === void 0 || options.hint === "" ? "" : ` ${options.hint}`}`
+          });
+        }
+      }
+      return violations;
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createIdempotencyKeyParityRule
+});

package/dist/trpc.d.cts

@@ -0,0 +1,59 @@
+import { IMetaRule } from '@noctcore/harness';
+
+/**
+ * Options for {@link createIdempotencyKeyParityRule}.
+ *
+ * Ported from Settly, which hardcoded the middleware (`IdempotencyMiddleware`),
+ * the key (`idempotencyKey`) and the two trees (`apps/api/src` routers,
+ * `apps/web/src` callers). Those are options; the decorator shape defaults to
+ * `nestjs-trpc`'s (`@Router({ alias })`, `@UseMiddlewares(...)`) and the client
+ * shape to a `trpc.<alias>.<method>` proxy. With no `middleware` the rule is inert.
+ */
+interface IdempotencyKeyParityOptions {
+    /** Rule id, for running more than one instance. Default `idempotency-key-parity`. */
+    readonly id?: string;
+    /** The middleware class that de-duplicates on a client-sent key. Unset or empty = inert. */
+    readonly middleware?: string;
+    /** Globs of the server router files. Default: none (inert). */
+    readonly routerGlobs?: readonly string[];
+    /** Globs of every client file that can call a procedure or send a key. Default: none. */
+    readonly clientGlobs?: readonly string[];
+    /** The token a client file must mention to count as sending a key. Default `idempotencyKey`. */
+    readonly keyToken?: string;
+    /** What precedes `<alias>.<method>` at a client call site. Default `trpc.`. */
+    readonly clientPrefix?: string;
+    /** The class decorator that names the router. Default `Router`. */
+    readonly routerDecorator?: string;
+    /** The key in that decorator's object argument holding the router's alias. Default `alias`. */
+    readonly aliasKey?: string;
+    /** The method decorator listing a procedure's middlewares. Default `UseMiddlewares`. */
+    readonly middlewareDecorator?: string;
+    /**
+     * `<alias>.<method>` procedures whose caller deliberately sends no key. Keep
+     * it empty: the honest fix for "a key will never be sent here" is to drop the
+     * middleware. Default: none.
+     */
+    readonly exempt?: readonly string[];
+    /** Paths with any of these segments are skipped. Default `node_modules`, `.git`, `dist`, `.turbo`, `coverage`. */
+    readonly skipDirs?: readonly string[];
+    /** Appended to every message: how this project threads the key. */
+    readonly hint?: string;
+    /** Whether a violation fails CI. Default `true`. */
+    readonly ciCritical?: boolean;
+}
+/**
+ * Every idempotency-guarded procedure has a client caller that sends a key, or
+ * no client caller at all.
+ *
+ * The middleware only de-duplicates when the client sends a key, and neither
+ * half fails when the other is missing: the server passes the request through,
+ * the client gets a normal response, and both test suites pass. A guard nobody
+ * sends a key to is decoration advertising double-submit protection that does
+ * not exist. The rule holds the two lists side by side. A procedure with no
+ * client caller passes: the guard is correct in advance of the screen that will
+ * use it. The reverse (a key sent to an unguarded procedure) is inert and needs
+ * no rule.
+ */
+declare function createIdempotencyKeyParityRule(options?: IdempotencyKeyParityOptions): IMetaRule;
+
+export { type IdempotencyKeyParityOptions, createIdempotencyKeyParityRule };

package/dist/trpc.d.ts

@@ -0,0 +1,59 @@
+import { IMetaRule } from '@noctcore/harness';
+
+/**
+ * Options for {@link createIdempotencyKeyParityRule}.
+ *
+ * Ported from Settly, which hardcoded the middleware (`IdempotencyMiddleware`),
+ * the key (`idempotencyKey`) and the two trees (`apps/api/src` routers,
+ * `apps/web/src` callers). Those are options; the decorator shape defaults to
+ * `nestjs-trpc`'s (`@Router({ alias })`, `@UseMiddlewares(...)`) and the client
+ * shape to a `trpc.<alias>.<method>` proxy. With no `middleware` the rule is inert.
+ */
+interface IdempotencyKeyParityOptions {
+    /** Rule id, for running more than one instance. Default `idempotency-key-parity`. */
+    readonly id?: string;
+    /** The middleware class that de-duplicates on a client-sent key. Unset or empty = inert. */
+    readonly middleware?: string;
+    /** Globs of the server router files. Default: none (inert). */
+    readonly routerGlobs?: readonly string[];
+    /** Globs of every client file that can call a procedure or send a key. Default: none. */
+    readonly clientGlobs?: readonly string[];
+    /** The token a client file must mention to count as sending a key. Default `idempotencyKey`. */
+    readonly keyToken?: string;
+    /** What precedes `<alias>.<method>` at a client call site. Default `trpc.`. */
+    readonly clientPrefix?: string;
+    /** The class decorator that names the router. Default `Router`. */
+    readonly routerDecorator?: string;
+    /** The key in that decorator's object argument holding the router's alias. Default `alias`. */
+    readonly aliasKey?: string;
+    /** The method decorator listing a procedure's middlewares. Default `UseMiddlewares`. */
+    readonly middlewareDecorator?: string;
+    /**
+     * `<alias>.<method>` procedures whose caller deliberately sends no key. Keep
+     * it empty: the honest fix for "a key will never be sent here" is to drop the
+     * middleware. Default: none.
+     */
+    readonly exempt?: readonly string[];
+    /** Paths with any of these segments are skipped. Default `node_modules`, `.git`, `dist`, `.turbo`, `coverage`. */
+    readonly skipDirs?: readonly string[];
+    /** Appended to every message: how this project threads the key. */
+    readonly hint?: string;
+    /** Whether a violation fails CI. Default `true`. */
+    readonly ciCritical?: boolean;
+}
+/**
+ * Every idempotency-guarded procedure has a client caller that sends a key, or
+ * no client caller at all.
+ *
+ * The middleware only de-duplicates when the client sends a key, and neither
+ * half fails when the other is missing: the server passes the request through,
+ * the client gets a normal response, and both test suites pass. A guard nobody
+ * sends a key to is decoration advertising double-submit protection that does
+ * not exist. The rule holds the two lists side by side. A procedure with no
+ * client caller passes: the guard is correct in advance of the screen that will
+ * use it. The reverse (a key sent to an unguarded procedure) is inert and needs
+ * no rule.
+ */
+declare function createIdempotencyKeyParityRule(options?: IdempotencyKeyParityOptions): IMetaRule;
+
+export { type IdempotencyKeyParityOptions, createIdempotencyKeyParityRule };

package/dist/trpc.js

@@ -0,0 +1,73 @@
+import {
+  DEFAULT_SKIP_DIRS,
+  escapeRegExp,
+  globFiles,
+  readSourceText
+} from "./chunk-OYFQKSJN.js";
+
+// src/trpc/idempotency-key-parity.ts
+var DEFAULT_ID = "idempotency-key-parity";
+function routerAlias(source, names) {
+  return names.alias.exec(source)?.[2] ?? null;
+}
+function guardedMethods(source, names) {
+  const methods = [];
+  const decorator = new RegExp(names.decorator.source, "gu");
+  let match;
+  while ((match = decorator.exec(source)) !== null) {
+    if (!names.middleware.test(match[1] ?? "")) continue;
+    const rest = source.slice(match.index + match[0].length);
+    const method = /\basync\s+([A-Za-z_$][\w$]*)\s*\(/u.exec(rest)?.[1];
+    if (method !== void 0) methods.push(method);
+  }
+  return methods;
+}
+function createIdempotencyKeyParityRule(options = {}) {
+  const id = options.id ?? DEFAULT_ID;
+  const middleware = options.middleware ?? "";
+  const keyToken = options.keyToken ?? "idempotencyKey";
+  const clientPrefix = options.clientPrefix ?? "trpc.";
+  const skipDirs = options.skipDirs ?? DEFAULT_SKIP_DIRS;
+  const exempt = new Set(options.exempt ?? []);
+  const names = {
+    alias: new RegExp(
+      `@${escapeRegExp(options.routerDecorator ?? "Router")}\\(\\{[^}]*\\b${escapeRegExp(options.aliasKey ?? "alias")}:\\s*(['"])([^'"]+)\\1`,
+      "u"
+    ),
+    decorator: new RegExp(`@${escapeRegExp(options.middlewareDecorator ?? "UseMiddlewares")}\\(([^)]*)\\)`, "u"),
+    middleware: new RegExp(`\\b${escapeRegExp(middleware)}\\b`, "u")
+  };
+  return {
+    id,
+    category: "source-text",
+    ciCritical: options.ciCritical ?? true,
+    description: "Procedures carrying the idempotency middleware must have a client caller that sends an idempotency key, or no client caller at all.",
+    run(ctx) {
+      if (middleware === "") return [];
+      const clientSources = globFiles(ctx.glob, options.clientGlobs ?? [], skipDirs).map((file) => readSourceText(ctx.read, file)).filter((text) => text !== null);
+      const violations = [];
+      for (const file of globFiles(ctx.glob, options.routerGlobs ?? [], skipDirs)) {
+        const source = readSourceText(ctx.read, file);
+        if (source === null || !names.middleware.test(source)) continue;
+        const alias = routerAlias(source, names);
+        if (alias === null) continue;
+        for (const method of guardedMethods(source, names)) {
+          const path = `${alias}.${method}`;
+          if (exempt.has(path)) continue;
+          const callers = clientSources.filter((text) => text.includes(`${clientPrefix}${path}`));
+          if (callers.length === 0) continue;
+          if (callers.some((text) => text.includes(keyToken))) continue;
+          violations.push({
+            file,
+            rule: id,
+            message: `\`${path}\` carries ${middleware} but its client callers never send \`${keyToken}\`, so the guard is inert. Send the key from the caller, or drop the middleware and say why.${options.hint === void 0 || options.hint === "" ? "" : ` ${options.hint}`}`
+          });
+        }
+      }
+      return violations;
+    }
+  };
+}
+export {
+  createIdempotencyKeyParityRule
+};

package/docs/rules/agents-doc-presence.md

@@ -2,6 +2,10 @@
 
 > An agent-contract doc must exist at the repo root, every surface, and every non-opted-out package.
 
+<!-- begin generated rule header -->
+Runs under `@noctcore/harness`, not ESLint · Factory `createAgentsDocPresenceRule` from `@noctcore/lint-meta-rules` · Category `source-text` · Fails CI by default: yes
+<!-- end generated rule header -->
+
 ## Why
 
 An agent editing a boundary should read its guardrails first. Requiring an `AGENTS.md` (or whatever
@@ -17,7 +21,15 @@ Reports a missing doc at:
 - every directory derived from `surfaceGlobs` (all surfaces), and
 - every directory derived from `packageGlobs`, except those in `optOut`.
 
-## Factory
+## What it does not flag
+
+- A package directory listed in `optOut`.
+- The repo root when `requireAtRoot` is `false`.
+- Directories that no `surfaceGlobs` or `packageGlobs` entry matches (the defaults look one level deep
+  under `apps/` and `packages/`).
+- The doc's content: an empty or stale file passes, since only its presence is checked.
+
+## Options
 
 ```ts
 createAgentsDocPresenceRule(options?: AgentsDocPresenceOptions): IMetaRule
@@ -32,9 +44,6 @@ createAgentsDocPresenceRule(options?: AgentsDocPresenceOptions): IMetaRule
 | `optOut` | `string[]` | `[]` | Package directories exempt from the requirement. |
 | `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
 
-De-projected from nightcore, which hardcoded `AGENTS.md`, the root/apps/packages layout and a fixed
-leaf opt-out set.
-
 ## When not to use it
 
 If your repo does not adopt an agent-contract doc convention, skip it.

package/docs/rules/canonical-helpers-single-home.md

@@ -2,6 +2,10 @@
 
 > A helper symbol must not be exported from two different helper homes.
 
+<!-- begin generated rule header -->
+Runs under `@noctcore/harness`, not ESLint · Factory `createCanonicalHelpersSingleHomeRule` from `@noctcore/lint-meta-rules` · Category `source-text` · Fails CI by default: yes
+<!-- end generated rule header -->
+
 ## Why
 
 When the same helper name is exported from multiple files, callers import inconsistent copies and the
@@ -15,7 +19,15 @@ extracts top-level exported identifiers (from `export function|const|let|var …
 lists — keyed on the **local** name before any `as`), and flags any name that appears as an export in
 more than one file. Strict, no baseline.
 
-## Factory
+## What it does not flag
+
+- A name exported from only one helper home, however many files import it.
+- An `export { x as y }` alias under a new public name: the check keys on the local name `x`.
+- Files outside `include`, and any path containing an `excludeContains` fragment (`/lib/` by default).
+- `export default`, `export class`, `export type` and `export interface` declarations: only
+  `function`, `const`, `let`, `var` declarations and `export { … }` lists are read.
+
+## Options
 
 ```ts
 createCanonicalHelpersSingleHomeRule(options?: CanonicalHelpersSingleHomeOptions): IMetaRule
@@ -27,8 +39,6 @@ createCanonicalHelpersSingleHomeRule(options?: CanonicalHelpersSingleHomeOptions
 | `excludeContains` | `string[]` | `['/lib/']` | Drop any matched path containing one of these fragments. |
 | `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
 
-De-projected from nightcore, which hardcoded `apps/web/src/**/*.utils.ts` and a `/lib/` exclusion.
-
 ## When not to use it
 
 If your project intentionally re-exports the same symbol from several modules (barrels, façades), scope

package/docs/rules/dockerfile-base-image-digest-pin.md

@@ -2,6 +2,10 @@
 
 > Dockerfile `FROM` base images are pinned by `@sha256:` digest.
 
+<!-- begin generated rule header -->
+Runs under `@noctcore/harness`, not ESLint · Factory `createDockerfileBaseImageDigestPinRule` from `@noctcore/lint-meta-rules` · Category `ci` · Fails CI by default: yes
+<!-- end generated rule header -->
+
 ## Why
 
 `FROM node:22-slim` names whatever the registry serves at build time, so two builds of one commit can
@@ -25,7 +29,16 @@ FROM deps AS build
 FROM scratch
 ```
 
-## Factory
+## What it does not flag
+
+- `FROM scratch` and `FROM <earlier stage>` (a name given by a previous `AS`).
+- `FROM ${BASE}` whose `ARG BASE=<default>` before the first `FROM` is digest-pinned.
+- Dockerfiles under any `skipDirs` segment (`node_modules`, `.git`, `dist`, `.turbo`, `coverage`) and
+  files the `dockerfileGlobs` do not match.
+- A `FROM` split with a line continuation (`\`): it is not read. Add a `Containerfile` glob if you use
+  Podman naming.
+
+## Options
 
 ```ts
 createDockerfileBaseImageDigestPinRule(options?: DockerfileBaseImageDigestPinOptions): IMetaRule
@@ -37,7 +50,7 @@ createDockerfileBaseImageDigestPinRule(options?: DockerfileBaseImageDigestPinOpt
 | `skipDirs` | `string[]` | `['node_modules', '.git', 'dist', '.turbo', 'coverage']` | A path with any of these segments is skipped. |
 | `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
 
-## Limits
+## When not to use it
 
-A `FROM` split with a line continuation (`\`) is not read. Add a `Containerfile` glob if you use
-Podman naming.
+If your images are built only for local development and you accept whatever a tag serves at build
+time, skip it.