@flagshark/core 1.0.0

package/dist/scan-repo.js

@@ -0,0 +1,55 @@
+/**
+ * Top-level orchestrator: walk the repo, detect flags, analyse staleness,
+ * return a single result object that consumers can render however they like.
+ */
+import { collectFiles } from './scanner.js';
+import { createDefaultRegistry } from './detection/index.js';
+import { PolyglotAnalyzer } from './detection/polyglot-analyzer.js';
+import { analyzeStaleness } from './staleness.js';
+const NOOP_LOGGER = {
+    debug: () => { },
+    info: () => { },
+    warn: () => { },
+    error: () => { },
+};
+export async function scanRepo(opts) {
+    const start = performance.now();
+    const logger = opts.logger ?? NOOP_LOGGER;
+    const threshold = opts.threshold ?? 6;
+    const registry = createDefaultRegistry();
+    const supportedExtensions = new Set(registry.getSupportedExtensions());
+    const analyzer = new PolyglotAnalyzer(registry, logger);
+    logger.debug('Collecting files...');
+    const files = collectFiles({
+        root: opts.cwd,
+        supportedExtensions,
+        diffRef: opts.diff,
+    });
+    logger.debug(`Detected ${files.size} candidate files`);
+    const filesScanned = files.size;
+    const analysisResult = await analyzer.analyzeFiles(files, opts.signal);
+    const staleFlags = await analyzeStaleness(analysisResult.totalFlags, { thresholdMonths: threshold, repoRoot: opts.cwd });
+    const totalFlags = analysisResult.totalFlags.size;
+    const uniqueStaleNames = new Set(staleFlags.map((f) => f.name)).size;
+    const healthScore = totalFlags === 0 ? 100 : Math.round(((totalFlags - uniqueStaleNames) / totalFlags) * 100);
+    const allFlags = [];
+    for (const flags of analysisResult.totalFlags.values()) {
+        allFlags.push(...flags);
+    }
+    const detectedProviders = [
+        ...new Set(allFlags
+            .map((f) => f.provider)
+            .filter((p) => p != null && p !== '')),
+    ];
+    return {
+        totalFlags,
+        filesScanned,
+        staleFlags,
+        detectedProviders,
+        // analysisResult.languages is Map<Language, number> — convert to plain object
+        languageBreakdown: Object.fromEntries(analysisResult.languages),
+        healthScore,
+        scanDuration: Math.round(performance.now() - start),
+    };
+}
+//# sourceMappingURL=scan-repo.js.map

package/dist/scan-repo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan-repo.js","sourceRoot":"","sources":["../src/scan-repo.ts"],"names":[],"mappings":"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"}

package/dist/scanner.d.ts

@@ -0,0 +1,18 @@
+/**
+ * File system scanner that wraps PolyglotAnalyzer.
+ *
+ * Reads files from disk, filters by supported extensions,
+ * and feeds them to the detection engine.
+ *
+ *   walkDir() → filterFiles() → readFiles() → PolyglotAnalyzer.analyzeFiles()
+ */
+export interface ScanOptions {
+    root: string;
+    supportedExtensions: Set<string>;
+    diffRef?: string;
+}
+/**
+ * Collects files to scan, reads their contents, and returns a Map<filePath, content>.
+ */
+export declare function collectFiles(options: ScanOptions): Map<string, string>;
+//# sourceMappingURL=scanner.d.ts.map

package/dist/scanner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scanner.d.ts","sourceRoot":"","sources":["../src/scanner.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAwBH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,mBAAmB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IAChC,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,WAAW,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CA4BtE"}

package/dist/scanner.js

