flaglint 0.1.5 → 0.2.0

package/CHANGELOG.md

@@ -5,6 +5,39 @@ 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.0] - 2026-05-22
+
+### Breaking Changes
+
+- **`FlagUsage.isStale: boolean` replaced with `stalenessSignals: StalenessSignal[]`**
+  The boolean had no provenance — you could not tell which signal (keyword, path, file-count, future LD API age) caused a flag to be marked stale. Replaced with a typed union array that records every signal that fired and why.
+
+  **Migration:** Replace `usage.isStale` checks with the exported helper:
+  ```typescript
+  import { isStale } from "flaglint";
+  if (isStale(usage)) { ... }
+  ```
+  JSON report consumers: the `usages[].isStale` field is gone. Use `usages[].stalenessSignals.length > 0` or the `isStale()` helper. Reports now include staleness provenance (source + keyword/pattern/count).
+
+- **Renamed config field: `staleThreshold` → `minFileCount`**
+  The field was previously documented as "days before a flag is considered stale" but was actually implemented as a file-count threshold (a flag is stale if it appears in ≤ N files). The rename makes the actual behavior honest.
+
+  **Migration:** In your `flaglint.config.json` or `.flaglintrc`, rename the field:
+  ```json
+  // Before
+  { "staleThreshold": 5 }
+  // After
+  { "minFileCount": 5 }
+  ```
+
+### Changed
+
+- Extracted shared stale detection logic (`STALE_KEYWORDS`, `checkStale`, `staleReason`) into `src/stale.ts` — single source of truth, eliminates duplicate keyword lists between scanner and reporter
+
+### Roadmap
+
+- `v0.3`: Replace `minFileCount` with real date-based staleness detection via `git log` integration
+
 ## [0.1.5] - 2026-05-21
 
 ### Fixed

package/README.md

@@ -107,7 +107,7 @@ Create `.flaglintrc` in your project root:
   "include": ["**/*.{ts,tsx,js,jsx}"],
   "exclude": ["**/node_modules/**", "**/dist/**"],
   "provider": "launchdarkly",
