flaglint 0.2.2 → 0.3.0

package/CHANGELOG.md

@@ -5,7 +5,12 @@ 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.2.2] - 2026-05-23
+## [0.3.0] - 2026-05-23
+
+### Added
+
+- **SARIF output**: `flaglint scan --format sarif --output flaglint.sarif` now emits SARIF 2.1.0 for GitHub Code Scanning / PR annotations.
+- **Persistent scan metadata**: `ScanResult` now includes `scannedAt` and `scanRoot`, giving JSON/SARIF/HTML reports a stable scan timestamp and source-root context.
 
 ### Fixed
 
@@ -13,6 +18,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Typed scan warnings**: `ScanResult.warnings` is now a typed `ScanWarning` union (`read-failure` | `parse-failure`) instead of opaque strings, preserving structured data at the domain boundary.
 - **StalenessEvaluator wired**: The `StalenessEvaluator` interface now has a call site in `scan()` — pass an `evaluator` to inject API-based staleness signals without touching core scanner logic.
 - **ScanConfig boundary**: `scan()` now accepts `ScanConfig` (scan-relevant fields only) rather than the full `FlagLintConfig`, decoupling the scanner from CLI output concerns (`reportTitle`, `outputDir`).
+- **Report count consistency**: Markdown and HTML stale candidate counts now exclude wildcard (`*`) usages, matching the CLI summary.
 
 ## [0.2.1] - 2026-05-23
 

package/README.md

@@ -3,7 +3,7 @@
 </p>
 
 <p align="center">
-  <strong>Find stale feature flags. Detect flag debt. Plan your OpenFeature migration.</strong>
+  <strong>Your LaunchDarkly codebase has flag debt. FlagLint tells you exactly what and where.</strong>
 </p>
 
 <p align="center">
@@ -24,11 +24,8 @@
 
 # FlagLint
 
