Getting Started
Library (@flagshark/core)
The detection engine behind FlagShark, as a library — build your own tooling on top of scanRepo().
2 min readLast updated: May 22, 2026
@flagshark/core is the detection engine that powers the flagshark CLI, the GitHub Action, and the FlagShark dashboard. The CLI and Action are the consumer products; @flagshark/core is the library underneath them — use it to build your own tooling in any JS/TS project. ESM-only, Node ≥18, MIT licensed.
Install
npm install @flagshark/coreQuickstart
import { scanRepo } from '@flagshark/core'
const result = await scanRepo({ cwd: process.cwd(), threshold: 30 })
console.log(`${result.totalFlags} flags, ${result.staleFlags.length} stale`)
console.log(`Health score: ${result.healthScore}/100`) // 0–100, higher is better
console.log(`Languages: ${Object.keys(result.languageBreakdown).join(', ')}`)scanRepo() performs a full scan of the repo at cwd: it collects files, runs the tree-sitter–based detection engine across all supported languages and providers, attributes each flag reference via git blame, and returns a ScanRepoResult — the same result object the CLI formats and prints.
Key exports
| Export | Description |
|---|---|
scanRepo(options: ScanRepoOptions) | Primary entry point. Runs a full scan and returns a ScanRepoResult. |
ScanRepoOptions, ScanRepoResult, ScanLogger | Types for the scanRepo API. |
analyzeStaleness(options: StalenessOptions) | Lower-level staleness analysis. Accepts a Map<string, FeatureFlag[]> (flag name → occurrences) and returns StaleFlag[] with StalenessSignal annotations. |
StaleFlag, StalenessOptions, StalenessSignal | Types for the staleness analysis API. |
collectFiles(options: ScanOptions) | Low-level file collection — returns the files to scan (as a path→content map) plus exclusion counts (CollectFilesResult). |
ScanOptions | Options type for collectFiles. |
FlagsharkConfigSchema, expandPresets, PRESETS, config types | Config module — parse, validate, and expand .flagshark.yml configuration, including provider preset expansion. |
Output formatters (output module) | Format a ScanRepoResult as text, json, markdown, csv, or sarif. |
Platform integration utilities (providers module) | Registry, cross-reference, and caching utilities for connecting live platform flag state to scan results. |
Bundling and WASM
@flagshark/core uses tree-sitter via WebAssembly for tier-1 language detection. The tree-sitter grammar .wasm files (~2.5 MB total) are external runtime assets — they must be resolvable at the path Node expects at runtime and are not inlined into the JS bundle. The .scm query files are inlined and require nothing extra.