@monoes/monograph 1.1.0 → 1.2.1

package/src/analysis/fallow-suppression.ts

@@ -0,0 +1,98 @@
+export type FallowIssueKind =
+  | 'unused-file'
+  | 'unused-export'
+  | 'unused-type'
+  | 'private-type-leak'
+  | 'unused-dependency'
+  | 'unused-dev-dependency'
+  | 'unused-enum-member'
+  | 'unused-class-member'
+  | 'unresolved-import'
+  | 'unlisted-dependency'
+  | 'duplicate-export'
+  | 'code-duplication'
+  | 'circular-dependency'
+  | 'type-only-dependency'
+  | 'test-only-dependency'
+  | 'boundary-violation'
+  | 'coverage-gaps'
+  | 'feature-flag'
+  | 'complexity'
+  | 'stale-suppression';
+
+export interface FallowSuppression {
+  line: number;
+  commentLine: number;
+  kind: FallowIssueKind | null;
+}
+
+const DISCRIMINANT_MAP: Record<FallowIssueKind, number> = {
+  'unused-file': 1,
+  'unused-export': 2,
+  'unused-type': 3,
+  'private-type-leak': 4,
+  'unused-dependency': 5,
+  'unused-dev-dependency': 6,
+  'unused-enum-member': 7,
+  'unused-class-member': 8,
+  'unresolved-import': 9,
+  'unlisted-dependency': 10,
+  'duplicate-export': 11,
+  'code-duplication': 12,
+  'circular-dependency': 13,
+  'type-only-dependency': 14,
+  'test-only-dependency': 15,
+  'boundary-violation': 16,
+  'coverage-gaps': 17,
+  'feature-flag': 18,
+  'complexity': 19,
+  'stale-suppression': 20,
+};
+
+const DISCRIMINANT_REVERSE: FallowIssueKind[] = [
+  'unused-file',
+  'unused-export',
+  'unused-type',
+  'private-type-leak',
+  'unused-dependency',
+  'unused-dev-dependency',
+  'unused-enum-member',
+  'unused-class-member',
+  'unresolved-import',
+  'unlisted-dependency',
+  'duplicate-export',
+  'code-duplication',
+  'circular-dependency',
+  'type-only-dependency',
+  'test-only-dependency',
+  'boundary-violation',
+  'coverage-gaps',
+  'feature-flag',
+  'complexity',
+  'stale-suppression',
+];
+
+const VALID_KINDS = new Set<string>(Object.keys(DISCRIMINANT_MAP));
+
+export function parseFallowIssueKind(s: string): FallowIssueKind | undefined {
+  if (s === 'circular-dependencies') return 'circular-dependency';
+  if (VALID_KINDS.has(s)) return s as FallowIssueKind;
+  return undefined;
+}
+
+export function issueKindToDiscriminant(kind: FallowIssueKind): number {
+  return DISCRIMINANT_MAP[kind];
+}
+
+export function issueKindFromDiscriminant(d: number): FallowIssueKind | undefined {
+  if (d <= 0 || d > 20) return undefined;
+  return DISCRIMINANT_REVERSE[d - 1];
+}
+
+export function isFallowSuppression(line: number): boolean {
+  return line === 0 || line > 0;
+}
+
+export function isFileWideSuppression(suppression: FallowSuppression): boolean {
+  return suppression.line === 0;
+}

package/src/analysis/feature-flags-config.ts

