awguard 1.6.0 → 1.7.0

package/src/baseline.js

@@ -18,6 +18,51 @@ export function applyBaseline(result, baseline) {
   };
 }
 
+export function reviewBaseline(result, baseline) {
+  const currentByFingerprint = new Map(result.findings.map((finding) => [finding.fingerprint, finding]));
+  const baselineFindings = baseline.findings || [];
+  const known = [];
+  const resolved = [];
+
+  for (const baselineFinding of baselineFindings) {
+    const currentFinding = currentByFingerprint.get(baselineFinding.fingerprint);
+    if (currentFinding) {
+      known.push({
+        ...baselineFinding,
+        current: currentFinding
+      });
+    } else {
+      resolved.push(baselineFinding);
+    }
+  }
+
+  const baselineFingerprints = new Set(baselineFindings.map((finding) => finding.fingerprint));
+  const newFindings = result.findings.filter((finding) => !baselineFingerprints.has(finding.fingerprint));
+
+  return {
+    summary: {
+      baselineFindings: baselineFindings.length,
+      known: known.length,
+      resolved: resolved.length,
+      new: newFindings.length,
+      pruneRecommended: resolved.length > 0
+    },
+    known,
+    resolved,
+    newFindings
+  };
+}
+
+export function pruneBaseline(baseline, review) {
+  const knownFingerprints = new Set(review.known.map((finding) => finding.fingerprint));
+  return {
+    ...baseline,
+    generatedAt: new Date().toISOString(),
+    prunedAt: new Date().toISOString(),
+    findings: (baseline.findings || []).filter((finding) => knownFingerprints.has(finding.fingerprint))
+  };
+}
+
 export function createBaseline(result) {
   return {
     version: 1,
@@ -55,6 +100,38 @@ export function writeBaseline(file, baseline) {
   return absoluteFile;
 }
 
+export function renderBaselineReview(review, { format = 'text', baselineFile = '' } = {}) {
+  if (format === 'json') return JSON.stringify(review, null, 2);
+
+  const lines = ['Agentic Workflow Guard Baseline Review', ''];
+  if (baselineFile) lines.push(`Baseline: ${baselineFile}`);
+  lines.push(
+    `Known findings: ${review.summary.known}`,
+    `Resolved baseline entries: ${review.summary.resolved}`,
+    `New findings not in baseline: ${review.summary.new}`,
+    ''
+  );
+
+  if (review.summary.resolved > 0) {
+    lines.push('Resolved baseline entries that can be pruned:', '');
+    for (const finding of review.resolved) {
+      lines.push(`- ${finding.ruleId} ${finding.file}:${finding.line} ${finding.title}`);
+    }
+    lines.push('', 'Run with `--prune` to rewrite the baseline without resolved entries.', '');
+  } else {
+    lines.push('No stale baseline entries found.', '');
+  }
+
+  if (review.summary.new > 0) {
+    lines.push('New findings not covered by the baseline:', '');
+    for (const finding of review.newFindings) {
+      lines.push(`- ${finding.ruleId} ${finding.file}:${finding.line} ${finding.title}`);
+    }
+  }
+
+  return lines.join('\n').trimEnd();
+}
+
 function summarizeBaseline(findings) {
   return findings.reduce(
     (summary, finding) => {

package/src/cli.js

@@ -1,16 +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 { loadReport, renderComparison } from './compare.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,
@@ -25,12 +42,28 @@ import {
 const HELP = `Agentic Workflow Guard
 
 Usage:
-  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] [--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
@@ -43,6 +76,7 @@ Examples:
   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
@@ -56,6 +90,74 @@ export async function runCli(args, env = process.env) {
     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) {
@@ -64,7 +166,9 @@ export async function runCli(args, env = process.env) {
   }
 
   if (options.compare.length > 0) {
-    const output = renderComparison(loadReport(options.compare[0]), loadReport(options.compare[1]));
+    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}`);
@@ -86,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;
@@ -114,6 +227,7 @@ export function parseArgs(args, env = {}) {
     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
   };
 
@@ -156,6 +270,8 @@ export function parseArgs(args, env = {}) {
       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 {
@@ -217,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 });
@@ -224,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

@@ -1,5 +1,13 @@
 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);
@@ -28,6 +36,10 @@ export function buildComparison(previous, current) {
     .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: {
@@ -36,13 +48,17 @@ export function buildComparison(previous, current) {
       introducedFindings: introducedFindings.length,
       resolvedFindings: resolvedFindings.length,
       unchangedFindings: unchangedFindings.length,
-      addedFiles: [...currentFiles].filter((file) => !previousFiles.has(file)).length,
-      removedFiles: [...previousFiles].filter((file) => !currentFiles.has(file)).length
+      addedFiles: addedFiles.length,
+      removedFiles: removedFiles.length,
+      addedSurfaces: addedSurfaces.length,
+      removedSurfaces: removedSurfaces.length
     },
     introducedFindings,
     resolvedFindings,
-    addedFiles: [...currentFiles].filter((file) => !previousFiles.has(file)).sort(),
-    removedFiles: [...previousFiles].filter((file) => !currentFiles.has(file)).sort()
+    addedFiles,
+    removedFiles,
+    addedSurfaces,
+    removedSurfaces
   };
 }
 
@@ -65,6 +81,10 @@ export function renderComparison(previous, current) {
   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', '');
@@ -73,6 +93,10 @@ export function renderComparison(previous, current) {
   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.');
@@ -101,10 +125,42 @@ function appendFiles(lines, files) {
   }
 }
 
+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

@@ -34,7 +34,8 @@ export function normalizeConfig(rawConfig = {}, source = 'config') {
   return {
     rules: normalizeRules(mergedConfig.rules || {}, source),
     suppressions: normalizeSuppressions(mergedConfig.suppressions || {}, source),
-    policy: normalizePolicy(mergedConfig.policy || {}, source)
+    policy: normalizePolicy(mergedConfig.policy || {}, source),
+    scan: normalizeScan(mergedConfig.scan || {}, source)
   };
 }
 
@@ -53,7 +54,8 @@ function mergePresetConfigs(rawConfig, source) {
   return mergeConfigObjects(merged, {
     rules: rawConfig.rules || {},
     suppressions: rawConfig.suppressions || {},
-    policy: rawConfig.policy || {}
+    policy: rawConfig.policy || {},
+    scan: rawConfig.scan || {}
   });
 }
 
@@ -70,6 +72,10 @@ function mergeConfigObjects(base, override) {
     policy: {
       ...(base.policy || {}),
       ...(override.policy || {})
+    },
+    scan: {
+      ...(base.scan || {}),
+      ...(override.scan || {})
     }
   };
 }
@@ -164,10 +170,33 @@ function normalizePolicy(policy, source) {
     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`);

package/src/demo.js

@@ -0,0 +1,90 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { buildComparison } from './compare.js';
+import { scanWorkflows } from './scanner.js';
+import { calculateScore } from './score.js';
+
+export function renderDemoWalkthrough({ packageRoot = getPackageRoot() } = {}) {
+  const unsafeRoot = path.join(packageRoot, 'examples', 'lab', 'unsafe');
+  const fixedRoot = path.join(packageRoot, 'examples', 'lab', 'fixed');
+  const unsafe = scanWorkflows({ root: unsafeRoot });
+  const fixed = scanWorkflows({ root: fixedRoot });
+  const comparison = buildComparison(toPortableReport(unsafe), toPortableReport(fixed));
+  const unsafeScore = calculateScore(unsafe);
+  const fixedScore = calculateScore(fixed);
+
+  const lines = [
+    '# Agentic Workflow Guard Demo',
+    '',
+    'This offline demo scans the built-in vulnerable lab and its fixed version.',
+    '',
+    '## Commands',
+    '',
+    '```bash',
+    'npx awguard@latest examples/lab/unsafe --format inventory',
+    'npx awguard@latest examples/lab/fixed --format inventory',
+    'npx awguard@latest examples/lab/fixed --fail-on high',
+    '```',
+    '',
+    '## Before And After',
+    '',
+    '| Lab | Scanned files | Findings | Highest | AWI score |',
+    '| --- | ---: | ---: | --- | --- |',
+    `| Unsafe | ${unsafe.scannedFiles.length} | ${unsafe.findings.length} | ${unsafe.summary.highest} | ${unsafeScore.grade} ${unsafeScore.score}/100 |`,
+    `| Fixed | ${fixed.scannedFiles.length} | ${fixed.findings.length} | ${fixed.summary.highest} | ${fixedScore.grade} ${fixedScore.score}/100 |`,
+    '',
+    '## Resolved Risk',
+    '',
+    `Resolved findings: **${comparison.summary.resolvedFindings}**`,
+    `Remaining findings: **${comparison.summary.currentFindings}**`,
+    '',
+    '## Unsafe Findings',
+    ''
+  ];
+
+  appendFindings(lines, unsafe.findings);
+  lines.push(
+    '',
+    '## Fixed Result',
+    '',
+    fixed.findings.length === 0
+      ? 'The fixed lab is clean for the enabled rules.'
+      : `The fixed lab still has ${fixed.findings.length} finding(s).`,
+    '',
+    'Lab docs: `examples/lab/README.md`'
+  );
+
+  return lines.join('\n');
+}
+
+function appendFindings(lines, findings) {
+  if (findings.length === 0) {
+    lines.push('None.');
+    return;
+  }
+
+  lines.push('| Severity | Rule | Location | Finding |', '| --- | --- | --- | --- |');
+  for (const finding of findings) {
+    lines.push(
+      `| ${escapeMarkdown(finding.severity)} | ${escapeMarkdown(finding.ruleId)} | \`${escapeMarkdown(
+        `${finding.file}:${finding.line}`
+      )}\` | ${escapeMarkdown(finding.title)} |`
+    );
+  }
+}
+
+function toPortableReport(result) {
+  return {
+    ...result,
+    scannedFiles: result.scannedFiles.map((file) => path.relative(result.root, file) || file)
+  };
+}
+
+function getPackageRoot() {
+  const sourceDir = path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(sourceDir, '..');
+}
+
+function escapeMarkdown(value) {
+  return String(value).replaceAll('|', '\\|');
+}