@veda-hq/eslint-plugin-shuddhi 0.2.0 → 0.6.4

package/README.md

@@ -50,7 +50,7 @@ of globs, with a `namespace` parameter:
 | input parsing | `no-hand-rolled-argv`, `env-through-schema`, `strict-scalar-parse`, `schema-parse-untrusted`, `schema-satisfies-contract`, `prisma-json-through-schema`, `no-regex-structured-parse` | `inputParsingConfigs` |
 | server boundary | `nest-body-dto`, `dto-field-constraints`, `no-local-api-contract`, `dto-implements-contract`, `no-capability-literal`, `compare-and-set` | `boundaryBlocks` |
 | NestJS and Prisma | `no-raw-sql-interpolation`, `nest-http-exception`, `prisma-transaction-multiwrite`, `nest-param-pipe`, `no-unbound-test-app`, `require-orderby-findfirst`, `no-self-mock-sut` | none |
-| test lint | 41 rules on test structure, vacuous assertions, process hygiene, fixtures and fakes | `testLintBlocks` |
+| test lint | 43 rules on test structure, vacuous assertions (among them `jsonnull-in-matcher`: a Prisma null sentinel inside `toMatchObject` or `objectContaining`), process hygiene, fixtures and fakes; and for scripts, `no-import-meta-dirname-cjs` (`import.meta.dirname` in a file tsx runs as CommonJS) | `testLintBlocks` |
 
 Every name of a repository's own helper (the safe-logging module, the child
 process runner, the argument parser, the contracts package) is a rule option,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veda-hq/eslint-plugin-shuddhi",