-  "staleThreshold": 1,
+  "minFileCount": 1,
   "reportTitle": "My Project Flag Report"
 }
 ```
@@ -117,7 +117,7 @@ Create `.flaglintrc` in your project root:
 | `include` | `string[]` | `["**/*.{ts,tsx,js,jsx}"]` | Glob patterns to scan |
 | `exclude` | `string[]` | `["**/node_modules/**", ...]` | Glob patterns to ignore |
 | `provider` | `string` | `"launchdarkly"` | Feature flag provider |
-| `staleThreshold` | `number` | `1` | Days before a flag is considered stale |
+| `minFileCount` | `number` | `1` | A flag is stale if it appears in ≤ N files (default: 1) |
 | `reportTitle` | `string` | — | Custom title for generated reports |
 | `outputDir` | `string` | `"."` | Default output directory |
 

package/dist/bin/flaglint.js

@@ -11,16 +11,34 @@ import chalk from "chalk";
 import ora from "ora";
 
 // src/scanner/index.ts
-import { readFile } from "fs/promises";
-import { relative } from "path";
-import fg from "fast-glob";
+import pLimit from "p-limit";
 import { parse } from "@typescript-eslint/typescript-estree";
-var LD_MEMBER_METHODS = /* @__PURE__ */ new Set(["variation", "variationDetail", "allFlags"]);
-var LD_CLIENT_PATTERN = /ld|client/i;
-var LD_HOOKS = /* @__PURE__ */ new Set(["useFlags", "useLDClient"]);
-var STALE_KEY_WORDS = ["old", "deprecated", "legacy", "temp", "tmp", "test", "demo"];
+
+// src/stale.ts
+var STALE_KEYWORDS = ["old", "deprecated", "legacy", "temp", "tmp", "test", "demo"];
 var STALE_FILE_RE = /\.(test|spec|mock)\.[jt]sx?$/;
 var STALE_PATH_RE = /\/deprecated\/|\/old\/|\/legacy\//;
+function checkStale(flagKey, filePath) {
+  if (STALE_FILE_RE.test(filePath)) return { source: "path", pattern: "test/spec/mock file" };
+  if (STALE_PATH_RE.test(filePath)) return { source: "path", pattern: "deprecated/old/legacy path" };
+  const lk = flagKey.toLowerCase();
+  const kw = STALE_KEYWORDS.find((k) => new RegExp(`(?:^|[-_])${k}(?:[-_]|$)`).test(lk));
+  if (kw) return { source: "keyword", keyword: kw };
+  return null;
+}
+function staleReason(u) {
+  for (const s of u.stalenessSignals) {
+    if (s.source === "keyword") return `Contains "${s.keyword}" in key`;
+    if (s.source === "path") return s.pattern === "test/spec/mock file" ? "Located in test file" : "Located in deprecated path";
+    if (s.source === "minFileCount") return `Appears in only ${s.fileCount} file(s) (threshold: ${s.threshold})`;
+  }
+  return "Flagged as stale";
+}
+
+// src/scanner/index.ts
+var LD_MEMBER_METHODS = /* @__PURE__ */ new Set(["variation", "variationDetail", "allFlags"]);
+var LD_CLIENT_PATTERN = /^ld|client/i;
+var LD_HOOKS = /* @__PURE__ */ new Set(["useFlags", "useLDClient"]);
 var DEFAULT_EXCLUDE = ["**/node_modules/**", "**/dist/**", "**/build/**", "**/.next/**"];
 function extractFlagKey(arg) {
   if (!arg) return { flagKey: "dynamic", isDynamic: true };
@@ -33,26 +51,28 @@ function extractFlagKey(arg) {
   }
   return { flagKey: "dynamic", isDynamic: true };
 }
-function checkStale(flagKey, filePath) {
-  if (STALE_FILE_RE.test(filePath)) return true;
-  if (STALE_PATH_RE.test(filePath)) return true;
-  const lk = flagKey.toLowerCase();
-  return STALE_KEY_WORDS.some((kw) => lk.includes(kw));
-}
-function walk(node, visit) {
-  if (!node || typeof node !== "object") return;
-  visit(node);
-  for (const key of Object.keys(node)) {
-    if (key === "parent") continue;
-    const val = node[key];
-    if (Array.isArray(val)) {
-      for (const item of val) {
-        if (item && typeof item === "object" && "type" in item) {
-          walk(item, visit);
+function walk(root, visit) {
+  if (!root || typeof root !== "object") return;
+  const stack = [root];
+  while (stack.length > 0) {
+    const node = stack.pop();
+    visit(node);
+    const children = [];
+    for (const key of Object.keys(node)) {
+      if (key === "parent") continue;
+      const val = node[key];
+      if (Array.isArray(val)) {
+        for (const item of val) {
+          if (item && typeof item === "object" && "type" in item) {
+            children.push(item);
+          }
         }
+      } else if (val && typeof val === "object" && "type" in val) {
+        children.push(val);
       }
-    } else if (val && typeof val === "object" && "type" in val) {
-      walk(val, visit);
+    }
+    for (let i = children.length - 1; i >= 0; i--) {
+      stack.push(children[i]);
     }
   }
 }
@@ -66,6 +86,7 @@ function detectUsages(ast, filePath) {
       if (callee.type === "MemberExpression" && !callee.computed && callee.object.type === "Identifier" && callee.property.type === "Identifier" && LD_CLIENT_PATTERN.test(callee.object.name) && LD_MEMBER_METHODS.has(callee.property.name)) {
         const method = callee.property.name;
         if (method === "allFlags") {
+          const sig = checkStale("*", filePath);
           usages.push({
             flagKey: "*",
             isDynamic: false,
@@ -73,10 +94,11 @@ function detectUsages(ast, filePath) {
             line: loc.line,
             column: loc.column,
             callType: "allFlags",
-            isStale: checkStale("*", filePath)
+            stalenessSignals: sig ? [sig] : []
           });
         } else {
           const { flagKey, isDynamic } = extractFlagKey(call.arguments[0]);
+          const sig = checkStale(flagKey, filePath);
           usages.push({
             flagKey,
             isDynamic,
@@ -84,7 +106,7 @@ function detectUsages(ast, filePath) {
             line: loc.line,
             column: loc.column,
             callType: method,
-            isStale: checkStale(flagKey, filePath)
+            stalenessSignals: sig ? [sig] : []
           });
         }
         return;
@@ -93,6 +115,7 @@ function detectUsages(ast, filePath) {
         const name = callee.name;
         if (name === "isFeatureEnabled") {
           const { flagKey, isDynamic } = extractFlagKey(call.arguments[0]);
+          const sig = checkStale(flagKey, filePath);
           usages.push({
             flagKey,
             isDynamic,
@@ -100,11 +123,12 @@ function detectUsages(ast, filePath) {
             line: loc.line,
             column: loc.column,
             callType: "isFeatureEnabled",
-            isStale: checkStale(flagKey, filePath)
+            stalenessSignals: sig ? [sig] : []
           });
           return;
         }
         if (LD_HOOKS.has(name)) {
+          const sig = checkStale("*", filePath);
           usages.push({
             flagKey: "*",
             isDynamic: false,
@@ -112,12 +136,13 @@ function detectUsages(ast, filePath) {
             line: loc.line,
             column: loc.column,
             callType: name === "useFlags" ? "hook-useFlags" : "hook-useLDClient",
-            isStale: checkStale("*", filePath)
+            stalenessSignals: sig ? [sig] : []
           });
           return;
         }
       }
       if (callee.type === "CallExpression" && callee.callee.type === "Identifier" && callee.callee.name === "withLDConsumer") {
+        const sig = checkStale("*", filePath);
         usages.push({
           flagKey: "*",
           isDynamic: false,
@@ -125,7 +150,7 @@ function detectUsages(ast, filePath) {
           line: loc.line,
           column: loc.column,
           callType: "hoc",
-          isStale: checkStale("*", filePath)
+          stalenessSignals: sig ? [sig] : []
         });
         return;
       }
@@ -134,6 +159,7 @@ function detectUsages(ast, filePath) {
       const jsx = node;
       if (jsx.name.type === "JSXIdentifier" && jsx.name.name === "LDProvider") {
         const loc = jsx.loc?.start ?? { line: 0, column: 0 };
+        const sigP = checkStale("*", filePath);
         usages.push({
           flagKey: "*",
           isDynamic: false,
@@ -141,14 +167,14 @@ function detectUsages(ast, filePath) {
           line: loc.line,
           column: loc.column,
           callType: "provider",
-          isStale: checkStale("*", filePath)
+          stalenessSignals: sigP ? [sigP] : []
         });
       }
     }
   });
   return usages;
 }
-async function scan(dir, config, onProgress) {
+async function scan(source, config, onProgress) {
   const start = Date.now();
   for (const pattern of config.include) {
     if (pattern.startsWith("/") || pattern.startsWith("..")) {
@@ -157,23 +183,17 @@ async function scan(dir, config, onProgress) {
       );
     }
   }
-  const files = await fg(config.include, {
-    cwd: dir,
-    absolute: true,
-    ignore: [...DEFAULT_EXCLUDE, ...config.exclude],
-    onlyFiles: true
-  });
+  const files = await source.listFiles(config.include, config.exclude);
   const allUsages = [];
   const warnings = [];
   let scannedFiles = 0;
-  for (const file of files) {
-    scannedFiles++;
-    onProgress?.(scannedFiles);
+  async function processFile(file) {
     let code;
     try {
-      code = await readFile(file, "utf8");
-    } catch {
-      continue;
+      code = await source.readFile(file);
+    } catch (err) {
+      const fsCode = err.code ?? "UNKNOWN";
+      return { usages: [], warning: `warn: could not read ${file} (${fsCode})` };
     }
     let ast;
     try {
@@ -185,12 +205,25 @@ async function scan(dir, config, onProgress) {
         tokens: false
       });
     } catch {
-      warnings.push(`warn: failed to parse ${relative(dir, file)}`);
-      continue;
+      return { usages: [], warning: `warn: failed to parse ${file}` };
     }
-    allUsages.push(...detectUsages(ast, file));
+    return { usages: detectUsages(ast, file), warning: null };
+  }
+  const limit = pLimit(50);
+  const results = await Promise.all(
+    files.map(
+      (file) => limit(async () => {
+        scannedFiles++;
+        onProgress?.(scannedFiles);
+        return processFile(file);
+      })
+    )
+  );
+  for (const r of results) {
+    allUsages.push(...r.usages);
+    if (r.warning) warnings.push(r.warning);
   }
-  if (config.staleThreshold > 0) {
+  if (config.minFileCount > 0) {
     const flagFileCount = /* @__PURE__ */ new Map();
     for (const usage of allUsages) {
       if (!usage.isDynamic && usage.flagKey !== "*") {
@@ -203,8 +236,12 @@ async function scan(dir, config, onProgress) {
     for (const usage of allUsages) {
       if (!usage.isDynamic && usage.flagKey !== "*") {
         const fileCount = flagFileCount.get(usage.flagKey)?.size ?? 0;
-        if (fileCount <= config.staleThreshold) {
-          usage.isStale = true;
+        if (fileCount <= config.minFileCount) {
+          usage.stalenessSignals.push({
+            source: "minFileCount",
+            fileCount,
+            threshold: config.minFileCount
+          });
         }
       }
     }
@@ -224,18 +261,36 @@ async function scan(dir, config, onProgress) {
   };
 }
 
+// src/scanner/local-source.ts
+import fg from "fast-glob";
+import { readFile } from "fs/promises";
+import { join, relative } from "path";
+var LocalFileSource = class {
+  constructor(dir) {
+    this.dir = dir;
+  }
+  dir;
+  async listFiles(include, exclude) {
+    const files = await fg(include, {
+      cwd: this.dir,
+      absolute: true,
+      ignore: [...DEFAULT_EXCLUDE, ...exclude],
+      onlyFiles: true
+    });
+    return files.map((f) => relative(this.dir, f));
+  }
+  async readFile(path) {
+    return readFile(join(this.dir, path), "utf8");
+  }
+};
+
+// src/types.ts
+var isStale = (u) => u.stalenessSignals.length > 0;
+
 // src/reporter/index.ts
 function esc(s) {
   return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 }
-function staleReason(u) {
-  if (/\.(test|spec|mock)\.[jt]sx?$/.test(u.file)) return "Located in test file";
-  if (/\/deprecated\/|\/old\/|\/legacy\//.test(u.file)) return "Located in deprecated path";
-  const kw = ["old", "deprecated", "legacy", "temp", "tmp", "test", "demo"].find(
-    (k) => u.flagKey.toLowerCase().includes(k)
-  );
-  return kw ? `Contains "${kw}" in key` : "Flagged as stale";
-}
 function buildFlagMap(usages) {
   const map = /* @__PURE__ */ new Map();
   for (const u of usages) {
@@ -246,7 +301,7 @@ function buildFlagMap(usages) {
     entry.usages.push(u);
     entry.files.add(u.file);
     entry.callTypes.add(u.callType);
-    if (u.isStale) entry.isStale = true;
+    if (isStale(u)) entry.isStale = true;
   }
   return map;
 }
@@ -258,7 +313,7 @@ function sortedFlagEntries(map) {
 }
 function formatMarkdown(result, options) {
   const { scannedFiles, totalUsages, uniqueFlags, usages, scanDurationMs } = result;
-  const staleUsages = usages.filter((u) => u.isStale);
+  const staleUsages = usages.filter(isStale);
   const dynamicUsages = usages.filter((u) => u.isDynamic);
   const flagMap = buildFlagMap(usages);
   const sorted = sortedFlagEntries(flagMap);
@@ -300,7 +355,7 @@ function formatMarkdown(result, options) {
     lines.push("| Flag Key | Reason | Location |");
     lines.push("|----------|--------|----------|");
     for (const [key, data] of staleFlags) {
-      const first = data.usages.find((u) => u.isStale) ?? data.usages[0];
+      const first = data.usages.find(isStale) ?? data.usages[0];
       lines.push(`| ${key} | ${staleReason(first)} | ${first.file}:${first.line} |`);
     }
     lines.push("");
@@ -322,7 +377,7 @@ function formatJSON(result) {
 }
 function formatHTML(result, options) {
   const { scannedFiles, totalUsages, uniqueFlags, usages, scanDurationMs } = result;
-  const staleCount = new Set(usages.filter((u) => u.isStale).map((u) => u.flagKey)).size;
+  const staleCount = new Set(usages.filter(isStale).map((u) => u.flagKey)).size;
   const dynamicCount = usages.filter((u) => u.isDynamic).length;
   const date = (/* @__PURE__ */ new Date()).toLocaleString();
   const flagMap = buildFlagMap(usages);
@@ -334,7 +389,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.1.5" : "0.1.0";
+  const version = true ? "0.2.0" : "0.1.0";
   return `<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -415,7 +470,7 @@ function formatReport(result, options) {
 }
 
 // src/config.ts
