@veda-hq/eslint-plugin-shuddhi 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The Veda Authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,68 @@
-# Temporary Holding Version
+# @veda-hq/eslint-plugin-shuddhi
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+शुद्धि, purification. ESLint rules for code that coding agents write and
+reviewers keep sending back: errors swallowed or stringified unsafely, input
+parsed by hand, NestJS and Prisma boundaries left open, and tests that pass
+without proving anything.
+
+Each rule closes a defect class that a code reviewer reported repeatedly after
+push. Its suite holds those findings, reduced, as invalid cases, with the
+corrected code and the near misses as valid ones.
+
+## Install
+
+```sh
+pnpm add -D eslint @veda-hq/eslint-plugin-shuddhi
+```
+
+ESLint 9 flat config, Node 24. `typescript` is an optional peer: only the rules
+that read types (`strict-scalar-parse`, `nest-body-dto`) need it, and only
+where the config gives the parser a TypeScript project.
+
+## Use
+
+```js
+// eslint.config.js
+import shuddhi from '@veda-hq/eslint-plugin-shuddhi';
+
+export default [
+  {
+    files: ['**/*.ts'],
+    plugins: { shuddhi },
+    rules: {
+      'shuddhi/no-swallowed-catch': 'error',
+      'shuddhi/no-vacuous-assertion': 'error',
+    },
+  },
+];
+```
+
+The plugin can be bound under any namespace: a repository that had these
+rules under its own prefix keeps its rule ids (and its bulk suppressions) by
+binding the plugin, or one family's `rules`, under that prefix.
+
+Each family also exports config-block helpers that turn its rules on for a set
+of globs, with a `namespace` parameter:
+
+| Family | Rules | Helper |
+| --- | --- | --- |
+| error handling | `no-swallowed-catch`, `safe-log`, `no-raw-error-string`, `no-direct-child-process` | `errorHandlingBlocks` |
+| 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` |
+
+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,
+so the messages point at the helper your repository actually has.
+
+## Checks
+
+`pnpm check`: the suites under `node --test` with at least 95% of lines and
+functions and 90% of branches covered, and a smoke import of the published
+entry point. The rules are plain JavaScript, shipped as written; the suites
+are TypeScript that Node runs by stripping types.
+
+## Licence
+
+MIT.

package/package.json

@@ -1,6 +1,67 @@
 {
   "name": "@veda-hq/eslint-plugin-shuddhi",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "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",
+    "eslintplugin",
+    "eslint-plugin",
+    "nestjs",
+    "prisma",
+    "vitest",
+    "testing",
+    "coding agents"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=24.15"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/veda-hq/veda.git",
+    "directory": "packages/eslint-plugin-shuddhi"
+  },
+  "homepage": "https://github.com/veda-hq/veda/tree/main/packages/eslint-plugin-shuddhi#readme",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "exports": {
+    ".": "./src/index.js",
+    "./error-handling": "./src/error-handling/index.js",
+    "./error-handling/configs": "./src/error-handling/configs.js",
+    "./input-parsing": "./src/input-parsing/index.js",
+    "./nest-prisma": "./src/nest-prisma/index.js",
+    "./server-boundary": "./src/server-boundary/index.js",
+    "./server-boundary/configs": "./src/server-boundary/configs.js",
+    "./test-lint": "./src/test-lint/index.js",
+    "./test-lint/configs": "./src/test-lint/configs.js",
+    "./nest-prisma/helpers": "./src/nest-prisma/helpers.js"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/fixtures"
+  ],
+  "peerDependencies": {
+    "eslint": "^9.24.0",
+    "typescript": ">=5.4 <6"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@typescript-eslint/rule-tester": "8.48.0",
+    "eslint": "9.39.1",
+    "typescript": "5.9.3",
+    "typescript-eslint": "8.48.0"
+  },
+  "scripts": {
+    "test": "node --test --experimental-test-coverage --test-coverage-lines=95 --test-coverage-functions=95 --test-coverage-branches=90 --test-coverage-exclude=src/**/*.test.ts --test-coverage-exclude=src/**/fixtures/** src/**/*.test.ts",
+    "smoke": "node --input-type=module -e \"const p = (await import('@veda-hq/eslint-plugin-shuddhi')).default; if (Object.keys(p.rules).length === 0) throw new Error('no rules');\"",
+    "check": "pnpm test && pnpm smoke"
+  }
 }

package/src/error-handling/configs.js

@@ -0,0 +1,122 @@
+/**
+ * Flat-config blocks for the error-handling rules (catalogue ERR-01, ERR-02
+ * with OBS-03, ERR-03, ERR-08).
+ *
+ * The rule ids need the plugin bound under a namespace, so a workspace takes
+ * them through {@link errorHandlingBlocks} rather than a bare spread. The
+ * namespace defaults to `shuddhi`; a project that already has these rules
+ * under another namespace (and suppressions recorded against those ids)
+ * passes its own.
+ */
+
+import { rules } from './index.js';
+
+/**
+ * The plugin object bound when the caller passes none. One module-level
+ * object, so calling the helpers twice binds the same plugin: flat config
+ * refuses two different objects under one namespace.
+ */
+const familyPlugin = { rules };
+
+/**
+ * @typedef {object} ErrorHandlingOptions
+ * @property {string} [namespace] Plugin namespace the rule ids use. Default `shuddhi`.
+ * @property {string} [helperModule] Module named in the safe-log and
+ *   no-raw-error-string messages as the home of `safeLog`, `safeInvoke` and
+ *   `errorDetail`.
+ * @property {string} [helperSourcePattern] Regular expression over import
+ *   specifiers: an import of `safeLog`/`safeInvoke` from a matching module is
+ *   the real wrapper (safe-log).
+ * @property {string} [runChildPath] The one file allowed to use the async
+ *   child_process APIs (the runner itself), as a path from `root`; also named
+ *   in the no-direct-child-process message.
+ * @property {string} [root] Directory `runChildPath` is relative to. Defaults
+ *   to ESLint's working directory.
+ */
+
+/** `'error'`, or `['error', options]` when any option was given. */
+function entry(options) {
+  const given = Object.fromEntries(
+    Object.entries(options).filter(([, value]) => value !== undefined),
+  );
+  return Object.keys(given).length > 0 ? ['error', given] : 'error';
+}
+
+/**
+ * The error-handling rules as a rules object.
+ *
+ * @param {ErrorHandlingOptions} [options]
+ */
+export function errorHandling({
+  namespace = 'shuddhi',
+  helperModule,
+  helperSourcePattern,
+  runChildPath,
+  root,
+} = {}) {
+  return {
+    // ERR-01. A catch that neither rethrows nor rejects needs
+    // `// fail-open: <reason>`; `no-empty` only ever saw empty blocks.
+    [`${namespace}/no-swallowed-catch`]: 'error',
+    // ERR-02 and OBS-03, one rule: injected loggers, and console on a catch
+    // path, go through safeLog/safeInvoke.
+    [`${namespace}/safe-log`]: entry({ helperModule, helperSourcePattern }),
+    // ERR-03. A caught value becomes text only through errorDetail().
+    [`${namespace}/no-raw-error-string`]: entry({ helperModule }),
+    // ERR-08. Async child processes only through the runner.
+    [`${namespace}/no-direct-child-process`]: entry({
+      allow: runChildPath === undefined ? undefined : [runChildPath],
+      runner: runChildPath,
+      root,
+    }),
+  };
+}
+
+/**
+ * Where the error-handling rules do not apply: tests, fixtures and mocks.
+ * A test's catch that captures an error to assert on it is the point of the
+ * test, and a test harness's direct spawn is not shipped tooling. Globs are
+ * relative to whichever workspace config uses them.
+ */
+const CODE_FILES = '**/*.{js,jsx,mjs,cjs,ts,tsx,mts,cts}';
+
+export const ERROR_HANDLING_EXEMPT = [
+  '**/*.test.*',
+  '**/*.spec.*',
+  '**/*.perf-test.*',
+  '**/*.fixture.*',
+  '**/__tests__/**',
+  '**/__mocks__/**',
+  '**/fixtures/**',
+  '**/test/**',
+  '**/e2e/**',
+];
+
+/**
+ * Config blocks that turn the error-handling rules on for `files` and off for
+ * {@link ERROR_HANDLING_EXEMPT}. Legacy hits are best held in the workspace's
+ * `eslint-suppressions.json` (ESLint bulk suppressions): counts only fall.
+ *
+ * @param {import('eslint').Linter.Config['files']} files
+ * @param {ErrorHandlingOptions & { plugin?: import('eslint').ESLint.Plugin }} [options]
+ *   `plugin` is the object bound under `namespace`; pass the one your config
+ *   already binds there, if any. Defaults to a plugin of this family's rules.
+ */
+export function errorHandlingBlocks(files, options = {}) {
+  const { plugin = familyPlugin, namespace = 'shuddhi', ...rest } = options;
+  const ruleSet = errorHandling({ namespace, ...rest });
+  return [
+    { files, plugins: { [namespace]: plugin }, rules: ruleSet },
+    {
+      // Each exemption is ANDed with a code extension (a nested array is an
+      // intersection in flat config). A bare `**/test/**` or `**/*.test.*`
+      // here would make ESLint lint every .sh and .json under those paths,
+      // since any `files` match marks a file as lintable.
+      files: ERROR_HANDLING_EXEMPT.map(glob => [glob, CODE_FILES]),
+      plugins: { [namespace]: plugin },
+      rules: Object.fromEntries(
+        Object.keys(ruleSet).map(rule => [rule, 'off']),
+      ),
+    },
+  ];
+}