@@ -0,0 +1,108 @@
+/**
+ * File system scanner that wraps PolyglotAnalyzer.
+ *
+ * Reads files from disk, filters by supported extensions,
+ * and feeds them to the detection engine.
+ *
+ *   walkDir() → filterFiles() → readFiles() → PolyglotAnalyzer.analyzeFiles()
+ */
+import { execFileSync } from 'node:child_process';
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, extname } from 'node:path';
+const SKIP_DIRS = new Set([
+    'node_modules',
+    'vendor',
+    '.git',
+    'dist',
+    'build',
+    'coverage',
+    '__pycache__',
+    '.next',
+    '.turbo',
+    '.cache',
+    '.venv',
+    'venv',
+    'env',
+]);
+const MAX_FILE_SIZE = 5 * 1024 * 1024; // 5MB
+/**
+ * Collects files to scan, reads their contents, and returns a Map<filePath, content>.
+ */
+export function collectFiles(options) {
+    const { root, supportedExtensions, diffRef } = options;
+    const files = new Map();
+    let filePaths;
+    if (diffRef) {
+        filePaths = getDiffFiles(diffRef, supportedExtensions);
+    }
+    else {
+        filePaths = walkDir(root, supportedExtensions);
+    }
+    for (const fp of filePaths) {
+        try {
+            const stat = statSync(fp);
+            if (stat.size > MAX_FILE_SIZE) {
+                continue;
+            }
+            if (stat.size === 0) {
+                continue;
+            }
+            files.set(fp, readFileSync(fp, 'utf-8'));
+        }
+        catch {
+            // Skip unreadable files
+        }
+    }
+    return files;
+}
+/**
+ * Get files changed since a git ref.
+ */
+function getDiffFiles(ref, supportedExtensions) {
+    try {
+        const output = execFileSync('git', ['diff', ref, '--name-only', '--diff-filter=ACMR'], {
+            encoding: 'utf-8',
+            timeout: 30000,
+        });
+        return output
+            .split('\n')
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0)
+            .filter((line) => supportedExtensions.has(extname(line)));
+    }
+    catch {
+        throw new Error(`Failed to get diff from ref "${ref}". Is this a git repository?`);
+    }
+}
+/**
+ * Recursively walk a directory, returning paths to supported source files.
+ */
+function walkDir(dir, supportedExtensions) {
+    const results = [];
+    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, supportedExtensions));
+            }
+            else if (entry.isFile()) {
+                const ext = extname(entry.name);
+                if (supportedExtensions.has(ext)) {
+                    results.push(fullPath);
+                }
+            }
+        }
+    }
+    catch {
+        // Skip unreadable directories
+    }
+    return results;
+}
+//# sourceMappingURL=scanner.js.map

package/dist/scanner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scanner.js","sourceRoot":"","sources":["../src/scanner.ts"],"names":[],"mappings":"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"}

package/dist/staleness.d.ts

@@ -0,0 +1,30 @@
+import { type FeatureFlag } from './detection/feature-flag.js';
+export interface StalenessSignal {
+    type: 'age' | 'hardcoded' | 'low-usage';
+    description: string;
+}
+export interface StaleFlag {
+    name: string;
+    filePath: string;
+    lineNumber: number;
+    language: string;
+    provider: string;
+    signals: StalenessSignal[];
+    /** Human-readable age, e.g. "14 months ago" */
+    age?: string;
+}
+export interface StalenessOptions {
+    /** Flag lines older than this are considered stale. Default: 6. */
+    thresholdMonths: number;
+    /** Absolute path to the git repository root. */
+    repoRoot: string;
+}
+/**
+ * Analyze a set of detected feature flags for staleness signals.
+ *
+ * @param flags  Map of flag name → all occurrences across the codebase.
+ * @param options  Staleness configuration (threshold, repo root).
+ * @returns Array of flags that have at least one staleness signal.
+ */
+export declare function analyzeStaleness(flags: Map<string, FeatureFlag[]>, options: StalenessOptions): Promise<StaleFlag[]>;
+//# sourceMappingURL=staleness.d.ts.map

package/dist/staleness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"staleness.d.ts","sourceRoot":"","sources":["../src/staleness.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,6BAA6B,CAAA;AAI9D,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,KAAK,GAAG,WAAW,GAAG,WAAW,CAAA;IACvC,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,eAAe,EAAE,CAAA;IAC1B,+CAA+C;IAC/C,GAAG,CAAC,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,gBAAgB;IAC/B,mEAAmE;IACnE,eAAe,EAAE,MAAM,CAAA;IACvB,gDAAgD;IAChD,QAAQ,EAAE,MAAM,CAAA;CACjB;AAyKD;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE,CAAC,EACjC,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,SAAS,EAAE,CAAC,CAyEtB"}