-import { existsSync, readFileSync } from "fs";
+import { readFile as readFile2, access } from "fs/promises";
 import { resolve } from "path";
 import { z, ZodError } from "zod";
 var FlagLintConfigSchema = z.object({
@@ -429,19 +484,24 @@ var FlagLintConfigSchema = z.object({
     "**/*.d.ts"
   ]),
   provider: z.enum(["launchdarkly", "unleash", "growthbook", "custom"]).default("launchdarkly"),
-  staleThreshold: z.number().int().min(0).default(1),
+  // TODO v0.3: replace minFileCount with real date-based staleness via git log
+  minFileCount: z.number().int().min(0).default(1),
   reportTitle: z.string().optional(),
   outputDir: z.string().default(".")
 });
 var SEARCH_PATHS = [".flaglintrc", ".flaglintrc.json", "flaglint.config.json"];
-function loadConfig(configPath) {
+async function loadConfig(configPath) {
   const candidates = configPath ? [configPath] : SEARCH_PATHS;
   for (const candidate of candidates) {
     const full = resolve(candidate);
-    if (!existsSync(full)) continue;
+    try {
+      await access(full);
+    } catch {
+      continue;
+    }
     let raw;
     try {
-      raw = JSON.parse(readFileSync(full, "utf8"));
+      raw = JSON.parse(await readFile2(full, "utf8"));
     } catch (err) {
       throw new Error(`Error reading ${candidate}: ${String(err)}`);
     }
@@ -504,7 +564,7 @@ Examples:
       }
       let config;
       try {
-        config = loadConfig(options.config);
+        config = await loadConfig(options.config);
       } catch (err) {
         process.stderr.write(chalk.red(String(err instanceof Error ? err.message : err)) + "\n");
         process.exit(1);
@@ -528,7 +588,7 @@ Examples:
       let lastSpinnerUpdate = 0;
       let result;
       try {
-        result = await scan(dir, config, (filesScanned) => {
+        result = await scan(new LocalFileSource(dir), config, (filesScanned) => {
           if (filesScanned - lastSpinnerUpdate >= 50) {
             spinner.text = `Scanning... (${filesScanned} files)`;
             lastSpinnerUpdate = filesScanned;
@@ -558,7 +618,9 @@ Examples:
         );
         process.exit(0);
       }
-      const staleCount = new Set(result.usages.filter((u) => u.isStale).map((u) => u.flagKey)).size;
+      const staleCount = new Set(
+        result.usages.filter((u) => isStale(u) && !u.isDynamic && u.flagKey !== "*").map((u) => u.flagKey)
+      ).size;
       const dynamicCount = new Set(result.usages.filter((u) => u.isDynamic).map((u) => u.flagKey)).size;
       process.stderr.write(
         chalk.green(
@@ -616,11 +678,13 @@ function keyLiteral(usage) {
 function buildItem(usage) {
   const k = keyLiteral(usage);
   if (usage.isDynamic) {
+    const isDetail = usage.callType === "variationDetail";
+    const methodName = isDetail ? "variationDetail" : "variation";
     return {
       usage,
-      openFeatureEquivalent: "client.getBooleanValue()",
-      codeChangeBefore: `ldClient.variation(flagKey, context, false)`,
-      codeChangeAfter: `await client.getBooleanValue(flagKey, false) // server SDK is async`,
+      openFeatureEquivalent: isDetail ? "client.getBooleanDetails()" : "client.getBooleanValue()",
+      codeChangeBefore: `ldClient.${methodName}(flagKey, context, false)`,
+      codeChangeAfter: isDetail ? `await client.getBooleanDetails(flagKey, false) // server SDK is async` : `await client.getBooleanValue(flagKey, false) // server SDK is async`,
       requiresManualReview: true,
       reviewReason: "Flag key determined at runtime; OpenFeature server SDK methods are async \u2014 add await and make the enclosing function async"
     };
@@ -744,7 +808,7 @@ function analyze(result) {
 function formatMigrationReport(analysis) {
   const { readinessScore, requiredPackages, items, manualReviewCount, autoMigrateCount } = analysis;
   const date = (/* @__PURE__ */ new Date()).toLocaleDateString();
-  const version = true ? "0.1.5" : "0.1.0";
+  const version = true ? "0.2.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";
@@ -852,7 +916,7 @@ Examples:
       }
       let config;
       try {
-        config = loadConfig(options.config);
+        config = await loadConfig(options.config);
       } catch (err) {
         process.stderr.write(chalk2.red(String(err instanceof Error ? err.message : err)) + "\n");
         process.exit(1);
@@ -874,7 +938,7 @@ Examples:
       });
       let scanResult;
       try {
-        scanResult = await scan(dir, config, (filesScanned) => {
+        scanResult = await scan(new LocalFileSource(dir), config, (filesScanned) => {
           spinner.text = `Scanning files... ${filesScanned}`;
         });
         spinner.text = "Analyzing migration readiness...";
@@ -942,7 +1006,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.1.5", "-v, --version", "output the current version").addHelpText(
+  program2.name("flaglint").description("Find stale feature flags. Detect flag debt. Plan your OpenFeature migration.").version("0.2.0", "-v, --version", "output the current version").addHelpText(
     "after",
     `
 Examples:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flaglint",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "Find stale feature flags. Detect flag debt. Plan your OpenFeature migration.",
   "type": "module",
   "bin": {
@@ -56,6 +56,7 @@
     "commander": "^12.1.0",
     "fast-glob": "^3.3.2",
     "ora": "^8.1.0",
+    "p-limit": "^7.3.0",
     "zod": "^3.23.8"
   },
   "devDependencies": {