@thoughtflow/core 0.1.2

package/dist/contracts/problem-tree.types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=problem-tree.types.js.map

package/dist/contracts/problem-tree.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"problem-tree.types.js","sourceRoot":"","sources":["../../src/contracts/problem-tree.types.ts"],"names":[],"mappings":""}

package/dist/contracts/prompt.types.d.ts

@@ -0,0 +1,41 @@
+import { SkillDefinition } from "./skill.types";
+import type { ContextDocument } from "./context-document.types";
+export interface PromptTemplate {
+    name: string;
+    content: string;
+}
+/**
+ * Structured policy sections rendered into the system prompt by PromptBuilder.
+ * Each present field becomes a clearly delimited section, placed after the base
+ * system prompt and before skill/runtime blocks.
+ */
+export interface PromptPolicy {
+    /** Clear statement of agent role and purpose. */
+    roleIntent?: string;
+    /**
+     * Instructions on when and how to use tools.
+     * Examples: parallelize independent reads, prefer specialized tools,
+     * do not repeat a tool with the same arguments.
+     */
+    toolUsePolicy?: string;
+    /** Explicit criteria that must be satisfied before the turn ends. */
+    stopCondition?: string;
+    /** Expected output format and structure (e.g. JSON schema, plain text, markdown). */
+    outputContract?: string;
+}
+export interface PromptBuildInput {
+    systemPrompt?: string;
+    userLanguage?: string;
+    userPrompt: string;
+    skills?: SkillDefinition[];
+    runtimeContext?: Record<string, unknown>;
+    /** Optional structured policy applied after the base system prompt. */
+    policy?: PromptPolicy;
+    /** Context documents to inject into the system prompt. @see ContextDocument */
+    contextDocs?: ContextDocument[];
+}
+export interface PromptBuildOutput {
+    systemPrompt: string;
+    userPrompt: string;
+}
+//# sourceMappingURL=prompt.types.d.ts.map

package/dist/contracts/prompt.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.types.d.ts","sourceRoot":"","sources":["../../src/contracts/prompt.types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAEhE,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,iDAAiD;IACjD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,qEAAqE;IACrE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,qFAAqF;IACrF,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,gBAAgB;IAC/B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,eAAe,EAAE,CAAC;IAC3B,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzC,uEAAuE;IACvE,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,+EAA+E;IAC/E,WAAW,CAAC,EAAE,eAAe,EAAE,CAAC;CACjC;AAED,MAAM,WAAW,iBAAiB;IAChC,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;CACpB"}

package/dist/contracts/prompt.types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=prompt.types.js.map

package/dist/contracts/prompt.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.types.js","sourceRoot":"","sources":["../../src/contracts/prompt.types.ts"],"names":[],"mappings":""}

package/dist/contracts/skill.types.d.ts

@@ -0,0 +1,39 @@
+export interface SkillDefinition {
+    name: string;
+    description?: string;
+    content: string;
+    tags?: string[];
+    /**
+     * Skill categories/triggers - contexts where this skill is relevant.
+     * Examples: "coding", "analysis", "planning", "knowledge-management"
+     */
+    triggers?: string[];
+    /**
+     * Whether skill content is lazy-loaded (loaded on-demand).
+     * If true, content will be empty until resolved
+     */
+    lazy?: boolean;
+    /**
+     * Estimated token cost of this skill when included in prompt
+     */
+    estimatedTokens?: number;
+    /**
+     * Priority (lower = higher priority when pruning by context window)
+     */
+    priority?: number;
+    /**
+     * Whether skill is always included by default
+     */
+    alwaysInclude?: boolean;
+}
+export interface SkillMetadata {
+    name?: string;
+    description?: string;
+    tags?: string[];
+    triggers?: string[];
+    lazy?: boolean;
+    estimatedTokens?: number;
+    priority?: number;
+    alwaysInclude?: boolean;
+}
+//# sourceMappingURL=skill.types.d.ts.map

package/dist/contracts/skill.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill.types.d.ts","sourceRoot":"","sources":["../../src/contracts/skill.types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;;OAEG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;OAEG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB"}

package/dist/contracts/skill.types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=skill.types.js.map

package/dist/contracts/skill.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill.types.js","sourceRoot":"","sources":["../../src/contracts/skill.types.ts"],"names":[],"mappings":""}

package/dist/contracts/storage.types.d.ts

