@parasraju/plumber-mcp 1.1.0 → 1.2.0

package/README.md

@@ -83,15 +83,15 @@ Add to `.vscode/mcp.json`:
 
 | Tool | Description |
 | --- | --- |
-| `plumber_scan` | Scan a local directory or file. Returns a score, grade, file count, and one line per issue with its fix. |
-| `plumber_list_rules` | List all 26 inspection rules with id, severity, title, and fix. |
-| `plumber_scan_text` | Scan a pasted code or config snippet. `filename` is optional and only selects the applicable rules. |
+| `plumber_scan` | Scan a local directory or file. Returns a score, grade, file count, and one line per issue with its fix. Optional `rulesFile`, or `.plumber-rules.json` in the target, adds a rule pack. |
+| `plumber_list_rules` | List all 26 inspection rules with id, severity, title, and fix. Optional `rulesFile` appends pack rules marked `source: pack`. |
+| `plumber_scan_text` | Scan a pasted code or config snippet. `filename` is optional and only selects the applicable rules. Optional `rulesFile` adds a rule pack. |
 
 Tool inputs are deliberately small so they cost few tokens:
 
-- `plumber_scan`: `target` (string, default `"."`)
-- `plumber_list_rules`: none
-- `plumber_scan_text`: `text` (string, required), `filename` (string, optional)
+- `plumber_scan`: `target` (string, default `"."`), `rulesFile` (string, optional)
+- `plumber_list_rules`: `rulesFile` (string, optional)
+- `plumber_scan_text`: `text` (string, required), `filename` (string, optional), `rulesFile` (string, optional)
 
 ## Example session
 
@@ -125,6 +125,72 @@ Tool inputs are deliberately small so they cost few tokens:
 - `sec/job-permissions` [HIGH] Job Writes Without Least-Privilege Permissions (Set least-privilege permissions on the job.)
 - `sec/secret-to-untrusted` [HIGH] Secret Passed to Untrusted Step (Scope the secret to the trusted step that needs it.)
 