-**Find stale feature flags. Detect flag debt. Plan your OpenFeature migration.**
-
-[![CI](https://github.com/flaglint/flaglint/actions/workflows/ci.yml/badge.svg)](https://github.com/flaglint/flaglint/actions/workflows/ci.yml)
-[![npm version](https://img.shields.io/npm/v/flaglint.svg)](https://www.npmjs.com/package/flaglint)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+Find zombie flags. Eliminate flag debt. Generate your OpenFeature
+migration plan.
 
 ---
 
@@ -36,6 +33,8 @@
 
 LaunchDarkly flags accumulate. Teams add them, forget to clean them up, and gradually build flag debt — dead code paths controlled by flags nobody manages. When you finally want to migrate to OpenFeature, you don't even know what you have.
 
+Like Uber's Piranha — for any JS/TS codebase.
+
 **FlagLint fixes this.** It scans your codebase, maps every flag usage, identifies stale candidates, and generates a step-by-step OpenFeature migration plan.
 
 ---
@@ -46,6 +45,49 @@ LaunchDarkly flags accumulate. Teams add them, forget to clean them up, and grad
 npx flaglint scan
 ```
 
+Example output:
+
+```text
+✓ 15 flag usages found across 6 unique flags (48ms)
+⚠  5 potentially stale flag(s) — review recommended
+ℹ  1 dynamic flag key(s) require manual review
+```
+
+Markdown report excerpt:
+
+```markdown
+## Flag Inventory
+| Flag Key | Usages | Files | Call Types | Status |
+|----------|--------|-------|------------|--------|
+| show-banner | 1 | 1 | variation | ✓ Active |
+| old-checkout | 1 | 1 | variation | ⚠ Stale |
+| temp-debug-mode | 1 | 1 | variation | ⚠ Stale |
+
+## ⚠ Stale Flag Candidates
+| Flag Key | Reason | Location |
+|----------|--------|----------|
+| old-checkout | Contains "old" in key | ld-stale.ts:1 |
+```
+
+### JSON output (`--format json`)
+
+Pipe-friendly. Every usage includes file, line, call type,
+and structured staleness signals:
+
+```json
+{
+  "flagKey": "old-checkout",
+  "isDynamic": false,
+  "file": "src/components/Checkout.tsx",
+  "line": 14,
+  "callType": "variation",
+  "stalenessSignals": [
+    { "source": "keyword", "keyword": "old" },
+    { "source": "minFileCount", "fileCount": 1, "threshold": 1 }
+  ]
+}
+```
+
 ---
 
 ## Installation
@@ -68,13 +110,15 @@ Scans a directory for LaunchDarkly SDK usage.
 flaglint scan ./src
 flaglint scan --format json --output report.json
 flaglint scan --format html --output report.html
+flaglint scan --format sarif --output flaglint.sarif
 ```
 
 | Option | Default | Description |
 |--------|---------|-------------|
-| `--format` | `markdown` | Output format: `json`, `markdown`, `html` |
+| `--format` | `markdown` | Output format: `json`, `markdown`, `html`, `sarif` |
 | `--output` | stdout | Write report to file |
-| `--config` | auto-detect | Path to `.flaglintrc` |
+| `--config` | auto-detect | Path to a config file |
+| `--exclude-tests` | — | Exclude test files from scan results |
 
 Exit code `0` when no stale flags found, `1` when stale flags exist — enabling CI blocking.
 
@@ -94,13 +138,13 @@ flaglint migrate --output MIGRATION.md
 |--------|---------|-------------|
 | `--output` | `MIGRATION.md` | Write migration plan to file |
 | `--dry-run` | — | Print plan to stdout, do not write file |
-| `--config` | auto-detect | Path to `.flaglintrc` |
+| `--config` | auto-detect | Path to a config file |
 
 ---
 
 ## Configuration
 
-Create `.flaglintrc` in your project root:
+Create `.flaglintrc`, `.flaglintrc.json`, or `flaglint.config.json` in your project root:
 
 ```json
 {
@@ -122,18 +166,53 @@ Create `.flaglintrc` in your project root:
 | `reportTitle` | `string` | — | Custom title for generated reports |
 | `outputDir` | `string` | `"."` | Default output directory |
 
-FlagLint searches for config in this order: `--config` flag → `.flaglintrc` → `.flaglintrc.json` → `flaglint.config.json`.
+FlagLint searches for config in this order: `--config` path → `.flaglintrc` → `.flaglintrc.json` → `flaglint.config.json`.
 
 ---
 
 ## CI Integration
 
+### Basic — block PRs on stale flags
+
 ```yaml
 - name: Check for stale flags
   run: npx flaglint scan --format json --output flaglint-report.json
   # exits 1 if stale flags found, blocking the PR
 ```
 
+### GitHub PR annotations via SARIF
+
+Stale flags appear as warnings directly in the PR diff —
+no dashboard, no separate tool.
+
+```yaml
+name: FlagLint
+on: [pull_request]
+
+jobs:
+  flaglint:
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - name: Scan for flag debt
+        run: npx flaglint scan --format sarif --output flaglint.sarif
+        continue-on-error: true
+      - name: Upload to GitHub Code Scanning
+        uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: flaglint.sarif
+```
+
+Stale flags show up as Code Scanning alerts on the exact file
+and line where the flag is used — reviewers see them in the PR
+without running anything locally.
+
 ---
 
 ## What FlagLint detects
@@ -142,9 +221,10 @@ FlagLint searches for config in this order: `--config` flag → `.flaglintrc`
 - `ldClient.allFlags()`
 - `useFlags()`, `useLDClient()` React hooks
 - `<LDProvider>` and `withLDConsumer()` patterns
+- Custom wrapper calls such as `flagPredicate("my-flag", false)` when configured with `wrappers`
 - Dynamic flag keys (runtime-determined, flagged for manual review)
 
-All detections include the **file path**, **line number**, **call type**, and a **stale heuristic** based on key names and file locations.
+All detections include the **file path**, **line number**, **call type**, and staleness signals based on key names, file locations, and low file counts.
 
 ---
 
@@ -169,6 +249,14 @@ See [CONTRIBUTING.md](./CONTRIBUTING.md).
 
 ---
 
+## Free flag debt audit
+
+Running this on a real codebase?
+[Book a free 30-minute audit →](https://flaglint.dev#waitlist)
+I'll run FlagLint on your repo and walk you through the results.
+
+---
+
 ## License
 
 MIT — see [LICENSE](./LICENSE).

package/dist/bin/flaglint.js

@@ -6,7 +6,7 @@ import { Command } from "commander";
 // src/commands/scan.ts
 import { writeFile } from "fs/promises";
 import { stat } from "fs/promises";
-import { resolve as resolve2 } from "path";
+import { resolve as resolve4 } from "path";
 import chalk from "chalk";
 import ora from "ora";
 
@@ -190,6 +190,7 @@ function detectUsages(ast, filePath, wrappers) {
 }
 async function scan(source, config, onProgress, evaluator) {
   const start = Date.now();
+  const scannedAt = (/* @__PURE__ */ new Date()).toISOString();
   for (const pattern of config.include) {
     if (pattern.startsWith("/") || pattern.startsWith("..")) {
       throw new Error(
@@ -270,6 +271,8 @@ async function scan(source, config, onProgress, evaluator) {
     )
   ];
   return {
+    scannedAt,
+    scanRoot: source.root ?? ".",
     scannedFiles,
     totalUsages: allUsages.length,
     uniqueFlags,
@@ -282,12 +285,14 @@ async function scan(source, config, onProgress, evaluator) {
 // src/scanner/local-source.ts
 import fg from "fast-glob";
 import { readFile } from "fs/promises";
-import { join, relative } from "path";
+import { join, relative, resolve } from "path";
 var LocalFileSource = class {
   constructor(dir) {
     this.dir = dir;
+    this.root = resolve(dir);
   }
   dir;
+  root;
   async listFiles(include, exclude) {
     const files = await fg(include, {
       cwd: this.dir,
@@ -302,6 +307,10 @@ var LocalFileSource = class {
   }
 };
 
+// src/reporter/index.ts
+import { resolve as resolve2 } from "path";
+import { pathToFileURL } from "url";
+
 // src/types.ts
 var isStale = (u) => u.stalenessSignals.length > 0;
 
@@ -331,11 +340,11 @@ function sortedFlagEntries(map) {
 }
 function formatMarkdown(result, options) {
   const { scannedFiles, totalUsages, uniqueFlags, usages, scanDurationMs } = result;
-  const staleUsages = usages.filter(isStale);
+  const staleUsages = usages.filter((u) => isStale(u) && !u.isDynamic && u.flagKey !== "*");
   const dynamicUsages = usages.filter((u) => u.isDynamic);
   const flagMap = buildFlagMap(usages);
   const sorted = sortedFlagEntries(flagMap);
-  const staleFlags = sorted.filter(([, d]) => d.isStale);
+  const staleFlags = sorted.filter(([key, d]) => key !== "*" && d.isStale);
   const lines = [];
   lines.push("# FlagLint Scan Report");
   if (options.title) lines.push("", options.title);
@@ -391,13 +400,128 @@ function formatMarkdown(result, options) {
   return lines.join("\n");
 }
 function formatJSON(result) {
-  return JSON.stringify({ generatedAt: (/* @__PURE__ */ new Date()).toISOString(), ...result }, null, 2);
+  return JSON.stringify({ generatedAt: result.scannedAt, ...result }, null, 2);
+}
+function signalRuleId(usage) {
+  const signal = usage.stalenessSignals[0];
+  if (!signal) return "flaglint.stale";
+  return `flaglint.${signal.source}`;
+}
+function signalMessage(usage) {
+  const reasons = usage.stalenessSignals.map((signal) => {
+    switch (signal.source) {
+      case "keyword":
+        return `keyword "${signal.keyword}"`;
+      case "path":
+        return `path pattern "${signal.pattern}"`;
+      case "minFileCount":
+        return `file count ${signal.fileCount} <= ${signal.threshold}`;
+    }
+  });
+  return reasons.length > 0 ? reasons.join(", ") : "staleness signal";
+}
+function sarifUri(file) {
+  return file.split(/[\\/]/).join("/");
+}
+function sarifRootUri(scanRoot) {
+  const uri = pathToFileURL(resolve2(scanRoot)).href;
+  return uri.endsWith("/") ? uri : `${uri}/`;
+}
+function formatSARIF(result) {
+  const staleUsages = result.usages.filter((u) => isStale(u) && !u.isDynamic && u.flagKey !== "*");
+  const rules = [
+    {
+      id: "flaglint.keyword",
+      name: "Stale flag keyword",
+      shortDescription: { text: "Flag key contains a stale keyword" },
+      helpUri: "https://github.com/flaglint/flaglint#what-flaglint-detects"
+    },
+    {
+      id: "flaglint.path",
+      name: "Stale flag path",
+      shortDescription: { text: "Flag usage appears in a stale path" },
+      helpUri: "https://github.com/flaglint/flaglint#what-flaglint-detects"
+    },
+    {
+      id: "flaglint.minFileCount",
+      name: "Low file count",
+      shortDescription: { text: "Flag appears in too few files" },
+      helpUri: "https://github.com/flaglint/flaglint#configuration"
+    }
+  ];
+  return JSON.stringify(
+    {
+      $schema: "https://json.schemastore.org/sarif-2.1.0.json",
+      version: "2.1.0",
+      runs: [
+        {
+          tool: {
+            driver: {
+              name: "FlagLint",
+              informationUri: "https://github.com/flaglint/flaglint",
+              rules
+            }
+          },
+          invocations: [
+            {
+              executionSuccessful: true,
+              startTimeUtc: result.scannedAt,
+              properties: {
+                scannedFiles: result.scannedFiles,
+                totalUsages: result.totalUsages,
+                uniqueFlags: result.uniqueFlags.length,
+                scanDurationMs: result.scanDurationMs
+              }
+            }
+          ],
+          originalUriBaseIds: {
+            "%SRCROOT%": {
+              uri: sarifRootUri(result.scanRoot)
+            }
+          },
+          results: staleUsages.map((usage) => ({
+            ruleId: signalRuleId(usage),
+            level: "warning",
+            message: {
+              text: `Potentially stale feature flag "${usage.flagKey}" detected: ${signalMessage(usage)}.`
+            },
+            locations: [
+              {
+                physicalLocation: {
+                  artifactLocation: {
+                    uri: sarifUri(usage.file),
+                    uriBaseId: "%SRCROOT%"
+                  },
+                  region: {
+                    startLine: Math.max(usage.line, 1),
+                    startColumn: Math.max(usage.column + 1, 1)
+                  }
+                }
+              }
+            ],
+            partialFingerprints: {
+              "flagKey/v1": usage.flagKey
+            },
+            properties: {
+              flagKey: usage.flagKey,
+              callType: usage.callType,
+              stalenessSignals: usage.stalenessSignals
+            }
+          }))
+        }
+      ]
+    },
+    null,
+    2
+  );
 }
 function formatHTML(result, options) {
   const { scannedFiles, totalUsages, uniqueFlags, usages, scanDurationMs } = result;
-  const staleCount = new Set(usages.filter(isStale).map((u) => u.flagKey)).size;
+  const staleCount = new Set(
+    usages.filter((u) => isStale(u) && !u.isDynamic && u.flagKey !== "*").map((u) => u.flagKey)
+  ).size;
   const dynamicCount = usages.filter((u) => u.isDynamic).length;
-  const date = (/* @__PURE__ */ new Date()).toLocaleString();
+  const date = new Date(result.scannedAt).toLocaleString();
   const flagMap = buildFlagMap(usages);
   const sorted = sortedFlagEntries(flagMap);
   const rows = sorted.map(([key, data]) => {
@@ -407,7 +531,7 @@ function formatHTML(result, options) {
     return `<tr class="${cls}"><td><code>${esc(key)}</code></td><td>${data.usages.length}</td><td>${fileList}</td><td>${[...data.callTypes].map(esc).join(", ")}</td><td>${status}</td></tr>`;
   }).join("\n      ");
   const title = options.title ? esc(options.title) : "FlagLint Scan Report";
-  const version = true ? "0.2.2" : "0.1.0";
+  const version = true ? "0.3.0" : "0.1.0";
   return `<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -482,14 +606,16 @@ function formatReport(result, options) {
       return formatJSON(result);
     case "html":
       return formatHTML(result, options);
-    default:
+    case "markdown":
       return formatMarkdown(result, options);
+    case "sarif":
+      return formatSARIF(result);
   }
 }
 
 // src/config.ts
 import { readFile as readFile2, access } from "fs/promises";
-import { resolve } from "path";
+import { resolve as resolve3 } from "path";
 import { z, ZodError } from "zod";
 var FlagLintConfigSchema = z.object({
   include: z.array(z.string()).default(["**/*.{ts,tsx,js,jsx}"]),
@@ -512,7 +638,7 @@ var SEARCH_PATHS = [".flaglintrc", ".flaglintrc.json", "flaglint.config.json"];
 async function loadConfig(configPath) {
   const candidates = configPath ? [configPath] : SEARCH_PATHS;
   for (const candidate of candidates) {
-    const full = resolve(candidate);
+    const full = resolve3(candidate);
     try {
       await access(full);
     } catch {
@@ -538,15 +664,16 @@ async function loadConfig(configPath) {
 }
 
 // src/commands/scan.ts
-var VALID_FORMATS = ["json", "markdown", "html"];
+var VALID_FORMATS = ["json", "markdown", "html", "sarif"];
 function registerScanCommand(program2) {
-  program2.command("scan").description("Scan a directory for feature flag usages and detect stale flags").argument("[dir]", "directory to scan", 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(
+  program2.command("scan").description("Scan a directory for feature flag usages and detect stale flags").argument("[dir]", "directory to scan", process.cwd()).option("-f, --format <format>", "output format: json | markdown | html | sarif", "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 scan                    scan current directory
   $ flaglint scan ./src              scan specific directory
   $ flaglint scan --format json      output as JSON
+  $ flaglint scan --format sarif     output as SARIF for GitHub Code Scanning
   $ flaglint scan --output report.md save to file
   $ flaglint scan --exclude-tests    skip test and spec files`
   ).action(
@@ -561,7 +688,7 @@ Examples:
         process.exit(2);
       }
       try {
-        const s = await stat(resolve2(dir));
+        const s = await stat(resolve4(dir));
         if (!s.isDirectory()) {
           process.stderr.write(chalk.red(`Error: Not a directory: ${dir}
 `));
@@ -661,7 +788,7 @@ Examples:
       }
       const report = formatReport(result, { format, title: config.reportTitle });
       if (options.output) {
-        const outPath = resolve2(options.output);
+        const outPath = resolve4(options.output);
         try {
           await writeFile(outPath, report, "utf8");
           process.stderr.write(chalk.dim(`   Report written to ${options.output}
@@ -686,7 +813,7 @@ Examples:
 // src/commands/migrate.ts
 import { writeFile as writeFile2 } from "fs/promises";
 import { stat as stat2 } from "fs/promises";
-import { resolve as resolve3 } from "path";
+import { resolve as resolve5 } from "path";
 import chalk2 from "chalk";
 import ora2 from "ora";
 
@@ -827,7 +954,7 @@ function analyze(result) {
 function formatMigrationReport(analysis) {
   const { readinessScore, requiredPackages, items, manualReviewCount, autoMigrateCount } = analysis;
   const date = (/* @__PURE__ */ new Date()).toLocaleDateString();
-  const version = true ? "0.2.2" : "0.1.0";
+  const version = true ? "0.3.0" : "0.1.0";
   let scoreLabel;
   if (readinessScore >= 80) scoreLabel = "\u2713 Your codebase is ready for migration";
   else if (readinessScore >= 50) scoreLabel = "\u26A0 Some manual work required before migration";
@@ -913,7 +1040,7 @@ Examples:
   ).action(
     async (dir, options) => {
       try {
-        const s = await stat2(resolve3(dir));
+        const s = await stat2(resolve5(dir));
         if (!s.isDirectory()) {
           process.stderr.write(chalk2.red(`Error: Not a directory: ${dir}
 `));
@@ -1003,7 +1130,7 @@ Examples:
         process.stdout.write(report + "\n");
         process.exit(0);
       }
-      const outPath = resolve3(options.output);
+      const outPath = resolve5(options.output);
       try {
         await writeFile2(outPath, report, "utf8");
         process.stderr.write(chalk2.green(`Migration plan written to ${options.output}
@@ -1025,7 +1152,7 @@ Examples:
 // src/cli.ts
 function createCLI() {
   const program2 = new Command();
-  program2.name("flaglint").description("Find stale feature flags. Detect flag debt. Plan your OpenFeature migration.").version("0.2.2", "-v, --version", "output the current version").addHelpText(
+  program2.name("flaglint").description("Find stale feature flags. Detect flag debt. Plan your OpenFeature migration.").version("0.3.0", "-v, --version", "output the current version").addHelpText(
     "after",
     `
 Examples:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flaglint",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Find stale feature flags. Detect flag debt. Plan your OpenFeature migration.",
   "type": "module",
   "bin": {
@@ -34,13 +34,15 @@
     "url": "https://github.com/flaglint/flaglint/issues"
   },
   "scripts": {
-    "build": "tsup",
+    "sync:www": "tsx scripts/sync-www.ts",
+    "build": "npm run sync:www && tsup",
     "dev": "tsup --watch",
     "typecheck": "tsc --noEmit",
     "typecheck:agent": "tsc --project tsconfig.agent.json",
     "test": "vitest",
     "test:run": "vitest run",
     "test:coverage": "vitest run --coverage",
+    "new-branch": "tsx scripts/new-branch.ts",
     "release:patch": "tsx scripts/release.ts patch",
     "release:minor": "tsx scripts/release.ts minor",
     "release:major": "tsx scripts/release.ts major"