prism0x2a 0.7.2 → 0.11.0

package/.next/standalone/node_modules/prismlens/dist/blueprint/index.d.mts

@@ -0,0 +1,484 @@
+interface FileCoverage {
+    statements: number;
+    branches: number;
+    functions: number;
+    lines: number;
+}
+
+type FileCategory = "app" | "component" | "lib" | "hook" | "unknown";
+type RenderEnvironment = "client" | "server" | "shared" | "unknown";
+type NextFileKind = "page" | "layout" | "route" | "loading" | "error" | "template" | "default" | "unknown";
+type ImportUsage = "runtime" | "type-only";
+interface ResolvedImport {
+    source: string;
+    resolvedPath: string | null;
+    kind: "internal" | "external";
+    importUsage: ImportUsage;
+}
+interface GraphNode {
+    id: string;
+    path: string;
+    category: FileCategory;
+    loc: number;
+    hasJsDoc: boolean;
+    label: string;
+}
+interface GraphEdge {
+    source: string;
+    target: string;
+    type: "import";
+}
+interface CycleGroup {
+    id: string;
+    paths: string[];
+    size: number;
+}
+interface BlueprintAnalysis {
+    hasCycles: boolean;
+    cycleCount: number;
+    stronglyConnectedComponents: CycleGroup[];
+    filesInCycles: string[];
+    cyclesEliminatedByTypeImportFiltering: number;
+}
+type ControlConfidence = "certain" | "inferred";
+type ControlKind = "button" | "input" | "textarea" | "select" | "checkbox" | "radio" | "tabs" | "dialog" | "table" | "search" | "toggle" | "dropdown" | "form" | "nav" | "other";
+interface ControlItem {
+    kind: ControlKind;
+    semanticRole: string;
+    count: number;
+    confidence: ControlConfidence;
+    hint?: string;
+}
+interface ControlInventory {
+    controls: ControlItem[];
+    formFieldCount: number;
+    actionCount: number;
+    hasSearch: boolean;
+    hasTabs: boolean;
+    hasTable: boolean;
+    hasForm: boolean;
+    hasDialog: boolean;
+    isInferred: boolean;
+}
+type ScreenKind = "dashboard" | "admin" | "chat" | "form" | "profile" | "settings" | "landing" | "list" | "detail" | "builder" | "wizard" | "recovery" | "page" | "layout" | "component" | "unknown";
+interface ScreenInfo {
+    /** Human-readable label, e.g. "Admin Dashboard", "Chat Composer" */
+    label: string;
+    screenKind: ScreenKind;
+    /** Inferred UI composition patterns: "form", "data-table", "chat", etc. */
+    uiPatterns: string[];
+    /** Non-React custom hooks used (e.g. useWidgetEditor, useDecisionEngine) */
+    customHooks: string[];
+    /** Event handler function names (handleSubmit, handleDelete, …) */
+    eventHandlers: string[];
+    /** Data source signals: "supabase", "http-fetch", "context", "router", … */
+    dataSources: string[];
+}
+interface HookCounts {
+    useState: number;
+    useReducer: number;
+    useEffect: number;
+    useMemo: number;
+    useCallback: number;
+    useRef: number;
+    total: number;
+}
+interface StateComplexity {
+    hookCounts: HookCounts;
+    localStateSignals: string[];
+    complexityNotes: string[];
+}
+/**
+ * TypedSignature — extracted by ts-morph AST enrichment pass.
+ * Populated after the regex scan for high-value files only.
+ */
+interface TypedSignature {
+    name: string;
+    kind: "function" | "component" | "hook" | "const" | "type" | "interface" | "unknown";
+    /** Full TypeScript type signature, e.g. "(userId: string) => Promise<User>" */
+    signature: string;
+    jsDoc: {
+        description: string | null;
+        params: Array<{
+            name: string;
+            type: string;
+            description: string;
+        }>;
+        returns: string | null;
+    };
+}
+interface SymbolSummary {
+    name: string;
+    kind: "function" | "component" | "hook" | "const" | "type" | "unknown";
+    exported: boolean;
+    doc: string | null;
+    /** TypeScript type signature from ts-morph enrichment (optional, high-value files only) */
+    signature?: string;
+}
+interface CodeSnippet {
+    label: string;
+    kind: "export" | "function" | "component" | "query" | "config-usage" | "table-usage";
+    snippet: string;
+}
+interface FileExplainability {
+    primaryDocBlock: string | null;
+    docBlocks: string[];
+    symbolSummaries: SymbolSummary[];
+    codeSnippets: CodeSnippet[];
+    matchedConfigIdsInCode: string[];
+    matchedTableNamesInCode: string[];
+    /** Typed signatures from ts-morph enrichment pass (optional — only on enriched files) */
+    typedSignatures?: TypedSignature[];
+}
+interface FileMetrics {
+    loc: number;
+    incomingRuntimeDeps: number;
+    outgoingRuntimeDeps: number;
+    jsxComponentCount: number;
+    uiPrimitiveCount: number;
+    complexityScore: number | null;
+    duplicationScore: number | null;
+    heatScore: number;
+}
+interface FileEntry {
+    id: string;
+    path: string;
+    category: FileCategory;
+    loc: number;
+    imports: string[];
+    exports: string[];
+    hasJsDoc: boolean;
+    docSummary: string | null;
+    docBlock: string | null;
+    renderEnvironment: RenderEnvironment;
+    nextFileKind: NextFileKind;
+    routePath: string | null;
+    hasUseClientDirective: boolean;
+    hasUseServerDirective: boolean;
+    isApiRoute: boolean;
+    isCyclic: boolean;
+    cycleGroupId: string | null;
+    jsxComponents: string[];
+    uiPrimitives: string[];
+    componentUsageCount: number;
+    topLevelJsxBlocks: string[];
+    metrics: FileMetrics;
+    stateComplexity: StateComplexity | null;
+    controlInventory: ControlInventory | null;
+    screenInfo: ScreenInfo | null;
+    explainability: FileExplainability;
+    relatedConfigIds: string[];
+    relatedTableNames: string[];
+    internalImports: string[];
+    externalImports: string[];
+    runtimeInternalImports: string[];
+    typeOnlyInternalImports: string[];
+    incomingInternalDependencies: string[];
+    outgoingInternalDependencies: string[];
+    resolvedImportMap: ResolvedImport[];
+    coverage: FileCoverage | null;
+    /** Git commit count in the last 90 days. undefined if not in a git repo or not computed. */
+    churn?: number;
+    /** JSDoc @-tags extracted from /** ... *\/ blocks, excluding @amber-* tags. Up to 5 unique tag names. */
+    jsdocTags?: Record<string, string[]>;
+    /** Commit activity stats for this file (90d / 180d windows). */
+    commitStats?: FileCommitStats;
+}
+interface BlueprintSummary {
+    fileCount: number;
+    pageCount: number;
+    componentCount: number;
+    libCount: number;
+    hookCount: number;
+    internalDependencyCount: number;
+    externalDependencyCount: number;
+    runtimeInternalDependencyCount: number;
+    typeOnlyInternalDependencyCount: number;
+    nodeCount: number;
+    edgeCount: number;
+    mostImportedFiles: Array<{
+        path: string;
+        count: number;
+    }>;
+    clientFileCount: number;
+    serverFileCount: number;
+    pageFileCount: number;
+    routeFileCount: number;
+    routesDiscovered: string[];
+    cyclicFileCount: number;
+    stronglyConnectedComponentCount: number;
+    largestCycleSize: number;
+    tsxFileCount: number;
+    filesWithJsxComponents: number;
+    filesWithUiPrimitives: number;
+    mostUsedUiPrimitives: Array<{
+        name: string;
+        count: number;
+    }>;
+    configSectionCount: number;
+    sqlTableCount: number;
+    sqlForeignKeyCount: number;
+    configCodeLinkCount: number;
+    schemaCodeLinkCount: number;
+    filesWithExplainability: number;
+    filesWithTableStringMatches: number;
+    filesWithConfigStringMatches: number;
+    filesWithStateComplexity: number;
+    topStateHeavyFiles: Array<{
+        path: string;
+        totalHooks: number;
+    }>;
+}
+interface CategoryHeat {
+    category: string;
+    averageHeat: number;
+    fileCount: number;
+}
+interface BlueprintHeatmap {
+    hottestFiles: Array<{
+        path: string;
+        heatScore: number;
+    }>;
+    categoryHeat: CategoryHeat[];
+}
+type SectionKind = "baseline" | "routing" | "ai" | "feature-config" | "processes" | "widgets" | "roles" | "theme" | "metrics" | "objects" | "registry" | "content" | "system" | "unknown";
+interface ConfigSection {
+    id: string;
+    label: string | null;
+    kind: SectionKind;
+    itemCount: number | null;
+    sampleKeys: string[];
+}
+interface ConfigLayer {
+    sourcePath: string;
+    found: boolean;
+    fileType: "json" | null;
+    appId: string | null;
+    topLevelKeys: string[];
+    sectionCount: number;
+    sections: ConfigSection[];
+}
+type TableCategory = "app" | "system" | "ai" | "workspace" | "content" | "unknown";
+interface SchemaTable {
+    name: string;
+    schema: string | null;
+    columnCount: number | null;
+    hasJsonb: boolean;
+    foreignKeyCount: number;
+    category: TableCategory;
+}
+interface SchemaForeignKey {
+    fromTable: string;
+    toTable: string;
+}
+interface SchemaLayer {
+    sourcePath: string;
+    found: boolean;
+    fileType: "sql" | null;
+    tableCount: number;
+    tables: SchemaTable[];
+    foreignKeys: SchemaForeignKey[];
+}
+interface CodeMatchLink {
+    path: string;
+    score: number;
+    reasons: string[];
+}
+interface ConfigToCodeLink {
+    configId: string;
+    configKind: string;
+    matchedFiles: CodeMatchLink[];
+}
+interface SchemaToCodeLink {
+    tableName: string;
+    category: string;
+    matchedFiles: CodeMatchLink[];
+}
+interface CrossReferences {
+    configToCode: ConfigToCodeLink[];
+    schemaToCode: SchemaToCodeLink[];
+}
+interface MarkdownDoc {
+    path: string;
+    title: string;
+    headingTree: string[];
+    loc: number;
+    wordCount?: number;
+    lastModified: string;
+    gitLastCommit?: string;
+}
+interface RecentCommit {
+    sha: string;
+    date: string;
+    subject: string;
+    files: string[];
+    insertions: number;
+    deletions: number;
+}
+interface FileCommitStats {
+    count_90d: number;
+    count_180d: number;
+    subjects_180d: string[];
+}
+interface BlueprintOutput {
+    generatedAt: string;
+    summary: BlueprintSummary;
+    analysis: BlueprintAnalysis;
+    heatmap: BlueprintHeatmap;
+    configLayer: ConfigLayer;
+    schemaLayer: SchemaLayer;
+    crossReferences: CrossReferences;
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+    files: FileEntry[];
+    markdownDocs?: MarkdownDoc[];
+    recentCommits?: RecentCommit[];
+    /** @todo tags collected from all scanned files (additive — optional). */
+    recentTodos?: Array<{
+        path: string;
+        text: string;
+    }>;
+    /** @deprecated tags collected from all scanned files (additive — optional). */
+    deprecatedSurface?: Array<{
+        path: string;
+        reason: string;
+    }>;
+}
+
+/** Enriched file graph ready for rendering or analysis. */
+interface BlueprintGraph {
+    files: FileEntry[];
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+    analysis: BlueprintAnalysis;
+}
+/** Per-file coverage keyed by repo-relative file path. */
+type CoverageMap = Map<string, FileCoverage>;
+/** Summary of changed files since a given scan time. */
+interface ChangeSet {
+    changedFiles: string[];
+    addedFiles: string[];
+    total: number;
+    lastScanAt: string;
+}
+/** Aggregated stats extracted from a Blueprint for quick UI display. */
+interface BlueprintStats {
+    totalFiles: number;
+    runtimeEdges: number;
+    tsxFiles: number;
+    appRoutes: number;
+    configSections: number;
+    sqlTables: number;
+    tableMatches: number;
+    configMatches: number;
+    cyclicFiles: number;
+    coverageFileCount: number;
+    hottestFile: {
+        path: string;
+        heatScore: number;
+    } | null;
+}
+/** Options accepted by generateBlueprint. */
+interface BlueprintOptions {
+    /** Glob patterns to include (default: the prismlens blueprintConfig.include). */
+    include?: string[];
+    /** Glob patterns to exclude (default: the prismlens blueprintConfig.exclude). */
+    exclude?: string[];
+    /** Write output/blueprint.json inside target when true (default: false). */
+    write?: boolean;
+    /** Path for blueprint.json relative to target (default: "output/blueprint.json"). */
+    outputPath?: string;
+}
+
+/**
+ * Run a full blueprint scan for `target` and return the result.
+ * All FS reads are relative to `target`. When `opts.write` is true the
+ * output is also persisted to `<target>/<opts.outputPath>`.
+ */
+declare function generateBlueprint(target: string, opts?: BlueprintOptions): Promise<BlueprintOutput>;
+/**
+ * Read a previously generated Blueprint from disk.
+ * Returns null when the file is absent or cannot be parsed.
+ * Default path: `<target>/output/blueprint.json`
+ */
+declare function readBlueprint(target: string, outputPath?: string): BlueprintOutput | null;
+
+/**
+ * Compute a concise stats summary from a full Blueprint snapshot.
+ * All fields are derived purely from the blueprint data — no FS access.
+ */
+declare function aggregateStats(blueprint: BlueprintOutput): BlueprintStats;
+
+/**
+ * Discover and parse all source files under `target`.
+ * Returns FileEntry[] with imports, exports, metrics, heat scores computed.
+ * Coverage is set to null — call mergeWithGraph() to annotate.
+ */
+declare function readSourceFiles(target: string, include?: readonly string[], exclude?: readonly string[]): Promise<FileEntry[]>;
+/**
+ * Extract import edges from a file set.
+ * Returns only runtime internal import edges (source → target by path).
+ */
+declare function extractEdges(files: FileEntry[]): GraphEdge[];
+/**
+ * Assemble a BlueprintGraph from file entries and edges.
+ * Computes cycle analysis (SCC) and annotates each FileEntry.
+ */
+declare function buildGraph(files: FileEntry[], edges: GraphEdge[]): BlueprintGraph;
+
+/** Read the pre-computed heat score from a file's metrics. Range: 0–100. */
+declare function calculateHeatScore(file: FileEntry): number;
+/** Aggregate average heat and file count per category across a file set. */
+declare function heatPerCategory(files: FileEntry[]): CategoryHeat[];
+/** Hex colour for a heat score (5 tiers matching the blueprint explorer). */
+declare function heatColor(score: number): string;
+/** Ordered gradient stops matching the 5 heat tiers (cold → hot). */
+declare const heatGradient: ReadonlyArray<{
+    threshold: number;
+    color: string;
+    label: string;
+}>;
+/** Return the top-N hottest files sorted descending by heat score. */
+declare function hottestFiles(files: FileEntry[], limit?: number): Array<{
+    path: string;
+    heatScore: number;
+}>;
+
+/**
+ * Read Vitest/Jest coverage-summary.json from the target project root.
+ * Returns an empty map when the file is absent or unparseable.
+ */
+declare function readCoverageData(target: string): CoverageMap;
+/**
+ * Annotate each file in a BlueprintGraph with coverage data from the map.
+ * Returns a new graph (files array is cloned; nodes/edges/analysis unchanged).
+ */
+declare function mergeWithGraph(graph: BlueprintGraph, coverage: CoverageMap): BlueprintGraph;
+
+/**
+ * Classify a file path (and optionally its content) into a FileCategory.
+ * Classification is path-based: app/ → "app", components/ → "component",
+ * lib/ → "lib", hooks/ → "hook", anything else → "unknown".
+ */
+declare function classifyFile(filePath: string, _content?: string): FileCategory;
+/**
+ * Return only the files matching one or more categories.
+ * Pass an empty array to return all files.
+ */
+declare function filterByCategory(files: FileEntry[], categories: FileCategory[]): FileEntry[];
+
+/**
+ * Return true when any source file under target has an mtime newer than
+ * lastScanTime. Useful for deciding whether a re-scan is warranted.
+ */
+declare function hasSourceChanged(target: string, lastScanTime: Date, include?: string[], exclude?: string[]): boolean;
+/**
+ * Return the set of files whose mtime is newer than lastScanTime, plus any
+ * files that exist now but are not in knownPaths.
+ *
+ * @param knownPaths - Set of repo-relative paths from the last Blueprint scan.
+ *   Pass an empty Set to treat all files as "added".
+ */
+declare function getSourceChangeSummary(target: string, lastScanTime: Date, knownPaths?: Set<string>, include?: string[], exclude?: string[]): ChangeSet;
+
+export { type BlueprintOutput as Blueprint, type GraphEdge as BlueprintEdge, type FileEntry as BlueprintFile, type BlueprintGraph, type BlueprintOptions, type BlueprintStats, type CategoryHeat, type ChangeSet, type CoverageMap, type FileCategory, aggregateStats, buildGraph, calculateHeatScore, classifyFile, extractEdges, filterByCategory, generateBlueprint, getSourceChangeSummary, hasSourceChanged, heatColor, heatGradient, heatPerCategory, hottestFiles, mergeWithGraph, readBlueprint, readCoverageData, readSourceFiles };