package/dist/staleness.js

@@ -0,0 +1,217 @@
+import { execFileSync, execSync } from 'child_process';
+// ── Helpers ────────────────────────────────────────────────────────
+/**
+ * Returns true when the repository is a shallow clone (git blame timestamps
+ * would all point to the checkout commit and be meaningless).
+ */
+function isShallowRepo(repoRoot) {
+    try {
+        const out = execSync('git rev-parse --is-shallow-repository', {
+            cwd: repoRoot,
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+        return out === 'true';
+    }
+    catch {
+        // Not a git repo at all – caller will handle.
+        return false;
+    }
+}
+/**
+ * Parse `git blame --porcelain` output and return a map of
+ * 1-based line number → author-time (unix seconds).
+ *
+ * Porcelain format per-line group:
+ *   <sha> <orig-line> <final-line> [<group-size>]
+ *   author ...
+ *   author-mail ...
+ *   author-time <unix-ts>
+ *   ...
+ *   \t<content line>
+ */
+function parseBlamePortcelain(output) {
+    const lineAges = new Map();
+    const lines = output.split('\n');
+    let currentLine = 0;
+    let currentAuthorTime = 0;
+    for (const line of lines) {
+        // Group header: <40-char sha> <orig> <final> [count]
+        const headerMatch = line.match(/^[0-9a-f]{40}\s+\d+\s+(\d+)(?:\s+\d+)?$/);
+        if (headerMatch) {
+            currentLine = parseInt(headerMatch[1], 10);
+            continue;
+        }
+        // author-time line
+        if (line.startsWith('author-time ')) {
+            currentAuthorTime = parseInt(line.slice('author-time '.length), 10);
+            continue;
+        }
+        // Content line (starts with tab) – marks end of this group's metadata.
+        if (line.startsWith('\t')) {
+            if (currentLine > 0 && currentAuthorTime > 0) {
+                lineAges.set(currentLine, currentAuthorTime);
+            }
+        }
+    }
+    return lineAges;
+}
+/**
+ * Run `git blame --porcelain` for a single file and return line → unix-ts map.
+ * Returns null on any failure (untracked file, binary, non-git dir, etc.).
+ */
+function blameFile(filePath, repoRoot) {
+    try {
+        const out = execFileSync('git', ['blame', '--porcelain', '--', filePath], {
+            cwd: repoRoot,
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+            maxBuffer: 10 * 1024 * 1024, // 10 MB – large files
+        });
+        return parseBlamePortcelain(out);
+    }
+    catch {
+        // Untracked, binary, or other git error – skip gracefully.
+        return null;
+    }
+}
+/**
+ * Convert a unix timestamp to a human-readable relative age string,
+ * e.g. "14 months ago", "3 years ago", "29 days ago".
+ */
+function formatAge(unixSeconds) {
+    const nowMs = Date.now();
+    const thenMs = unixSeconds * 1000;
+    const diffMs = nowMs - thenMs;
+    const seconds = Math.floor(diffMs / 1000);
+    const minutes = Math.floor(seconds / 60);
+    const hours = Math.floor(minutes / 60);
+    const days = Math.floor(hours / 24);
+    const months = Math.floor(days / 30.44); // average days/month
+    const years = Math.floor(days / 365.25);
+    if (years >= 1) {
+        return `${years} year${years === 1 ? '' : 's'} ago`;
+    }
+    if (months >= 1) {
+        return `${months} month${months === 1 ? '' : 's'} ago`;
+    }
+    if (days >= 1) {
+        return `${days} day${days === 1 ? '' : 's'} ago`;
+    }
+    return 'less than a day ago';
+}
+// ── Signal detectors ───────────────────────────────────────────────
+/**
+ * Check whether a flag's line is older than the threshold.
+ * Returns the signal + age string, or null if the signal doesn't fire.
+ */
+function checkAgeSignal(authorTime, thresholdMonths) {
+    if (authorTime === undefined) {
+        return null;
+    }
+    const thresholdMs = thresholdMonths * 30.44 * 24 * 60 * 60 * 1000;
+    const ageMs = Date.now() - authorTime * 1000;
+    if (ageMs < thresholdMs) {
+        return null;
+    }
+    const age = formatAge(authorTime);
+    return {
+        signal: {
+            type: 'age',
+            description: `Flag reference last modified ${age} (threshold: ${thresholdMonths} months)`,
+        },
+        age,
+    };
+}
+/**
+ * Check whether a flag appears in only one file.
+ */
+function checkLowUsageSignal(flagName, occurrences) {
+    const uniqueFiles = new Set(occurrences.map((o) => o.filePath));
+    if (uniqueFiles.size > 1) {
+        return null;
+    }
+    return {
+        type: 'low-usage',
+        description: `Flag "${flagName}" only appears in 1 file — may have been fully rolled out`,
+    };
+}
+/**
+ * Hardcoded signal — placeholder for tree-sitter v2.
+ * Always returns null (no signal) for the regex v1 implementation.
+ */
+function checkHardcodedSignal(_flag) {
+    return null;
+}
+// ── Main entry point ───────────────────────────────────────────────
+/**
+ * Analyze a set of detected feature flags for staleness signals.
+ *
+ * @param flags  Map of flag name → all occurrences across the codebase.
+ * @param options  Staleness configuration (threshold, repo root).
+ * @returns Array of flags that have at least one staleness signal.
+ */
+export async function analyzeStaleness(flags, options) {
+    const { thresholdMonths = 6, repoRoot } = options;
+    // ── 1. Determine whether we can use git blame at all ──
+    const shallow = isShallowRepo(repoRoot);
+    // ── 2. Collect unique files that need blaming ──
+    const fileBlames = new Map();
+    if (!shallow) {
+        const filesToBlame = new Set();
+        for (const occurrences of flags.values()) {
+            for (const flag of occurrences) {
+                filesToBlame.add(flag.filePath);
+            }
+        }
+        for (const file of filesToBlame) {
+            fileBlames.set(file, blameFile(file, repoRoot));
+        }
+    }
+    // ── 3. Evaluate signals for every flag occurrence ──
+    const staleFlags = [];
+    for (const [flagName, occurrences] of flags) {
+        // Low-usage is per-flag-name (not per-occurrence).
+        const lowUsageSignal = checkLowUsageSignal(flagName, occurrences);
+        for (const flag of occurrences) {
+            const signals = [];
+            let age;
+            // Age signal (git blame)
+            if (!shallow) {
+                const blame = fileBlames.get(flag.filePath);
+                const authorTime = blame?.get(flag.lineNumber);
+                const ageResult = checkAgeSignal(authorTime, thresholdMonths);
+                if (ageResult) {
+                    signals.push(ageResult.signal);
+                    age = ageResult.age;
+                }
+                else if (authorTime !== undefined) {
+                    age = formatAge(authorTime);
+                }
+            }
+            // Low-usage signal
+            if (lowUsageSignal) {
+                signals.push(lowUsageSignal);
+            }
+            // Hardcoded signal (v2 placeholder)
+            const hardcoded = checkHardcodedSignal(flag);
+            if (hardcoded) {
+                signals.push(hardcoded);
+            }
+            // Only include flags that have at least one signal.
+            if (signals.length > 0) {
+                staleFlags.push({
+                    name: flag.name,
+                    filePath: flag.filePath,
+                    lineNumber: flag.lineNumber,
+                    language: flag.language,
+                    provider: flag.provider ?? 'unknown',
+                    signals,
+                    age,
+                });
+            }
+        }
+    }
+    return staleFlags;
+}
+//# sourceMappingURL=staleness.js.map

package/dist/staleness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"staleness.js","sourceRoot":"","sources":["../src/staleness.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@flagshark/core",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Detection engine for FlagShark — finds feature flag references across 13 languages.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/FlagShark/flagshark.git",
+    "directory": "packages/core"
+  },
+  "keywords": ["feature-flags", "polyglot-analysis", "static-analysis"],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist/"],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "p-limit": "^6.0.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "engines": { "node": ">=18.0.0" }
+}