flagshark 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FlagShark
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,175 @@
+# FlagShark
+
+Find stale feature flags in your codebase. CLI tool + GitHub Action.
+
+```bash
+npx flagshark scan
+```
+
+```
+🦈 FlagShark v1.0.0
+
+Scanned 156 files across 4 languages
+Detected providers: LaunchDarkly (JS SDK), Unleash (Go SDK)
+Found 23 feature flags, 7 stale
+
+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        │
+└──────────────────┴────────────────────────┴───────────────┴──────────────────────────────┘
+
+Flag Health Score: 70/100 (7/23 flags are stale)
+```
+
+## Install
+
+```bash
+# Run without installing
+npx flagshark scan
+
+# Or install globally
+npm install -g flagshark
+```
+
+## CLI Usage
+
+```bash
+# Scan current directory
+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
+flagshark scan --diff main
+
+# Custom staleness threshold (default: 6 months)
+flagshark scan --threshold 3
+
+# Show all stale flags (default shows top 10)
+flagshark scan --verbose
+```
+
+### Exit codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | No stale flags found |
+| 1 | Stale flags detected |
+| 2 | Runtime error |
+
+## GitHub Action
+
+Add to your workflow:
+
+```yaml
+name: FlagShark
+on: [pull_request]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  flagshark:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Required for git blame age detection
+      - uses: FlagShark/flagshark@v1
+```
+
+### Action Inputs
+
+| 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) |
+
+### What the Action does
+
+On every PR, FlagShark comments with a table of stale flags found in the changed files:
+
+> ### 🦈 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.
+
+## Configuration
+
+### `.flagsharkignore`
+
+Exclude files or specific flags:
+
+```
+# Glob patterns for files
+test/**
+fixtures/**
+
+# Specific flag names (prefix with flag:)
+flag:PERMANENT_ADMIN_OVERRIDE
+flag:MAINTENANCE_MODE
+```
+
+## License
+
+MIT

package/action/index.ts

