flagshark 1.2.0 → 1.3.1

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,7 +1,9 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { scanRepo } from "@flagshark/core";
+import { readFileSync, existsSync } from "node:fs";
+import { parse as parseYaml } from "yaml";
+import { scanRepo, FlagsharkConfigSchema } from "@flagshark/core";
 
 // src/formatter.ts
 var VERSION = "1.2.0";
@@ -49,6 +51,9 @@ function formatText(result, options) {
   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("");
@@ -85,6 +90,13 @@ function formatText(result, options) {
     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) {
@@ -110,6 +122,7 @@ function formatJson(result) {
     detectedProviders: result.detectedProviders,
     languages,
     flags,
+    excludedPaths: result.excludedPaths,
     scanDuration: result.scanDuration,
     links: {
       dashboard: "https://flagshark.com",
@@ -121,7 +134,7 @@ function formatJson(result) {
 }
 
 // src/cli.ts
-var VERSION2 = "1.2.0";
+var VERSION2 = "1.3.1";
 var HELP_TEXT = `
 flagshark scan [options]
 
@@ -132,19 +145,30 @@ Options:
   --verbose         Show all stale flags (not just top 10)
   --help            Show help
   --version         Show version
+
+Configuration:
+  --config <path>          Use this config file (overrides .flagshark.yml discovery)
+  --no-config              Skip config file discovery
+  --no-ignore-file         Skip .flagsharkignore discovery
+  --show-excluded          Show excluded files in text output
 `.trim();
 function parseArgs(argv) {
   const args = {
     json: false,
     diff: null,
-    threshold: 6,
+    threshold: void 0,
     verbose: false,
     help: false,
     version: false
   };
   let i = 2;
   while (i < argv.length) {
-    const arg = argv[i];
+    let arg = argv[i];
+    if (arg.startsWith("--") && arg.includes("=")) {
+      const eqIdx = arg.indexOf("=");
+      argv.splice(i, 1, arg.slice(0, eqIdx), arg.slice(eqIdx + 1));
+      arg = argv[i];
+    }
     switch (arg) {
       case "--json":
         args.json = true;
@@ -174,6 +198,32 @@ function parseArgs(argv) {
       case "-v":
         args.version = true;
         break;
+      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);
+        }
+        args.engine = value;
+        break;
+      }
+      case "--config":
+        i++;
+        args.configPath = argv[i];
+        if (!args.configPath) {
+          throw new Error("--config requires a file path argument");
+        }
+        break;
+      case "--no-config":
+        args.noConfig = true;
+        break;
+      case "--no-ignore-file":
+        args.noIgnoreFile = true;
+        break;
+      case "--show-excluded":
+        args.showExcluded = true;
+        break;
       case "scan":
         break;
       default:
@@ -212,12 +262,48 @@ async function main() {
   } else {
     logger.info("Scanning current directory...");
   }
+  let configOverride;
+  if (args.configPath) {
+    if (!existsSync(args.configPath)) {
+      process.stderr.write(`Error: config file not found: ${args.configPath}
+`);
+      process.exit(2);
+    }
+    const raw = readFileSync(args.configPath, "utf-8");
+    const parsed = parseYaml(raw);
+    const configResult = FlagsharkConfigSchema.safeParse(parsed);
+    if (!configResult.success) {
+      process.stderr.write(`Error: invalid config at ${args.configPath}: ${configResult.error.message}
+`);
+      process.exit(2);
+    }
+    configOverride = configResult.data;
+  }
   const result = await scanRepo({
     cwd: process.cwd(),
     threshold: args.threshold,
     diff: args.diff ?? void 0,
+    engine: args.engine,
+    config: configOverride,
+    noConfig: args.noConfig,
+    noIgnoreFile: args.noIgnoreFile,
+    collectExcludedPaths: args.showExcluded,
     logger
   });
+  if (args.verbose && result.effectiveExcludes) {
+    const r = result.effectiveExcludes;
+    const allRules = [
+      ...r.paths.map((p) => `excludes.paths: ${p}`),
+      ...r.files.map((p) => `excludes.files: ${p}`),
+      ...r.presets.flatMap((name, i) => [`excludes.presets[${i}]: ${name}`]),
+      ...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}
+`);
+    }
+  }
   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)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flagshark",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "type": "module",
   "description": "Find stale feature flags in your codebase",
   "license": "MIT",
@@ -17,12 +17,13 @@
 "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",
+  "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",
   "typecheck": "tsc --noEmit"
 },
 "dependencies": {
-  "@flagshark/core": "1.0.0",
+  "@flagshark/core": "1.3.1",
+  "yaml": "^2.4.0",
   "zod": "^3.23.0"
 },
 "devDependencies": {