+### Custom rule packs — bring your own rules
+
+Bring rule packs when you need custom rules the built-in set does not ship: an internal secret format, a banned pattern, or a house naming rule. A pack is one local JSON file. This release does not read YAML packs, and it does not download a pack from a URL.
+
+The file is a top-level object `{ "rules": [...] }`. Each rule uses these fields:
+
+- `id` (string, required) — must start with `custom/`, for example `custom/no-internal-api-key`. Any other id is rejected. An id that matches a built-in rule, or another rule in the same pack, is rejected. The built-in rule is left unchanged.
+- `severity` (string, required) — one of `CRITICAL`, `HIGH`, `MEDIUM`, `LOW`. Anything else is rejected.
+- `title` (string, required) — short name, for example `Internal API key format`.
+- `pattern` (string, required) — a JavaScript regular expression, matched against the file text. A pattern that does not compile rejects that rule.
+- `files` (array of glob strings, optional) — for example `["**/*.js", "**/*.ts"]`. The rule runs only on files that match one of these globs. Omit it to use every file Plumber already scans. Globs support `*`, `?`, and `**`. `*` does not cross a `/`; use `**/*.js` to match JavaScript in any directory.
+- `fix` (string, required) — the plain-English fix, in the same voice as the built-in rules. A rule with no fix is rejected.
+
+On `plumber_scan`, globs only filter files the scanner already opens: `.py`, `.js`, `.jsx`, `.ts`, `.tsx`, `.html`, `.htm`, `.css`, `.scss`, `.env*`, and GitHub Actions workflow YAML. `plumber_scan_text` applies the same globs to the `filename` you pass.
+
+A bad rule is dropped. The tool result includes a `Pack error:` line that names the rule and the problem (invalid JSON names the pack file, because there is no rule yet). The 26 built-in rules still run. A broken pack does not wipe the report and does not stop the server.
+
+One pack is loaded, in this order:
+
+1. `rulesFile`, when the tool call includes it. A relative path is resolved from the server's working directory.
+2. Auto-load, only for `plumber_scan`, and only when `rulesFile` is omitted. Plumber reads `.plumber-rules.json` in the directory passed as `target`. A file target uses the directory that contains that file. Parent folders and subfolders are not searched. `plumber_scan_text` and `plumber_list_rules` do not auto-load.
+3. When both are present, `rulesFile` is the pack that runs. The two files are not merged.
+
+The scan result names the pack on one line: the file path and how many pack rules loaded, for example `Pack: /repo/.plumber-rules.json (2 pack rules loaded)`.
+
+`plumber_list_rules` with no `rulesFile` returns the 26 built-in rules. With `rulesFile`, the pack rules follow the built-ins and each one ends with `source: pack`.
+
+Save this file as `.plumber-rules.json` in the directory you scan, or pass the path as `rulesFile`. The same example ships at `examples/custom-rules.example.json`.
+
+```json
+{
+  "rules": [
+    {
+      "id": "custom/no-internal-api-key",
+      "severity": "CRITICAL",
+      "title": "Internal API key format",
+      "pattern": "\\bINT_[A-Z0-9]{16}\\b",
+      "files": ["**/*.js", "**/*.ts"],
+      "fix": "Move the internal key to an environment variable and rotate it."
+    },
+    {
+      "id": "custom/no-banned-marker",
+      "severity": "MEDIUM",
+      "title": "Banned ship marker",
+      "pattern": "\\bDO_NOT_SHIP\\b",
+      "files": ["**/*.js", "**/*.py"],
+      "fix": "Remove the banned marker before committing this file."
+    }
+  ]
+}
+```
+
+Three ways to run that pack:
+
+1. Auto-load: write it to `.plumber-rules.json`, then call `plumber_scan` with `{ "target": "." }`.
+2. `rulesFile` on `plumber_scan`: `{ "target": ".", "rulesFile": "examples/custom-rules.example.json" }`. This is the pack that runs when `.plumber-rules.json` is also present.
+3. `rulesFile` on `plumber_scan_text`: `{ "text": "const internal = \"INT_ABCDEFGHIJ123456\";\n", "filename": "src/config.js", "rulesFile": "examples/custom-rules.example.json" }`. A snippet that does not match the pattern produces no pack finding.
+
+`src/config.js` containing `INT_ABCDEFGHIJ123456` then reports:
+
+```
+- [CRITICAL] Internal API key format (Move the internal key to an environment variable and rotate it.) — src/config.js:1
+```
+
+The secret-format rule above does not check Python files. The banned-marker rule does, because its `files` list says so.
+
 ## Links
 
 - CLI: [plumber-linter](https://www.npmjs.com/package/plumber-linter)
@@ -134,6 +200,9 @@ Tool inputs are deliberately small so they cost few tokens:
 
 ## Changelog
 
+## 1.2.0
+- Custom rule packs: load your own rules from `.plumber-rules.json` or a `rulesFile`, ids under `custom/`.
+
 ## 1.1.0
 - Workflow YAML rules: sec/pull-request-target, sec/expression-injection, pipe/action-unpinned, sec/job-permissions, sec/secret-to-untrusted.
 

package/bin/plumber-mcp.js

@@ -8,6 +8,10 @@
  *   plumber_list_rules  list every inspection rule
  *   plumber_scan_text   scan a pasted snippet
  *
+ * Each tool accepts an optional rulesFile path to one local JSON rule pack.
+ * plumber_scan also reads .plumber-rules.json in the target when rulesFile is omitted.
+ * Packs are never fetched from a URL.
+ *
  * Only JSON-RPC goes to stdout. Diagnostics go to stderr.
  */
 
@@ -21,7 +25,7 @@ const {
   ErrorCode,
   McpError
 } = require('@modelcontextprotocol/sdk/types.js');
-const { RULES, SCANNABLE_EXTS, scanLocalDirectory, scanText } = require('../src/engine.js');
+const { RULES, SCANNABLE_EXTS, scanLocalDirectory, scanText, loadRulePack, resolveScanPack } = require('../src/engine.js');
 
 // v1.0.1 fix: read the version from package.json so serverInfo never drifts.
 // Repro (v1.0.0): initialize -> serverInfo.version was hardcoded to "1.0.0".
@@ -34,7 +38,8 @@ const TOOLS = [
     inputSchema: {
       type: 'object',
       properties: {
-        target: { type: 'string', description: 'Directory or file path to scan (default ".")' }
+        target: { type: 'string', description: 'Directory or file path to scan (default ".")' },
+        rulesFile: { type: 'string', description: 'Optional path to a local JSON rule pack. When omitted, .plumber-rules.json is loaded from the scan target if that file exists.' }
       },
       additionalProperties: false
     }
@@ -44,7 +49,9 @@ const TOOLS = [
     description: 'List all Plumber inspection rules with severity, title, and recommended fix.',
     inputSchema: {
       type: 'object',
-      properties: {},
+      properties: {
+        rulesFile: { type: 'string', description: 'Optional path to a local JSON rule pack. Pack rules are listed after the built-in rules and marked as custom.' }
+      },
       additionalProperties: false
     }
   },
@@ -55,7 +62,8 @@ const TOOLS = [
       type: 'object',
       properties: {
         text: { type: 'string', description: 'Code or config snippet to scan' },
-        filename: { type: 'string', description: 'Optional filename used to select applicable rules (e.g. app.js)' }
+        filename: { type: 'string', description: 'Optional filename used to select applicable rules (e.g. app.js)' },
+        rulesFile: { type: 'string', description: 'Optional path to a local JSON rule pack applied to this snippet. Pasted snippets do not auto-load a pack.' }
       },
       required: ['text'],
       additionalProperties: false
@@ -63,22 +71,47 @@ const TOOLS = [
   }
 ];
 
+function packLoadedLine(pack) {
+  const count = Array.isArray(pack.rules) ? pack.rules.length : 0;
+  const label = count === 1 ? 'pack rule' : 'pack rules';
+  return `Pack: ${pack.path} (${count} ${label} loaded)`;
+}
+
+function formatPackBanner(pack) {
+  if (!pack) return '';
+  const lines = [packLoadedLine(pack)];
+  const errors = Array.isArray(pack.errors) ? pack.errors : [];
+  for (let i = 0; i < errors.length; i++) {
+    lines.push(`Pack error: ${errors[i]}`);
+  }
+  return lines.join('\n');
+}
+
+function formatListedRule(rule) {
+  const severity = rule.sev || rule.severity;
+  const line = `${rule.id} [${severity}] ${rule.title} (${rule.fix})`;
+  if (rule.source === 'pack') return `${line} source: pack`;
+  return line;
+}
+
 function formatReport(report) {
   const header = [
     `Plumber Health Report for ${report.repo_name}`,
     report.total_files === 0 ? 'Score: n/a' : `Score: ${report.score}/100 (Grade ${report.grade})`,
     `Files: ${report.total_files} | Issues: ${report.issues.length}`
   ].join('\n');
+  const banner = formatPackBanner(report.pack);
+  const top = banner ? `${header}\n${banner}` : header;
 
   // v1.0.1 fix: do not report "No issues found." when nothing was scanned.
   // Repro (v1.0.0): plumber_scan { target: ".github/workflows/ci.yml" } (or a
   //   Dockerfile, or an empty dir) -> "Score: 100/100 (Grade A) ... No issues found."
   if (report.total_files === 0) {
-    return `${header}\n\nNo scannable files found, so nothing was checked. Supported: ${SCANNABLE_EXTS.join(' ')} and .env* files.`;
+    return `${top}\n\nNo scannable files found, so nothing was checked. Supported: ${SCANNABLE_EXTS.join(' ')} and .env* files.`;
   }
 
   if (report.issues.length === 0) {
-    return `${header}\n\nNo issues found.`;
+    return `${top}\n\nNo issues found.`;
   }
 
   const locations = new Map();
@@ -94,7 +127,7 @@ function formatReport(report) {
     return `- [${issue.severity}] ${issue.title} (${issue.fix})${suffix}`;
   });
 
-  return `${header}\n\n${lines.join('\n')}`;
+  return `${top}\n\n${lines.join('\n')}`;
 }
 
 function requireString(value, name) {
@@ -114,15 +147,29 @@ function requireText(text) {
 
 function runScanTool(args) {
   const target = requireString(args.target, 'target') || '.';
+  const rulesFile = requireString(args.rulesFile, 'rulesFile');
   const absolute = path.resolve(target);
 
   if (!fs.existsSync(absolute)) {
     throw new McpError(ErrorCode.InvalidParams, `Target path does not exist: ${absolute}`);
   }
 
+  let pack = null;
   try {
-    return formatReport(scanLocalDirectory(absolute));
+    pack = resolveScanPack(absolute, rulesFile);
   } catch (err) {
+    pack = {
+      path: rulesFile || absolute,
+      rules: [],
+      errors: [`Pack failed to load: ${err.message}`],
+      broken: true
+    };
+  }
+
+  try {
+    return formatReport(scanLocalDirectory(absolute, pack ? { pack } : undefined));
+  } catch (err) {
+    if (err instanceof McpError) throw err;
     throw new McpError(ErrorCode.InternalError, `Scan failed: ${err.message}`);
   }
 }
@@ -130,16 +177,55 @@ function runScanTool(args) {
 function runScanTextTool(args) {
   const text = requireText(args.text);
   const filename = requireString(args.filename, 'filename');
+  const rulesFile = requireString(args.rulesFile, 'rulesFile');
+  let pack = null;
+  if (rulesFile) {
+    try {
+      pack = loadRulePack(rulesFile);
+    } catch (err) {
+      pack = {
+        path: rulesFile,
+        rules: [],
+        errors: [`Pack ${rulesFile} failed to load: ${err.message}`],
+        broken: true
+      };
+    }
+  }
 
   try {
-    return formatReport(scanText(text, filename));
+    return formatReport(scanText(text, filename, pack ? { pack } : undefined));
   } catch (err) {
+    if (err instanceof McpError) throw err;
     throw new McpError(ErrorCode.InternalError, `Scan failed: ${err.message}`);
   }
 }
 
-function runListRulesTool() {
-  return RULES.map((rule) => `${rule.id} [${rule.sev}] ${rule.title} (${rule.fix})`).join('\n');
+function runListRulesTool(args) {
+  const rulesFile = requireString(args && args.rulesFile, 'rulesFile');
+  let pack = null;
+  if (rulesFile) {
+    try {
+      pack = loadRulePack(rulesFile);
+    } catch (err) {
+      pack = {
+        path: rulesFile,
+        rules: [],
+        errors: [`Pack ${rulesFile} failed to load: ${err.message}`],
+        broken: true
+      };
+    }
+  }
+  const lines = RULES.map((rule) => formatListedRule(rule));
+  if (!pack) return lines.join('\n');
+  for (let i = 0; i < pack.rules.length; i++) {
+    lines.push(formatListedRule(pack.rules[i]));
+  }
+  lines.push(packLoadedLine(pack));
+  const errors = pack.errors || [];
+  for (let i = 0; i < errors.length; i++) {
+    lines.push(`Pack error: ${errors[i]}`);
+  }
+  return lines.join('\n');
 }
 
 async function main() {
@@ -155,7 +241,7 @@ async function main() {
     if (name === 'plumber_scan') {
       text = runScanTool(args);
     } else if (name === 'plumber_list_rules') {
-      text = runListRulesTool();
+      text = runListRulesTool(args);
     } else if (name === 'plumber_scan_text') {
       text = runScanTextTool(args);
     } else {

package/examples/custom-rules.example.json

@@ -0,0 +1,20 @@
+{
+  "rules": [
+    {
+      "id": "custom/no-internal-api-key",
+      "severity": "CRITICAL",
+      "title": "Internal API key format",
+      "pattern": "\\bINT_[A-Z0-9]{16}\\b",
+      "files": ["**/*.js", "**/*.ts"],
+      "fix": "Move the internal key to an environment variable and rotate it."
+    },
+    {
+      "id": "custom/no-banned-marker",
+      "severity": "MEDIUM",
+      "title": "Banned ship marker",
+      "pattern": "\\bDO_NOT_SHIP\\b",
+      "files": ["**/*.js", "**/*.py"],
+      "fix": "Remove the banned marker before committing this file."
+    }
+  ]
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@parasraju/plumber-mcp",
-  "version": "1.1.0",
-  "description": "Plumber as an MCP server — let your AI coding agent scan repos and GitHub Actions workflows for leaked secrets, dead code, and AI slop, with fixes in plain English.",
+  "version": "1.2.0",
+  "description": "Plumber as an MCP server — let your AI coding agent scan repos and GitHub Actions workflows for leaked secrets, dead code, and AI slop, with fixes in plain English. Add your own checks with custom rule packs.",
   "main": "src/engine.js",
   "bin": {
     "plumber-mcp": "bin/plumber-mcp.js"
@@ -15,6 +15,7 @@
   "files": [
     "bin",
     "src",
+    "examples",
     "README.md"
   ],
   "keywords": [
@@ -31,7 +32,9 @@
     "github-actions",
     "ci-cd",
     "workflow",
-    "yaml"
+    "yaml",
+    "custom-rules",
+    "rule-packs"
   ],
   "repository": {
     "type": "git",

package/src/engine.js

@@ -12,6 +12,9 @@
  * ships only `bin/` and `README.md`, so a relative import from the MCP package
  * would break `plumber-linter` for npm consumers. The CLI is intentionally left
  * untouched; keep the detection rules in this file in sync with the CLI.
+ *
+ * Rule packs (v1.2.0) are local JSON files. Their ids start with custom/
+ * and are never written into RULES, so a pack cannot replace a built-in.
  */
 
 const fs = require('fs');
@@ -54,6 +57,9 @@ const RULES = [
   { id: 'sec/secret-to-untrusted', cat: 'Leaks & Secrets', sev: 'HIGH', title: 'Secret Passed to Untrusted Step', fix: 'Scope the secret to the trusted step that needs it.' }
 ];
 
+const BUILTIN_IDS = new Set(RULES.map((rule) => rule.id));
+const PACK_SEVERITIES = new Set(['CRITICAL', 'HIGH', 'MEDIUM', 'LOW']);
+
 const SEV_WEIGHT = { CRITICAL: 4, HIGH: 3, MEDIUM: 2, LOW: 1, INFO: 0 };
 
 function gradeFor(score) {
@@ -66,7 +72,8 @@ function scoreFor(issueCount) {
 
 const SCANNABLE_EXTS = ['.py', '.js', '.jsx', '.ts', '.tsx', '.html', '.htm', '.css', '.scss', '.env'];
 
-function scanLocalDirectory(dirPath) {
+function scanLocalDirectory(dirPath, options) {
+  const pack = options && options.pack ? options.pack : null;
   const scannableExts = new Set(SCANNABLE_EXTS);
   const skipDirs = new Set(['.git', 'node_modules', 'dist', 'build', '.next', '.nuxt', 'vendor', '.venv', 'venv', '__pycache__']);
 
@@ -94,6 +101,13 @@ function scanLocalDirectory(dirPath) {
           const lines = content.split('\n');
           totalLines += lines.length;
           const fileIssues = inspectFile(rel, content, lines, ext, false);
+          if (pack) {
+            try {
+              fileIssues.push(...collectPackIssues(rel, content, lines, pack));
+            } catch (packErr) {
+              notePackError(pack, `Pack rules failed on ${rel}: ${packErr.message}`);
+            }
+          }
           if (fileIssues.length > 0) {
             issues.push(...fileIssues);
             fileReports.push({ path: rel, issues: fileIssues });
@@ -132,7 +146,7 @@ function scanLocalDirectory(dirPath) {
   const score = scoreFor(issues.length);
   const grade = gradeFor(score);
 
-  return {
+  const report = {
     repo_name: path.basename(dirPath),
     total_files: totalFiles,
     total_lines: totalLines,
@@ -141,20 +155,30 @@ function scanLocalDirectory(dirPath) {
     issues,
     file_reports: fileReports
   };
+  if (pack) report.pack = pack;
+  return report;
 }
 
-function scanText(text, filename) {
+function scanText(text, filename, options) {
   if (typeof text !== 'string') {
     throw new TypeError('text must be a string');
   }
+  const pack = options && options.pack ? options.pack : null;
   const name = filename && typeof filename === 'string' ? filename.replace(/\\/g, '/') : 'snippet.js';
   const ext = path.extname(name).toLowerCase();
   const content = text.replace(/\r\n?/g, '\n');
   const lines = content.split('\n');
   const issues = inspectFile(name, content, lines, ext, true);
+  if (pack) {
+    try {
+      issues.push(...collectPackIssues(name, content, lines, pack));
+    } catch (err) {
+      notePackError(pack, `Pack rules failed on ${name}: ${err.message}`);
+    }
+  }
   const score = scoreFor(issues.length);
 
-  return {
+  const report = {
     repo_name: name,
     total_files: 1,
     total_lines: lines.length,
@@ -163,6 +187,8 @@ function scanText(text, filename) {
     issues,
     file_reports: issues.length > 0 ? [{ path: name, issues }] : []
   };
+  if (pack) report.pack = pack;
+  return report;
 }
 
 // v1.0.1 fix: match "test"/"spec" as a path segment or filename part, not as a
@@ -774,10 +800,296 @@ function escapeRegExp(value) {
   return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 
+function notePackError(pack, message) {
+  if (!pack.errors) pack.errors = [];
+  if (pack.errors.indexOf(message) === -1) pack.errors.push(message);
+}
+
+function clipDetail(value) {
+  const text = String(value || '');
+  return text.length > 300 ? text.slice(0, 300) + '...' : text;
+}
+
+function ruleLabel(rule, index) {
+  if (rule && typeof rule.id === 'string' && rule.id.trim() !== '') return rule.id;
+  return 'rules[' + index + ']';
+}
+
+function globToRegExp(glob) {
+  let normalized = String(glob).replace(/\\/g, '/');
+  if (normalized.startsWith('./')) normalized = normalized.slice(2);
+  let source = '';
+  let i = 0;
+  while (i < normalized.length) {
+    const c = normalized[i];
+    if (c === '*' && normalized[i + 1] === '*') {
+      if (normalized[i + 2] === '/') {
+        source += '(?:.*/)?';
+        i += 3;
+      } else {
+        source += '.*';
+        i += 2;
+      }
+      continue;
+    }
+    if (c === '*') {
+      source += '[^/]*';
+      i += 1;
+      continue;
+    }
+    if (c === '?') {
+      source += '[^/]';
+      i += 1;
+      continue;
+    }
+    source += escapeRegExp(c);
+    i += 1;
+  }
+  return new RegExp('^' + source + '$');
+}
+
+function fileMatchesRule(relPath, rule) {
+  if (!rule.globs || rule.globs.length === 0) return true;
+  const norm = String(relPath || '').replace(/\\/g, '/');
+  for (let i = 0; i < rule.globs.length; i++) {
+    if (rule.globs[i].test(norm)) return true;
+  }
+  return false;
+}
+
+function firstNonEmptyMatch(regex, text) {
+  const flags = regex.flags.includes('g') ? regex.flags : regex.flags + 'g';
+  const re = new RegExp(regex.source, flags);
+  let match;
+  while ((match = re.exec(text)) !== null) {
+    if (match[0].length > 0) return match;
+    if (re.lastIndex <= match.index) re.lastIndex = match.index + 1;
+  }
+  return null;
+}
+
+function findPackHits(rule, content, lines) {
+  const hits = [];
+  for (let i = 0; i < lines.length; i++) {
+    const match = firstNonEmptyMatch(rule.regex, lines[i]);
+    if (!match) continue;
+    const evidence = String(lines[i] || '').trim();
+    if (!evidence) continue;
+    hits.push({ line: i + 1, evidence: evidence });
+  }
+  if (hits.length > 0) return hits;
+  const match = firstNonEmptyMatch(rule.regex, content);
+  if (!match) return hits;
+  const evidence = String(match[0]).replace(/\s+/g, ' ').trim();
+  if (!evidence) return hits;
+  const line = content.slice(0, match.index).split('\n').length;
+  hits.push({ line: line > 0 ? line : 1, evidence: evidence });
+  return hits;
+}
+
+function packIssue(rule, hit) {
+  return {
+    rule_id: rule.id,
+    title: rule.title,
+    severity: rule.severity,
+    line: hit.line > 0 ? hit.line : 1,
+    evidence: String(hit.evidence).slice(0, 90),
+    fix: rule.fix,
+    source: 'pack'
+  };
+}
+
+function collectPackIssues(relPath, content, lines, pack) {
+  if (!pack || !Array.isArray(pack.rules) || pack.rules.length === 0) return [];
+  const issues = [];
+  for (let i = 0; i < pack.rules.length; i++) {
+    const rule = pack.rules[i];
+    try {
+      if (!fileMatchesRule(relPath, rule)) continue;
+      const hits = findPackHits(rule, content, lines);
+      for (let h = 0; h < hits.length; h++) {
+        issues.push(packIssue(rule, hits[h]));
+      }
+    } catch (err) {
+      notePackError(pack, `Rejected pack rule ${rule && rule.id ? rule.id : 'rules[' + i + ']'}: pattern failed during scan (${clipDetail(err.message)})`);
+    }
+  }
+  return issues;
+}
+
+function missingPackFields(rule) {
+  const missing = [];
+  if (!rule || typeof rule.id !== 'string' || rule.id.trim() === '') missing.push('id');
+  if (!rule || typeof rule.severity !== 'string' || rule.severity.trim() === '') missing.push('severity');
+  if (!rule || typeof rule.title !== 'string' || rule.title.trim() === '') missing.push('title');
+  if (!rule || typeof rule.pattern !== 'string' || rule.pattern.trim() === '') missing.push('pattern');
+  if (!rule || typeof rule.fix !== 'string' || rule.fix.trim() === '') missing.push('fix');
+  return missing;
+}
+
+function compilePackRule(rule, index, seen) {
+  if (!rule || typeof rule !== 'object' || Array.isArray(rule)) {
+    return { error: 'Rejected pack rule rules[' + index + ']: rule must be an object with id, severity, title, pattern, and fix' };
+  }
+  const missing = missingPackFields(rule);
+  if (missing.length > 0) {
+    return { error: 'Rejected pack rule ' + ruleLabel(rule, index) + ': missing ' + missing.join(', ') };
+  }
+  if (BUILTIN_IDS.has(rule.id)) {
+    return { error: 'Rejected pack rule ' + rule.id + ': duplicate id (matches built-in rule ' + rule.id + ')' };
+  }
+  if (!rule.id.startsWith('custom/') || rule.id === 'custom/' || /\s/.test(rule.id)) {
+    return { error: 'Rejected pack rule ' + rule.id + ': id must start with custom/' };
+  }
+  if (seen.has(rule.id)) {
+    return { error: 'Rejected pack rule ' + rule.id + ': duplicate id' };
+  }
+  seen.add(rule.id);
+  if (!PACK_SEVERITIES.has(rule.severity)) {
+    return { error: 'Rejected pack rule ' + rule.id + ': unknown severity "' + clipDetail(rule.severity) + '" (expected CRITICAL, HIGH, MEDIUM, or LOW)' };
+  }
+  let regex;
+  try {
+    regex = new RegExp(rule.pattern);
+  } catch (err) {
+    return { error: 'Rejected pack rule ' + rule.id + ': bad regex (' + clipDetail(err.message) + ')' };
+  }
+  let files = null;
+  if (rule.files !== undefined) {
+    if (!Array.isArray(rule.files) || rule.files.some((item) => typeof item !== 'string' || item.trim() === '')) {
+      return { error: 'Rejected pack rule ' + rule.id + ': files must be an array of glob strings' };
+    }
+    if (rule.files.length > 0) files = rule.files.slice();
+  }
+  let globs = null;
+  if (files) {
+    try {
+      globs = files.map((item) => globToRegExp(item));
+    } catch (err) {
+      return { error: 'Rejected pack rule ' + rule.id + ': files must be an array of glob strings (' + clipDetail(err.message) + ')' };
+    }
+  }
+  return {
+    rule: {
+      id: rule.id,
+      cat: 'Custom',
+      sev: rule.severity,
+      severity: rule.severity,
+      title: rule.title,
+      pattern: rule.pattern,
+      fix: rule.fix,
+      files: files,
+      globs: globs,
+      regex: regex,
+      source: 'pack'
+    }
+  };
+}
+
+function readRulePack(filePath) {
+  const resolved = path.resolve(filePath);
+  let raw;
+  try {
+    raw = fs.readFileSync(resolved, 'utf8');
+  } catch (err) {
+    if (err && err.code === 'ENOENT') {
+      return { path: resolved, rules: [], errors: ['Pack file not found: ' + resolved], broken: true };
+    }
+    return { path: resolved, rules: [], errors: ['Pack file could not be read: ' + resolved + ' (' + err.message + ')'], broken: true };
+  }
+  let data;
+  try {
+    data = JSON.parse(String(raw).replace(/^\uFEFF/, ''));
+  } catch (err) {
+    return { path: resolved, rules: [], errors: ['Invalid JSON in ' + resolved + ': ' + clipDetail(err.message)], broken: true };
+  }
+  if (!data || typeof data !== 'object' || Array.isArray(data) || !Array.isArray(data.rules)) {
+    return { path: resolved, rules: [], errors: ['Pack ' + resolved + ' must be a JSON object with a "rules" array'], broken: true };
+  }
+  const rules = [];
+  const errors = [];
+  const seen = new Set();
+  for (let i = 0; i < data.rules.length; i++) {
+    const compiled = compilePackRule(data.rules[i], i, seen);
+    if (compiled.error) {
+      errors.push(compiled.error);
+      continue;
+    }
+    rules.push(compiled.rule);
+  }
+  return { path: resolved, rules: rules, errors: errors, broken: false };
+}
+
+function loadRulePack(filePath) {
+  if (typeof filePath !== 'string' || filePath.trim() === '') {
+    return { path: '', rules: [], errors: ['Pack file path must be a non-empty string'], broken: true };
+  }
+  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(filePath)) {
+    return {
+      path: filePath,
+      rules: [],
+      errors: ['Rejected pack ' + filePath + ': rule packs must be local JSON files'],
+      broken: true
+    };
+  }
+  try {
+    return readRulePack(filePath);
+  } catch (err) {
+    return {
+      path: filePath,
+      rules: [],
+      errors: ['Pack ' + filePath + ' failed to load: ' + clipDetail(err.message)],
+      broken: true
+    };
+  }
+}
+
+function resolveScanPack(targetPath, rulesFile) {
+  if (typeof rulesFile === 'string' && rulesFile.trim() !== '') {
+    return loadRulePack(rulesFile);
+  }
+  if (typeof targetPath !== 'string' || targetPath.trim() === '') return null;
+  let root = targetPath;
+  try {
+    const stat = fs.statSync(targetPath);
+    root = stat.isDirectory() ? targetPath : path.dirname(targetPath);
+  } catch (err) {
+    return {
+      path: targetPath,
+      rules: [],
+      errors: ['Pack auto-load failed for ' + targetPath + ': ' + err.message],
+      broken: true
+    };
+  }
+  const candidate = path.join(root, '.plumber-rules.json');
+  try {
+    const stat = fs.statSync(candidate);
+    if (!stat.isFile()) {
+      return {
+        path: candidate,
+        rules: [],
+        errors: ['Pack file is not a file: ' + candidate],
+        broken: true
+      };
+    }
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return null;
+    return {
+      path: candidate,
+      rules: [],
+      errors: ['Pack file could not be read: ' + candidate + ' (' + err.message + ')'],
+      broken: true
+    };
+  }
+  return loadRulePack(candidate);
+}
+
 module.exports = {
   RULES,
   SEV_WEIGHT,
   SCANNABLE_EXTS,
   scanLocalDirectory,
-  scanText
+  scanText,
+  loadRulePack,
+  resolveScanPack
 };