awguard 1.6.0 → 1.7.0

package/src/doctor.js

@@ -0,0 +1,189 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+import { loadConfig } from './config.js';
+import { scanWorkflows } from './scanner.js';
+
+const schemaPath = 'schemas/awguard.config.schema.json';
+
+export function buildDoctorReport({ root = '.', configPath = '', presets = [], env = process.env } = {}) {
+  const checks = [];
+  const packageInfo = readPackageInfo();
+  const packageRoot = getPackageRoot();
+
+  addCheck(
+    checks,
+    nodeMajor(process.version) >= 20 ? 'ok' : 'fail',
+    'Node.js runtime',
+    `${process.version} detected; AWGuard requires Node.js 20 or newer.`,
+    'Install a current Node.js release before running AWGuard.'
+  );
+
+  addCheck(
+    checks,
+    packageInfo.version ? 'ok' : 'warn',
+    'AWGuard package metadata',
+    packageInfo.version ? `awguard ${packageInfo.version}` : 'Could not read package.json version.',
+    'Reinstall the package if this command is running from a broken checkout.'
+  );
+
+  const absoluteRoot = path.resolve(root);
+  if (!fs.existsSync(absoluteRoot)) {
+    addCheck(
+      checks,
+      'fail',
+      'Scan target',
+      `Target does not exist: ${absoluteRoot}`,
+      'Pass a repository directory, workflow file, agent instruction file, or MCP config file.'
+    );
+    return finish(checks);
+  }
+
+  const targetStat = fs.statSync(absoluteRoot);
+  addCheck(
+    checks,
+    targetStat.isDirectory() || targetStat.isFile() ? 'ok' : 'fail',
+    'Scan target',
+    `${absoluteRoot} is a ${targetStat.isDirectory() ? 'directory' : targetStat.isFile() ? 'file' : 'special file'}.`,
+    'Pass a regular file or directory.'
+  );
+
+  let configResult;
+  try {
+    configResult = loadConfig({ configPath, root: absoluteRoot, presets });
+    addCheck(
+      checks,
+      'ok',
+      'Configuration',
+      configResult.path
+        ? `Loaded ${path.relative(process.cwd(), configResult.path) || configResult.path}.`
+        : 'No config file found; using defaults and CLI presets.',
+      `Add "$schema": "https://raw.githubusercontent.com/Mughal-Baig/agentic-workflow-guard/main/${schemaPath}" to awguard.config.json for editor validation.`
+    );
+  } catch (error) {
+    addCheck(checks, 'fail', 'Configuration', error.message, 'Fix the config file or run without --config.');
+    return finish(checks);
+  }
+
+  addCheck(
+    checks,
+    fs.existsSync(path.join(packageRoot, schemaPath)) ? 'ok' : 'warn',
+    'Config schema',
+    `Schema path: ${schemaPath}`,
+    'Publish package files with the schemas directory included.'
+  );
+
+  let result;
+  try {
+    result = scanWorkflows({ root: absoluteRoot, config: configResult.config });
+  } catch (error) {
+    addCheck(checks, 'fail', 'Scanner smoke test', error.message, 'Check file permissions and scan target contents.');
+    return finish(checks);
+  }
+
+  if (result.scannedFiles.length === 0) {
+    addCheck(
+      checks,
+      'warn',
+      'Scanner smoke test',
+      'No GitHub Actions workflow, agent instruction, or MCP config files were found.',
+      'Run AWGuard again after adding agent workflows, AGENTS.md-style files, or MCP configs.'
+    );
+  } else {
+    const findingText =
+      result.findings.length === 0
+        ? 'no findings'
+        : `${result.findings.length} finding(s), highest severity ${result.summary.highest}`;
+    addCheck(
+      checks,
+      result.findings.length === 0 ? 'ok' : 'warn',
+      'Scanner smoke test',
+      `Scanned ${result.scannedFiles.length} file(s); ${findingText}.`,
+      'Use --format score, --format inventory, or --format sarif for CI-ready reports.'
+    );
+  }
+
+  if (env.GITHUB_ACTIONS === 'true') {
+    addCheck(
+      checks,
+      env.GITHUB_STEP_SUMMARY ? 'ok' : 'warn',
+      'GitHub Actions summary',
+      env.GITHUB_STEP_SUMMARY
+        ? 'GITHUB_STEP_SUMMARY is available for job summary output.'
+        : 'GITHUB_STEP_SUMMARY is not available in this environment.',
+      'Run inside a modern GitHub Actions job to receive the Markdown job summary.'
+    );
+  }
+
+  return finish(checks);
+}
+
+export function renderDoctorReport(report) {
+  const lines = [
+    '# Agentic Workflow Guard Doctor',
+    '',
+    `Status: **${report.status.toUpperCase()}**`,
+    '',
+    '| Check | Status | Detail |',
+    '| --- | --- | --- |'
+  ];
+
+  for (const check of report.checks) {
+    lines.push(`| ${escapeMarkdown(check.title)} | ${statusLabel(check.status)} | ${escapeMarkdown(check.detail)} |`);
+  }
+
+  const nextSteps = report.checks.filter((check) => check.status !== 'ok' && check.nextStep);
+  if (nextSteps.length > 0) {
+    lines.push('', '## Next Steps', '');
+    for (const check of nextSteps) {
+      lines.push(`- ${check.title}: ${check.nextStep}`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+function addCheck(checks, status, title, detail, nextStep = '') {
+  checks.push({ status, title, detail, nextStep });
+}
+
+function finish(checks) {
+  return {
+    status: checks.some((check) => check.status === 'fail')
+      ? 'fail'
+      : checks.some((check) => check.status === 'warn')
+        ? 'warn'
+        : 'ok',
+    checks
+  };
+}
+
+function nodeMajor(version) {
+  const match = String(version).match(/^v?(\d+)/);
+  return match ? Number(match[1]) : 0;
+}
+
+function readPackageInfo() {
+  const packageFile = path.join(getPackageRoot(), 'package.json');
+  try {
+    return JSON.parse(fs.readFileSync(packageFile, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function getPackageRoot() {
+  const sourceDir = path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(sourceDir, '..');
+}
+
+function statusLabel(status) {
+  if (status === 'ok') return 'OK';
+  if (status === 'warn') return 'WARN';
+  return 'FAIL';
+}
+
+function escapeMarkdown(value) {
+  return String(value).replaceAll('|', '\\|').replaceAll('\n', ' ');
+}

package/src/explain.js

@@ -0,0 +1,147 @@
+import { ruleCatalog } from './scanner.js';
+
+const ruleDetails = {
+  AWG001: {
+    detects: 'User-controlled GitHub issue, pull request, comment, branch, or event text reaching an AI prompt.',
+    why: 'The model may treat attacker-supplied text as instructions and use privileged tools or repository context.',
+    safePattern: 'Delimit untrusted text, keep the job read-only, and require human review before any write action.'
+  },
+  AWG002: {
+    detects: 'Untrusted GitHub context interpolated directly into shell scripts.',
+    why: 'Shell interpolation can turn event text into command execution or argument injection.',
+    safePattern: 'Move values into environment variables and reference them with shell quoting.'
+  },
+  AWG003: {
+    detects: 'pull_request_target workflows that check out pull request head code.',
+    why: 'Untrusted fork code can run with base-repository privileges.',
+    safePattern: 'Use pull_request for untrusted code or keep pull_request_target limited to metadata-only work.'
+  },
+  AWG004: {
+    detects: 'Agent jobs with broad write-capable GitHub token permissions.',
+    why: 'Prompt injection becomes much more damaging when the agent can write repository state.',
+    safePattern: 'Use contents: read by default and isolate write actions behind a reviewed apply job.'
+  },
+  AWG005: {
+    detects: 'Secrets exposed to workflows driven by untrusted agent input.',
+    why: 'An attacker can steer the agent or scripts into revealing credentials.',
+    safePattern: 'Keep secrets out of untrusted event workflows and use a separate approved privileged workflow.'
+  },
+  AWG006: {
+    detects: 'Agent command flags that skip approvals or permission prompts.',
+    why: 'Autonomous execution removes the human gate that normally stops unsafe tool use.',
+    safePattern: 'Require confirmation for file writes, command execution, and repository changes.'
+  },
+  AWG007: {
+    detects: 'Model or agent output flowing into eval, shell, or pipe-to-shell execution.',
+    why: 'Model output is data, not trusted code.',
+    safePattern: 'Validate structured output with a narrow parser before using it.'
+  },
+  AWG008: {
+    detects: 'Agent workflows without explicit permissions.',
+    why: 'Default permissions are easy to misunderstand and can drift as repository settings change.',
+    safePattern: 'Declare the minimum required permissions in every agent workflow.'
+  },
+  AWG009: {
+    detects: 'workflow_run jobs that consume artifacts before scripts execute.',
+    why: 'Artifacts can carry untrusted content from an earlier workflow into a more privileged job.',
+    safePattern: 'Verify artifact provenance, names, checksums, and expected schema before use.'
+  },
+  AWG010: {
+    detects: 'Third-party actions that are not pinned to commit SHAs in sensitive agent workflows.',
+    why: 'Mutable tags can change behavior after review.',
+    safePattern: 'Pin third-party actions to reviewed commit SHAs.'
+  },
+  AWG011: {
+    detects: 'Suppression comments that are malformed, unjustified, or disallowed by config.',
+    why: 'Weak suppressions can hide real agentic workflow risk.',
+    safePattern: 'Use narrow rule IDs and a clear reviewed false-positive reason.'
+  },
+  AWG012: {
+    detects: 'Persistent agent instructions that weaken approval, permission, or secret boundaries.',
+    why: 'Instruction files are durable context that can affect future agent runs.',
+    safePattern: 'Keep repository instructions conservative and explicit about human review.'
+  },
+  AWG013: {
+    detects: 'MCP configs that start mutable packages, unpinned containers, or shell wrappers.',
+    why: 'MCP servers expand agent tool authority before runtime scanners can inspect behavior.',
+    safePattern: 'Pin packages/images and avoid shell wrappers for project-scoped MCP servers.'
+  },
+  AWG014: {
+    detects: 'MCP configs that hardcode credentials or authorization material.',
+    why: 'Committed secrets can be used by anyone with repository access and may be exposed by agents.',
+    safePattern: 'Move credentials into prompts, environment variables, or a secret manager.'
+  },
+  AWG015: {
+    detects: 'Agentic files, MCP servers, packages, or commands outside configured policy allowlists.',
+    why: 'New agent surfaces should be visible in review before they gain trust.',
+    safePattern: 'Approve only reviewed files, servers, packages, and commands.'
+  },
+  AWG016: {
+    detects: 'actions/checkout credentials persisting in elevated agent workflows.',
+    why: 'Persisted checkout credentials can give later agent or shell steps repository write access.',
+    safePattern: 'Use persist-credentials: false and keep writeback in a separate reviewed job.'
+  },
+  AWG017: {
+    detects: 'Agent jobs with write permissions that commit, tag, publish, or push without a reviewable boundary.',
+    why: 'Autonomous writeback can change protected repository state before a maintainer reviews the result.',
+    safePattern: 'Push to an isolated branch, open a draft pull request, or upload artifacts for a human apply step.'
+  },
+  AWG018: {
+    detects: 'Untrusted GitHub event text flowing into MCP tool arguments or environment variables.',
+    why: 'MCP tools can bridge prompt input into external systems, so injected text can become tool instructions.',
+    safePattern: 'Treat event text as untrusted data, sanitize it, and require review before passing it to MCP tools.'
+  },
+  AWG019: {
+    detects: 'MCP package specs outside configured trusted package scopes.',
+    why: 'Project-scoped MCP packages expand agent capability, so publisher reputation should be reviewed before trust is granted.',
+    safePattern: 'Keep trusted package scopes narrow, pin approved packages, and document the review in policy.'
+  }
+};
+
+export function renderRuleExplanation(ruleId = '') {
+  const normalizedRuleId = String(ruleId || '').toUpperCase();
+  if (!normalizedRuleId) return renderRuleIndex();
+
+  const rule = ruleCatalog[normalizedRuleId];
+  if (!rule) {
+    throw new Error(`unknown rule id: ${normalizedRuleId}. Use awguard explain to list available rules.`);
+  }
+
+  const details = ruleDetails[normalizedRuleId] || {};
+  return [
+    `# ${normalizedRuleId}: ${rule.title}`,
+    '',
+    `Severity: **${rule.severity}**`,
+    '',
+    `Remediation code: \`${rule.remediationCode}\``,
+    '',
+    `Detects: ${details.detects || rule.title}`,
+    '',
+    `Why it matters: ${details.why || 'This pattern can increase agentic workflow risk.'}`,
+    '',
+    `Safe pattern: ${details.safePattern || rule.suggestion}`,
+    '',
+    `Suggested fix: ${rule.suggestion}`,
+    '',
+    'Useful commands:',
+    '',
+    '```bash',
+    'npx awguard@latest . --format inventory',
+    'npx awguard@latest . --fix-dry-run',
+    'npx awguard@latest . --format sarif --output awguard.sarif --fail-on none',
+    '```'
+  ].join('\n');
+}
+
+function renderRuleIndex() {
+  const lines = ['# Agentic Workflow Guard Rules', '', '| Rule | Severity | Remediation Code | Title |', '| --- | --- | --- | --- |'];
+  for (const [ruleId, rule] of Object.entries(ruleCatalog)) {
+    lines.push(`| ${ruleId} | ${rule.severity} | \`${rule.remediationCode}\` | ${escapeMarkdown(rule.title)} |`);
+  }
+  lines.push('', 'Run `awguard explain AWG001` for details about one rule.');
+  return lines.join('\n');
+}
+
+function escapeMarkdown(value) {
+  return String(value).replaceAll('|', '\\|');
+}

package/src/init.js

@@ -21,7 +21,7 @@ export function renderInitGuide({ actionRef = 'v0' } = {}) {
     '  scan:',
     '    runs-on: ubuntu-latest',
     '    steps:',
-    '      - uses: actions/checkout@v4',
+    '      - uses: actions/checkout@v6',
     `      - uses: Mughal-Baig/agentic-workflow-guard@${actionRef}`,
     '        with:',
     '          preset: strict',
@@ -40,11 +40,14 @@ export function renderInitGuide({ actionRef = 'v0' } = {}) {
     '```json',
     JSON.stringify(
       {
+        $schema:
+          'https://raw.githubusercontent.com/Mughal-Baig/agentic-workflow-guard/main/schemas/awguard.config.schema.json',
         extends: ['strict'],
         policy: {
           approvedFiles: ['AGENTS.md', '.github/workflows/*'],
           approvedMcpServers: [],
           approvedMcpPackages: [],
+          approvedMcpPackageScopes: ['@modelcontextprotocol/'],
           approvedMcpCommands: ['npx', 'node', 'uvx', 'docker']
         },
         suppressions: {

package/src/policy-packs.js

@@ -0,0 +1,99 @@
+export const policyPackNames = ['oss', 'strict', 'enterprise'];
+
+export function renderPolicyPack(name = 'oss') {
+  const normalized = String(name || 'oss').toLowerCase();
+  if (normalized === 'list') return renderPolicyPackList();
+  const pack = policyPacks[normalized];
+  if (!pack) {
+    throw new Error(`unknown policy pack: ${name}. Available policy packs: ${policyPackNames.join(', ')}`);
+  }
+
+  return [
+    `# AWGuard Policy Pack: ${pack.title}`,
+    '',
+    pack.description,
+    '',
+    '```json',
+    JSON.stringify(pack.config, null, 2),
+    '```'
+  ].join('\n');
+}
+
+function renderPolicyPackList() {
+  return ['Available AWGuard policy packs:', ...policyPackNames.map((name) => `- ${name}`)].join('\n');
+}
+
+const schemaUrl =
+  'https://raw.githubusercontent.com/Mughal-Baig/agentic-workflow-guard/main/schemas/awguard.config.schema.json';
+
+const policyPacks = {
+  oss: {
+    title: 'Open Source Maintainer',
+    description:
+      'A practical starting point for public repositories that want visibility without too much friction.',
+    config: {
+      $schema: schemaUrl,
+      extends: ['strict'],
+      scan: {
+        include: ['.github/workflows/*', 'AGENTS.md', '.github/agents/*', '.github/prompts/*', '.mcp.json'],
+        exclude: ['node_modules/*', 'dist/*', 'build/*']
+      },
+      policy: {
+        approvedFiles: ['AGENTS.md', '.github/workflows/*'],
+        approvedMcpServers: [],
+        approvedMcpPackages: [],
+        approvedMcpPackageScopes: ['@modelcontextprotocol/'],
+        approvedMcpCommands: ['node', 'npx', 'uvx', 'docker']
+      },
+      suppressions: {
+        minimumReasonLength: 20
+      }
+    }
+  },
+  strict: {
+    title: 'Strict Repository',
+    description: 'A tighter pack for repositories where agentic surfaces should be reviewed before use.',
+    config: {
+      $schema: schemaUrl,
+      extends: ['strict'],
+      scan: {
+        include: ['.github/workflows/*', 'AGENTS.md', 'CLAUDE.md', 'CODEX.md', '.github/**', '.mcp.json', '.vscode/mcp.json'],
+        exclude: ['node_modules/*', 'dist/*', 'build/*', 'coverage/*']
+      },
+      policy: {
+        approvedFiles: [],
+        approvedMcpServers: [],
+        approvedMcpPackages: [],
+        approvedMcpPackageScopes: [],
+        approvedMcpCommands: []
+      },
+      suppressions: {
+        allowedRules: [],
+        minimumReasonLength: 30
+      }
+    }
+  },
+  enterprise: {
+    title: 'Enterprise MCP Governance',
+    description: 'A pack for organizations that want pinned MCP startup and explicit agent surface review.',
+    config: {
+      $schema: schemaUrl,
+      extends: ['strict'],
+      scan: {
+        include: ['.github/workflows/*', 'AGENTS.md', 'CLAUDE.md', 'CODEX.md', '.github/**', '.cursor/**', '.mcp.json', '.vscode/mcp.json'],
+        exclude: ['node_modules/*', 'vendor/*', 'dist/*', 'build/*', 'coverage/*']
+      },
+      policy: {
+        approvedFiles: ['AGENTS.md'],
+        approvedMcpServers: [],
+        approvedMcpPackages: [],
+        approvedMcpPackageScopes: ['@modelcontextprotocol/'],
+        approvedMcpCommands: ['node', 'docker']
+      },
+      suppressions: {
+        allowedRules: ['AWG010'],
+        minimumReasonLength: 40
+      }
+    }
+  }
+};

package/src/policy-wizard.js

@@ -0,0 +1,165 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { classifyScanFile } from './scanner.js';
+
+const mcpRunnerCommands = new Set(['npx', 'pnpx', 'bunx', 'uvx', 'pipx']);
+const schemaUrl =
+  'https://raw.githubusercontent.com/Mughal-Baig/agentic-workflow-guard/main/schemas/awguard.config.schema.json';
+
+export function buildPolicyWizard(result, { existingConfig = {} } = {}) {
+  const policy = existingConfig.policy || {};
+  const approvedFiles = mergeUnique(policy.approvedFiles || [], result.scannedFiles.map((file) => relativeFile(result.root, file)));
+  const mcp = collectMcpAllowlist(result);
+
+  const baseConfig = Object.keys(existingConfig).length > 0 ? existingConfig : { $schema: schemaUrl, extends: ['strict'] };
+  const config = {
+    ...baseConfig,
+    policy: {
+      approvedFiles,
+      approvedMcpServers: mergeUnique(policy.approvedMcpServers || [], mcp.servers),
+      approvedMcpPackages: mergeUnique(policy.approvedMcpPackages || [], mcp.packages),
+      approvedMcpPackageScopes: mergeUnique(policy.approvedMcpPackageScopes || [], mcp.packageScopes),
+      approvedMcpCommands: mergeUnique(policy.approvedMcpCommands || [], mcp.commands)
+    }
+  };
+
+  return {
+    summary: {
+      approvedFiles: config.policy.approvedFiles.length,
+      approvedMcpServers: config.policy.approvedMcpServers.length,
+      approvedMcpPackages: config.policy.approvedMcpPackages.length,
+      approvedMcpPackageScopes: config.policy.approvedMcpPackageScopes.length,
+      approvedMcpCommands: config.policy.approvedMcpCommands.length
+    },
+    config,
+    reviewSteps: [
+      'Review every approved file before committing the policy.',
+      'Pin mutable MCP packages and containers before approving them.',
+      'Keep command allowlists narrow; prefer node, npx, uvx, and docker only when reviewed.'
+    ]
+  };
+}
+
+export function renderPolicyWizard(wizard, { format = 'markdown' } = {}) {
+  if (format === 'json') return JSON.stringify(wizard.config, null, 2);
+
+  return [
+    '# AWGuard Policy Wizard',
+    '',
+    '| Allowlist | Count |',
+    '| --- | ---: |',
+    `| Files | ${wizard.summary.approvedFiles} |`,
+    `| MCP servers | ${wizard.summary.approvedMcpServers} |`,
+    `| MCP packages | ${wizard.summary.approvedMcpPackages} |`,
+    `| MCP package scopes | ${wizard.summary.approvedMcpPackageScopes} |`,
+    `| MCP commands | ${wizard.summary.approvedMcpCommands} |`,
+    '',
+    'Review steps:',
+    '',
+    ...wizard.reviewSteps.map((step) => `- ${step}`),
+    '',
+    'Starter config:',
+    '',
+    '```json',
+    JSON.stringify(wizard.config, null, 2),
+    '```'
+  ].join('\n');
+}
+
+function collectMcpAllowlist(result) {
+  const allowlist = {
+    servers: [],
+    packages: [],
+    packageScopes: [],
+    commands: []
+  };
+
+  for (const file of result.scannedFiles) {
+    if (classifyScanFile(file, result.root) !== 'mcp-config') continue;
+    const parsed = parseJsonLike(fs.readFileSync(file, 'utf8'));
+    if (!parsed) continue;
+
+    for (const server of collectMcpServers(parsed)) {
+      if (server.name) allowlist.servers.push(server.name);
+      const command = normalizeCommand(server.config.command);
+      if (command) allowlist.commands.push(command);
+      const packageSpec = findPackageSpec(command, arrayOfStrings(server.config.args));
+      if (packageSpec) allowlist.packages.push(packageSpec);
+      const packageScope = packageScopeFromSpec(packageSpec);
+      if (packageScope) allowlist.packageScopes.push(packageScope);
+    }
+  }
+
+  return {
+    servers: uniqueSorted(allowlist.servers),
+    packages: uniqueSorted(allowlist.packages),
+    packageScopes: uniqueSorted(allowlist.packageScopes),
+    commands: uniqueSorted(allowlist.commands)
+  };
+}
+
+function collectMcpServers(config) {
+  const servers = [];
+  collectMcpContainer(config.mcpServers, servers);
+  collectMcpContainer(config.servers, servers);
+  if (config.projects && typeof config.projects === 'object') {
+    for (const project of Object.values(config.projects)) {
+      collectMcpContainer(project?.mcpServers, servers);
+      collectMcpContainer(project?.servers, servers);
+    }
+  }
+  return servers;
+}
+
+function collectMcpContainer(container, servers) {
+  if (!container || typeof container !== 'object' || Array.isArray(container)) return;
+  for (const [name, config] of Object.entries(container)) {
+    if (config && typeof config === 'object' && !Array.isArray(config)) {
+      servers.push({ name, config });
+    }
+  }
+}
+
+function parseJsonLike(text) {
+  try {
+    return JSON.parse(stripJsonComments(text).replace(/,\s*([}\]])/g, '$1'));
+  } catch {
+    return null;
+  }
+}
+
+function stripJsonComments(text) {
+  return text.replace(/(^|\s)\/\/.*$/gm, '$1').replace(/\/\*[\s\S]*?\*\//g, '');
+}
+
+function findPackageSpec(command, args) {
+  if (!mcpRunnerCommands.has(command)) return '';
+  return args.find((arg) => !arg.startsWith('-') && !arg.includes('=')) || '';
+}
+
+function packageScopeFromSpec(packageSpec = '') {
+  if (!packageSpec.startsWith('@')) return '';
+  const slashIndex = packageSpec.indexOf('/');
+  return slashIndex === -1 ? '' : packageSpec.slice(0, slashIndex + 1);
+}
+
+function arrayOfStrings(value) {
+  return Array.isArray(value) ? value.filter((item) => typeof item === 'string') : [];
+}
+
+function normalizeCommand(value) {
+  if (typeof value !== 'string') return '';
+  return path.basename(value).toLowerCase();
+}
+
+function relativeFile(root, file) {
+  return path.relative(root, file).split(path.sep).join('/') || path.basename(file);
+}
+
+function mergeUnique(existing, discovered) {
+  return uniqueSorted([...existing, ...discovered].filter(Boolean).map(String));
+}
+
+function uniqueSorted(values) {
+  return [...new Set(values)].sort();
+}