@@ -0,0 +1,47 @@
+export interface SdkPattern {
+  packageName: string;
+  displayName: string;
+  callPatterns: RegExp[];
+}
+
+export const KNOWN_SDK_PATTERNS: SdkPattern[] = [
+  {
+    packageName: 'launchdarkly-js-client-sdk',
+    displayName: 'LaunchDarkly',
+    callPatterns: [/ldClient\.variation\s*\(/, /\.variation\s*\(/],
+  },
+  {
+    packageName: '@statsig/js-client',
+    displayName: 'Statsig',
+    callPatterns: [/\.checkGate\s*\(/, /\.getExperiment\s*\(/, /Statsig\.checkGate/],
+  },
+  {
+    packageName: 'unleash-client',
+    displayName: 'Unleash',
+    callPatterns: [/\.isEnabled\s*\(/, /unleash\.isEnabled/],
+  },
+  {
+    packageName: '@growthbook/growthbook',
+    displayName: 'GrowthBook',
+    callPatterns: [/\.isOn\s*\(/, /\.evalFeature\s*\(/, /growthbook\.isOn/],
+  },
+  {
+    packageName: 'configcat-js',
+    displayName: 'ConfigCat',
+    callPatterns: [/\.getValueAsync\s*\(/, /configcat\.getValue/],
+  },
+  {
+    packageName: 'flagsmith',
+    displayName: 'Flagsmith',
+    callPatterns: [/flagsmith\.hasFeature\s*\(/, /flagsmith\.getValue\s*\(/],
+  },
+  {
+    packageName: '@splitsoftware/splitio',
+    displayName: 'Split',
+    callPatterns: [/\.getTreatment\s*\(/, /splitClient\.getTreatment/],
+  },
+];
+
+export function detectSdkFromPackageJson(deps: Record<string, string>): SdkPattern[] {
+  return KNOWN_SDK_PATTERNS.filter(sdk => deps[sdk.packageName] !== undefined);
+}

package/src/analysis/feature-flags.ts

@@ -0,0 +1,218 @@
+import { readFileSync, readdirSync, statSync } from 'fs';
+import { join, extname } from 'path';
+
+export type FlagKind = 'EnvironmentVariable' | 'SdkCall' | 'ConfigObject';
+export type FlagConfidence = 'High' | 'Medium' | 'Low';
+
+export interface FeatureFlag {
+  filePath: string;
+  flagName: string;
+  kind: FlagKind;
+  confidence: FlagConfidence;
+  line: number;
+  col: number;
+  sdkName?: string;
+  guardLineStart?: number;
+  guardLineEnd?: number;
+  guardedDeadExports?: string[];
+}
+
+export interface FlagsConfig {
+  sdkPatterns: string[];
+  envPrefixes: string[];
+}
+
+export const DEFAULT_FLAGS_CONFIG: FlagsConfig = {
+  envPrefixes: ['FEATURE_', 'FF_', 'FLAG_', 'ENABLE_', 'DISABLE_', 'AB_', 'EXP_', 'EXPERIMENT_'],
+  sdkPatterns: [
+    'launchdarkly', 'ld-client', '@launchdarkly',
+    'statsig', '@statsig',
+    'unleash', 'unleash-client',
+    'growthbook', '@growthbook',
+    'configcat', 'config-cat',
+    'flagsmith',
+    'split-io', '@splitsoftware',
+  ],
+};
+
+// SDK method patterns that signal flag evaluation
+const SDK_CALL_PATTERNS = [
+  /\.variation\s*\(/,
+  /\.isEnabled\s*\(/,
+  /\.checkGate\s*\(/,
+  /\.getExperiment\s*\(/,
+  /\.isOn\s*\(/,
+  /\.getFeature\s*\(/,
+  /\.getTreatment\s*\(/,
+  /\.evaluate\s*\(/,
+  /featureIsEnabled\s*\(/,
+  /getFlag\s*\(/,
+  /flagEnabled\s*\(/,
+];
+
+const ENV_VAR_RE = /process\.env\.([A-Z][A-Z0-9_]+)/g;
+const CONFIG_OBJECT_RE = /(?:featureFlags?|flags?|features?)\s*[\[.]\s*['"]([A-Za-z][A-Za-z0-9_-]*)['"]|(?:isEnabled|isActive|isOn)\s*\(\s*['"]([A-Za-z][A-Za-z0-9_-]*)['"]/g;
+
+function isSourceFile(filePath: string): boolean {
+  const ext = extname(filePath).toLowerCase();
+  return ['.ts', '.tsx', '.js', '.jsx', '.mts', '.mjs', '.cts', '.cjs'].includes(ext);
+}
+
+function detectFlagsInLine(
+  line: string,
+  lineNum: number,
+  filePath: string,
+  config: FlagsConfig,
+): FeatureFlag[] {
+  const found: FeatureFlag[] = [];
+
+  // Environment variable flags
+  let m: RegExpExecArray | null;
+  const envRe = new RegExp(ENV_VAR_RE.source, 'g');
+  while ((m = envRe.exec(line)) !== null) {
+    const varName = m[1]!;
+    const isFlag = config.envPrefixes.some(p => varName.startsWith(p));
+    if (isFlag) {
+      found.push({
+        filePath, flagName: varName, kind: 'EnvironmentVariable',
+        confidence: 'High', line: lineNum, col: m.index + 1,
+      });
+    }
+  }
+
+  // SDK call patterns
+  for (const pattern of SDK_CALL_PATTERNS) {
+    const sdkMatch = pattern.exec(line);
+    if (sdkMatch) {
+      // Try to extract the flag name from the first string argument
+      const argMatch = line.slice(sdkMatch.index).match(/\(\s*['"]([^'"]+)['"]/);
+      if (argMatch) {
+        found.push({
+          filePath, flagName: argMatch[1]!, kind: 'SdkCall',
+          confidence: 'High', line: lineNum, col: sdkMatch.index + 1,
+          sdkName: detectSdkName(line),
+        });
+      }
+    }
+  }
+
+  // Config object heuristics
+  const configRe = new RegExp(CONFIG_OBJECT_RE.source, 'g');
+  while ((m = configRe.exec(line)) !== null) {
+    const flagName = m[1] ?? m[2];
+    if (flagName) {
+      found.push({
+        filePath, flagName, kind: 'ConfigObject',
+        confidence: 'Medium', line: lineNum, col: m.index + 1,
+      });
+    }
+  }
+
+  return found;
+}
+
+function detectSdkName(line: string): string {
+  const lower = line.toLowerCase();
+  if (lower.includes('launchdarkly') || lower.includes('ldclient')) return 'LaunchDarkly';
+  if (lower.includes('statsig')) return 'Statsig';
+  if (lower.includes('unleash')) return 'Unleash';
+  if (lower.includes('growthbook')) return 'GrowthBook';
+  if (lower.includes('configcat')) return 'ConfigCat';
+  if (lower.includes('flagsmith')) return 'Flagsmith';
+  if (lower.includes('split')) return 'Split';
+  return 'unknown';
+}
+
+export function analyzeFeatureFlags(
+  rootDir: string,
+  config: FlagsConfig = DEFAULT_FLAGS_CONFIG,
+): FeatureFlag[] {
+  const flags: FeatureFlag[] = [];
+  walkDir(rootDir, filePath => {
+    if (!isSourceFile(filePath)) return;
+    let content: string;
+    try { content = readFileSync(filePath, 'utf8'); } catch { return; }
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      const detected = detectFlagsInLine(lines[i]!, i + 1, filePath, config);
+      flags.push(...detected);
+    }
+  });
+  return flags;
+}
+
+export function crossReferenceWithDeadCode(
+  flags: FeatureFlag[],
+  deadExports: Array<{ filePath: string; name: string; line: number }>,
+): FeatureFlag[] {
+  // Pregroup dead exports by filePath to avoid O(F*D) nested scan
+  const deadByFile = new Map<string, Array<{ name: string; line: number }>>();
+  for (const e of deadExports) {
+    let arr = deadByFile.get(e.filePath);
+    if (!arr) {
+      arr = [];
+      deadByFile.set(e.filePath, arr);
+    }
+    arr.push({ name: e.name, line: e.line });
+  }
+
+  return flags.map(flag => {
+    if (flag.guardLineStart == null || flag.guardLineEnd == null) return flag;
+    const fileDeads = deadByFile.get(flag.filePath);
+    if (!fileDeads) return flag;
+    const start = flag.guardLineStart ?? 0;
+    const end = flag.guardLineEnd ?? Infinity;
+    const guarded = fileDeads
+      .filter(e => e.line >= start && e.line <= end)
+      .map(e => e.name);
+    return guarded.length > 0 ? { ...flag, guardedDeadExports: guarded } : flag;
+  });
+}
+
+function walkDir(dir: string, fn: (filePath: string) => void): void {
+  let entries: string[];
+  try { entries = readdirSync(dir); } catch { return; }
+  for (const entry of entries) {
+    if (entry === 'node_modules' || entry === '.git' || entry === 'dist' || entry === 'build') continue;
+    const full = join(dir, entry);
+    let st;
+    try { st = statSync(full); } catch { continue; }
+    if (st.isDirectory()) walkDir(full, fn);
+    else if (st.isFile()) fn(full);
+  }
+}
+
+export interface FlagsSummary {
+  totalFlags: number;
+  byKind: Record<FlagKind, number>;
+  byConfidence: Record<FlagConfidence, number>;
+  uniqueFlagNames: number;
+  filesWithFlags: number;
+  deadCodeOverlaps: number;
+}
+
+export function summarizeFlags(flags: FeatureFlag[]): FlagsSummary {
+  // Single pass over flags instead of 7 separate filter/map passes
+  const byKind: Record<FlagKind, number> = { EnvironmentVariable: 0, SdkCall: 0, ConfigObject: 0 };
+  const byConfidence: Record<FlagConfidence, number> = { High: 0, Medium: 0, Low: 0 };
+  const flagNames = new Set<string>();
+  const filePaths = new Set<string>();
+  let deadCodeOverlaps = 0;
+
+  for (const f of flags) {
+    byKind[f.kind]++;
+    byConfidence[f.confidence]++;
+    flagNames.add(f.flagName);
+    filePaths.add(f.filePath);
+    if ((f.guardedDeadExports?.length ?? 0) > 0) deadCodeOverlaps++;
+  }
+
+  return {
+    totalFlags: flags.length,
+    byKind,
+    byConfidence,
+    uniqueFlagNames: flagNames.size,
+    filesWithFlags: filePaths.size,
+    deadCodeOverlaps,
+  };
+}

package/src/analysis/file-classifier.ts

@@ -0,0 +1,84 @@
+import { extname } from 'path';
+
+export type FileType = 'CODE' | 'DOCUMENT' | 'PAPER' | 'IMAGE' | 'VIDEO';
+
+const CODE_EXTENSIONS = new Set([
+  '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs',
+  '.py', '.pyw', '.java', '.kt', '.kts', '.go',
+  '.rs', '.rb', '.php', '.swift', '.cs', '.cpp',
+  '.c', '.h', '.hpp', '.cc', '.m', '.r', '.scala',
+  '.lua', '.sh', '.bash', '.zsh', '.ps1', '.psm1',
+  '.sql', '.graphql', '.gql', '.proto', '.yaml', '.yml',
+  '.toml', '.json', '.xml', '.html', '.css', '.scss',
+  '.sass', '.less', '.vue', '.svelte', '.astro',
+]);
+
+const DOCUMENT_EXTENSIONS = new Set([
+  '.md', '.mdx', '.rst', '.txt', '.pdf', '.docx',
+  '.doc', '.odt', '.rtf', '.tex', '.adoc',
+]);
+
+const IMAGE_EXTENSIONS = new Set([
+  '.png', '.jpg', '.jpeg', '.gif', '.svg', '.webp',
+  '.ico', '.bmp', '.tiff', '.tif',
+]);
+
+const VIDEO_EXTENSIONS = new Set([
+  '.mp4', '.mkv', '.avi', '.mov', '.webm', '.flv',
+  '.wmv', '.m4v',
+]);
+
+const PAPER_URL_PATTERNS = [
+  /arxiv\.org/,
+  /semanticscholar\.org/,
+  /openreview\.net/,
+  /dl\.acm\.org/,
+  /ieeexplore\.ieee\.org/,
+  /springer\.com\/article/,
+];
+
+const PAPER_FILENAME_SIGNALS = [
+  /(^|[^a-zA-Z])(attention|transformer|neural|deep.?learn|bert|gpt|llm|arxiv)([^a-zA-Z]|$)/i,
+  /\d{4}\.\d{4,5}/,
+];
+
+export function classifyFile(pathOrUrl: string): FileType {
+  if (PAPER_URL_PATTERNS.some(p => p.test(pathOrUrl))) return 'PAPER';
+
+  const ext = extname(pathOrUrl).toLowerCase();
+
+  if (IMAGE_EXTENSIONS.has(ext)) return 'IMAGE';
+  if (VIDEO_EXTENSIONS.has(ext)) return 'VIDEO';
+
+  if (DOCUMENT_EXTENSIONS.has(ext)) {
+    if (ext === '.pdf' && PAPER_FILENAME_SIGNALS.some(p => p.test(pathOrUrl))) return 'PAPER';
+    return 'DOCUMENT';
+  }
+
+  if (CODE_EXTENSIONS.has(ext)) return 'CODE';
+
+  return 'CODE';
+}
+
+const PAPER_CONTENT_SIGNALS: RegExp[] = [
+  /\\cite\{/,
+  /\[\d{1,3}\](?:\[\d{1,3}\])+/,
+  /\bEq(?:uation|n)?\.\s*\d+/i,
+  /\bdoi:\s*10\.\d{4,}/i,
+  /^Abstract\b/im,
+  /\bWe propose\b/i,
+  /\bProceedings\s+of\b/i,
+  /\b(Journal|Preprint|arXiv)\b/i,
+  /\d{4}\.\d{4,5}/,
+  /\b\d+\(\d+\):\d+-\d+\b/,
+  /\\bibliography\{/,
+  /\bTable of Contents\b.*\n.*\bIntroduction\b/is,
+];
+
+const PAPER_CONTENT_THRESHOLD = 1;
+
+export function classifyContent(text: string): FileType {
+  const matches = PAPER_CONTENT_SIGNALS.filter(p => p.test(text)).length;
+  if (matches >= PAPER_CONTENT_THRESHOLD) return 'PAPER';
+  return 'DOCUMENT';
+}

package/src/analysis/git-changed-files.ts

@@ -0,0 +1,62 @@
+import { execSync } from 'node:child_process';
+import * as path from 'node:path';
+
+const GIT_REF_ALLOWLIST = /^[a-zA-Z0-9._/~^@{}[\]:-]+$/;
+const DANGEROUS_PATTERNS = /\.\.|`|\$\(|;|&&|\|\|/;
+
+export function validateGitRef(ref: string): void {
+  if (!GIT_REF_ALLOWLIST.test(ref) || DANGEROUS_PATTERNS.test(ref)) {
+    throw new Error(`Invalid git ref: ${JSON.stringify(ref)} — only alphanumeric, dots, slashes, hyphens, and common git ref characters are allowed`);
+  }
+}
+
+export function resolveGitToplevel(cwd: string): string {
+  try {
+    return execSync('git rev-parse --show-toplevel', { cwd, encoding: 'utf8' }).trim();
+  } catch {
+    return cwd;
+  }
+}
+
+export function collectGitPaths(root: string, since?: string): string[] {
+  try {
+    let cmd: string;
+    if (since) {
+      validateGitRef(since);
+      cmd = `git diff --name-only --diff-filter=ACM ${since}`;
+    } else {
+      cmd = 'git ls-files';
+    }
+    const output = execSync(cmd, { cwd: root, encoding: 'utf8' });
+    return output
+      .split('\n')
+      .map(l => l.trim())
+      .filter(l => l.length > 0)
+      .map(l => path.resolve(root, l));
+  } catch {
+    return [];
+  }
+}
+
+export function tryGetChangedFiles(root: string, since?: string): string[] | null {
+  if (!since) return null;
+  try {
+    validateGitRef(since);
+    return collectGitPaths(root, since);
+  } catch {
+    return null;
+  }
+}
+
+export function filterResultsByChangedFiles<T extends { filePath: string }>(
+  results: T[],
+  changedFiles: string[],
+): T[] {
+  const changedSet = new Set(changedFiles.map(f => path.normalize(f)));
+  return results.filter(r => changedSet.has(path.normalize(r.filePath)));
+}
+
+export function getChangedFilesSince(root: string, since: string): string[] {
+  validateGitRef(since);
+  return collectGitPaths(root, since);
+}

package/src/analysis/health-baseline.ts

@@ -0,0 +1,80 @@
+export interface HealthFileCounts {
+  complexityModerate: number;
+  complexityHigh: number;
+  complexityCritical: number;
+  crapModerate: number;
+  crapHigh: number;
+  crapCritical: number;
+}
+
+export interface HealthBaselineData {
+  counts: Map<string, HealthFileCounts>;
+}
+
+export interface HealthFinding {
+  filePath: string;
+  kind: 'complexity_moderate' | 'complexity_high' | 'complexity_critical' | 'crap_moderate' | 'crap_high' | 'crap_critical';
+  functionName?: string;
+  line?: number;
+}
+
+function toRelativePath(filePath: string, root: string): string {
+  const normalized = filePath.replace(/\\/g, '/');
+  const rootNorm = root.replace(/\\/g, '/').replace(/\/$/, '') + '/';
+  return normalized.startsWith(rootNorm) ? normalized.slice(rootNorm.length) : normalized;
+}
+
+function buildCountsFromFindings(findings: HealthFinding[], root: string): Map<string, HealthFileCounts> {
+  const map = new Map<string, HealthFileCounts>();
+  const zero = (): HealthFileCounts => ({
+    complexityModerate: 0, complexityHigh: 0, complexityCritical: 0,
+    crapModerate: 0, crapHigh: 0, crapCritical: 0,
+  });
+  for (const f of findings) {
+    const key = toRelativePath(f.filePath, root);
+    const counts = map.get(key) ?? zero();
+    const fieldMap: Record<string, keyof HealthFileCounts> = {
+      'complexity_moderate': 'complexityModerate',
+      'complexity_high': 'complexityHigh',
+      'complexity_critical': 'complexityCritical',
+      'crap_moderate': 'crapModerate',
+      'crap_high': 'crapHigh',
+      'crap_critical': 'crapCritical',
+    };
+    const field = fieldMap[f.kind];
+    if (field) counts[field]++;
+    map.set(key, counts);
+  }
+  return map;
+}
+
+export function buildHealthBaseline(findings: HealthFinding[], root: string): HealthBaselineData {
+  return { counts: buildCountsFromFindings(findings, root) };
+}
+
+export function filterNewHealthFindings(
+  current: HealthFinding[],
+  baseline: HealthBaselineData,
+  root: string,
+): HealthFinding[] {
+  // Build counts from CURRENT findings (not the baseline) to compare per-kind per-file
+  const currentCounts = buildCountsFromFindings(current, root);
+  return current.filter(f => {
+    const key = toRelativePath(f.filePath, root);
+    const saved = baseline.counts.get(key);
+    if (!saved) return true;
+    const fieldMap: Record<string, keyof HealthFileCounts> = {
+      'complexity_moderate': 'complexityModerate',
+      'complexity_high': 'complexityHigh',
+      'complexity_critical': 'complexityCritical',
+      'crap_moderate': 'crapModerate',
+      'crap_high': 'crapHigh',
+      'crap_critical': 'crapCritical',
+    };
+    const field = fieldMap[f.kind];
+    if (!field) return true;
+    const currentCount = currentCounts.get(key)?.[field] ?? 0;
+    const savedCount = saved[field];
+    return currentCount > savedCount;
+  });
+}

package/src/analysis/issue-filters.ts

@@ -0,0 +1,86 @@
+// Selective issue filters — zero out AnalysisResults fields so callers can
+// run any subset of checks in one pass without rerunning the pipeline.
+
+export type IssueFilterKey =
+  | 'unusedFiles' | 'unusedExports' | 'unusedDeps' | 'unusedTypes'
+  | 'privateTypeLeaks' | 'unusedEnumMembers' | 'unusedClassMembers'
+  | 'unresolvedImports' | 'unlistedDeps' | 'duplicateExports'
+  | 'circularDeps' | 'boundaryViolations' | 'staleSuppressions';
+
+export interface IssueFilters {
+  unusedFiles: boolean;
+  unusedExports: boolean;
+  unusedDeps: boolean;
+  unusedTypes: boolean;
+  privateTypeLeaks: boolean;
+  unusedEnumMembers: boolean;
+  unusedClassMembers: boolean;
+  unresolvedImports: boolean;
+  unlistedDeps: boolean;
+  duplicateExports: boolean;
+  circularDeps: boolean;
+  boundaryViolations: boolean;
+  staleSuppressions: boolean;
+}
+
+export const ALL_FILTERS_OFF: IssueFilters = {
+  unusedFiles: false, unusedExports: false, unusedDeps: false, unusedTypes: false,
+  privateTypeLeaks: false, unusedEnumMembers: false, unusedClassMembers: false,
+  unresolvedImports: false, unlistedDeps: false, duplicateExports: false,
+  circularDeps: false, boundaryViolations: false, staleSuppressions: false,
+};
+
+export const ALL_FILTERS_ON: IssueFilters = {
+  unusedFiles: true, unusedExports: true, unusedDeps: true, unusedTypes: true,
+  privateTypeLeaks: true, unusedEnumMembers: true, unusedClassMembers: true,
+  unresolvedImports: true, unlistedDeps: true, duplicateExports: true,
+  circularDeps: true, boundaryViolations: true, staleSuppressions: true,
+};
+
+/** Returns true if at least one filter is active. */
+export function anyFiltersActive(filters: IssueFilters): boolean {
+  return Object.values(filters).some(Boolean);
+}
+
+/** When a caller passes an explicit list of check names, turn those on and all others off. */
+export function activateExplicitOptIns(checks: IssueFilterKey[]): IssueFilters {
+  const result = { ...ALL_FILTERS_OFF };
+  for (const key of checks) result[key] = true;
+  return result;
+}
+
+/** Zero out result fields that are disabled in the filters.
+ *  Works with any object whose keys overlap IssueFilterKey names. */
+export function applyIssueFilters<T extends Record<string, unknown>>(
+  results: T,
+  filters: IssueFilters,
+): T {
+  const out = { ...results };
+  const keyMap: Partial<Record<IssueFilterKey, string>> = {
+    unusedFiles: 'deadFiles',
+    unusedExports: 'unusedExports',
+    unusedDeps: 'unusedDependencies',
+    unusedTypes: 'unusedTypes',
+    privateTypeLeaks: 'privateTypeLeaks',
+    unusedEnumMembers: 'unusedEnumMembers',
+    unusedClassMembers: 'unusedClassMembers',
+    unresolvedImports: 'unresolvedImports',
+    unlistedDeps: 'unlistedDependencies',
+    duplicateExports: 'duplicateExports',
+    circularDeps: 'circularDependencies',
+    boundaryViolations: 'boundaryViolations',
+    staleSuppressions: 'staleSuppressions',
+  };
+  for (const [filterKey, resultKey] of Object.entries(keyMap) as [IssueFilterKey, string][]) {
+    if (!filters[filterKey] && resultKey in out) {
+      (out as Record<string, unknown>)[resultKey] = Array.isArray(out[resultKey]) ? [] : undefined;
+    }
+  }
+  return out;
+}
+
+/** Parse a comma-separated string of filter keys into an IssueFilters object. */
+export function parseIssueFilters(csv: string): IssueFilters {
+  const keys = csv.split(',').map(s => s.trim()).filter(Boolean) as IssueFilterKey[];
+  return activateExplicitOptIns(keys);
+}