-  "version": "0.2.0",
+  "version": "0.6.4",
   "description": "ESLint rules for code coding agents write: error handling, input parsing, NestJS and Prisma boundaries, and test quality. Each rule closes a defect class reviewers kept finding after push.",
   "keywords": [
     "eslint",

package/src/test-lint/configs.js

@@ -59,6 +59,7 @@ export const TEST_FILE_RULES = {
   [id('no-partial-git-mask')]: 'error',
   [id('env-via-stub')]: 'error',
   [id('detached-teardown')]: 'error',
+  [id('jsonnull-in-matcher')]: 'error',
 };
 
 /** Rules for Nest server tests only. */
@@ -67,10 +68,14 @@ export const SERVER_TEST_RULES = {
   [id('e2e-uses-supertest')]: 'error',
 };
 
-/** Rules for tooling scripts (SHELL-09). */
+/**
+ * Rules for tooling scripts (SHELL-09): the non-test sources `testLintBlocks`
+ * binds to its `scripts` globs.
+ */
 export const SCRIPT_RULES = {
   [id('no-process-exit')]: 'error',
   [id('cli-entry-helper')]: 'error',
+  [id('no-import-meta-dirname-cjs')]: 'error',
 };
 
 /** Rules for Detox end-to-end suites (TEST-WEAK-01). */

package/src/test-lint/import-meta-cjs.js

@@ -0,0 +1,195 @@
+/**
+ * SHELL-09, the module format a script runs in: `import.meta.dirname` and
+ * `import.meta.filename` in a file that runs as CommonJS
+ * (`no-import-meta-dirname-cjs`). `import-meta-cjs.test.ts` owns it.
+ *
+ * WHY. tsx runs a `.ts`, `.tsx` or `.js` file as CommonJS when its nearest
+ * package.json has no `"type": "module"` (or there is none). Its CJS
+ * transform defines `import.meta.url` (except in `.cts` and `.cjs` files)
+ * and nothing else, so `import.meta.dirname` is undefined and
+ * `resolve(import.meta.dirname, ...)` throws when the script loads. Vitest
+ * runs the same file as ESM, where both exist, so the script's tests pass.
+ * Measured on tsx 4.21.
+ *
+ * SCOPE. `.mts` and `.mjs` files always run as ESM and are never reported;
+ * `.cts` and `.cjs` files always run as CommonJS and are reported whatever
+ * the package says. Test files (`*.test.*`, `*.spec.*`) are skipped: Vitest
+ * runs them as ESM. A package.json that cannot be read or parsed leaves the
+ * format unknown, and nothing is reported.
+ *
+ * ACCEPTED LIMIT. A `.js` file is reported as tsx runs it. Plain Node (not
+ * tsx) may run a `.js` file in a package with no `type` field as ESM, from
+ * its `import.meta` syntax (module syntax detection); that is not measured
+ * here, and such a file may be a false positive.
+ */
+import { readFileSync } from 'node:fs';
+import { basename, dirname, extname, join, resolve } from 'node:path';
+
+import { propertyName, WRAPPERS } from './helpers.js';
+
+/** Extensions whose format the nearest package.json decides. */
+const BY_PACKAGE = new Set(['.ts', '.tsx', '.js']);
+
+/** Extensions that always run as CommonJS. */
+const ALWAYS_CJS = new Set(['.cts', '.cjs']);
+
+/** Vitest runs these as ESM. */
+const TEST_FILE = /\.(?:test|spec)\./;
+
+/** The `import.meta` properties tsx leaves undefined under CommonJS. */
+const REPLACEMENTS = {
+  cjsPackage: {
+    dirname: 'dirname(fileURLToPath(import.meta.url))',
+    filename: 'fileURLToPath(import.meta.url)',
+  },
+  cjsFile: { dirname: '__dirname', filename: '__filename' },
+};
+
+/**
+ * A package.json's text, null when there is none at `path`, or undefined
+ * when it exists but cannot be read.
+ *
+ * @param {string} path
+ */
+function readPackageJson(path) {
+  try {
+    return readFileSync(path, 'utf8');
+  } catch (error) {
+    // fail-open: a missing file means no package.json here, any other read failure an unknown format; the rule then reports nothing.
+    return error.code === 'ENOENT' ? null : undefined;
+  }
+}
+
+/**
+ * A lookup of the module format a directory's files run in: `'module'`,
+ * `'commonjs'` (no package.json up to the root, or a nearest one with no
+ * `"type": "module"`) or `'unknown'` (the nearest one cannot be read or
+ * parsed). Each directory is looked up once: every directory a walk passes
+ * is cached with its answer.
+ *
+ * @param {(path: string) => string | null | undefined} [read]
+ */
+function packageTypeLookup(read = readPackageJson) {
+  const cache = new Map();
+  return function packageTypeOf(start) {
+    const passed = [];
+    let type = 'commonjs';
+    for (let dir = start; ; dir = dirname(dir)) {
+      if (cache.has(dir)) {
+        type = cache.get(dir);
+        break;
+      }
+      passed.push(dir);
+      const text = read(join(dir, 'package.json'));
+      if (text !== null) {
+        type = formatOf(text);
+        break;
+      }
+      if (dirname(dir) === dir) break;
+    }
+    for (const dir of passed) cache.set(dir, type);
+    return type;
+  };
+}
+
+/** The format a package.json's text sets, or `'unknown'` when unreadable. */
+function formatOf(text) {
+  if (text === undefined) return 'unknown';
+  try {
+    return JSON.parse(text)?.type === 'module' ? 'module' : 'commonjs';
+  } catch {
+    // fail-open: a package.json that does not parse leaves the format unknown, and the rule reports nothing.
+    return 'unknown';
+  }
+}
+
+/** The lookup the rule uses: one per lint process. */
+const packageTypeOf = packageTypeLookup();
+
+const noImportMetaDirnameCjs = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'import.meta.dirname and import.meta.filename in a file that tsx runs as CommonJS, where they are undefined (SHELL-09)',
+    },
+    schema: [],
+    messages: {
+      cjsPackage:
+        'import.meta.{{property}} is undefined when this file runs as CommonJS (its nearest package.json, if any, has no "type": "module"; tsx runs it as CJS and defines only import.meta.url there). Use {{replacement}}.',
+      cjsFile:
+        'import.meta.{{property}} is undefined in a {{extension}} file, which always runs as CommonJS (tsx defines not even import.meta.url there). Use {{replacement}}.',
+    },
+  },
+  create(context) {
+    const given = context.physicalFilename ?? context.filename;
+    // `<input>` and `<text>`: ESLint's names for code with no file.
+    if (/^<.*>$/.test(given)) return {};
+    const filename = resolve(context.cwd, given);
+    const name = basename(filename);
+    if (TEST_FILE.test(name)) return {};
+    const extension = extname(name);
+    if (!ALWAYS_CJS.has(extension) && !BY_PACKAGE.has(extension)) return {};
+    /** The message for this file, decided on the first hit. */
+    let messageId;
+    const messageFor = () => {
+      if (messageId === undefined) {
+        messageId = ALWAYS_CJS.has(extension)
+          ? 'cjsFile'
+          : packageTypeOf(dirname(filename)) === 'commonjs'
+            ? 'cjsPackage'
+            : null;
+      }
+      return messageId;
+    };
+    const report = (node, property) => {
+      if (property !== 'dirname' && property !== 'filename') return;
+      const id = messageFor();
+      if (id === null) return;
+      context.report({
+        node,
+        messageId: id,
+        data: {
+          property,
+          extension,
+          replacement: REPLACEMENTS[id][property],
+        },
+      });
+    };
+    return {
+      MetaProperty(node) {
+        if (node.meta.name !== 'import' || node.property.name !== 'meta') {
+          return;
+        }
+        // Through type-only wrappers: `(import.meta as Meta).dirname`.
+        let inner = node;
+        while (
+          WRAPPERS.has(inner.parent.type) &&
+          inner.parent.expression === inner
+        ) {
+          inner = inner.parent;
+        }
+        const parent = inner.parent;
+        if (parent.type === 'MemberExpression' && parent.object === inner) {
+          report(parent, propertyName(parent));
+          return;
+        }
+        // `const { dirname } = import.meta`
+        if (
+          parent.type === 'VariableDeclarator' &&
+          parent.init === inner &&
+          parent.id.type === 'ObjectPattern'
+        ) {
+          for (const property of parent.id.properties) {
+            if (property.type === 'Property' && !property.computed) {
+              const { key } = property;
+              report(property, key.type === 'Identifier' ? key.name : key.value);
+            }
+          }
+        }
+      },
+    };
+  },
+};
+
+export { noImportMetaDirnameCjs, packageTypeLookup };