@@ -0,0 +1,154 @@
+export interface StorageListOptions<T> {
+    filter?: Partial<T>;
+    limit?: number;
+    offset?: number;
+    orderBy?: keyof T;
+    order?: "asc" | "desc";
+}
+export interface StorageSearchOptions {
+    /** Full-text search, case-insensitive, matches `content` and `title` fields. */
+    query?: string;
+    /** AND match — entry must have ALL listed tags. */
+    tags?: string[];
+    category?: string;
+    /** Filter by conversation session (uuidv4). */
+    sessionId?: string;
+    from?: Date;
+    to?: Date;
+    limit?: number;
+    offset?: number;
+}
+export interface IStorageAdapter<T extends {
+    id: string;
+}> {
+    create(item: Omit<T, "id">): Promise<T>;
+    read(id: string): Promise<T | null>;
+    update(id: string, patch: Partial<T>): Promise<T>;
+    delete(id: string): Promise<void>;
+    list(options?: StorageListOptions<T>): Promise<T[]>;
+    search(options: StorageSearchOptions): Promise<T[]>;
+    count(filter?: Partial<T>): Promise<number>;
+    initialize?(): Promise<void>;
+    dispose?(): Promise<void>;
+}
+import { ConversationRole, ToolCall } from "./message.types";
+import { ConversationInterruptDecision, ConversationPendingInterrupt } from "./interrupt.types";
+/** Storage-layer message — includes sessionId and compression metadata. */
+export interface StoredMessage {
+    id: string;
+    /** Original in-memory message id from ConversationMessage. */
+    messageId?: string;
+    /** uuidv4 of the Conversation instance that produced this message. */
+    sessionId: string;
+    role: ConversationRole;
+    content: string;
+    /** Tool execution id that this tool message corresponds to. */
+    toolCallId?: string;
+    /** Additional structured metadata attached to the message. */
+    metadata?: Record<string, unknown>;
+    toolCalls?: ToolCall[];
+    tokenCount?: number;
+    /**
+     * true = this entry is a compressed summary replacing multiple older messages.
+     * Compressed messages are NOT sent to the LLM but are accessible via the
+     * conversation_history tool.
+     */
+    compressed?: boolean;
+    /** IDs of original messages that were compressed into this entry. */
+    compressedFrom?: string[];
+    createdAt: string;
+}
+/** Persisted knowledge entry written by the knowledge tool. */
+export interface KnowledgeEntry {
+    id: string;
+    /**
+     * Optional — cross-session knowledge leaves this undefined.
+     * Session-scoped entries set this to the conversation's sessionId.
+     */
+    sessionId?: string;
+    /** Freeform string — user defines their own taxonomy. */
+    category: string;
+    title: string;
+    content: string;
+    tags: string[];
+    createdAt: string;
+    updatedAt: string;
+}
+/** Persisted pending interrupt snapshot for durable resume. */
+export interface StoredInterrupt {
+    id: string;
+    sessionId: string;
+    pending: ConversationPendingInterrupt;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Persisted audit entry for an interrupt resolution decision set. */
+export interface StoredInterruptResolution {
+    id: string;
+    sessionId: string;
+    interruptId: string;
+    decisions: ConversationInterruptDecision[];
+    resolvedAt: string;
+    createdAt: string;
+}
+/** Persisted per-step checkpoint snapshot for thread progression. */
+export interface StoredCheckpoint {
+    id: string;
+    sessionId: string;
+    threadId: string;
+    step: number;
+    messagesCount: number;
+    lastMessageId?: string;
+    createdAt: string;
+}
+/** Generic long-term store record (namespace/key/value) compatible with search/list APIs. */
+export interface StoreEntry {
+    id: string;
+    sessionId: string;
+    namespace: string;
+    key: string;
+    value: unknown;
+    valueText: string;
+    tags: string[];
+    /** Mirrors `key` for built-in full-text adapter support. */
+    title: string;
+    /** Mirrors serialized value for built-in full-text adapter support. */
+    content: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface ConversationStorageConfig {
+    /**
+     * Stores conversation messages (history, compression).
+     * Default: InMemoryAdapter<StoredMessage>.
+     */
+    messages?: IStorageAdapter<StoredMessage>;
+    /**
+     * Stores knowledge entries written by the knowledge tool.
+     * Default: InMemoryAdapter<KnowledgeEntry>.
+     */
+    knowledge?: IStorageAdapter<KnowledgeEntry>;
+    /**
+     * Stores pending interrupt snapshots to support resume() after reload.
+     * Default: InMemoryAdapter<StoredInterrupt>.
+     */
+    interrupts?: IStorageAdapter<StoredInterrupt>;
+    /**
+     * Stores resolved HITL decisions for audit trail and post-run inspection.
+     * Default: InMemoryAdapter<StoredInterruptResolution>.
+     */
+    interruptResolutions?: IStorageAdapter<StoredInterruptResolution>;
+    /**
+     * Stores per-step checkpoints for thread progression and replay inspection.
+     * Default: InMemoryAdapter<StoredCheckpoint>.
+     */
+    checkpoints?: IStorageAdapter<StoredCheckpoint>;
+    /**
+     * Generic namespace/key/value long-term store backend.
+     * Default: InMemoryAdapter<StoreEntry>.
+     */
+    store?: IStorageAdapter<StoreEntry>;
+    codebaseVectorStore?: import("./vector-store.types").IVectorStore;
+    codebaseEmbeddingProvider?: import("./vector-store.types").IEmbeddingProvider;
+}
+//# sourceMappingURL=storage.types.d.ts.map

package/dist/contracts/storage.types.d.ts.map

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

package/dist/contracts/storage.types.js

@@ -0,0 +1,11 @@
+"use strict";
+// ─────────────────────────────────────────────────────────────────────────────
+// Storage Abstraction Layer — Faza 0
+//
+// All persistent data (messages, knowledge, tasks) flows through this interface.
+// Default implementation: InMemoryAdapter (zero dependencies).
+// Users provide their own adapters (Redis, SQLite, PostgreSQL) without changing
+// any other code.
+// ─────────────────────────────────────────────────────────────────────────────
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=storage.types.js.map

package/dist/contracts/storage.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.types.js","sourceRoot":"","sources":["../../src/contracts/storage.types.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,qCAAqC;AACrC,EAAE;AACF,iFAAiF;AACjF,+DAA+D;AAC/D,gFAAgF;AAChF,kBAAkB;AAClB,gFAAgF"}

package/dist/contracts/structural-decoder.types.d.ts

@@ -0,0 +1,251 @@
+export type SymbolKind = "class" | "interface" | "type" | "enum" | "function" | "method" | "property" | "variable" | "constant" | "namespace" | "module" | "decorator" | "struct" | "trait" | "protocol" | "table" | "column" | "index" | "relation" | "model" | "field" | "endpoint" | "message" | "service" | "route" | "container" | "volume" | "env_var" | "migration";
+export type VisibilityModifier = "public" | "private" | "protected" | "internal";
+/**
+ * A symbol extracted from source code by a structural decoder.
+ * Language-agnostic: same shape regardless of whether source is TS, Java, Python, etc.
+ */
+export interface ExtractedSymbol {
+    /** Symbol name. */
+    name: string;
+    /** What kind of code construct this is. */
+    kind: SymbolKind;
+    /** 1-based inclusive start line. */
+    startLine: number;
+    /** 1-based inclusive end line. */
+    endLine: number;
+    /** Visibility (if detectable). */
+    visibility?: VisibilityModifier;
+    /** Whether it's exported/public API. */
+    exported: boolean;
+    /** For classes/interfaces: member symbols (methods, properties). */
+    members?: ExtractedSymbol[];
+    /** For classes: parent class name. */
+    extends?: string;
+    /** For classes: implemented interfaces. */
+    implements?: string[];
+    /** For functions/methods: parameter names and types (if typed). */
+    parameters?: ParameterInfo[];
+    /** Return type (if typed). */
+    returnType?: string;
+    /** For properties/constants: type annotation. */
+    typeAnnotation?: string;
+    /** Decorators/annotations applied to this symbol. */
+    decorators?: string[];
+    /** Generic type parameters. */
+    typeParameters?: string[];
+    /** Whether this is abstract. */
+    isAbstract?: boolean;
+    /** Whether this is static. */
+    isStatic?: boolean;
+    /** Whether this is async. */
+    isAsync?: boolean;
+}
+export interface ParameterInfo {
+    name: string;
+    type?: string;
+    optional?: boolean;
+    defaultValue?: string;
+}
+export interface ImportInfo {
+    /** Module specifier / path. */
+    source: string;
+    /** Named imports (null for namespace/default). */
+    names: string[] | null;
+    /** Whether it's a default import. */
+    isDefault: boolean;
+    /** Whether it's a namespace import (import * as ...). */
+    isNamespace: boolean;
+    /** Whether it's a type-only import. */
+    isTypeOnly: boolean;
+    /** Line number of the import statement. */
+    line: number;
+}
+export interface ExportInfo {
+    /** Exported name (null for default exports). */
+    name: string | null;
+    /** What kind of thing is exported. */
+    kind: SymbolKind | "re-export" | "default" | "unknown";
+    /** Source file if re-export. */
+    source?: string;
+    /** Line number. */
+    line: number;
+    /** Type-only export. */
+    isTypeOnly: boolean;
+}
+/**
+ * Classifies a file by its architectural role, not its language.
+ * "code" is the default for traditional source files.
+ */
+export type ResourceKind = "code" | "schema" | "config" | "infra" | "api-spec" | "migration" | "test-fixture";
+/**
+ * Complete structural snapshot of a single file.
+ * Produced by a StructuralDecoder — language-agnostic output.
+ */
+export interface StructuralSnapshot {
+    /** Relative file path from project root. */
+    filePath: string;
+    /** Detected language. */
+    language: string;
+    /** Total lines in the file. */
+    totalLines: number;
+    /** All top-level symbols (classes, functions, interfaces, etc.). */
+    symbols: ExtractedSymbol[];
+    /** Import statements. */
+    imports: ImportInfo[];
+    /** Export statements / declarations. */
+    exports: ExportInfo[];
+    /** File-level decorators or annotations. */
+    fileDecorators?: string[];
+    /** SHA-256 hash of the content at decode time. */
+    contentHash: string;
+    /** Timestamp of decoding. */
+    decodedAt: string;
+    /** Which decoder produced this snapshot. */
+    decoderName: string;
+    /** Architectural role of this file (code, schema, config, infra, etc.). */
+    resourceKind?: ResourceKind;
+}
+/**
+ * Interface for language-specific structural decoders.
+ * Each decoder extracts symbols, imports, exports from source code
+ * using language-native tools (ts-morph, tree-sitter, etc.)
+ * rather than LLM inference.
+ */
+export interface StructuralDecoder {
+    /** Unique decoder name (e.g. "typescript", "tree-sitter-java"). */
+    readonly name: string;
+    /** File extensions this decoder handles (e.g. [".ts", ".tsx"]). */
+    readonly supportedExtensions: string[];
+    /** Languages this decoder handles (e.g. ["typescript", "tsx"]). */
+    readonly supportedLanguages: string[];
+    /**
+     * Can this decoder handle the given file?
+     * May check extension, shebang, content patterns.
+     */
+    canDecode(filePath: string, content?: string): boolean;
+    /**
+     * Extract structural information from a source file.
+     * Returns a language-agnostic StructuralSnapshot.
+     *
+     * @param filePath - Relative path from project root
+     * @param content - File content as string
+     * @param projectRoot - Absolute path to project root (for resolving references)
+     */
+    decode(filePath: string, content: string, projectRoot?: string): StructuralSnapshot;
+    /**
+     * Optional: Dispose of resources (e.g. ts-morph Project, tree-sitter Parser).
+     */
+    dispose?(): void;
+}
+/**
+ * Configuration for the decoder registry.
+ */
+export interface DecoderRegistryConfig {
+    /** Project root for resolving tsconfig etc. */
+    projectRoot: string;
+    /** Optional tsconfig path for TypeScript decoder. */
+    tsconfigPath?: string;
+    /** Whether to enable TypeScript decoder (default: auto-detect). */
+    enableTypeScript?: boolean;
+    /** Whether to enable tree-sitter fallback (default: true if available). */
+    enableTreeSitter?: boolean;
+}
+/** Identifies a pipeline stage. */
+export type PipelineStageId = "structural-decode" | "incremental-analyze" | "knowledge-graph-build" | "doc-generate" | "graph-render";
+/**
+ * A pipeline stage that reads from a store and writes to a store.
+ * Each stage can consume output of previous stages.
+ */
+export interface AnalysisPipelineStage<TInput = unknown, TOutput = unknown> {
+    /** Stage identifier. */
+    readonly id: PipelineStageId;
+    /** Human-readable name. */
+    readonly name: string;
+    /** What this stage requires as input (previous stage ID or null for first). */
+    readonly requires: PipelineStageId | null;
+    /**
+     * Run this stage.
+     * @param input - Output from the required previous stage (null for first stage)
+     * @param storeDir - Directory for persisting this stage's output
+     * @param config - Pipeline-level configuration
+     */
+    run(input: TInput | null, storeDir: string, config: PipelineConfig): Promise<TOutput>;
+    /**
+     * Load cached output from a previous run.
+     * Returns null if no valid cache exists.
+     */
+    loadCached(storeDir: string): TOutput | null;
+}
+/**
+ * Pipeline-level configuration shared by all stages.
+ */
+export interface PipelineConfig {
+    /** Absolute path to project root. */
+    projectRoot: string;
+    /** Project name. */
+    projectName: string;
+    /** Store base directory for all stages. */
+    storeBaseDir: string;
+    /** Ollama URL (if LLM stages needed). */
+    ollamaUrl?: string;
+    /** LLM model name. */
+    model?: string;
+    /** Context window size. */
+    numCtx?: number;
+    /** Maximum files to process. */
+    maxFiles?: number;
+    /** Abort signal. */
+    signal?: AbortSignal;
+    /** Progress callback (string message, backward compat). */
+    onProgress?: (stage: PipelineStageId, message: string) => void;
+    /** Structured progress callback — emitted alongside onProgress. */
+    onPhaseProgress?: (event: PipelineProgressEvent) => void;
+    /**
+     * When true: if structural decoder extracted symbols for a file,
+     * synthesize RangeAnalysisResult directly from the snapshot and skip
+     * the LLM analyzeRange callback for that file.
+     * Default: false.
+     */
+    structuralFastPath?: boolean;
+}
+/** Lifecycle status of a pipeline phase or run. */
+export type PipelinePhaseStatus = "pending" | "running" | "complete" | "failed" | "skipped";
+/** Per-stage tracking record inside a PipelineRun. */
+export interface PipelinePhase {
+    id: PipelineStageId;
+    name: string;
+    status: PipelinePhaseStatus;
+    /** Completion fraction 0–1. */
+    progress: number;
+    startedAt?: string;
+    completedAt?: string;
+    durationMs?: number;
+    /** Stage-specific summary (files, edges, LLM calls, etc.). */
+    details?: Record<string, unknown>;
+    /** Error message if status === "failed". */
+    error?: string;
+}
+/** A full pipeline execution record — persisted to central registry. */
+export interface PipelineRun {
+    uuid: string;
+    projectName: string;
+    projectRoot: string;
+    storeBaseDir: string;
+    model?: string;
+    createdAt: string;
+    updatedAt: string;
+    /** Rolled-up status across all phases. */
+    status: PipelinePhaseStatus;
+    phases: PipelinePhase[];
+}
+/** Structured progress event emitted by CodeAnalysisPipeline. */
+export interface PipelineProgressEvent {
+    runId?: string;
+    stage: PipelineStageId;
+    status: PipelinePhaseStatus;
+    /** Completion fraction 0–1. */
+    progress: number;
+    message: string;
+    details?: Record<string, unknown>;
+}
+//# sourceMappingURL=structural-decoder.types.d.ts.map

package/dist/contracts/structural-decoder.types.d.ts.map

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

package/dist/contracts/structural-decoder.types.js

@@ -0,0 +1,14 @@
+"use strict";
+// ─────────────────────────────────────────────────────────────────────────────
+// Structural Decoder Types — Language-agnostic code structure extraction
+//
+// Provides a unified interface for extracting symbols, imports, exports,
+// class hierarchies, and references from source code. Language-specific
+// decoders (TypeScript via ts-morph, others via tree-sitter) implement
+// the StructuralDecoder interface and produce a unified StructuralSnapshot.
+//
+// Used by IncrementalAnalyzer to avoid LLM calls for structural questions.
+// LLM is then focused only on semantic/business understanding.
+// ─────────────────────────────────────────────────────────────────────────────
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=structural-decoder.types.js.map

package/dist/contracts/structural-decoder.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"structural-decoder.types.js","sourceRoot":"","sources":["../../src/contracts/structural-decoder.types.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,yEAAyE;AACzE,EAAE;AACF,yEAAyE;AACzE,wEAAwE;AACxE,uEAAuE;AACvE,4EAA4E;AAC5E,EAAE;AACF,2EAA2E;AAC3E,+DAA+D;AAC/D,gFAAgF"}