pr-checkmate 1.23.22 → 1.23.24

package/.eslintrc.js

@@ -93,19 +93,9 @@ module.exports = {
       },
     ],
     'import-x/no-duplicates': 'error',
-    // Documentation (#62)
-    'jsdoc/require-jsdoc': [
-      'warn',
-      {
-        publicOnly: true,
-        require: {
-          FunctionDeclaration: true,
-          MethodDefinition: true,
-          ClassDeclaration: true,
-          ArrowFunctionExpression: false,
-        },
-      },
-    ],
+    // Documentation (#62). `jsdoc/require-jsdoc` is deliberately absent — see the
+    // note in eslint-flat-config.mjs. These three check docblocks that exist and
+    // fix only inside them; they never fabricate one.
     'jsdoc/check-param-names': 'warn',
     'jsdoc/check-tag-names': 'warn',
     'jsdoc/check-types': 'warn',

package/README.md

@@ -13,7 +13,7 @@
 
 > PR CheckMate is a security-first PR gate: secret scanning, dependency
 > vulnerability checks, and a signed SBOM + independent VirusTotal scan on
-> every release — plus 51 code-quality checks across 11 languages bundled in
+> every release — plus 53 code-quality checks across 12 languages bundled in
 > for free, running in CI on every pull request. The bundled languages need no
 > per-language toolchain setup.
 
@@ -82,6 +82,7 @@ tool installed; the check skips gracefully when the tool is absent.
 | C# | `dotnet format` | .NET SDK on the runner |
 | Ruby | RuboCop | `rubocop` on the runner |
 | PHP | PHP-CS-Fixer | `php-cs-fixer` on the runner |
+| Shell | ShellCheck | `shellcheck` on the runner |
 
 Secret scanning (gitleaks) and the universal git-diff checks are bundled and run for
 every language.
@@ -181,12 +182,13 @@ For a runner-dependency language, add its toolchain setup step before the run: G
 `actions/setup-go`, Rust with `dtolnay/rust-toolchain`, C# with `actions/setup-dotnet`,
 Ruby with `ruby/setup-ruby` (plus `gem install rubocop`), PHP with
 `shivammathur/setup-php` (tools: `php-cs-fixer`), Kotlin by fetching the `ktlint`
-binary. Swift's `swiftlint` is pre-installed on `macos-latest`. Anything missing is
+binary. Swift's `swiftlint` is pre-installed on `macos-latest`, and `shellcheck` is
+pre-installed on `ubuntu-latest` — neither needs a setup step. Anything missing is
 skipped, not failed.
 
 ## Checks
 
-51 checks, grouped by category and run in parallel within each phase:
+53 checks, grouped by category and run in parallel within each phase:
 
 - Universal git-diff (18) — language-agnostic and bundled: merge-conflict markers,
   secret scan, diff security (JS/TS/Python/Go/Kotlin), diff smells, GitHub Actions and
@@ -196,9 +198,10 @@ skipped, not failed.
 - Dependencies (7) — unused/missing, circular, outdated, license compliance, npm audit,
   a cross-language vuln scan (osv-scanner, opt-in), and a direct-dependency vuln scan
   (grype, on by default).
-- Quality (6) — duplicate code, dead code, multi-language spellcheck, markdown lint, YAML lint, config validation.
+- Quality (7) — duplicate code, dead code, multi-language spellcheck, markdown lint,
+  YAML lint, broken symlinks, config validation.
 - PR hygiene (4) — size, title, body, and commit-message convention.