package/src/test-lint/index.js

@@ -13,8 +13,11 @@
  * a module here, owned by the colocated suite of the same name:
  * `vacuous-assertion` (TEST-WEAK-03), `test-structure` (TEST-STRUCT-02),
  * `process-hygiene` (SHELL-09 and TEST-STRUCT-11), `sql-fake` (TEST-WEAK-10)
- * and `detox` (TEST-WEAK-01). `helpers.js` holds only what two or more
- * families read; a family imports nothing from another.
+ * and `detox` (TEST-WEAK-01), with two single-rule modules:
+ * `jsonnull-in-matcher` (a TEST-WEAK-03 shape: a Prisma null sentinel inside
+ * a partial matcher) and `import-meta-cjs` (a SHELL-09 script rule:
+ * `import.meta.dirname` in a file tsx runs as CommonJS). `helpers.js` holds
+ * only what two or more families read; a family imports nothing from another.
  *
  * `c05.js` adds three to the same test-file block: a test that returns before
  * its assertions with none on the return path, a recursive removal of a path
@@ -63,6 +66,8 @@ import {
   variableOf,
   WRAPPERS,
 } from './helpers.js';
+import { noImportMetaDirnameCjs } from './import-meta-cjs.js';
+import { jsonnullInMatcher } from './jsonnull-in-matcher.js';
 import {
   cliEntryHelper,
   detachedTeardown,
@@ -199,6 +204,8 @@ export const rules = {
   'spawn-timeout': spawnTimeout,
   'no-raw-group-kill': noRawGroupKill,
   'detached-teardown': detachedTeardown,
+  'jsonnull-in-matcher': jsonnullInMatcher,
+  'no-import-meta-dirname-cjs': noImportMetaDirnameCjs,
 };
 
 /** The c05 candidate extensions (`c05-candidates.js`), in catalogue order. */

package/src/test-lint/jsonnull-in-matcher.js

@@ -0,0 +1,150 @@
+/**
+ * TEST-WEAK-03, one more vacuous shape: a Prisma null sentinel inside a
+ * partial matcher (`jsonnull-in-matcher`). `jsonnull-in-matcher.test.ts`
+ * owns it.
+ *
+ * WHY. `Prisma.JsonNull`, `Prisma.DbNull` and `Prisma.AnyNull` are class
+ * instances with no own enumerable keys. A partial matcher compares an
+ * expected object by its keys, so the sentinel has nothing to compare:
+ * inside `toMatchObject` it matches any stored value (5, null, an object,
+ * the other sentinel), and inside `expect.objectContaining` any value that
+ * is an object with no keys (`Prisma.DbNull`, `Prisma.JsonNull`, `{}`), so it
+ * cannot tell JSON null from database NULL. Measured on Vitest 4.1 with the
+ * Prisma runtime's own sentinel instances. `toBe` and `toStrictEqual`
+ * compare the instance itself.
+ *
+ * SCOPE. The sentinel is reported where it is the matcher's argument or is
+ * reached from it through object property values, array elements, spreads,
+ * type-only wrappers and `const` bindings (three deep). A nested call (an
+ * inner `expect.objectContaining`) is a matcher of its own and is checked
+ * when that call is visited.
+ */
+import {
+  calledMethod,
+  constInit,
+  propertyName,
+  unwrap,
+  variableOf,
+} from './helpers.js';
+
+/** The sentinels with no enumerable keys. */
+const PRISMA_NULLS = new Set(['JsonNull', 'DbNull', 'AnyNull']);
+
+/** How deep a `const` binding is followed from a matcher argument. */
+const BINDING_DEPTH = 3;
+
+/**
+ * The sentinel's name when `node` is one: `Prisma.JsonNull`, a named import
+ * of it from `@prisma/client` (or a subpath), or a `const { JsonNull } =
+ * Prisma` binding; otherwise null.
+ */
+function prismaNullName(node, context) {
+  if (node.type === 'MemberExpression') {
+    const name = propertyName(node);
+    const object = unwrap(node.object);
+    return object.type === 'Identifier' &&
+      object.name === 'Prisma' &&
+      PRISMA_NULLS.has(name)
+      ? name
+      : null;
+  }
+  if (node.type !== 'Identifier') return null;
+  const variable = variableOf(node, context);
+  if (!variable || variable.defs.length !== 1) return null;
+  const [def] = variable.defs;
+  if (def.type === 'ImportBinding') {
+    const imported =
+      def.node.type === 'ImportSpecifier' ? def.node.imported : null;
+    const name = imported?.name ?? imported?.value;
+    return /^@prisma\/client(\/|$)/.test(def.parent.source.value) &&
+      PRISMA_NULLS.has(name)
+      ? name
+      : null;
+  }
+  // `const { JsonNull } = Prisma`, or renamed: `const { DbNull: dbNull } = Prisma`.
+  const init = def.type === 'Variable' ? unwrap(def.node.init) : null;
+  if (
+    init?.type !== 'Identifier' ||
+    init.name !== 'Prisma' ||
+    def.node.id.type !== 'ObjectPattern'
+  ) {
+    return null;
+  }
+  const property = def.node.id.properties.find(
+    entry => entry.type === 'Property' && unwrap(entry.value) === def.name,
+  );
+  const key = property && !property.computed ? property.key.name : null;
+  return PRISMA_NULLS.has(key) ? key : null;
+}
+
+/** The partial matcher a call is, or null: `toMatchObject` or `objectContaining`. */
+function partialMatcher(call) {
+  const method = calledMethod(call);
+  if (method === 'toMatchObject' || method === 'objectContaining') return method;
+  return null;
+}
+
+const jsonnullInMatcher = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'A Prisma null sentinel inside toMatchObject or objectContaining, where it has no keys to compare (TEST-WEAK-03)',
+    },
+    schema: [],
+    messages: {
+      toMatchObject:
+        'Prisma.{{name}} matches any value inside toMatchObject (it has no enumerable keys). Assert the field on its own: expect(data.col).toBe(Prisma.{{name}}) for a value given to Prisma, expect(row.col).toBeNull() for a row read back.',
+      objectContaining:
+        'Prisma.{{name}} matches any object without keys inside objectContaining (it has no enumerable keys), so Prisma.DbNull, Prisma.JsonNull and {} all pass. Assert the field on its own: expect(data.col).toBe(Prisma.{{name}}) for a value given to Prisma, expect(row.col).toBeNull() for a row read back.',
+    },
+  },
+  create(context) {
+    const reported = new Set();
+
+    /** Report every sentinel reached from `node`, the argument of `matcher`. */
+    function visit(node, matcher, depth) {
+      const value = unwrap(node);
+      if (!value) return;
+      switch (value.type) {
+        case 'ObjectExpression':
+          for (const property of value.properties) {
+            visit(
+              property.type === 'Property' ? property.value : property.argument,
+              matcher,
+              depth,
+            );
+          }
+          return;
+        case 'ArrayExpression':
+          for (const element of value.elements) visit(element, matcher, depth);
+          return;
+        case 'SpreadElement':
+          visit(value.argument, matcher, depth);
+          return;
+        default:
+          break;
+      }
+      const name = prismaNullName(value, context);
+      if (name !== null) {
+        if (reported.has(value)) return;
+        reported.add(value);
+        context.report({ node: value, messageId: matcher, data: { name } });
+        return;
+      }
+      if (value.type === 'Identifier' && depth < BINDING_DEPTH) {
+        visit(constInit(value, context), matcher, depth + 1);
+      }
+    }
+
+    return {
+      CallExpression(node) {
+        const matcher = partialMatcher(node);
+        if (matcher === null) return;
+        for (const argument of node.arguments) visit(argument, matcher, 0);
+      },
+    };
+  },
+};
+
+export { jsonnullInMatcher };