flagshark 1.3.0 → 1.4.0

package/README.md

@@ -1,60 +1,82 @@
-# flagshark
+# 🦈 flagshark
 
-Find stale feature flags in your codebase. CLI tool + GitHub Action.
+**Find stale feature flags in your codebase.** Polyglot CLI + GitHub Action. 13 languages, 13 providers, zero config.
 
 ```bash
 npx flagshark scan
 ```
 
 ```
-🦈 FlagShark v1.1.1
+🦈 FlagShark v1.3.0 — scanned 156 files in 2.3s
+                       (47 excluded via .flagsharkignore + test-files preset)
 
-Scanned 156 files across 4 languages
-Detected providers: LaunchDarkly (JS SDK), Unleash (Go SDK)
-Found 23 feature flags, 7 stale
+Detected providers: LaunchDarkly (Node SDK), Unleash, PostHog
+Found 23 feature flags · 7 stale · health 70/100 ⚠️
 
-Stale flags:
 ┌──────────────────┬────────────────────────┬───────────────┬──────────────────────────────┐
 │ Flag             │ File                   │ Added         │ Signal                       │
 ├──────────────────┼────────────────────────┼───────────────┼──────────────────────────────┤
-│ CHECKOUT_V2      │ src/checkout.ts:47     │ 14 months ago │ Age > 6 months               │
-│ NEW_NAV          │ src/layout.tsx:12      │ 8 months ago  │ Age > 6 months, Single file  │
-│ BETA_SEARCH      │ src/search.ts:91       │ 11 months ago │ Single file reference        │
+│ CHECKOUT_V2      │ src/checkout.ts:47     │ 14 months ago │ age                          │
+│ NEW_NAV          │ src/layout.tsx:12      │ 8 months ago  │ age, low-usage               │
+│ BETA_SEARCH      │ src/search.ts:91       │ 11 months ago │ low-usage                    │
 └──────────────────┴────────────────────────┴───────────────┴──────────────────────────────┘
 
-Flag Health Score: 70/100 (7/23 flags are stale)
+Exit code: 1 (stale flags found)
 ```
 
