@foxlight/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,669 @@
+/** Unique identifier for a component within a project. */
+type ComponentId = string;
+/** The front-end framework a component belongs to. */
+type Framework = 'react' | 'vue' | 'svelte' | 'angular' | 'web-component' | 'unknown';
+/** How a component is exported from its module. */
+type ExportKind = 'named' | 'default' | 're-export';
+/**
+ * Core representation of a UI component discovered in the codebase.
+ * This is the central entity that all Foxlight tools operate on.
+ */
+interface ComponentInfo {
+    /** Stable identifier (typically: filePath#componentName) */
+    id: ComponentId;
+    /** Human-readable component name (e.g. "DataTable") */
+    name: string;
+    /** Absolute file path where the component is defined */
+    filePath: string;
+    /** Line number where the component definition starts */
+    line: number;
+    /** Detected framework */
+    framework: Framework;
+    /** How the component is exported */
+    exportKind: ExportKind;
+    /** Props / inputs the component accepts */
+    props: PropInfo[];
+    /** Components this component renders (children in the tree) */
+    children: ComponentId[];
+    /** Components that render this component (parents in the tree) */
+    usedBy: ComponentId[];
+    /** npm packages this component directly imports */
+    dependencies: string[];
+    /** Custom metadata that plugins can attach */
+    metadata: Record<string, unknown>;
+}
+/**
+ * A single prop / input on a component.
+ */
+interface PropInfo {
+    /** Prop name */
+    name: string;
+    /** TypeScript type as a string (e.g. "string", "() => void") */
+    type: string;
+    /** Whether the prop is required */
+    required: boolean;
+    /** Default value expression, if any */
+    defaultValue?: string;
+    /** JSDoc / comment description */
+    description?: string;
+}
+/** An edge in the import graph between two modules. */
+interface ImportEdge {
+    /** Absolute path of the importing module */
+    source: string;
+    /** Absolute path or package name of the imported module */
+    target: string;
+    /** The specific symbols imported */
+    specifiers: ImportSpecifier[];
+    /** Whether this is a type-only import */
+    typeOnly: boolean;
+}
+interface ImportSpecifier {
+    /** Imported name (or "default" / "*") */
+    imported: string;
+    /** Local alias, if renamed */
+    local: string;
+}
+/** Size information for a single module or component. */
+interface SizeInfo {
+    /** Raw (uncompressed) size in bytes */
+    raw: number;
+    /** Gzipped size in bytes */
+    gzip: number;
+    /** Brotli-compressed size in bytes */
+    brotli?: number;
+}
+/** Bundle contribution for a single component. */
+interface ComponentBundleInfo {
+    componentId: ComponentId;
+    /** Size of the component's own code */
+    selfSize: SizeInfo;
+    /** Size including all unique dependencies (not shared with other components) */
+    exclusiveSize: SizeInfo;
+    /** Total size including all dependencies (including shared) */
+    totalSize: SizeInfo;
+    /** The chunk(s) this component ends up in */
+    chunks: string[];
+}
+/** Aggregated health score for a component. */
+interface ComponentHealth {
+    componentId: ComponentId;
+    /** Overall health score 0-100 */
+    score: number;
+    /** Individual metric scores */
+    metrics: HealthMetrics;
+    /** When these metrics were last computed */
+    computedAt: string;
+}
+interface HealthMetrics {
+    /** Bundle size score (smaller = better) */
+    bundleSize: MetricScore;
+    /** Test coverage score */
+    testCoverage: MetricScore;
+    /** Accessibility score (from axe-core scans) */
+    accessibility: MetricScore;
+    /** Code staleness (recently modified = better) */
+    freshness: MetricScore;
+    /** Runtime performance (render time) */
+    performance: MetricScore;
+    /** Error rate in production */
+    reliability: MetricScore;
+}
+interface MetricScore {
+    /** Score 0-100 */
+    score: number;
+    /** Raw value (e.g. "45KB", "87%", "120ms") */
+    value: string;
+    /** Human-readable label */
+    label: string;
+    /** Severity level */
+    level: 'good' | 'warning' | 'critical';
+}
+/** Cost model for a hosting provider. */
+interface CostModel {
+    provider: 'vercel' | 'netlify' | 'aws' | 'cloudflare' | 'custom';
+    /** Cost per 1M function invocations (USD) */
+    invocationCostPer1M: number;
+    /** Cost per GB bandwidth (USD) */
+    bandwidthCostPerGB: number;
+    /** Cost per GB storage (USD/month) */
+    storageCostPerGB: number;
+    /** Cost per 1M edge function invocations */
+    edgeCostPer1M?: number;
+    /** Base monthly cost (USD) */
+    baseCost: number;
+}
+/** Cost impact estimate for a code change. */
+interface CostImpact {
+    /** Estimated monthly cost delta (USD) */
+    monthlyDelta: number;
+    /** Breakdown by cost category */
+    breakdown: CostBreakdownItem[];
+    /** Current estimated monthly cost */
+    currentMonthlyCost: number;
+    /** Projected monthly cost after change */
+    projectedMonthlyCost: number;
+}
+interface CostBreakdownItem {
+    category: 'invocations' | 'bandwidth' | 'storage' | 'edge' | 'base';
+    description: string;
+    currentCost: number;
+    projectedCost: number;
+    delta: number;
+}
+/** Result of analyzing a dependency upgrade. */
+interface UpgradePreview {
+    /** Package being upgraded */
+    packageName: string;
+    /** Current version */
+    fromVersion: string;
+    /** Target version */
+    toVersion: string;
+    /** Risk assessment */
+    risk: 'low' | 'medium' | 'high';
+    /** Individual checks that were run */
+    checks: UpgradeCheck[];
+}
+interface UpgradeCheck {
+    name: string;
+    status: 'pass' | 'warn' | 'fail';
+    summary: string;
+    details?: string;
+}
+/** User-facing configuration (foxlight.config.ts). */
+interface FoxlightConfig {
+    /** Root directory of the project */
+    rootDir: string;
+    /** Glob patterns for source files to analyze */
+    include: string[];
+    /** Glob patterns to exclude */
+    exclude: string[];
+    /** Framework hint (auto-detected if omitted) */
+    framework?: Framework;
+    /** Storybook config path, if applicable */
+    storybook?: string;
+    /** Cost model configuration */
+    costModel?: CostModel;
+    /** Baseline storage config for visual regression */
+    baselines?: BaselineConfig;
+    /** Plugin configurations */
+    plugins?: PluginConfig[];
+}
+interface BaselineConfig {
+    /** Storage provider */
+    provider: 's3' | 'gcs' | 'r2' | 'local' | 'git-lfs';
+    /** Bucket or directory name */
+    bucket: string;
+    /** Optional prefix / path within the bucket */
+    prefix?: string;
+    /** Region (for cloud storage) */
+    region?: string;
+}
+interface PluginConfig {
+    name: string;
+    options?: Record<string, unknown>;
+}
+/** A point-in-time snapshot of the entire project analysis. */
+interface ProjectSnapshot {
+    /** Unique snapshot ID */
+    id: string;
+    /** Git commit SHA */
+    commitSha: string;
+    /** Git branch */
+    branch: string;
+    /** When the snapshot was created */
+    createdAt: string;
+    /** All discovered components */
+    components: ComponentInfo[];
+    /** Import graph edges */
+    imports: ImportEdge[];
+    /** Bundle info per component */
+    bundleInfo: ComponentBundleInfo[];
+    /** Health scores */
+    health: ComponentHealth[];
+}
+/** Diff between two snapshots. */
+interface SnapshotDiff {
+    base: {
+        id: string;
+        commitSha: string;
+    };
+    head: {
+        id: string;
+        commitSha: string;
+    };
+    components: {
+        added: ComponentInfo[];
+        removed: ComponentInfo[];
+        modified: ComponentModification[];
+    };
+    bundleDiff: BundleDiffEntry[];
+    healthDiff: HealthDiffEntry[];
+}
+interface ComponentModification {
+    componentId: ComponentId;
+    changes: string[];
+    propsAdded: string[];
+    propsRemoved: string[];
+    propsModified: string[];
+}
+interface BundleDiffEntry {
+    componentId: ComponentId;
+    before: SizeInfo;
+    after: SizeInfo;
+    delta: SizeInfo;
+}
+interface HealthDiffEntry {
+    componentId: ComponentId;
+    beforeScore: number;
+    afterScore: number;
+    delta: number;
+}
+
+/**
+ * The ComponentRegistry is the shared data layer for Foxlight.
+ * It holds all discovered components, their relationships,
+ * bundle data, and health scores.
+ */
+declare class ComponentRegistry {
+    private components;
+    private imports;
+    private bundleInfo;
+    private health;
+    /** Register a discovered component. */
+    addComponent(component: ComponentInfo): void;
+    /** Register multiple components at once. */
+    addComponents(components: ComponentInfo[]): void;
+    /** Get a component by ID. */
+    getComponent(id: ComponentId): ComponentInfo | undefined;
+    /** Get all registered components. */
+    getAllComponents(): ComponentInfo[];
+    /** Check if a component exists in the registry. */
+    hasComponent(id: ComponentId): boolean;
+    /** Remove a component from the registry. */
+    removeComponent(id: ComponentId): boolean;
+    /** Total number of registered components. */
+    get size(): number;
+    /** Add an import edge to the graph. */
+    addImport(edge: ImportEdge): void;
+    /** Add multiple import edges. */
+    addImports(edges: ImportEdge[]): void;
+    /** Get all imports originating from a file. */
+    getImportsFrom(filePath: string): ImportEdge[];
+    /** Get all imports targeting a file or package. */
+    getImportsTo(target: string): ImportEdge[];
+    /** Get the full import graph. */
+    getAllImports(): ImportEdge[];
+    /** Set bundle size info for a component. */
+    setBundleInfo(info: ComponentBundleInfo): void;
+    /** Get bundle info for a component. */
+    getBundleInfo(id: ComponentId): ComponentBundleInfo | undefined;
+    /** Get all bundle info entries. */
+    getAllBundleInfo(): ComponentBundleInfo[];
+    /** Set health score for a component. */
+    setHealth(h: ComponentHealth): void;
+    /** Get health score for a component. */
+    getHealth(id: ComponentId): ComponentHealth | undefined;
+    /** Get all health scores. */
+    getAllHealth(): ComponentHealth[];
+    /** Find components that use the given component (parents). */
+    getConsumers(id: ComponentId): ComponentInfo[];
+    /** Find components that the given component renders (children). */
+    getDependents(id: ComponentId): ComponentInfo[];
+    /** Get components that have no parents (top-level / page components). */
+    getRootComponents(): ComponentInfo[];
+    /** Get components that have no children (leaf / primitive components). */
+    getLeafComponents(): ComponentInfo[];
+    /**
+     * Find all components reachable from the given component (full subtree).
+     * Uses BFS to avoid stack overflow on deep trees.
+     */
+    getSubtree(id: ComponentId): ComponentInfo[];
+    /** Create a point-in-time snapshot of the registry. */
+    createSnapshot(commitSha: string, branch: string): ProjectSnapshot;
+    /** Load a snapshot into the registry, replacing current state. */
+    loadSnapshot(snapshot: ProjectSnapshot): void;
+    /** Compute the diff between two snapshots. */
+    static diff(base: ProjectSnapshot, head: ProjectSnapshot): SnapshotDiff;
+    /** Clear all data from the registry. */
+    clear(): void;
+}
+
+/**
+ * A directed graph built from import relationships.
+ * Supports cycle detection, topological sorting, and
+ * impact analysis (what's affected if a module changes).
+ */
+declare class DependencyGraph {
+    private nodes;
+    /** Build the graph from a list of import edges. */
+    static fromImports(edges: ImportEdge[]): DependencyGraph;
+    /** Add a directed edge from source to target. */
+    addEdge(source: string, target: string): void;
+    /** Get all direct dependencies of a module. */
+    getDependencies(id: string): string[];
+    /** Get all modules that directly depend on a module. */
+    getDependents(id: string): string[];
+    /**
+     * Get all modules transitively affected if the given module changes.
+     * Walks the "incoming" edges (dependents) recursively.
+     */
+    getImpactedModules(id: string): string[];
+    /**
+     * Get all transitive dependencies of a module.
+     * Walks "outgoing" edges recursively.
+     */
+    getTransitiveDependencies(id: string): string[];
+    /**
+     * Detect cycles in the graph.
+     * Returns an array of cycles, where each cycle is an array of module IDs.
+     */
+    detectCycles(): string[][];
+    /**
+     * Topological sort of the graph.
+     * Returns null if the graph has cycles.
+     */
+    topologicalSort(): string[] | null;
+    /**
+     * Find shared dependencies between two modules.
+     * Useful for understanding which code is shared vs. unique.
+     */
+    getSharedDependencies(idA: string, idB: string): string[];
+    /**
+     * Find dependencies unique to a module (not shared with any other top-level module).
+     * Used for calculating "exclusive" bundle size.
+     */
+    getExclusiveDependencies(id: string, allTopLevel: string[]): string[];
+    /** Get all node IDs in the graph. */
+    getAllNodes(): string[];
+    /** Get the total number of nodes. */
+    get nodeCount(): number;
+    /** Get the total number of edges. */
+    get edgeCount(): number;
+    private ensureNode;
+}
+
+/**
+ * Resolve and load the Foxlight configuration.
+ * Searches for config files in the given directory, or returns defaults.
+ */
+declare function loadConfig(rootDir: string): Promise<FoxlightConfig>;
+/**
+ * Create a default configuration for the given root directory.
+ */
+declare function createDefaultConfig(rootDir: string): FoxlightConfig;
+/**
+ * Auto-detect the framework used in a project by examining package.json.
+ */
+declare function detectFramework(rootDir: string): Promise<Framework>;
+
+/** Default weights for each health metric (must sum to 1). */
+interface HealthWeights {
+    bundleSize: number;
+    testCoverage: number;
+    accessibility: number;
+    freshness: number;
+    performance: number;
+    reliability: number;
+}
+declare const DEFAULT_WEIGHTS: HealthWeights;
+/** All available data for computing a component's health. */
+interface HealthInput {
+    component: ComponentInfo;
+    bundleInfo?: ComponentBundleInfo;
+    /** Test coverage percentage (0-100) */
+    testCoverage?: number;
+    /** Accessibility score (0-100, e.g., from axe-core) */
+    accessibilityScore?: number;
+    /** Days since the component was last modified */
+    daysSinceModified?: number;
+    /** Average render time in milliseconds */
+    renderTimeMs?: number;
+    /** Error rate (0-1, e.g., 0.02 = 2% error rate) */
+    errorRate?: number;
+}
+/**
+ * Compute the full health score for a component.
+ */
+declare function computeComponentHealth(input: HealthInput, weights?: HealthWeights): ComponentHealth;
+/**
+ * Compute health scores for multiple components.
+ */
+declare function computeAllHealth(inputs: HealthInput[], weights?: HealthWeights): ComponentHealth[];
+
+declare const COST_MODELS: Record<string, CostModel>;
+/** Monthly traffic assumptions for cost estimation. */
+interface TrafficProfile {
+    /** Monthly page views */
+    monthlyPageViews: number;
+    /** Average number of SSR/serverless function invocations per page view */
+    invocationsPerPageView: number;
+    /** Percentage of requests handled at the edge (0-1) */
+    edgeRatio: number;
+}
+declare const DEFAULT_TRAFFIC: TrafficProfile;
+/**
+ * Estimate the monthly cost impact of a change in bundle size.
+ *
+ * Computes costs based on:
+ * - Bandwidth: more bytes served = higher bandwidth cost
+ * - Invocations: unchanged (but included for completeness)
+ * - Storage: cost of storing assets on CDN/hosting
+ * - Edge: edge function invocation costs
+ */
+declare function estimateCostImpact(currentBundleInfo: ComponentBundleInfo[], updatedBundleInfo: ComponentBundleInfo[], costModel: CostModel, traffic?: TrafficProfile): CostImpact;
+/**
+ * Estimate cost for a single set of bundle info (not a delta).
+ */
+declare function estimateMonthlyCost(bundleInfo: ComponentBundleInfo[], costModel: CostModel, traffic?: TrafficProfile): number;
+
+interface UpgradeAnalysisOptions {
+    /** Project root directory */
+    rootDir: string;
+    /** Package name to analyze (e.g., "react") */
+    packageName: string;
+    /** Target version to upgrade to (e.g., "19.0.0"). If omitted, uses latest. */
+    targetVersion?: string;
+    /** Components that depend on this package (for impact analysis) */
+    affectedComponents?: ComponentInfo[];
+}
+/**
+ * Analyze the impact of upgrading a dependency.
+ *
+ * Runs several checks:
+ * 1. Version resolution (current vs target)
+ * 2. Semver risk assessment (major/minor/patch)
+ * 3. Component impact (which components use this dep)
+ * 4. Peer dependency compatibility
+ * 5. Bundle size change estimate
+ */
+declare function analyzeUpgrade(options: UpgradeAnalysisOptions): Promise<UpgradePreview>;
+/**
+ * Analyze multiple upgrades at once.
+ */
+declare function analyzeUpgrades(rootDir: string, packages: Array<{
+    name: string;
+    targetVersion?: string;
+}>, allComponents?: ComponentInfo[]): Promise<UpgradePreview[]>;
+
+/**
+ * Extract ES module import statements from a script string
+ * using regex matching. Handles:
+ * - Default imports: `import Foo from '...'`
+ * - Named imports: `import { a, b } from '...'`
+ * - Mixed imports: `import Foo, { a } from '...'`
+ * - Namespace imports: `import * as Foo from '...'`
+ * - Type imports: `import type { ... } from '...'`
+ *
+ * @param script — The JavaScript/TypeScript source text to scan.
+ * @param filePath — The file this script belongs to (used as the `source` in ImportEdge).
+ */
+declare function extractImportsFromScript(script: string, filePath: string): ImportEdge[];
+
+/** Istanbul coverage data for a single file. */
+interface IstanbulCoverageFile {
+    path: string;
+    statementMap: Record<string, {
+        start: {
+            line: number;
+        };
+        end: {
+            line: number;
+        };
+    }>;
+    fnMap: Record<string, {
+        name: string;
+        decl: {
+            start: {
+                line: number;
+            };
+        };
+    }>;
+    branchMap: Record<string, {
+        loc: {
+            start: {
+                line: number;
+            };
+        };
+    }>;
+    s: Record<string, number>;
+    f: Record<string, number>;
+    b: Record<string, number[]>;
+}
+interface ComponentCoverage {
+    componentId: string;
+    filePath: string;
+    statementsCovered: number;
+    statementsTotal: number;
+    functionsCovered: number;
+    functionsTotal: number;
+    percentage: number;
+    isCovered: boolean;
+}
+interface CoverageReport {
+    components: Map<string, ComponentCoverage>;
+    totalStatementsCovered: number;
+    totalStatementsTotal: number;
+    overallPercentage: number;
+}
+/**
+ * Load coverage data from Istanbul JSON format.
+ * Looks for coverage/coverage-final.json by default.
+ */
+declare function loadCoverageData(projectRoot: string, customCoveragePath?: string): Promise<Record<string, IstanbulCoverageFile>>;
+/**
+ * Map coverage data to components.
+ * Matches files in coverage data to component file paths.
+ */
+declare function mapCoverageToComponents(coverageData: Record<string, IstanbulCoverageFile>, componentFilePaths: Set<string>): CoverageReport;
+/**
+ * Get coverage percentage for a component by file path or ID.
+ * Returns 0 if no coverage data found (uncovered component).
+ */
+declare function getComponentCoverage(componentFilePath: string, coverage: CoverageReport): number;
+/**
+ * Find components with no test coverage (0% coverage).
+ */
+declare function findUncoveredComponents(coverage: CoverageReport): ComponentCoverage[];
+/**
+ * Find components with low test coverage (below threshold).
+ */
+declare function findLowCoverageComponents(coverage: CoverageReport, threshold?: number): ComponentCoverage[];
+/**
+ * Generate a coverage report summary.
+ */
+declare function summarizeCoverage(coverage: CoverageReport): string;
+
+interface UnusedComponent {
+    id: string;
+    name: string;
+    filePath: string;
+    potentialSavings?: string;
+    reason: 'never_imported' | 'unused_export' | 'orphaned';
+}
+interface UnusedExport {
+    filePath: string;
+    exportName: string;
+    reason: 'exported_but_unused' | 're_exported_unused';
+}
+interface DeadCodeReport {
+    unusedComponents: UnusedComponent[];
+    orphanedComponents: UnusedComponent[];
+    unusedExports: UnusedExport[];
+    totalPotentialBytes: number;
+}
+/**
+ * Analyze the component registry to find dead code.
+ */
+declare function detectDeadCode(registry: ComponentRegistry): DeadCodeReport;
+/**
+ * Get components that should definitely be safe to remove.
+ * These are unused components with no dependencies.
+ */
+declare function findSafeRemovalCandidates(report: DeadCodeReport): UnusedComponent[];
+/**
+ * Format dead code report for display.
+ */
+declare function formatDeadCodeReport(report: DeadCodeReport): string;
+
+interface ComponentAPI {
+    componentId: string;
+    name: string;
+    filePath: string;
+    exportKind: 'named' | 'default' | 're-export';
+    props: PropInfo[];
+    timestamp: string;
+    version?: string;
+}
+interface APISnapshot {
+    components: Map<string, ComponentAPI>;
+    timestamp: string;
+    hash?: string;
+}
+type BreakingChangeType = 'prop_removed' | 'prop_required_changed' | 'export_removed' | 'export_kind_changed';
+interface BreakingChange {
+    componentId: string;
+    componentName: string;
+    changeType: BreakingChangeType;
+    description: string;
+    affectedItems: string[];
+    severity: 'critical' | 'high' | 'medium';
+}
+interface APIChangeSummary {
+    addedComponents: ComponentAPI[];
+    removedComponents: ComponentAPI[];
+    modifiedComponents: {
+        component: ComponentAPI;
+        changes: APIChange[];
+    }[];
+    breaking: BreakingChange[];
+    nonBreaking: APIChange[];
+}
+interface APIChange {
+    type: 'added' | 'removed' | 'modified';
+    field: 'prop' | 'export_kind';
+    oldValue?: unknown;
+    newValue?: unknown;
+}
+/**
+ * Create a snapshot of component APIs.
+ */
+declare function createAPISnapshot(components: ComponentInfo[], hash?: string): APISnapshot;
+/**
+ * Serialize snapshot to JSON for storage.
+ */
+declare function snapshotToJSON(snapshot: APISnapshot): string;
+/**
+ * Deserialize snapshot from JSON.
+ */
+declare function snapshotFromJSON(json: string): APISnapshot;
+/**
+ * Compare two API snapshots and detect breaking changes.
+ */
+declare function compareSnapshots(oldSnapshot: APISnapshot, newSnapshot: APISnapshot): APIChangeSummary;
+/**
+ * Format API changes for display.
+ */
+declare function formatAPIChangeSummary(summary: APIChangeSummary): string;
+
+export { type APIChangeSummary, type APISnapshot, type BaselineConfig, type BreakingChange, type BundleDiffEntry, COST_MODELS, type ComponentAPI, type ComponentBundleInfo, type ComponentCoverage, type ComponentHealth, type ComponentId, type ComponentInfo, type ComponentModification, ComponentRegistry, type CostBreakdownItem, type CostImpact, type CostModel, type CoverageReport, DEFAULT_TRAFFIC, DEFAULT_WEIGHTS, type DeadCodeReport, DependencyGraph, type ExportKind, type FoxlightConfig, type Framework, type HealthDiffEntry, type HealthInput, type HealthMetrics, type HealthWeights, type ImportEdge, type ImportSpecifier, type MetricScore, type PluginConfig, type ProjectSnapshot, type PropInfo, type SizeInfo, type SnapshotDiff, type TrafficProfile, type UnusedComponent, type UnusedExport, type UpgradeAnalysisOptions, type UpgradeCheck, type UpgradePreview, analyzeUpgrade, analyzeUpgrades, compareSnapshots, computeAllHealth, computeComponentHealth, createAPISnapshot, createDefaultConfig, detectDeadCode, detectFramework, estimateCostImpact, estimateMonthlyCost, extractImportsFromScript, findLowCoverageComponents, findSafeRemovalCandidates, findUncoveredComponents, formatAPIChangeSummary, formatDeadCodeReport, getComponentCoverage, loadConfig, loadCoverageData, mapCoverageToComponents, snapshotFromJSON, snapshotToJSON, summarizeCoverage };