-- Per-language (16) — lint, format, and type-check for the languages listed above.
+- Per-language (17) — lint, format, and type-check for the languages listed above.
 
 Each check has its own page in the
 [per-check reference](https://github.com/Mybono/pr_checkmate_public/blob/main/documentation/checks/INDEX.md),
@@ -269,4 +272,4 @@ affect it.
 
 LicenseRef Proprietary © 2025-2026 Artur Polishchuk. Free to install and run via the
 published npm package (see [LICENSE](LICENSE) for the exact grant); the source is not
-open-source and is not licensed for copying, modification, or redistribution.
+open-source and is not licensed for copying, modification, or redistribution.

package/cspell.json

@@ -422,6 +422,7 @@
     "distroless",
     "dlib",
     "Doar",
+    "docblocks",
     "Doch",
     "dockerfiles",
     "dockerization",

package/dist/cli.js

@@ -20,6 +20,8 @@ const COMMAND_TO_CHECK = {
     outdated: 'Outdated Deps',
     markdown: 'Markdown',
     'yaml-lint': 'YAML Lint',
+    symlinks: 'Broken Symlinks',
+    shellcheck: 'ShellCheck',
     typecheck: 'TypeScript',
     'diff-smell': 'Diff Smells',
     'diff-security': 'Diff Security',

package/dist/core/checks/languages/shellcheck.d.ts

@@ -0,0 +1,8 @@
+import { Check } from '../../types';
+/**
+ * Lints changed shell scripts with ShellCheck. Runner-dependency: needs the
+ * `shellcheck` binary on the runner (like Go Vet/Clippy/RuboCop), gracefully
+ * skipping when it's absent. `-f gcc` gives one line per finding, ending in
+ * `[SCxxxx]`, which both a human and the count below can read directly.
+ */
+export declare const shellcheckCheck: Check;

package/dist/core/checks/languages/shellcheck.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.shellcheckCheck = void 0;
+const utils_1 = require("../../../utils");
+const execa_1 = require("../../../utils/execa");
+const targets_1 = require("../../targets");
+const types_1 = require("../../types");
+const SHELL_GLOBS = ['*.sh', '*.bash', '*.ksh'];
+/**
+ * Lints changed shell scripts with ShellCheck. Runner-dependency: needs the
+ * `shellcheck` binary on the runner (like Go Vet/Clippy/RuboCop), gracefully
+ * skipping when it's absent. `-f gcc` gives one line per finding, ending in
+ * `[SCxxxx]`, which both a human and the count below can read directly.
+ */
+exports.shellcheckCheck = {
+    name: 'ShellCheck',
+    phase: 'informational',
+    applies(ctx) {
+        return ctx.config.shellcheck?.enabled !== false;
+    },
+    async run(ctx) {
+        const targets = await (0, targets_1.resolveTargetFiles)(ctx, SHELL_GLOBS);
+        if (targets === null)
+            return (0, types_1.skip)('git unavailable');
+        if (targets.length === 0)
+            return (0, types_1.pass)('no shell scripts changed');
+        const minSeverity = ctx.config.shellcheck?.minSeverity;
+        const ignore = ctx.config.shellcheck?.ignore ?? [];
+        const args = ['-f', 'gcc'];
+        if (minSeverity)
+            args.push('-S', minSeverity);
+        if (ignore.length > 0)
+            args.push('-e', ignore.join(','));
+        args.push(...targets);
+        const result = await (0, execa_1.execa)('shellcheck', args, { cwd: ctx.cwd, reject: false });
+        // execa v9 with reject:false does NOT throw on a missing binary — it resolves
+        // with `code: 'ENOENT'`. Detect that on the result, not via try/catch.
+        if (result.code === 'ENOENT')
+            return (0, types_1.skip)('shellcheck not installed');
+        if (result.exitCode === 0) {
+            utils_1.logger.info('[ShellCheck]: ✅ No issues found');
+            return (0, types_1.pass)();
+        }
+        const lines = [result.stdout, result.stderr]
+            .filter(Boolean)
+            .join('\n')
+            .split('\n')
+            .filter(Boolean);
+        utils_1.logger.warn(`[ShellCheck]: ⚠️ ${lines.length} issue(s):`);
+        lines.slice(0, 10).forEach(l => utils_1.logger.warn(`  ${l}`));
+        if (lines.length > 10)
+            utils_1.logger.warn(`  ... and ${lines.length - 10} more`);
+        return (0, types_1.warn)(`${lines.length} issue(s) in ${targets.length} file(s)`);
+    },
+};

package/dist/core/checks/quality/symlinks.d.ts

@@ -0,0 +1,16 @@
+import { Check } from '../../types';
+/** True when `fullPath` is a symlink whose target does not exist. */
+export declare function isBrokenSymlink(fullPath: string): boolean;
+/**
+ * Flags tracked symlinks whose target does not exist. `fs.existsSync` follows a
+ * symlink to its target, so it returns `false` for exactly the broken case while
+ * the link itself is still a real, tracked file — that's what makes a plain
+ * existence check (as used by `resolveTargetFiles`) unusable here and requires
+ * the dedicated `isBrokenSymlink` pass over `fs.lstatSync` above.
+ *
+ * Whole-repo scan (not delta), like Case Collision: a broken link fails a
+ * checkout or build regardless of which PR introduced it, so it's worth
+ * catching even when this run's diff never touched it. Informational and warns
+ * by default — promote to a gate per repo with `symlinks.severity`.
+ */
+export declare const symlinksCheck: Check;

package/dist/core/checks/quality/symlinks.js

@@ -0,0 +1,62 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.symlinksCheck = void 0;
+exports.isBrokenSymlink = isBrokenSymlink;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const config_1 = require("../../../config");
+const utils_1 = require("../../../utils");
+const targets_1 = require("../../targets");
+const types_1 = require("../../types");
+const findings_1 = require("../findings");
+/** True when `fullPath` is a symlink whose target does not exist. */
+function isBrokenSymlink(fullPath) {
+    let stat;
+    try {
+        stat = node_fs_1.default.lstatSync(fullPath);
+    }
+    catch {
+        return false; // gone between listing and stat
+    }
+    return stat.isSymbolicLink() && !node_fs_1.default.existsSync(fullPath);
+}
+/**
+ * Flags tracked symlinks whose target does not exist. `fs.existsSync` follows a
+ * symlink to its target, so it returns `false` for exactly the broken case while
+ * the link itself is still a real, tracked file — that's what makes a plain
+ * existence check (as used by `resolveTargetFiles`) unusable here and requires
+ * the dedicated `isBrokenSymlink` pass over `fs.lstatSync` above.
+ *
+ * Whole-repo scan (not delta), like Case Collision: a broken link fails a
+ * checkout or build regardless of which PR introduced it, so it's worth
+ * catching even when this run's diff never touched it. Informational and warns
+ * by default — promote to a gate per repo with `symlinks.severity`.
+ */
+exports.symlinksCheck = {
+    name: 'Broken Symlinks',
+    phase: 'informational',
+    applies(ctx) {
+        return ctx.config.symlinks?.enabled !== false;
+    },
+    async run(ctx) {
+        const files = await (0, targets_1.listTrackedFiles)(ctx, ['*'], (0, config_1.getSourcePaths)());
+        if (files.length === 0)
+            return (0, types_1.skip)('no tracked files');
+        const ignore = ctx.config.symlinks?.ignore ?? [];
+        const broken = [];
+        for (const file of files) {
+            if (ignore.length > 0 && (0, utils_1.matchesAnyGlob)(file, ignore))
+                continue;
+            if (isBrokenSymlink(node_path_1.default.join(ctx.cwd, file)))
+                broken.push(file);
+        }
+        if (broken.length === 0)
+            return (0, types_1.pass)();
+        const sev = (0, findings_1.severityEmitter)(ctx.config.symlinks?.severity, 'warn');
+        broken.forEach(f => sev.log(`[Broken Symlinks]: ${sev.icon} ${f} — target does not exist`));
+        return sev.emit(`${broken.length} broken symlink(s)`);
+    },
+};

package/dist/core/registry.js

@@ -31,6 +31,7 @@ const python_typecheck_1 = require("./checks/languages/python-typecheck");
 const ruby_lint_1 = require("./checks/languages/ruby-lint");
 const rust_format_1 = require("./checks/languages/rust-format");
 const rust_lint_1 = require("./checks/languages/rust-lint");
+const shellcheck_1 = require("./checks/languages/shellcheck");
 const swift_lint_1 = require("./checks/languages/swift-lint");
 const typecheck_1 = require("./checks/languages/typecheck");
 const commitlint_1 = require("./checks/pr/commitlint");
@@ -45,6 +46,7 @@ const duplicate_check_1 = require("./checks/quality/duplicate-check");
 const license_header_1 = require("./checks/quality/license-header");
 const markdown_lint_1 = require("./checks/quality/markdown-lint");
 const spellcheck_1 = require("./checks/quality/spellcheck");
+const symlinks_1 = require("./checks/quality/symlinks");
 const yaml_lint_1 = require("./checks/quality/yaml-lint");
 const diff_security_1 = require("./checks/security/diff-security");
 const dockerfile_security_1 = require("./checks/security/dockerfile-security");
@@ -95,6 +97,7 @@ exports.REGISTRY = [
     markdown_lint_1.markdownLintCheck,
     spellcheck_1.spellcheckCheck,
     yaml_lint_1.yamlLintCheck,
+    symlinks_1.symlinksCheck,
     python_lint_1.pythonLintCheck,
     python_typecheck_1.pythonTypecheckCheck,
     dead_code_1.deadCodeCheck,
@@ -103,6 +106,7 @@ exports.REGISTRY = [
     go_lint_1.goLintCheck,
     rust_lint_1.rustLintCheck,
     ruby_lint_1.rubyLintCheck,
+    shellcheck_1.shellcheckCheck,
     // format
     prettier_1.prettierCheck,
     cpp_format_1.cppFormatCheck,

package/dist/interfaces/index.d.ts

@@ -211,6 +211,16 @@ export interface PRCheckMateConfig {
     configValidation?: {
         enabled?: boolean;
     };
+    symlinks?: {
+        enabled?: boolean;
+        severity?: 'error' | 'warn';
+        ignore?: string[];
+    };
+    shellcheck?: {
+        enabled?: boolean;
+        minSeverity?: 'error' | 'warning' | 'info' | 'style';
+        ignore?: string[];
+    };
     yamlLint?: {
         enabled?: boolean;
         severity?: 'error' | 'warn';

package/eslint-default-rules.json

@@ -34,18 +34,6 @@
     }
   ],
   "import/no-duplicates": "error",
-  "jsdoc/require-jsdoc": [
-    "warn",
-    {
-      "publicOnly": true,
-      "require": {
-        "FunctionDeclaration": true,
-        "MethodDefinition": true,
-        "ClassDeclaration": true,
-        "ArrowFunctionExpression": false
-      }
-    }
-  ],
   "jsdoc/check-param-names": "warn",
   "jsdoc/check-tag-names": "warn",
   "jsdoc/check-types": "warn",

package/eslint.config.mjs

@@ -26,6 +26,28 @@ import jsdocPlugin from 'eslint-plugin-jsdoc';
  * `eslint.rules: { "prettier/prettier": "error" }` or
  * `severity: { "Prettier": "error" }` in pr-checkmate.json.
  *
+ * FIXERS THAT FABRICATE CONTENT ARE NOT SHIPPED. `jsdoc/require-jsdoc` used to be in
+ * this set at `warn`, and it is auto-fixable — but unlike `prettier/prettier`, whose
+ * fixer produces the right answer, this one has no answer to produce. It writes an
+ * empty stub:
+ *
+ *     \/**
+ *      *
+ *      *\/
+ *
+ * which satisfies the rule permanently. The check runs in write mode by default
+ * outside CI, so one run stamped 150 stubs across one client's `src` and reported zero
+ * warnings; inside CI the auto-format commit pushes them back to the branch, so
+ * deleting them by hand never holds. The rule therefore reported a real gap once, and
+ * from then on guaranteed that every public method looked documented while none of it
+ * was — the signal destroyed by the same run that raised it.
+ *
+ * Whether a method is worth explaining is a judgement a fixer cannot make. The three
+ * `jsdoc/check-*` rules stay: they validate docblocks that already exist and fix only
+ * within them, so they never invent content. Documentation coverage, if a repo wants
+ * to enforce it, belongs in review — or in `eslint.rules` of its own pr-checkmate.json,
+ * where whoever turns it on knows what the fixer will do.
+ *
  * A JSON file cannot carry this note, hence it lives here; `src/config/.eslintrc.js`
  * holds the same rule set for the legacy ESLint <9 path and must stay in sync.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "pr-checkmate",
-    "version": "1.23.22",
+    "version": "1.23.24",
     "description": "Security-first PR gate for CI: secret scanning, grype dependency scanning, SBOM — plus linting and formatting across 11 languages",
     "keywords": [
         "github-actions",
@@ -120,8 +120,8 @@
         "tar": "7.5.22",
         "axios": "1.18.1",
         "form-data": "4.0.6",
-        "brace-expansion": "5.0.8",
-        "fast-uri": "4.1.1",
+        "brace-expansion": "5.0.9",
+        "fast-uri": "4.1.2",
         "follow-redirects": "1.16.0",
         "lodash": "4.18.1",
         "minimatch": "10.2.5",

package/pr-checkmate.schema.json

@@ -174,6 +174,22 @@
         "ignore": { "type": "array", "items": { "type": "string" } }
       }
     },
+    "symlinks": {
+      "type": "object",
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "severity": { "enum": ["error", "warn"] },
+        "ignore": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "shellcheck": {
+      "type": "object",
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "minSeverity": { "enum": ["error", "warning", "info", "style"] },
+        "ignore": { "type": "array", "items": { "type": "string" } }
+      }
+    },
     "circularDeps": {
       "type": "object",
       "properties": {

package/src/config/.eslintrc.js

@@ -93,19 +93,9 @@ module.exports = {
       },
     ],
     'import-x/no-duplicates': 'error',
-    // Documentation (#62)
-    'jsdoc/require-jsdoc': [
-      'warn',
-      {
-        publicOnly: true,
-        require: {
-          FunctionDeclaration: true,
-          MethodDefinition: true,
-          ClassDeclaration: true,
-          ArrowFunctionExpression: false,
-        },
-      },
-    ],
+    // Documentation (#62). `jsdoc/require-jsdoc` is deliberately absent — see the
+    // note in eslint-flat-config.mjs. These three check docblocks that exist and
+    // fix only inside them; they never fabricate one.
     'jsdoc/check-param-names': 'warn',
     'jsdoc/check-tag-names': 'warn',
     'jsdoc/check-types': 'warn',

package/src/config/cspell.json

@@ -422,6 +422,7 @@
     "distroless",
     "dlib",
     "Doar",
+    "docblocks",
     "Doch",
     "dockerfiles",
     "dockerization",

package/src/config/eslint-default-rules.json

@@ -34,18 +34,6 @@
     }
   ],
   "import/no-duplicates": "error",
-  "jsdoc/require-jsdoc": [
-    "warn",
-    {
-      "publicOnly": true,
-      "require": {
-        "FunctionDeclaration": true,
-        "MethodDefinition": true,
-        "ClassDeclaration": true,
-        "ArrowFunctionExpression": false
-      }
-    }
-  ],
   "jsdoc/check-param-names": "warn",
   "jsdoc/check-tag-names": "warn",
   "jsdoc/check-types": "warn",

package/src/config/pr-checkmate.schema.json

@@ -174,6 +174,22 @@
         "ignore": { "type": "array", "items": { "type": "string" } }
       }
     },
+    "symlinks": {
+      "type": "object",
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "severity": { "enum": ["error", "warn"] },
+        "ignore": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "shellcheck": {
+      "type": "object",
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "minSeverity": { "enum": ["error", "warning", "info", "style"] },
+        "ignore": { "type": "array", "items": { "type": "string" } }
+      }
+    },
     "circularDeps": {
       "type": "object",
       "properties": {