@@ -0,0 +1,243 @@
+/**
+ * GitHub Action entry point for FlagShark.
+ *
+ * This is a thin wrapper around the same detection engine used by the CLI.
+ * It runs the scan, posts a PR comment with results, and sets a status check.
+ *
+ * Architecture:
+ *   action/index.ts (this file)
+ *       │
+ *       ├─ Runs the same scanner + staleness logic as the CLI
+ *       ├─ Posts a PR comment with markdown table
+ *       └─ Sets a GitHub check status (pass/fail)
+ */
+
+import { readFileSync, readdirSync, statSync } from 'node:fs'
+import { join, extname } from 'node:path'
+
+import * as core from '@actions/core'
+import * as github from '@actions/github'
+
+import { createDefaultRegistry } from '../src/detection/index.js'
+import { PolyglotAnalyzer } from '../src/detection/polyglot-analyzer.js'
+import { analyzeStaleness } from '../src/staleness.js'
+
+import type { FeatureFlag } from '../src/detection/feature-flag.js'
+import type { StaleFlag } from '../src/staleness.js'
+
+const COMMENT_MARKER = '<!-- flagshark-action -->'
+const SKIP_DIRS = new Set([
+  'node_modules',
+  'vendor',
+  '.git',
+  'dist',
+  'build',
+  'coverage',
+  '__pycache__',
+  '.next',
+  '.turbo',
+])
+
+const logger = {
+  debug: (...args: unknown[]) => core.debug(args.map(String).join(' ')),
+  info: (...args: unknown[]) => core.info(args.map(String).join(' ')),
+  warn: (...args: unknown[]) => core.warning(args.map(String).join(' ')),
+  error: (...args: unknown[]) => core.error(args.map(String).join(' ')),
+}
+
+async function run(): Promise<void> {
+  const startTime = Date.now()
+
+  try {
+    const scanMode = core.getInput('scan') || 'changed'
+    const threshold = parseInt(core.getInput('threshold') || '6', 10)
+    const failThreshold = parseInt(core.getInput('fail-threshold') || '0', 10)
+
+    const registry = createDefaultRegistry()
+    const supportedExts = new Set(registry.getSupportedExtensions())
+    const analyzer = new PolyglotAnalyzer(registry, logger)
+
+    // Determine files to scan
+    let filePaths: string[]
+
+    if (scanMode === 'changed' && github.context.payload.pull_request) {
+      const token = process.env.GITHUB_TOKEN || core.getInput('token')
+      if (!token) {
+        core.setFailed('GITHUB_TOKEN is required for changed-file scanning')
+        return
+      }
+      const octokit = github.getOctokit(token)
+      const { data: prFiles } = await octokit.rest.pulls.listFiles({
+        ...github.context.repo,
+        pull_number: github.context.payload.pull_request.number,
+        per_page: 100,
+      })
+      filePaths = prFiles
+        .filter((f) => f.status !== 'removed')
+        .map((f) => f.filename)
+        .filter((f) => supportedExts.has(extname(f)))
+    } else {
+      filePaths = walkDir('.', supportedExts)
+    }
+
+    // Read file contents
+    const files = new Map<string, string>()
+    for (const fp of filePaths) {
+      try {
+        const stat = statSync(fp)
+        if (stat.size > 5 * 1024 * 1024) {
+          continue
+        }
+        files.set(fp, readFileSync(fp, 'utf-8'))
+      } catch {
+        // Skip unreadable files
+      }
+    }
+
+    core.info(`Scanning ${files.size} files...`)
+
+    // Run detection
+    const result = await analyzer.analyzeFiles(files)
+    const totalFlags = result.totalFlags.size
+
+    // Run staleness analysis
+    const staleFlags = await analyzeStaleness(result.totalFlags as Map<string, FeatureFlag[]>, {
+      thresholdMonths: threshold,
+      repoRoot: process.cwd(),
+    })
+
+    // Use unique stale flag names (not occurrences) for health score — matches CLI formula
+    const uniqueStaleNames = new Set(staleFlags.map((f) => f.name)).size
+    const healthScore =
+      totalFlags > 0 ? Math.round(((totalFlags - uniqueStaleNames) / totalFlags) * 100) : 100
+
+    const scanDuration = Date.now() - startTime
+
+    // Set outputs
+    core.setOutput('health-score', healthScore.toString())
+    core.setOutput('stale-count', staleFlags.length.toString())
+    core.setOutput('total-count', totalFlags.toString())
+
+    // Post PR comment (only on PRs)
+    if (github.context.payload.pull_request && staleFlags.length > 0) {
+      const token = process.env.GITHUB_TOKEN || core.getInput('token')
+      if (token) {
+        await postComment(token, staleFlags, totalFlags, healthScore)
+      }
+    }
+
+    // Set status check
+    if (failThreshold > 0 && healthScore < failThreshold) {
+      core.setFailed(
+        `Flag health score ${healthScore}/100 is below threshold ${failThreshold}/100. ` +
+          `${staleFlags.length} stale flags found.`,
+      )
+    } else {
+      core.info(`Flag Health Score: ${healthScore}/100 (${staleFlags.length}/${totalFlags} stale)`)
+    }
+
+    // Summary
+    core.summary
+      .addHeading('FlagShark Results', 2)
+      .addRaw(`**Health Score:** ${healthScore}/100\n\n`)
+      .addRaw(`**Flags:** ${totalFlags} total, ${staleFlags.length} stale\n\n`)
+      .addRaw(`**Scan time:** ${scanDuration}ms\n`)
+    await core.summary.write()
+  } catch (error) {
+    if (error instanceof Error) {
+      core.setFailed(error.message)
+    } else {
+      core.setFailed('An unexpected error occurred')
+    }
+  }
+}
+
+async function postComment(
+  token: string,
+  staleFlags: StaleFlag[],
+  totalFlags: number,
+  healthScore: number,
+): Promise<void> {
+  const octokit = github.getOctokit(token)
+  const { owner, repo } = github.context.repo
+  const prNumber = github.context.payload.pull_request!.number
+
+  const displayFlags = staleFlags.slice(0, 10)
+  const remaining = staleFlags.length - displayFlags.length
+
+  let body = `${COMMENT_MARKER}\n`
+  body += `### 🦈 FlagShark found ${staleFlags.length} stale flag${staleFlags.length !== 1 ? 's' : ''}\n\n`
+  body += '| Flag | File | Added | Signal |\n'
+  body += '|------|------|-------|--------|\n'
+
+  for (const flag of displayFlags) {
+    const signals = flag.signals.map((s) => s.description).join(', ')
+    body += `| \`${flag.name}\` | ${flag.filePath}:${flag.lineNumber} | ${flag.age || 'unknown'} | ${signals} |\n`
+  }
+
+  if (remaining > 0) {
+    body += `\n... and ${remaining} more stale flags.\n`
+  }
+
+  body += `\n**Flag Health:** ${healthScore}/100 (${totalFlags} total, ${staleFlags.length} stale)\n`
+  body +=
+    '\nFull analysis → [FlagShark](https://github.com/FlagShark/flagshark)\n'
+
+  // Find existing comment to update
+  const { data: comments } = await octokit.rest.issues.listComments({
+    owner,
+    repo,
+    issue_number: prNumber,
+    per_page: 100,
+  })
+
+  const existing = comments.find((c) => c.body?.includes(COMMENT_MARKER))
+
+  if (existing) {
+    await octokit.rest.issues.updateComment({
+      owner,
+      repo,
+      comment_id: existing.id,
+      body,
+    })
+    core.info('Updated existing FlagShark comment')
+  } else {
+    await octokit.rest.issues.createComment({
+      owner,
+      repo,
+      issue_number: prNumber,
+      body,
+    })
+    core.info('Posted new FlagShark comment')
+  }
+}
+
+function walkDir(dir: string, supportedExts: Set<string>): string[] {
+  const results: string[] = []
+
+  try {
+    const entries = readdirSync(dir, { withFileTypes: true })
+    for (const entry of entries) {
+      if (SKIP_DIRS.has(entry.name)) {
+        continue
+      }
+      if (entry.name.startsWith('.')) {
+        continue
+      }
+
+      const fullPath = join(dir, entry.name)
+
+      if (entry.isDirectory()) {
+        results.push(...walkDir(fullPath, supportedExts))
+      } else if (entry.isFile() && supportedExts.has(extname(entry.name))) {
+        results.push(fullPath)
+      }
+    }
+  } catch {
+    // Skip unreadable directories
+  }
+
+  return results
+}
+
+run()

package/bin/flagshark.mjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../dist/cli.js'