flaglint 0.5.4 → 0.6.0

package/CHANGELOG.md

@@ -5,6 +5,72 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.6.0] - 2026-06-02
+
+### Added
+
+- add flaglint audit command with risk-scored flag debt report
+- migrate homepage into Astro, unify site into single build
+- add dark/light/auto theme toggle + search to homepage
+- add Mermaid diagrams to Safety Model and How FlagLint Works
+- add Mermaid diagrams to Safety Model and How FlagLint Works
+- complete favicon stack for Google Search and mobile
+- replace plain-text architecture diagram with styled HTML flow
+- add JSON-LD SoftwareApplication structured data to homepage
+- align trust and privacy page nav with homepage nav
+- add Further Reading section to quickstart linking to blog posts
+- add cross-links between blog posts
+- rename blog to FlagLint Blog and set focused description
+- add Docs and Blog links to homepage nav and footer
+- add Blog link to marketing homepage nav
+- add blog to flaglint.dev using starlight-blog
+- add terminal demo GIF (scan, migrate --dry-run, validate CI gate)
+
+### Fixed
+
+- docs UX series P1-P9 (GIF, TOC, title, sidebar, cards, blog frames)
+- UX and codebase series (A1–A5, B1–B5)
+- sync package-lock.json after rebase (add png-to-ico)
+- UX and codebase series (A1–A5, B1–B5)
+- align dynamic key label with scan reporter terminology
+- restore branded README header and correct docs links
+
+### Changed
+
+- trigger cloudflare rebuild
+- untrack www/ build output + fix GIF paths + add Why FlagLint CTA
+- add excerpt markers to both blog posts for blog index truncation
+- rebuild after rebase onto main (PR #83 docs UX changes)
+- rebuild docs after rebase onto main (A1-A5/B1-B5 + favicon state)
+- rebuild docs after rebase onto main (favicon + blog state)
+- rebuild docs site with blog and demo GIF
+- add LinkedIn URL to blog post authors
+- remove debug artifacts from demo fixture folder
+- update version references to 0.5.4
+
+### Other
+
+- Merge feat/audit-command: add flaglint audit command
+- Merge pull request #86 from flaglint/feat/docs-ux-fixes
+- Merge pull request #85 from flaglint/fix/blog-excerpt-markers
+- Merge pull request #84 from flaglint/feat/homepage-theme-search
+- Merge pull request #83 from flaglint/fix/complete-series-p1-p12
+- Merge pull request #82 from flaglint/feat/favicon-stack
+- Merge pull request #80 from flaglint/fix/validate-dynamic-key-label
+- Merge pull request #78 from flaglint/feat/architecture-diagram
+- Merge pull request #77 from flaglint/feat/structured-data-jsonld
+- Merge pull request #76 from flaglint/feat/consistent-nav
+- Merge pull request #75 from flaglint/feat/quickstart-further-reading
+- Merge branch 'main' into feat/quickstart-further-reading
+- Merge pull request #74 from flaglint/feat/blog-cross-links
+- Merge pull request #73 from flaglint/feat/blog-title-description
+- Merge pull request #72 from flaglint/feat/nav-footer-blog-docs
+- Merge pull request #71 from flaglint/chore/bump-version-0.5.4
+- Update README.md
+- Merge pull request #70 from flaglint/chore/bump-version-0.5.4
+- Merge pull request #69 from flaglint/chore/bump-version-0.5.4
+- chore/bump-version-0.5.4
+
 ## Unreleased
 
 ### Fixed

package/README.md

@@ -23,7 +23,8 @@
 
 # FlagLint
 
-**Standardize LaunchDarkly usage on OpenFeature.**
+**The argument-order difference between LaunchDarkly and OpenFeature 
+silently breaks flag evaluations in production. FlagLint catches it.**
 
 FlagLint inventories direct LaunchDarkly Node.js SDK calls, generates reviewable migration plans,
 and prevents new vendor-coupled flag access from entering your codebase.
@@ -31,6 +32,8 @@ LaunchDarkly remains your provider. OpenFeature becomes the evaluation API your
 
 **[Documentation](https://flaglint.dev/docs)** · **[Quickstart](https://flaglint.dev/docs/quickstart)** · **[Enterprise Demo](https://flaglint.dev/docs/enterprise-demo)** · **[npm](https://npmjs.com/package/flaglint)** · **[Issues](https://github.com/flaglint/flaglint/issues)**
 
+![FlagLint demo](./flaglint-demo.gif)
+
 ---
 
 ## Quick start
@@ -67,6 +70,20 @@ npx flaglint migrate ./src --dry-run
 
 ---
 
+### `flaglint audit [dir]`
+
+Generates a local flag debt audit report. No API keys or credentials needed.
+
+```bash
+flaglint audit ./src
+flaglint audit ./src --format html --output audit.html
+flaglint audit ./src --format json
+```
+
+Produces a risk-scored inventory of every LaunchDarkly flag in your codebase — sorted by risk level (high / medium / low) with the reasons for each rating. Useful for planning migration scope before running `migrate --dry-run`.
+
+---
+
 ## Before → After (real output from enterprise demo)
 
 ```diff

package/dist/bin/flaglint.js

@@ -303,6 +303,9 @@ function detectUsages(ast, code, filePath, wrappers) {
             callType: "isFeatureEnabled",
             stalenessSignals: sig ? [sig] : []
           });
+          migrationInventory.push(
+            buildMigrationInventoryItem(code, filePath, loc, call, "isFeatureEnabled", call.arguments, flagKey, isDynamic)
+          );
           return;
         }
         if (LD_HOOKS.has(name)) {
@@ -316,6 +319,25 @@ function detectUsages(ast, code, filePath, wrappers) {
             callType: name === "useFlags" ? "hook-useFlags" : "hook-useLDClient",
             stalenessSignals: sig ? [sig] : []
           });
+          const hookCallRange = expressionRange(call);
+          migrationInventory.push({
+            file: filePath,
+            line: loc.line,
+            column: loc.column,
+            launchDarklyMethod: name === "useFlags" ? "hook-useFlags" : "hook-useLDClient",
+            callExpression: expressionText(code, call),
+            rangeStart: hookCallRange?.[0],
+            rangeEnd: hookCallRange?.[1],
+            isAwaited: false,
+            flagKeyExpression: void 0,
+            staticFlagKey: void 0,
+            isDynamic: false,
+            valueType: "unknown",
+            fallbackExpression: void 0,
+            evaluationContextExpression: void 0,
+            safelyAutomatable: false,
+            manualReviewReason: "dynamic-key"
+          });
           return;
         }
       }
@@ -331,6 +353,9 @@ function detectUsages(ast, code, filePath, wrappers) {
           callType: "variation",
           stalenessSignals: sig ? [sig] : []
         });
+        migrationInventory.push(
+          buildMigrationInventoryItem(code, filePath, loc, call, "variation", call.arguments, flagKey, isDynamic)
+        );
         return;
       }
       if (callee.type === "CallExpression" && callee.callee.type === "Identifier" && callee.callee.name === "withLDConsumer") {
@@ -542,8 +567,9 @@ function formatMarkdown(result, options) {
   lines.push("|----------|--------|-------|------------|--------|");
   for (const [key, data] of sorted) {
     const status = data.isStale ? "\u26A0 Stale" : "\u2713 Active";
+    const displayKey = key === "*" || data.usages.some((u) => u.isDynamic && u.flagKey === key) ? "(dynamic key)" : key;
     lines.push(
-      `| ${key} | ${data.usages.length} | ${data.files.size} | ${[...data.callTypes].join(", ")} | ${status} |`
+      `| ${displayKey} | ${data.usages.length} | ${data.files.size} | ${[...data.callTypes].join(", ")} | ${status} |`
     );
   }
   lines.push("");
@@ -763,7 +789,7 @@ function formatHTML(result, options) {
     <div class="card"><div class="card-num orange">${manualCount}</div><div class="card-label">Manual Review (${manualPct}%)</div></div>
     <div class="card"><div class="card-num blue">${detailBulkCount}</div><div class="card-label">Detail/Bulk Calls</div></div>` : "";
   const title = options.title ? esc(options.title) : "FlagLint Scan Report";
-  const version = true ? "0.5.4" : "0.1.0";
+  const version = true ? "0.6.0" : "0.1.0";
   return `<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -894,6 +920,9 @@ var FlagLintConfigSchema = z.object({
     "**/coverage/**",
     "**/*.d.ts"
   ]),
+  // Governs which vendor SDK the scanner targets.
+  // Currently only "launchdarkly" is wired in the scanner.
+  // Other values are accepted for forward compatibility (v0.7+).
   provider: z.enum(["launchdarkly", "unleash", "growthbook", "custom"]).default("launchdarkly"),
   // TODO v0.3: replace minFileCount with real date-based staleness via git log
   minFileCount: z.number().int().min(0).default(0),
@@ -1216,7 +1245,7 @@ function formatMigrationReport(analysis) {
     unsupportedUnknownCount
   } = analysis;
   const date = (/* @__PURE__ */ new Date()).toLocaleDateString();
-  const version = true ? "0.5.4" : "0.1.0";
+  const version = true ? "0.6.0" : "0.1.0";
   const lines = [];
   lines.push("# OpenFeature Migration Inventory");
   lines.push(`Generated by FlagLint v${version} on ${date}`);
@@ -1713,7 +1742,7 @@ function validateScanResult(result, options = {}) {
   };
 }
 function violationLabel(v) {
-  if (v.isDynamic) return `${v.callType}(dynamic key \u2014 manual review required)`;
+  if (v.isDynamic) return `${v.callType}("(dynamic key)")`;
   if (v.flagKey === "*") return `${v.callType}(bulk inventory)`;
   return `${v.callType}("${v.flagKey}")`;
 }
@@ -1977,10 +2006,442 @@ Examples:
   );
 }
 
+// src/commands/audit.ts
+import { writeFile as writeFile5 } from "fs/promises";
+import { stat as stat4 } from "fs/promises";
+import { resolve as resolve8 } from "path";
+import chalk4 from "chalk";
+import ora4 from "ora";
+
+// src/auditor/index.ts
+function scoreFlag(usages, inventoryItems) {
+  const highReasons = [];
+  const mediumReasons = [];
+  if (usages.some((u) => u.isDynamic)) {
+    highReasons.push("dynamic key");
+  }
+  if (inventoryItems.some((i) => i.manualReviewReason === "detail-method")) {
+    highReasons.push("detail evaluation");
+  }
+  if (inventoryItems.some((i) => i.manualReviewReason === "bulk-inventory-call")) {
+    highReasons.push("bulk call");
+  }
+  if (usages.some((u) => u.stalenessSignals.length > 0)) {
+    highReasons.push("stale signal");
+  }
+  if (usages.some((u) => u.callType === "variation" && u.isDynamic)) {
+    if (!highReasons.includes("wrapper usage")) {
+      highReasons.push("wrapper usage");
+    }
+  }
+  if (usages.some(
+    (u) => u.callType === "hook-useFlags" || u.callType === "hook-useLDClient" || u.callType === "hoc" || u.callType === "provider"
+  )) {
+    highReasons.push("react/browser hook");
+  }
+  if (highReasons.length > 0) {
+    return { riskLevel: "high", riskReasons: highReasons };
+  }
+  if (inventoryItems.some((i) => i.safelyAutomatable)) {
+    mediumReasons.push("safely automatable");
+  }
+  if (inventoryItems.some((i) => i.valueType === "object")) {
+    mediumReasons.push("json variation");
+  }
+  if (inventoryItems.some((i) => i.manualReviewReason === "unknown-fallback")) {
+    mediumReasons.push("unknown fallback");
+  }
+  if (mediumReasons.length > 0) {
+    return { riskLevel: "medium", riskReasons: mediumReasons };
+  }
+  return { riskLevel: "low", riskReasons: [] };
+}
+function buildAuditReport(scanResult, inventoryItems) {
+  const usagesByFlag = /* @__PURE__ */ new Map();
+  for (const u of scanResult.usages) {
+    const key = u.flagKey;
+    if (!usagesByFlag.has(key)) usagesByFlag.set(key, []);
+    usagesByFlag.get(key).push(u);
+  }
+  const inventoryByFlag = /* @__PURE__ */ new Map();
+  for (const item of inventoryItems) {
+    const key = item.staticFlagKey ?? "*";
+    if (!inventoryByFlag.has(key)) inventoryByFlag.set(key, []);
+    inventoryByFlag.get(key).push(item);
+  }
+  const allFlagKeys = /* @__PURE__ */ new Set([...usagesByFlag.keys()]);
+  const flags = [];
+  for (const flagKey of allFlagKeys) {
+    const usages = usagesByFlag.get(flagKey) ?? [];
+    const items = inventoryByFlag.get(flagKey) ?? [];
+    const { riskLevel, riskReasons } = scoreFlag(usages, items);
+    const files = [...new Set(usages.map((u) => u.file))];
+    const callTypes = [...new Set(usages.map((u) => u.callType))];
+    flags.push({
+      flagKey,
+      riskLevel,
+      riskReasons,
+      callTypes,
+      fileCount: files.length,
+      usageCount: usages.length,
+      safelyAutomatable: items.some((i) => i.safelyAutomatable),
+      hasStaleSignal: usages.some((u) => u.stalenessSignals.length > 0),
+      isDynamic: usages.some((u) => u.isDynamic),
+      files
+    });
+  }
+  const riskOrder = { high: 0, medium: 1, low: 2 };
+  flags.sort((a, b) => {
+    const levelDiff = riskOrder[a.riskLevel] - riskOrder[b.riskLevel];
+    if (levelDiff !== 0) return levelDiff;
+    return b.usageCount - a.usageCount;
+  });
+  const highRisk = flags.filter((f) => f.riskLevel === "high").length;
+  const mediumRisk = flags.filter((f) => f.riskLevel === "medium").length;
+  const lowRisk = flags.filter((f) => f.riskLevel === "low").length;
+  const summary = {
+    totalFlags: flags.length,
+    highRisk,
+    mediumRisk,
+    lowRisk,
+    totalUsages: scanResult.totalUsages,
+    dynamicKeys: scanResult.usages.filter((u) => u.isDynamic).length,
+    detailEvaluations: inventoryItems.filter((i) => i.manualReviewReason === "detail-method").length,
+    bulkCalls: inventoryItems.filter((i) => i.manualReviewReason === "bulk-inventory-call").length,
+    wrapperUsages: scanResult.usages.filter((u) => u.callType === "variation").length,
+    staleSignals: scanResult.usages.filter((u) => u.stalenessSignals.length > 0).length,
+    safelyAutomatable: inventoryItems.filter((i) => i.safelyAutomatable).length,
+    manualReview: inventoryItems.filter((i) => !i.safelyAutomatable).length,
+    scannedFiles: scanResult.scannedFiles,
+    scanDurationMs: scanResult.scanDurationMs,
+    scannedAt: scanResult.scannedAt,
+    scanRoot: scanResult.scanRoot
+  };
+  return { summary, flags };
+}
+
+// src/auditor/reporter.ts
+function esc2(s) {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function formatAuditJson(report) {
+  return JSON.stringify(report, null, 2);
+}
+function formatAuditMarkdown(report) {
+  const { summary, flags } = report;
+  const lines = [];
+  lines.push("# FlagLint Audit Report");
+  lines.push("");
+  lines.push(`**Scanned at:** ${summary.scannedAt}  `);
+  lines.push(`**Scan root:** ${summary.scanRoot}  `);
+  lines.push(`**Files scanned:** ${summary.scannedFiles}  `);
+  lines.push(`**Duration:** ${summary.scanDurationMs}ms`);
+  lines.push("");
+  lines.push("## Summary");
+  lines.push("");
+  lines.push("| Total Flags | High Risk | Medium Risk | Low Risk | Total Usages |");
+  lines.push("|-------------|-----------|-------------|----------|--------------|");
+  lines.push(
+    `| ${summary.totalFlags} | ${summary.highRisk} | ${summary.mediumRisk} | ${summary.lowRisk} | ${summary.totalUsages} |`
+  );
+  lines.push("");
+  lines.push(
+    "| Dynamic Keys | Detail Evals | Bulk Calls | Stale Signals | Safely Automatable | Manual Review |"
+  );
+  lines.push(
+    "|--------------|--------------|------------|---------------|-------------------|---------------|"
+  );
+  lines.push(
+    `| ${summary.dynamicKeys} | ${summary.detailEvaluations} | ${summary.bulkCalls} | ${summary.staleSignals} | ${summary.safelyAutomatable} | ${summary.manualReview} |`
+  );
+  lines.push("");
+  lines.push("## Flag Debt Inventory");
+  lines.push("");
+  lines.push("| Flag Key | Risk | Usages | Files | Call Types | Reasons |");
+  lines.push("|----------|------|--------|-------|------------|---------|");
+  const riskLabel = {
+    high: "\u{1F534} High",
+    medium: "\u{1F7E1} Medium",
+    low: "\u{1F7E2} Low"
+  };
+  for (const flag of flags) {
+    const reasons = flag.riskReasons.join(", ") || "\u2014";
+    lines.push(
+      `| \`${flag.flagKey}\` | ${riskLabel[flag.riskLevel]} | ${flag.usageCount} | ${flag.fileCount} | ${flag.callTypes.join(", ")} | ${reasons} |`
+    );
+  }
+  lines.push("");
+  lines.push("## Next Steps");
+  lines.push("");
+  lines.push(
+    "- Run `flaglint migrate --dry-run` to preview safe OpenFeature rewrites"
+  );
+  lines.push(
+    "- Run `flaglint validate --no-direct-launchdarkly` to enforce OF boundary in CI"
+  );
+  lines.push(
+    "- Review HIGH risk flags manually before any automated migration"
+  );
+  lines.push("");
+  return lines.join("\n");
+}
+function formatAuditHtml(report) {
+  const { summary, flags } = report;
+  const version = true ? "0.6.0" : "0.1.0";
+  const date = new Date(summary.scannedAt).toLocaleString();
+  const riskBadge = (level) => {
+    if (level === "high")
+      return '<span class="badge badge-high">High</span>';
+    if (level === "medium")
+      return '<span class="badge badge-medium">Medium</span>';
+    return '<span class="badge badge-low">Low</span>';
+  };
+  const rows = flags.map((f) => {
+    const reasons = f.riskReasons.length > 0 ? esc2(f.riskReasons.join(", ")) : "\u2014";
+    return `<tr>
+          <td><code>${esc2(f.flagKey)}</code></td>
+          <td>${riskBadge(f.riskLevel)}</td>
+          <td>${f.usageCount}</td>
+          <td>${f.fileCount}</td>
+          <td>${f.callTypes.map(esc2).join(", ")}</td>
+          <td>${reasons}</td>
+        </tr>`;
+  }).join("\n        ");
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>FlagLint Audit Report</title>
+  <style>
+    :root{--bg:#fff;--surface:#f8f9fa;--border:#dee2e6;--text:#212529;--muted:#6c757d;--card-shadow:0 1px 3px rgba(0,0,0,.1)}
+    @media(prefers-color-scheme:dark){:root{--bg:#0f172a;--surface:#1e293b;--border:#334155;--text:#e2e8f0;--muted:#94a3b8;--card-shadow:0 1px 3px rgba(0,0,0,.4)}}
+    *{box-sizing:border-box;margin:0;padding:0}
+    body{background:var(--bg);color:var(--text);font-family:system-ui,-apple-system,sans-serif;padding:2rem;max-width:1200px;margin:0 auto;line-height:1.5}
+    h1{font-size:1.75rem;margin-bottom:.25rem}
+    h2{font-size:1.125rem;margin:2rem 0 .75rem;padding-bottom:.5rem;border-bottom:1px solid var(--border)}
+    .subtitle{color:var(--muted);margin-bottom:1.5rem;font-size:.875rem}
+    .cards{display:flex;gap:1rem;flex-wrap:wrap;margin-bottom:2rem}
+    .card{flex:1;min-width:140px;background:var(--surface);border:1px solid var(--border);border-radius:8px;padding:1rem;box-shadow:var(--card-shadow)}
+    .card-num{font-size:1.875rem;font-weight:700;line-height:1}
+    .card-num.red{color:#dc2626}
+    .card-num.amber{color:#d97706}
+    .card-num.green{color:#16a34a}
+    .card-num.blue{color:#3b82f6}
+    .card-num.purple{color:#7c3aed}
+    .card-num.orange{color:#ea580c}
+    .card-label{color:var(--muted);font-size:.75rem;margin-top:.375rem;text-transform:uppercase;letter-spacing:.05em}
+    table{width:100%;border-collapse:collapse;font-size:.8125rem}
+    th{text-align:left;padding:.625rem .75rem;background:var(--surface);border-bottom:2px solid var(--border);font-weight:600;white-space:nowrap}
+    td{padding:.625rem .75rem;border-bottom:1px solid var(--border);vertical-align:top}
+    code{font-family:ui-monospace,monospace;font-size:.8em;background:var(--surface);padding:.1em .3em;border-radius:3px}
+    .badge{display:inline-block;padding:.2em .6em;border-radius:4px;font-size:.75rem;font-weight:600}
+    .badge-high{background:#fee2e2;color:#991b1b}
+    .badge-medium{background:#fef3c7;color:#92400e}
+    .badge-low{background:#dcfce7;color:#166534}
+    @media(prefers-color-scheme:dark){
+      .badge-high{background:#7f1d1d;color:#fca5a5}
+      .badge-medium{background:#78350f;color:#fcd34d}
+      .badge-low{background:#14532d;color:#86efac}
+    }
+    .steps{margin:.75rem 0 1rem 1.25rem;line-height:2}
+    footer{margin-top:3rem;padding-top:1rem;border-top:1px solid var(--border);color:var(--muted);font-size:.75rem;text-align:center}
+    footer a{color:var(--muted)}
+  </style>
+</head>
+<body>
+  <h1>FlagLint Audit Report</h1>
+  <p class="subtitle">
+    ${esc2(summary.scanRoot)} &middot; ${esc2(summary.scannedFiles.toString())} files &middot; ${esc2(summary.scanDurationMs.toString())}ms &middot; ${esc2(date)}
+  </p>
+
+  <h2>Summary</h2>
+  <div class="cards">
+    <div class="card"><div class="card-num">${summary.totalFlags}</div><div class="card-label">Total Flags</div></div>
+    <div class="card"><div class="card-num red">${summary.highRisk}</div><div class="card-label">High Risk</div></div>
+    <div class="card"><div class="card-num amber">${summary.mediumRisk}</div><div class="card-label">Medium Risk</div></div>
+    <div class="card"><div class="card-num green">${summary.lowRisk}</div><div class="card-label">Low Risk</div></div>
+    <div class="card"><div class="card-num purple">${summary.safelyAutomatable}</div><div class="card-label">Safely Automatable</div></div>
+    <div class="card"><div class="card-num orange">${summary.manualReview}</div><div class="card-label">Manual Review</div></div>
+  </div>
+
+  <h2>Flag Debt Inventory</h2>
+  <table>
+    <thead>
+      <tr>
+        <th>Flag Key</th>
+        <th>Risk</th>
+        <th>Usages</th>
+        <th>Files</th>
+        <th>Call Types</th>
+        <th>Risk Reasons</th>
+      </tr>
+    </thead>
+    <tbody>
+        ${rows}
+    </tbody>
+  </table>
+
+  <h2>Next Steps</h2>
+  <ol class="steps">
+    <li>Run <code>flaglint migrate --dry-run</code> to preview safe OpenFeature rewrites</li>
+    <li>Run <code>flaglint validate --no-direct-launchdarkly</code> to enforce OF boundary in CI</li>
+    <li>Review HIGH risk flags manually before any automated migration</li>
+  </ol>
+
+  <footer>
+    Generated by <a href="https://flaglint.dev">FlagLint</a> ${esc2(version)}
+  </footer>
+</body>
+</html>`;
+}
+
+// src/commands/audit.ts
+var VALID_AUDIT_FORMATS = ["json", "markdown", "html"];
+function registerAuditCommand(program2) {
+  program2.command("audit").description("Generate a flag debt audit report").argument("[dir]", "directory to audit", process.cwd()).option("-f, --format <format>", "output format: json | markdown | html", "markdown").option("-o, --output <file>", "write report to file").option("-c, --config <path>", "path to .flaglintrc config file").option("--exclude-tests", "exclude test files (*.test.*, *.spec.*, __tests__/, tests/)").addHelpText(
+    "after",
+    `
+Examples:
+  $ flaglint audit                    generate flag debt audit report
+  $ flaglint audit --format html     shareable HTML report
+  $ flaglint audit --output audit.md save to file`
+  ).action(
+    async (dir, options) => {
+      if (!VALID_AUDIT_FORMATS.includes(options.format)) {
+        process.stderr.write(
+          chalk4.red(
+            `Error: Invalid format '${options.format}'. Must be one of: ${VALID_AUDIT_FORMATS.join(", ")}
+`
+          )
+        );
+        process.exit(2);
+      }
+      try {
+        const s = await stat4(resolve8(dir));
+        if (!s.isDirectory()) {
+          process.stderr.write(chalk4.red(`Error: Not a directory: ${dir}
+`));
+          process.exit(1);
+        }
+      } catch (err) {
+        const code = err.code;
+        if (code === "ENOENT") {
+          process.stderr.write(chalk4.red(`Error: Directory not found: ${dir}
+`));
+        } else if (code === "EACCES") {
+          process.stderr.write(chalk4.red(`Error: Permission denied: ${dir}
+`));
+        } else {
+          process.stderr.write(chalk4.red(`Error: Cannot access directory: ${dir}
+`));
+        }
+        process.exit(1);
+      }
+      let config;
+      try {
+        config = await loadConfig(options.config);
+      } catch (err) {
+        process.stderr.write(
+          chalk4.red(String(err instanceof Error ? err.message : err)) + "\n"
+        );
+        process.exit(1);
+      }
+      const TEST_PATTERNS = [
+        "**/*.test.ts",
+        "**/*.test.tsx",
+        "**/*.spec.ts",
+        "**/*.spec.tsx",
+        "**/__tests__/**",
+        "**/tests/**"
+      ];
+      const scanConfig = options.excludeTests ? { ...config, exclude: [...config.exclude, ...TEST_PATTERNS] } : config;
+      const format = options.format;
+      const spinner = ora4(`Auditing ${dir}...`).start();
+      process.once("SIGINT", () => {
+        spinner.stop();
+        process.exit(130);
+      });
+      let lastSpinnerUpdate = 0;
+      let scanResult;
+      try {
+        scanResult = await scan(new LocalFileSource(dir), scanConfig, (filesScanned) => {
+          if (filesScanned - lastSpinnerUpdate >= 50) {
+            spinner.text = `Scanning... (${filesScanned} files)`;
+            lastSpinnerUpdate = filesScanned;
+          }
+        });
+        spinner.stop();
+      } catch (err) {
+        spinner.fail("Audit scan failed");
+        process.stderr.write(chalk4.red(String(err)) + "\n");
+        process.exit(1);
+      }
+      for (const w of scanResult.warnings) {
+        const msg = w.kind === "read-failure" ? `warn: could not read ${w.file} (${w.fsCode})` : `warn: failed to parse ${w.file}`;
+        process.stderr.write(chalk4.yellow(msg + "\n"));
+      }
+      if (scanResult.scannedFiles === 0) {
+        process.stderr.write(
+          chalk4.yellow("No matching files found. Check your .flaglintrc include patterns.\n")
+        );
+        process.exit(0);
+      }
+      if (scanResult.totalUsages === 0) {
+        process.stderr.write(
+          chalk4.dim(
+            `No LaunchDarkly SDK usage detected in ${scanResult.scannedFiles} files.
+`
+          )
+        );
+        process.exit(0);
+      }
+      const auditReport = buildAuditReport(
+        scanResult,
+        scanResult.migrationInventory ?? []
+      );
+      let output;
+      if (format === "json") {
+        output = formatAuditJson(auditReport);
+      } else if (format === "html") {
+        output = formatAuditHtml(auditReport);
+      } else {
+        output = formatAuditMarkdown(auditReport);
+      }
+      if (options.output) {
+        const outPath = resolve8(options.output);
+        try {
+          await writeFile5(outPath, output, "utf8");
+          process.stderr.write(chalk4.dim(`   Report written to ${options.output}
+`));
+        } catch (err) {
+          process.stderr.write(
+            chalk4.red(
+              `Error: Failed to write report to ${options.output}: ${err instanceof Error ? err.message : String(err)}
+`
+            )
+          );
+          process.exit(1);
+        }
+      } else {
+        process.stdout.write(output + "\n");
+      }
+      const { totalFlags, highRisk, mediumRisk, lowRisk } = auditReport.summary;
+      process.stderr.write(
+        chalk4.green(
+          `\u2713 Audit complete: ${totalFlags} flags \u2014 ${highRisk} high risk, ${mediumRisk} medium risk, ${lowRisk} low risk
+`
+        )
+      );
+      process.exit(0);
+    }
+  );
+}
+
 // src/cli.ts
 function createCLI() {
   const program2 = new Command();
-  program2.name("flaglint").description("LaunchDarkly Node.js server SDK -> OpenFeature migration.").version("0.5.4", "-v, --version", "output the current version").addHelpText(
+  program2.name("flaglint").description("Scan LaunchDarkly Node.js SDK usage, generate safe OpenFeature migration diffs, and enforce the vendor boundary in CI.").version("0.6.0", "-v, --version", "output the current version").addHelpText(
     "after",
     `
 Examples:
@@ -1990,11 +2451,15 @@ Examples:
   $ flaglint scan --output report.md save to file
   $ flaglint migrate                 generate migration plan
   $ flaglint migrate --dry-run       preview without writing
-  $ flaglint validate --no-direct-launchdarkly  enforce OF migration in CI`
+  $ flaglint validate --no-direct-launchdarkly  enforce OF migration in CI
+  $ flaglint audit                   generate flag debt audit report
+  $ flaglint audit --format html     shareable HTML report
+  $ flaglint audit --output audit.md save to file`
   );
   registerScanCommand(program2);
   registerMigrateCommand(program2);
   registerValidateCommand(program2);
+  registerAuditCommand(program2);
   return program2;
 }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "flaglint",
-  "version": "0.5.4",
-  "description": "LaunchDarkly Node.js server SDK -> OpenFeature migration.",
+  "version": "0.6.0",
+  "description": "Scan LaunchDarkly Node.js SDK usage, generate safe OpenFeature migration diffs, and enforce the vendor boundary in CI.",
   "type": "module",
   "bin": {
     "flaglint": "dist/bin/flaglint.js"
@@ -71,9 +71,11 @@
     "@vitest/coverage-v8": "^4.1.6",
     "astro": "^6.3.8",
     "clipboardy": "^4.0.0",
+    "png-to-ico": "^3.0.1",
     "tsup": "^8.2.4",
     "tsx": "^4.19.0",
     "typescript": "^5.5.4",
-    "vitest": "^4.1.6"
+    "vitest": "^4.1.6",
+    "starlight-blog": "^0.26.1"
   }
 }