awguard 1.5.0 → 1.7.0

package/src/cli.js

@@ -1,14 +1,33 @@
 import process from 'node:process';
 import fs from 'node:fs';
 import path from 'node:path';
-import { applyBaseline, createBaseline, loadBaseline, writeBaseline } from './baseline.js';
+import { applyAutofixPlan, buildAutofixPlan, renderAutofixPlan } from './autofix.js';
+import {
+  applyBaseline,
+  createBaseline,
+  loadBaseline,
+  pruneBaseline,
+  renderBaselineReview,
+  reviewBaseline,
+  writeBaseline
+} from './baseline.js';
+import { renderBadgeSnippets } from './badges.js';
+import { loadReport, renderComparison, renderComparisonJson } from './compare.js';
+import { renderDemoWalkthrough } from './demo.js';
 import { loadConfig } from './config.js';
+import { buildDoctorReport, renderDoctorReport } from './doctor.js';
+import { renderRuleExplanation } from './explain.js';
+import { renderInitGuide } from './init.js';
+import { renderPolicyPack } from './policy-packs.js';
+import { buildPolicyWizard, renderPolicyWizard } from './policy-wizard.js';
 import { renderFixDryRun } from './remediation.js';
 import { scanWorkflows, severityRank } from './scanner.js';
+import { renderTemplates } from './templates.js';
 import {
   renderBadge,
   renderGithubAnnotations,
   renderGraph,
+  renderGithubStepSummary,
   renderHtml,
   renderJson,
   renderMarkdown,
@@ -16,15 +35,35 @@ import {
   renderSarif,
   renderScore,
   renderSurfaceInventory,
+  renderSurfaceInventoryJson,
   renderText
 } from './reporters.js';
 
 const HELP = `Agentic Workflow Guard
 
 Usage:
-  awguard [path] [--config file] [--preset name] [--format text|json|markdown|github|sarif|graph|html|migration|score|badge|inventory] [--output file] [--baseline file] [--write-baseline file] [--fix-dry-run] [--fail-on none|low|medium|high|critical]
+  awguard [path] [--config file] [--preset name] [--format text|json|markdown|github|sarif|graph|html|migration|score|badge|inventory|inventory-json] [--output file] [--baseline file] [--write-baseline file] [--fix-dry-run] [--fix] [--fail-on none|low|medium|high|critical]
+  awguard init
+  awguard doctor [path] [--config file] [--preset name]
+  awguard explain [AWG###]
+  awguard badges [--repo OWNER/REPO] [--branch main] [--badge-file docs/awguard-badge.json] [--site URL]
+  awguard demo
+  awguard templates [all|github|code-scanning|gitlab|pre-commit|vscode]
+  awguard policy-pack [oss|strict|enterprise]
+  awguard policy-wizard [path] [--config file] [--preset name] [--dry-run] [--format markdown|json] [--output file]
+  awguard baseline-review [path] --baseline file [--config file] [--preset name] [--format text|json] [--prune]
+  awguard --compare previous.json current.json
 
 Examples:
+  awguard init
+  awguard doctor
+  awguard explain AWG001
+  awguard badges --repo OWNER/REPO --site https://OWNER.github.io/REPO/
+  awguard demo
+  awguard templates github
+  awguard policy-pack strict
+  awguard policy-wizard . --dry-run
+  awguard baseline-review . --baseline awguard.baseline.json
   awguard .
   awguard .mcp.json
   awguard . --config awguard.config.json
@@ -33,16 +72,92 @@ Examples:
   awguard . --format html --output awguard-report.html
   awguard . --format migration --output awguard-migration.md
   awguard . --format inventory
+  awguard . --format inventory-json --output awguard-inventory.json
   awguard . --format score
   awguard . --format badge --output awguard-badge.json
   awguard . --fix-dry-run
+  awguard . --fix
   awguard . --format sarif --output awguard.sarif --fail-on none
   awguard . --write-baseline awguard.baseline.json
   awguard . --baseline awguard.baseline.json --fail-on high
+  awguard --compare old-awguard.json new-awguard.json
   awguard . --format github --fail-on medium
 `;
 
 export async function runCli(args, env = process.env) {
+  if (args[0] === 'init') {
+    console.log(renderInitGuide());
+    return;
+  }
+
+  if (args[0] === 'doctor') {
+    const options = parseArgs(args.slice(1), env);
+    const report = buildDoctorReport({
+      root: options.path,
+      configPath: options.config,
+      presets: options.presets,
+      env
+    });
+    console.log(renderDoctorReport(report));
+    if (report.status === 'fail') process.exitCode = 1;
+    return;
+  }
+
+  if (args[0] === 'explain') {
+    console.log(renderRuleExplanation(args[1]));
+    return;
+  }
+
+  if (args[0] === 'badges') {
+    console.log(renderBadgeSnippets(parseBadgeArgs(args.slice(1))));
+    return;
+  }
+
+  if (args[0] === 'demo') {
+    console.log(renderDemoWalkthrough());
+    return;
+  }
+
+  if (args[0] === 'templates') {
+    console.log(renderTemplates(args[1] || 'all'));
+    return;
+  }
+
+  if (args[0] === 'policy-pack') {
+    console.log(renderPolicyPack(args[1] || 'oss'));
+    return;
+  }
+
+  if (args[0] === 'policy-wizard') {
+    const options = parsePolicyWizardArgs(args.slice(1));
+    const loaded = loadConfig({ configPath: options.config, root: options.path, presets: options.presets });
+    const result = scanWorkflows({ root: options.path, config: loaded.config });
+    const wizard = buildPolicyWizard(result, { existingConfig: loaded.path ? JSON.parse(fs.readFileSync(loaded.path, 'utf8')) : {} });
+    const output = renderPolicyWizard(wizard, { format: options.format });
+    if (options.output && !options.dryRun) {
+      const outputFile = writeOutput(options.output, `${output}\n`);
+      console.error(`Wrote ${outputFile}`);
+    } else {
+      console.log(output);
+    }
+    return;
+  }
+
+  if (args[0] === 'baseline-review') {
+    const options = parseBaselineReviewArgs(args.slice(1));
+    if (!options.baseline) throw new Error('baseline-review requires --baseline file');
+    const { config } = loadConfig({ configPath: options.config, root: options.path, presets: options.presets });
+    const result = scanWorkflows({ root: options.path, config });
+    const baseline = loadBaseline(options.baseline);
+    const review = reviewBaseline(result, baseline);
+    if (options.prune) {
+      writeBaseline(options.baseline, pruneBaseline(baseline, review));
+    }
+    console.log(renderBaselineReview(review, { format: options.format, baselineFile: options.baseline }));
+    if (options.prune && options.format !== 'json') console.error(`Pruned baseline ${path.resolve(options.baseline)}`);
+    return;
+  }
+
   const options = parseArgs(args, env);
 
   if (options.help) {
@@ -50,6 +165,19 @@ export async function runCli(args, env = process.env) {
     return;
   }
 
+  if (options.compare.length > 0) {
+    const previous = loadReport(options.compare[0]);
+    const current = loadReport(options.compare[1]);
+    const output = options.format === 'json' ? renderComparisonJson(previous, current) : renderComparison(previous, current);
+    if (options.output) {
+      const outputFile = writeOutput(options.output, output);
+      console.error(`Wrote ${outputFile}`);
+    } else {
+      console.log(output);
+    }
+    return;
+  }
+
   const { config } = loadConfig({ configPath: options.config, root: options.path, presets: options.presets });
   let result = scanWorkflows({ root: options.path, config });
 
@@ -62,15 +190,24 @@ export async function runCli(args, env = process.env) {
     console.error(`Wrote baseline ${baselineFile}`);
   }
 
-  const output = options.fixDryRun ? renderFixDryRun(result) : render(result, options.format);
+  if (options.fix) {
+    const plan = applyAutofixPlan(buildAutofixPlan(result));
+    console.log(renderAutofixPlan(plan, { applied: true }));
+    return;
+  }
+
+  const output = options.fixDryRun ? renderFixDryRun(result, { autofixPlan: buildAutofixPlan(result) }) : render(result, options.format);
 
+  let outputFile = '';
   if (options.output) {
-    const outputFile = writeOutput(options.output, output);
+    outputFile = writeOutput(options.output, output);
     console.error(`Wrote ${outputFile}`);
   } else if (output.trim().length > 0) {
     console.log(output);
   }
 
+  writeGithubStepSummary({ env, result, options, outputFile });
+
   const findingsToFailOn = result.findings.filter((finding) => finding.baselineState !== 'known');
   if (shouldFail(findingsToFailOn, options.failOn)) {
     process.exitCode = 1;
@@ -87,8 +224,10 @@ export function parseArgs(args, env = {}) {
     baseline: readInput(env, 'baseline') || '',
     writeBaseline: readInput(env, 'write_baseline') || readInput(env, 'write-baseline') || '',
     config: readInput(env, 'config') || '',
+    compare: [],
     presets: splitList(readInput(env, 'preset') || readInput(env, 'presets') || ''),
     fixDryRun: readBoolInput(env, 'fix_dry_run') || readBoolInput(env, 'fix-dry-run'),
+    fix: readBoolInput(env, 'fix'),
     help: false
   };
 
@@ -121,12 +260,18 @@ export function parseArgs(args, env = {}) {
       options.config = args[++index];
     } else if (arg.startsWith('--config=')) {
       options.config = arg.slice('--config='.length);
+    } else if (arg === '--compare') {
+      options.compare = [args[++index], args[++index]].filter(Boolean);
+    } else if (arg.startsWith('--compare=')) {
+      options.compare = arg.slice('--compare='.length).split(',').map((item) => item.trim()).filter(Boolean);
     } else if (arg === '--preset') {
       options.presets.push(...splitList(args[++index]));
     } else if (arg.startsWith('--preset=')) {
       options.presets.push(...splitList(arg.slice('--preset='.length)));
     } else if (arg === '--fix-dry-run') {
       options.fixDryRun = true;
+    } else if (arg === '--fix') {
+      options.fix = true;
     } else if (!arg.startsWith('-')) {
       options.path = arg;
     } else {
@@ -145,9 +290,13 @@ export function parseArgs(args, env = {}) {
     'migration',
     'score',
     'badge',
-    'inventory'
+    'inventory',
+    'inventory-json'
   ]);
   validateEnum('fail-on', options.failOn, ['none', 'low', 'medium', 'high', 'critical']);
+  if (options.compare.length !== 0 && options.compare.length !== 2) {
+    throw new Error('--compare requires two awguard --format json report files');
+  }
 
   return options;
 }
@@ -167,6 +316,7 @@ function render(result, format) {
   if (format === 'score') return renderScore(result);
   if (format === 'badge') return renderBadge(result);
   if (format === 'inventory') return renderSurfaceInventory(result);
+  if (format === 'inventory-json') return renderSurfaceInventoryJson(result);
   if (format === 'github') return renderGithubAnnotations(result);
   return renderText(result);
 }
@@ -183,6 +333,119 @@ function readBoolInput(env, name) {
   return value === 'true' || value === '1' || value === 'yes';
 }
 
+function parsePolicyWizardArgs(args) {
+  const options = {
+    path: '.',
+    config: '',
+    presets: [],
+    dryRun: false,
+    format: 'markdown',
+    formatSpecified: false,
+    output: ''
+  };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === '--config') {
+      options.config = args[++index];
+    } else if (arg.startsWith('--config=')) {
+      options.config = arg.slice('--config='.length);
+    } else if (arg === '--preset') {
+      options.presets.push(...splitList(args[++index]));
+    } else if (arg.startsWith('--preset=')) {
+      options.presets.push(...splitList(arg.slice('--preset='.length)));
+    } else if (arg === '--dry-run') {
+      options.dryRun = true;
+    } else if (arg === '--format') {
+      options.format = args[++index];
+      options.formatSpecified = true;
+    } else if (arg.startsWith('--format=')) {
+      options.format = arg.slice('--format='.length);
+      options.formatSpecified = true;
+    } else if (arg === '--output') {
+      options.output = args[++index];
+    } else if (arg.startsWith('--output=')) {
+      options.output = arg.slice('--output='.length);
+    } else if (!arg.startsWith('-')) {
+      options.path = arg;
+    } else {
+      throw new Error(`unknown policy-wizard option: ${arg}`);
+    }
+  }
+
+  if (options.output && !options.formatSpecified) options.format = 'json';
+  validateEnum('policy-wizard format', options.format, ['markdown', 'json']);
+  return options;
+}
+
+function parseBaselineReviewArgs(args) {
+  const options = {
+    path: '.',
+    baseline: '',
+    config: '',
+    presets: [],
+    format: 'text',
+    prune: false
+  };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === '--baseline') {
+      options.baseline = args[++index];
+    } else if (arg.startsWith('--baseline=')) {
+      options.baseline = arg.slice('--baseline='.length);
+    } else if (arg === '--config') {
+      options.config = args[++index];
+    } else if (arg.startsWith('--config=')) {
+      options.config = arg.slice('--config='.length);
+    } else if (arg === '--preset') {
+      options.presets.push(...splitList(args[++index]));
+    } else if (arg.startsWith('--preset=')) {
+      options.presets.push(...splitList(arg.slice('--preset='.length)));
+    } else if (arg === '--format') {
+      options.format = args[++index];
+    } else if (arg.startsWith('--format=')) {
+      options.format = arg.slice('--format='.length);
+    } else if (arg === '--prune') {
+      options.prune = true;
+    } else if (!arg.startsWith('-')) {
+      options.path = arg;
+    } else {
+      throw new Error(`unknown baseline-review option: ${arg}`);
+    }
+  }
+
+  validateEnum('baseline-review format', options.format, ['text', 'json']);
+  return options;
+}
+
+function parseBadgeArgs(args) {
+  const options = {};
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === '--repo') {
+      options.repo = args[++index];
+    } else if (arg.startsWith('--repo=')) {
+      options.repo = arg.slice('--repo='.length);
+    } else if (arg === '--branch') {
+      options.branch = args[++index];
+    } else if (arg.startsWith('--branch=')) {
+      options.branch = arg.slice('--branch='.length);
+    } else if (arg === '--badge-file') {
+      options.badgeFile = args[++index];
+    } else if (arg.startsWith('--badge-file=')) {
+      options.badgeFile = arg.slice('--badge-file='.length);
+    } else if (arg === '--site') {
+      options.site = args[++index];
+    } else if (arg.startsWith('--site=')) {
+      options.site = arg.slice('--site='.length);
+    } else {
+      throw new Error(`unknown badges option: ${arg}`);
+    }
+  }
+  return options;
+}
+
 function writeOutput(file, output) {
   const absoluteFile = path.resolve(file);
   fs.mkdirSync(path.dirname(absoluteFile), { recursive: true });
@@ -190,6 +453,19 @@ function writeOutput(file, output) {
   return absoluteFile;
 }
 
+function writeGithubStepSummary({ env, result, options, outputFile }) {
+  if (env.GITHUB_ACTIONS !== 'true' || !env.GITHUB_STEP_SUMMARY) return;
+
+  try {
+    fs.appendFileSync(
+      env.GITHUB_STEP_SUMMARY,
+      `${renderGithubStepSummary(result, { format: options.format, failOn: options.failOn, outputFile })}\n`
+    );
+  } catch (error) {
+    console.error(`awguard: could not write GitHub job summary: ${error.message}`);
+  }
+}
+
 function shouldFail(findings, threshold) {
   if (threshold === 'none') return false;
   const thresholdRank = severityRank[threshold];

package/src/compare.js

@@ -0,0 +1,166 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { classifyScanFile } from './scanner.js';
+
+const surfaceLabels = {
+  'github-workflow': 'GitHub Actions workflows',
+  'agent-context': 'Agent context files',
+  'mcp-config': 'MCP configs',
+  other: 'Other scanned files'
+};
+
+export function loadReport(file) {
+  const absoluteFile = path.resolve(file);
+  if (!fs.existsSync(absoluteFile)) {
+    throw new Error(`report file does not exist: ${absoluteFile}`);
+  }
+
+  const report = JSON.parse(fs.readFileSync(absoluteFile, 'utf8'));
+  if (!Array.isArray(report.findings) || !Array.isArray(report.scannedFiles)) {
+    throw new Error(`report file must be awguard --format json output: ${absoluteFile}`);
+  }
+
+  return report;
+}
+
+export function buildComparison(previous, current) {
+  const previousFindings = mapByFingerprint(previous.findings);
+  const currentFindings = mapByFingerprint(current.findings);
+  const previousFiles = new Set(previous.scannedFiles || []);
+  const currentFiles = new Set(current.scannedFiles || []);
+
+  const introducedFindings = [...currentFindings.entries()]
+    .filter(([fingerprint]) => !previousFindings.has(fingerprint))
+    .map(([, finding]) => finding);
+  const resolvedFindings = [...previousFindings.entries()]
+    .filter(([fingerprint]) => !currentFindings.has(fingerprint))
+    .map(([, finding]) => finding);
+  const unchangedFindings = [...currentFindings.keys()].filter((fingerprint) => previousFindings.has(fingerprint));
+  const addedFiles = [...currentFiles].filter((file) => !previousFiles.has(file)).sort();
+  const removedFiles = [...previousFiles].filter((file) => !currentFiles.has(file)).sort();
+  const addedSurfaces = groupFilesBySurface(addedFiles, current.root || previous.root);
+  const removedSurfaces = groupFilesBySurface(removedFiles, previous.root || current.root);
+
+  return {
+    summary: {
+      previousFindings: previous.findings.length,
+      currentFindings: current.findings.length,
+      introducedFindings: introducedFindings.length,
+      resolvedFindings: resolvedFindings.length,
+      unchangedFindings: unchangedFindings.length,
+      addedFiles: addedFiles.length,
+      removedFiles: removedFiles.length,
+      addedSurfaces: addedSurfaces.length,
+      removedSurfaces: removedSurfaces.length
+    },
+    introducedFindings,
+    resolvedFindings,
+    addedFiles,
+    removedFiles,
+    addedSurfaces,
+    removedSurfaces
+  };
+}
+
+export function renderComparison(previous, current) {
+  const comparison = buildComparison(previous, current);
+  const lines = [
+    '# Agentic Workflow Guard Comparison',
+    '',
+    `Previous findings: **${comparison.summary.previousFindings}**`,
+    `Current findings: **${comparison.summary.currentFindings}**`,
+    `Introduced findings: **${comparison.summary.introducedFindings}**`,
+    `Resolved findings: **${comparison.summary.resolvedFindings}**`,
+    `Unchanged findings: **${comparison.summary.unchangedFindings}**`,
+    `Added scanned files: **${comparison.summary.addedFiles}**`,
+    `Removed scanned files: **${comparison.summary.removedFiles}**`,
+    ''
+  ];
+
+  lines.push('## Introduced Findings', '');
+  appendFindings(lines, comparison.introducedFindings);
+  lines.push('', '## Resolved Findings', '');
+  appendFindings(lines, comparison.resolvedFindings);
+  lines.push('', '## Added Agentic Surfaces', '');
+  appendSurfaces(lines, comparison.addedSurfaces);
+  lines.push('', '## Removed Agentic Surfaces', '');
+  appendSurfaces(lines, comparison.removedSurfaces);
+  lines.push('', '## Added Files', '');
+  appendFiles(lines, comparison.addedFiles);
+  lines.push('', '## Removed Files', '');
+  appendFiles(lines, comparison.removedFiles);
+
+  return lines.join('\n');
+}
+
+export function renderComparisonJson(previous, current) {
+  return JSON.stringify(buildComparison(previous, current), null, 2);
+}
+
+function appendFindings(lines, findings) {
+  if (findings.length === 0) {
+    lines.push('None.');
+    return;
+  }
+
+  lines.push('| Severity | Rule | Location | Finding |');
+  lines.push('| --- | --- | --- | --- |');
+  for (const finding of findings) {
+    lines.push(
+      `| ${escapeMarkdown(finding.severity)} | ${escapeMarkdown(finding.ruleId)} | ${escapeMarkdown(
+        `${finding.file}:${finding.line}`
+      )} | ${escapeMarkdown(finding.title)} |`
+    );
+  }
+}
+
+function appendFiles(lines, files) {
+  if (files.length === 0) {
+    lines.push('None.');
+    return;
+  }
+
+  for (const file of files) {
+    lines.push(`- \`${file.replaceAll('`', '\\`')}\``);
+  }
+}
+
+function appendSurfaces(lines, surfaces) {
+  if (surfaces.length === 0) {
+    lines.push('None.');
+    return;
+  }
+
+  lines.push('| Surface | Files |');
+  lines.push('| --- | ---: |');
+  for (const surface of surfaces) {
+    lines.push(`| ${escapeMarkdown(surface.label)} | ${surface.files.length} |`);
+  }
+}
+
+function mapByFingerprint(findings) {
+  return new Map(findings.map((finding) => [finding.fingerprint || `${finding.ruleId}:${finding.file}:${finding.line}`, finding]));
+}
+
+function groupFilesBySurface(files, root = process.cwd()) {
+  const groups = new Map();
+  for (const file of files) {
+    const surface = classifyScanFile(file, root || process.cwd());
+    if (!groups.has(surface)) {
+      groups.set(surface, {
+        surface,
+        label: surfaceLabels[surface] || surfaceLabels.other,
+        files: []
+      });
+    }
+    groups.get(surface).files.push(file);
+  }
+
+  return [...groups.values()]
+    .map((group) => ({ ...group, files: group.files.sort() }))
+    .sort((a, b) => a.label.localeCompare(b.label));
+}
+
+function escapeMarkdown(value) {
+  return String(value).replaceAll('|', '\\|');
+}

package/src/config.js

@@ -33,7 +33,9 @@ export function normalizeConfig(rawConfig = {}, source = 'config') {
 
   return {
     rules: normalizeRules(mergedConfig.rules || {}, source),
-    suppressions: normalizeSuppressions(mergedConfig.suppressions || {}, source)
+    suppressions: normalizeSuppressions(mergedConfig.suppressions || {}, source),
+    policy: normalizePolicy(mergedConfig.policy || {}, source),
+    scan: normalizeScan(mergedConfig.scan || {}, source)
   };
 }
 
@@ -51,7 +53,9 @@ function mergePresetConfigs(rawConfig, source) {
 
   return mergeConfigObjects(merged, {
     rules: rawConfig.rules || {},
-    suppressions: rawConfig.suppressions || {}
+    suppressions: rawConfig.suppressions || {},
+    policy: rawConfig.policy || {},
+    scan: rawConfig.scan || {}
   });
 }
 
@@ -64,6 +68,14 @@ function mergeConfigObjects(base, override) {
     suppressions: {
       ...(base.suppressions || {}),
       ...(override.suppressions || {})
+    },
+    policy: {
+      ...(base.policy || {}),
+      ...(override.policy || {})
+    },
+    scan: {
+      ...(base.scan || {}),
+      ...(override.scan || {})
     }
   };
 }
@@ -149,6 +161,50 @@ function normalizeSuppressions(suppressions, source) {
   };
 }
 