+## Why FlagShark
+
+- **Zero install, zero config.** `npx flagshark scan` works on any repo today.
+- **Polyglot.** TypeScript, JavaScript, Go, Python, Java, Kotlin, Swift, Ruby, C#, PHP, Rust, C/C++, Objective-C.
+- **Provider-aware.** Auto-detects 13 flag SDKs — no custom rules to maintain.
+- **AST-based detection** for TS/JS/Go/Python via [tree-sitter](https://tree-sitter.github.io/). Flag names inside strings, comments, and unrelated calls aren't false positives.
+- **Two staleness signals** — `git blame` age + single-file usage. Both run automatically.
+- **MIT licensed.** No account, no token, no telemetry.
+
 ## Install
 
 ```bash
-# Run without installing
+# Recommended — run without installing
 npx flagshark scan
 
-# Or install globally
+# Or globally
 npm install -g flagshark
 ```
 
-Building a tool on top of the engine? Use [`@flagshark/core`](https://www.npmjs.com/package/@flagshark/core) directly.
+## CLI
+
+```bash
+flagshark scan [options]
+
+Scan options:
+  --diff <ref>             Only scan files changed since this git ref (e.g. main, HEAD~1)
+  --threshold <months>     Staleness age threshold (default: 6, or config.threshold)
+  --verbose                Show all stale flags + effective exclude rules
+
+Output:
+  --json                   Emit JSON to stdout (stable schema for tooling)
+
+Configuration:
+  --config <path>          Use this config file (overrides .flagshark.yml discovery)
+  --no-config              Skip .flagshark.yml discovery
+  --no-ignore-file         Skip .flagsharkignore discovery
+  --show-excluded          List excluded files in the output
+```
 
-## CLI Usage
+Example invocations:
 
 ```bash
-# Scan current directory
+# Scan current directory, default 6-month threshold
 flagshark scan
 
-# JSON output (for piping to other tools)
-flagshark scan --json
-
-# Only scan files changed since a git ref
-flagshark scan --diff HEAD~1
+# Scan only files changed since main
 flagshark scan --diff main
 
-# Custom staleness threshold (default: 6 months)
-flagshark scan --threshold 3
+# Stricter threshold + JSON for piping
+flagshark scan --threshold 3 --json | jq '.staleFlags'
 
-# Show all stale flags (default shows top 10)
-flagshark scan --verbose
+# Use a custom config file
+flagshark scan --config ./tooling/flagshark.yml
 ```
 
 ### Exit codes
@@ -63,11 +85,64 @@ flagshark scan --verbose
 |------|---------|
 | 0 | No stale flags found |
 | 1 | Stale flags detected |
-| 2 | Runtime error |
+| 2 | Runtime or configuration error |
 
-## GitHub Action
+## Configuration
+
+FlagShark is zero-config by default. When you want more control, two files compose:
+
+### `.flagsharkignore` — skip files entirely
+
+Drop a `.flagsharkignore` at your repo root. Same syntax as `.gitignore`:
+
+```gitignore
+examples/
+**/*.test.ts
+**/*_test.go
+**/test_*.py
+!examples/important-flag-test.ts   # Re-include with `!`
+```
 
-Add to your workflow:
+### `.flagshark.yml` — full config
+
+```yaml
+threshold: 6
+
+excludes:
+  paths:
+    - 'examples/**'
+  files:
+    - '**/*.test.ts'
+  presets:
+    - test-files                 # Curated bundles — see table below
+    - snapshots
+
+suppress:
+  flags:
+    - 'INTERNAL_DEBUG_*'         # Don't report these flag names
+    - 'PERMANENT_KILLSWITCH'
+
+paths:                           # Per-path threshold overrides
+  - match: 'src/critical/**'
+    threshold: 3
+  - match: 'src/experimental/**'
+    threshold: 12
+```
+
+The unconditional baseline — `node_modules`, `.git`, `dist`, `build`, `coverage`, `__pycache__`, `vendor`, `.next`, `.turbo` — is always skipped.
+
+### Built-in presets
+
+| Preset | Covers |
+|---|---|
+| `test-files` | `*.test.*`, `*.spec.*`, `*_test.go`, `test_*.py`, `*Test.java`, `*_spec.rb`, `__tests__/**`, etc. |
+| `snapshots` | `*.snap`, `__snapshots__/**` |
+| `examples` | `examples/**`, `demo/**` |
+| `stories` | `*.stories.{ts,tsx,js,jsx}` (Storybook) |
+| `fixtures` | `__fixtures__/**`, `fixtures/**` |
+| `generated` | `*.generated.{ts,js}`, `*.gen.go`, `generated/**` |
+
+## GitHub Action
 
 ```yaml
 name: FlagShark
@@ -83,95 +158,25 @@ jobs:
     steps:
       - uses: actions/checkout@v4
         with:
-          fetch-depth: 0  # Required for git blame (staleness) and changed-file scanning
+          fetch-depth: 0
       - uses: FlagShark/flagshark@v1
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 ```
 
-### Action Inputs
+See the [main repo README](https://github.com/FlagShark/flagshark) for action inputs and full docs.
 
-| Input | Default | Description |
-|-------|---------|-------------|
-| `scan` | `changed` | `changed` (PR files only) or `full` (entire repo) |
-| `threshold` | `6` | Staleness threshold in months |
-| `fail-threshold` | `0` | Health score below which the check fails (0 = never fail) |
+## Library usage
 
-### Scan Modes
+Building a tool on top of the engine? Use [`@flagshark/core`](https://www.npmjs.com/package/@flagshark/core) directly:
 
-**`scan: changed`** (default) scans only files modified in the PR. Fast, focused on what you're changing.
+```ts
+import { scanRepo } from '@flagshark/core'
 
-**`scan: full`** scans the entire repository. Shows your full flag health score and finds stale flags everywhere, not just in changed files:
-
-```yaml
-      - uses: FlagShark/flagshark@v1
-        with:
-          scan: full
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+const result = await scanRepo({ cwd: process.cwd(), threshold: 6 })
+console.log(`${result.staleFlags.length} stale of ${result.totalFlags}`)
 ```
 
-### What the Action does
-
-On every PR, FlagShark comments with a table of stale flags:
-
-> ### 🦈 FlagShark found 3 stale flags
->
-> | Flag | File | Added | Signal |
-> |------|------|-------|--------|
-> | `CHECKOUT_V2` | src/checkout.ts:47 | 14 months ago | Age > 6 months |
-> | `NEW_NAV` | src/layout.tsx:12 | 8 months ago | Single file |
->
-> **Flag Health:** 70/100
-
-It also sets a GitHub status check that can optionally block merge if health drops below a threshold.
-
-## Supported Languages
-
-FlagShark detects feature flags across 13 languages:
-
-| Language | Extensions |
-|----------|-----------|
-| TypeScript/JavaScript | .ts, .tsx, .js, .jsx, .mjs, .cjs |
-| Go | .go |
-| Python | .py |
-| Java | .java |
-| Kotlin | .kt |
-| Swift | .swift |
-| Ruby | .rb |
-| C# | .cs |
-| PHP | .php |
-| Rust | .rs |
-| C/C++ | .c, .cpp, .h, .hpp |
-| Objective-C | .m |
-
-## Supported Providers
-
-Auto-detected from imports (no configuration needed):
-
-- LaunchDarkly
-- Unleash
-- Flipt
-- Split.io
-- PostHog
-- Flagsmith
-- ConfigCat
-- Statsig
-- GrowthBook
-- DevCycle
-- Eppo
-- Optimizely
-- Custom flag implementations
-
-## How Staleness Works
-
-A flag is marked stale if **any** of these signals fires:
-
-1. **Age:** `git blame` shows the flag reference was added more than 6 months ago (configurable with `--threshold`)
-2. **Single file:** The flag name appears in only one file across the entire repo, suggesting a completed rollout
-
-FlagShark only checks files that actually import a flag SDK. A function called `isEnabled()` in a file that doesn't import LaunchDarkly/Unleash/etc. won't be flagged. This prevents false positives.
-
 ## License
 
 MIT

package/dist/cli.js

@@ -1,140 +1,13 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { readFileSync, existsSync } from "node:fs";
+import { readFileSync, existsSync, writeFileSync } from "node:fs";
 import { parse as parseYaml } from "yaml";
-import { scanRepo, FlagsharkConfigSchema } from "@flagshark/core";
-
-// src/formatter.ts
-var VERSION = "1.2.0";
-function pad(str, width) {
-  if (str.length > width) {
-    return str.slice(0, width - 1) + "\u2026";
-  }
-  return str.padEnd(width);
-}
-function buildTable(flags) {
-  const cols = {
-    flag: 16,
-    file: 22,
-    added: 13,
-    signal: 28
-  };
-  const hBorder = (left, mid, right) => `${left}${"\u2500".repeat(cols.flag + 2)}${mid}${"\u2500".repeat(cols.file + 2)}${mid}${"\u2500".repeat(cols.added + 2)}${mid}${"\u2500".repeat(cols.signal + 2)}${right}`;
-  const lines = [];
-  lines.push(hBorder("\u250C", "\u252C", "\u2510"));
-  lines.push(
-    `\u2502 ${pad("Flag", cols.flag)} \u2502 ${pad("File", cols.file)} \u2502 ${pad("Added", cols.added)} \u2502 ${pad("Signal", cols.signal)} \u2502`
-  );
-  lines.push(hBorder("\u251C", "\u253C", "\u2524"));
-  for (const sf of flags) {
-    const fileRef = `${sf.filePath}:${sf.lineNumber}`;
-    const signalText = sf.signals.map((s) => {
-      if (s.type === "age") {
-        return "Age > threshold";
-      }
-      if (s.type === "low-usage") {
-        return "Single file";
-      }
-      return s.description;
-    }).join(", ");
-    lines.push(
-      `\u2502 ${pad(sf.name, cols.flag)} \u2502 ${pad(fileRef, cols.file)} \u2502 ${pad(sf.age ?? "unknown", cols.added)} \u2502 ${pad(signalText, cols.signal)} \u2502`
-    );
-  }
-  lines.push(hBorder("\u2514", "\u2534", "\u2518"));
-  return lines.join("\n");
-}
-function formatText(result, options) {
-  const lines = [];
-  lines.push(`\u{1F988} FlagShark v${VERSION}`);
-  lines.push("");
-  const langCount = Object.keys(result.languageBreakdown).length;
-  lines.push(`Scanned ${result.filesScanned} files across ${langCount} language${langCount === 1 ? "" : "s"}`);
-  if (result.excludedCount && result.excludedCount > 0) {
-    lines.push(`(${result.excludedCount} excluded via .flagsharkignore + excludes)`);
-  }
-  if (result.totalFlags === 0) {
-    lines.push("No feature flags detected.");
-    lines.push("");
-    lines.push("Supported providers: LaunchDarkly, Unleash, Flipt, Split.io, PostHog, and more.");
-    lines.push("Run flagshark scan --help for configuration options.");
-    return lines.join("\n");
-  }
-  if (result.detectedProviders.length > 0) {
-    lines.push(`Detected providers: ${result.detectedProviders.join(", ")}`);
-  }
-  const uniqueStaleNames = new Set(result.staleFlags.map((f) => f.name));
-  const staleCount = uniqueStaleNames.size;
-  lines.push(`Found ${result.totalFlags} feature flags, ${staleCount} stale`);
-  if (staleCount > 0) {
-    lines.push("");
-    lines.push("Stale flags:");
-    const displayCount = options.verbose ? staleCount : Math.min(staleCount, options.maxDisplay);
-    const displayFlags = result.staleFlags.slice(0, displayCount);
-    lines.push(buildTable(displayFlags));
-    const remaining = staleCount - displayCount;
-    if (remaining > 0) {
-      lines.push("");
-      lines.push(`... and ${remaining} more (use --verbose to see all)`);
-    }
-  }
-  lines.push("");
-  if (staleCount === 0) {
-    lines.push(`Flag Health Score: ${result.healthScore}/100 \u2713 All flags look healthy!`);
-  } else {
-    lines.push(
-      `Flag Health Score: ${result.healthScore}/100 (${staleCount}/${result.totalFlags} flags are stale)`
-    );
-    lines.push("");
-    lines.push("Automate cleanup \u2192 https://flagshark.com");
-    lines.push("Open source CLI  \u2192 https://github.com/FlagShark/flagshark");
-  }
-  if (result.excludedPaths && result.excludedPaths.length > 0) {
-    lines.push("");
-    lines.push(`Excluded files (${result.excludedPaths.length}):`);
-    for (const p of result.excludedPaths) {
-      lines.push(`  ${p}`);
-    }
-  }
-  return lines.join("\n");
-}
-function formatJson(result) {
-  const languages = { ...result.languageBreakdown };
-  const flags = result.staleFlags.map((sf) => ({
-    name: sf.name,
-    file: sf.filePath,
-    line: sf.lineNumber,
-    language: sf.language,
-    provider: sf.provider,
-    stale: true,
-    signals: sf.signals.map((s) => ({
-      type: s.type,
-      description: s.description
-    })),
-    age: sf.age ?? null
-  }));
-  const output = {
-    version: VERSION,
-    totalFlags: result.totalFlags,
-    staleFlags: new Set(result.staleFlags.map((f) => f.name)).size,
-    healthScore: result.healthScore,
-    detectedProviders: result.detectedProviders,
-    languages,
-    flags,
-    excludedPaths: result.excludedPaths,
-    scanDuration: result.scanDuration,
-    links: {
-      dashboard: "https://flagshark.com",
-      cli: "https://github.com/FlagShark/flagshark",
-      npm: "https://www.npmjs.com/package/flagshark"
-    }
-  };
-  return JSON.stringify(output, null, 2);
+import { scanRepo, FlagsharkConfigSchema, selectFormatter } from "@flagshark/core";
+function toErrorMessage(err) {
+  return err instanceof Error ? err.message : String(err);
 }
-
-// src/cli.ts
-var VERSION2 = "1.3.0";
+var VERSION = "1.3.1";
 var HELP_TEXT = `
 flagshark scan [options]
 
@@ -151,15 +24,27 @@ Configuration:
   --no-config              Skip config file discovery
   --no-ignore-file         Skip .flagsharkignore discovery
   --show-excluded          Show excluded files in text output
+
+Output:
+  --format <fmt>           Output format: text | json | markdown | csv | sarif (default: text)
+  --output <path> | -o     Write output to this file instead of stdout
+  --json                   Shorthand for --format json (deprecated, will be removed in v2)
+
+Platform integration:
+  --no-cache             Skip platform-flag cache, force re-fetch
+  --fail-on-error        Fail on any missing-in-platform flag (default: true)
+  --no-fail-on-error     Disable fail-on-error
 `.trim();
 function parseArgs(argv) {
   const args = {
     json: false,
+    format: "text",
     diff: null,
     threshold: void 0,
     verbose: false,
     help: false,
-    version: false
+    version: false,
+    failOnError: true
   };
   let i = 2;
   while (i < argv.length) {
@@ -172,6 +57,19 @@ function parseArgs(argv) {
     switch (arg) {
       case "--json":
         args.json = true;
+        args.format = "json";
+        break;
+      case "--format": {
+        const v = argv[++i];
+        if (!["text", "json", "markdown", "csv", "sarif"].includes(v)) {
+          throw new Error(`--format must be one of text, json, markdown, csv, sarif; got '${v}'`);
+        }
+        args.format = v;
+        break;
+      }
+      case "--output":
+      case "-o":
+        args.output = argv[++i];
         break;
       case "--diff":
         i++;
@@ -201,9 +99,7 @@ function parseArgs(argv) {
       case "--engine": {
         const value = argv[++i];
         if (value !== "regex" && value !== "tree-sitter") {
-          process.stderr.write(`Error: --engine must be 'regex' or 'tree-sitter', got '${value}'
-`);
-          process.exit(2);
+          throw new Error(`--engine must be 'regex' or 'tree-sitter', got '${value}'`);
         }
         args.engine = value;
         break;
@@ -224,6 +120,15 @@ function parseArgs(argv) {
       case "--show-excluded":
         args.showExcluded = true;
         break;
+      case "--no-cache":
+        args.noCache = true;
+        break;
+      case "--no-fail-on-error":
+        args.failOnError = false;
+        break;
+      case "--fail-on-error":
+        args.failOnError = true;
+        break;
       case "scan":
         break;
       default:
@@ -245,16 +150,23 @@ function createLogger(verbose) {
     error: (...args) => console.error("[error]", ...args)
   };
 }
-async function main() {
-  const args = parseArgs(process.argv);
+async function runCli(argv, io) {
+  let args;
+  try {
+    args = parseArgs(argv);
+  } catch (err) {
+    io.stderr.write(`[error] ${toErrorMessage(err)}
+`);
+    return 2;
+  }
   if (args.version) {
-    process.stdout.write(`flagshark v${VERSION2}
+    io.stdout.write(`flagshark v${VERSION}
 `);
-    process.exit(0);
+    return 0;
   }
   if (args.help) {
-    process.stdout.write(HELP_TEXT + "\n");
-    process.exit(0);
+    io.stdout.write(HELP_TEXT + "\n");
+    return 0;
   }
   const logger = createLogger(args.verbose);
   if (args.diff) {
@@ -265,22 +177,29 @@ async function main() {
   let configOverride;
   if (args.configPath) {
     if (!existsSync(args.configPath)) {
-      process.stderr.write(`Error: config file not found: ${args.configPath}
+      io.stderr.write(`Error: config file not found: ${args.configPath}
 `);
-      process.exit(2);
+      return 2;
     }
     const raw = readFileSync(args.configPath, "utf-8");
-    const parsed = parseYaml(raw);
+    let parsed;
+    try {
+      parsed = parseYaml(raw);
+    } catch (err) {
+      io.stderr.write(`Error: invalid YAML at ${args.configPath}: ${toErrorMessage(err)}
+`);
+      return 2;
+    }
     const configResult = FlagsharkConfigSchema.safeParse(parsed);
     if (!configResult.success) {
-      process.stderr.write(`Error: invalid config at ${args.configPath}: ${configResult.error.message}
+      io.stderr.write(`Error: invalid config at ${args.configPath}: ${configResult.error.message}
 `);
-      process.exit(2);
+      return 2;
     }
     configOverride = configResult.data;
   }
   const result = await scanRepo({
-    cwd: process.cwd(),
+    cwd: io.cwd,
     threshold: args.threshold,
     diff: args.diff ?? void 0,
     engine: args.engine,
@@ -288,6 +207,7 @@ async function main() {
     noConfig: args.noConfig,
     noIgnoreFile: args.noIgnoreFile,
     collectExcludedPaths: args.showExcluded,
+    noCache: args.noCache,
     logger
   });
   if (args.verbose && result.effectiveExcludes) {
@@ -299,20 +219,36 @@ async function main() {
       ...r.ignoreFile.map((p) => `.flagsharkignore: ${p}`)
     ];
     if (allRules.length > 0) {
-      process.stderr.write("Effective excludes:\n");
-      for (const rule of allRules) process.stderr.write(`  ${rule}
+      io.stderr.write("Effective excludes:\n");
+      for (const rule of allRules) io.stderr.write(`  ${rule}
 `);
     }
   }
-  const output = args.json ? formatJson(result) + "\n" : formatText(result, { json: false, verbose: args.verbose, maxDisplay: 10 }) + "\n";
-  const exitCode = result.staleFlags.length > 0 ? 1 : 0;
-  if (process.stdout.write(output)) {
-    process.exit(exitCode);
-  } else {
-    process.stdout.once("drain", () => process.exit(exitCode));
+  const formatter = selectFormatter(args.format);
+  const output = formatter(result, {
+    version: VERSION,
+    scanMode: args.diff ? "changed" : "full",
+    verbose: args.verbose
+  });
+  const hasErrorSignals = result.staleFlags.some(
+    (f) => f.signals.some((s) => s.severity === "error")
+  );
+  const exitCode = args.failOnError && hasErrorSignals ? 1 : result.staleFlags.length > 0 ? 1 : 0;
+  if (args.output) {
+    writeFileSync(args.output, output);
+    return exitCode;
   }
+  const finalOutput = output.endsWith("\n") ? output : output + "\n";
+  io.stdout.write(finalOutput);
+  return exitCode;
 }
-main().catch((err) => {
+
+// src/main.ts
+runCli(process.argv, {
+  stdout: process.stdout,
+  stderr: process.stderr,
+  cwd: process.cwd()
+}).then((code) => process.exit(code)).catch((err) => {
   console.error(`[error] ${err instanceof Error ? err.message : String(err)}`);
   process.exit(2);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flagshark",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "type": "module",
   "description": "Find stale feature flags in your codebase",
   "license": "MIT",
@@ -17,17 +17,19 @@
 "main": "./dist/cli.js",
 "files": ["dist/", "bin/"],
 "scripts": {
-  "build": "esbuild src/cli.ts --bundle --platform=node --target=node18 --format=esm --outfile=dist/cli.js --external:zod --external:@flagshark/core --external:yaml",
-  "test": "vitest run",
+  "build": "esbuild src/main.ts --bundle --platform=node --target=node18 --format=esm --outfile=dist/cli.js --external:zod --external:@flagshark/core --external:yaml",
+  "test": "bun run build && vitest run",
+  "test:coverage": "bun run build && vitest run --coverage",
   "typecheck": "tsc --noEmit"
 },
 "dependencies": {
-  "@flagshark/core": "1.2.0",
+  "@flagshark/core": "1.4.0",
   "yaml": "^2.4.0",
   "zod": "^3.23.0"
 },
 "devDependencies": {
   "@types/node": "^22.0.0",
+  "@vitest/coverage-v8": "^3.0.0",
   "esbuild": "^0.24.0",
   "typescript": "^5.7.0",
   "vitest": "^3.0.0"