+function normalizePolicy(policy, source) {
+  if (!isObject(policy)) {
+    throw new Error(`${source} policy must be an object`);
+  }
+
+  return {
+    approvedFiles: normalizeStringArray(policy.approvedFiles || [], `${source} policy.approvedFiles`),
+    approvedMcpServers: normalizeStringArray(policy.approvedMcpServers || [], `${source} policy.approvedMcpServers`),
+    approvedMcpPackages: normalizeStringArray(policy.approvedMcpPackages || [], `${source} policy.approvedMcpPackages`),
+    approvedMcpPackageScopes: normalizeStringArray(policy.approvedMcpPackageScopes || [], `${source} policy.approvedMcpPackageScopes`),
+    approvedMcpCommands: normalizeStringArray(policy.approvedMcpCommands || [], `${source} policy.approvedMcpCommands`)
+  };
+}
+
+function normalizeScan(scan, source) {
+  if (!isObject(scan)) {
+    throw new Error(`${source} scan must be an object`);
+  }
+
+  return {
+    include: normalizeStringArray(scan.include || [], `${source} scan.include`),
+    exclude: normalizeStringArray(scan.exclude || [], `${source} scan.exclude`),
+    maxFiles: normalizeOptionalPositiveInteger(scan.maxFiles, `${source} scan.maxFiles`),
+    maxFileBytes: normalizeOptionalPositiveInteger(scan.maxFileBytes, `${source} scan.maxFileBytes`)
+  };
+}
+
+function normalizeOptionalPositiveInteger(value, source) {
+  if (value === undefined || value === null || value === '') return undefined;
+  const number = Number(value);
+  if (!Number.isInteger(number) || number < 1) {
+    throw new Error(`${source} must be a positive integer`);
+  }
+  return number;
+}
+
+function normalizeStringArray(value, source) {
+  if (!Array.isArray(value)) {
+    throw new Error(`${source} must be an array`);
+  }
+
+  return value.map((item) => String(item));
+}
+
 function ensureKnownRule(ruleId, source) {
   if (!ruleCatalog[ruleId]) {
     throw new Error(`${source} references unknown rule id: ${ruleId}`);