@aroman22/codegraph-vba 1.3.3

package/dist/types.d.ts

@@ -0,0 +1,409 @@
+/**
+ * CodeGraph Type Definitions
+ *
+ * Core types for the semantic knowledge graph system.
+ */
+/**
+ * Types of nodes in the knowledge graph.
+ *
+ * Defined as a runtime-iterable `as const` array so the same source
+ * of truth backs both the TS type and any runtime validation
+ * (e.g. the search query parser).
+ */
+export declare const NODE_KINDS: readonly ["file", "module", "class", "struct", "interface", "trait", "protocol", "function", "method", "property", "field", "variable", "constant", "enum", "enum_member", "type_alias", "namespace", "parameter", "import", "export", "route", "component", "query", "form-layout", "form-instance-control"];
+export type NodeKind = (typeof NODE_KINDS)[number];
+/**
+ * Types of edges (relationships) between nodes
+ */
+export type EdgeKind = 'contains' | 'calls' | 'imports' | 'exports' | 'extends' | 'implements' | 'references' | 'type_of' | 'returns' | 'instantiates' | 'overrides' | 'decorates' | 'event-handler' | 'opens-form';
+/**
+ * Supported programming languages. See NODE_KINDS for why this is a
+ * runtime-iterable const array.
+ */
+export declare const LANGUAGES: readonly ["typescript", "javascript", "tsx", "jsx", "python", "go", "rust", "java", "c", "cpp", "csharp", "razor", "php", "ruby", "swift", "kotlin", "dart", "svelte", "vue", "astro", "liquid", "pascal", "scala", "lua", "luau", "objc", "r", "vba", "sql", "yaml", "twig", "xml", "properties", "unknown"];
+export type Language = (typeof LANGUAGES)[number];
+/**
+ * A node in the knowledge graph representing a code symbol
+ */
+export interface Node {
+    /** Unique identifier (hash of file path + qualified name) */
+    id: string;
+    /** Type of code element */
+    kind: NodeKind;
+    /** Simple name (e.g., "calculateTotal") */
+    name: string;
+    /** Fully qualified name (e.g., "src/utils.ts::MathHelper.calculateTotal") */
+    qualifiedName: string;
+    /** File path relative to project root */
+    filePath: string;
+    /** Programming language */
+    language: Language;
+    /** Starting line number (1-indexed) */
+    startLine: number;
+    /** Ending line number (1-indexed) */
+    endLine: number;
+    /** Starting column (0-indexed) */
+    startColumn: number;
+    /** Ending column (0-indexed) */
+    endColumn: number;
+    /** Documentation string if present */
+    docstring?: string;
+    /** Function/method signature */
+    signature?: string;
+    /** Visibility modifier */
+    visibility?: 'public' | 'private' | 'protected' | 'internal';
+    /** Whether symbol is exported */
+    isExported?: boolean;
+    /** Whether symbol is async */
+    isAsync?: boolean;
+    /** Whether symbol is static */
+    isStatic?: boolean;
+    /** Whether symbol is abstract */
+    isAbstract?: boolean;
+    /** Decorators/annotations applied */
+    decorators?: string[];
+    /** Generic type parameters */
+    typeParameters?: string[];
+    /**
+     * Normalized return/result type name for a function/method (the bare class
+     * name, smart-pointer pointee unwrapped). Captured for C/C++ so resolution
+     * can infer a chained receiver's type from what the inner call returns —
+     * `Foo::instance().bar()` resolves `bar` on `Foo` (issue #645). Undefined for
+     * languages/symbols where it isn't captured.
+     */
+    returnType?: string;
+    /** When the node was last updated */
+    updatedAt: number;
+    /**
+     * Optional metadata bag for language-/extractor-specific annotations.
+     * Used by VBA to carry `hasClassInitializer` / `initializerName` on class
+     * nodes and `controlType` on form property nodes; reserved by other
+     * extractors for similar per-language extras. Mirrors the
+     * `Edge.metadata` shape (`Record<string, unknown>`).
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * An edge representing a relationship between two nodes
+ */
+export interface Edge {
+    /** Source node ID */
+    source: string;
+    /** Target node ID */
+    target: string;
+    /** Type of relationship */
+    kind: EdgeKind;
+    /** Additional context about the relationship */
+    metadata?: Record<string, unknown>;
+    /** Line number where relationship occurs (e.g., call site) */
+    line?: number;
+    /** Column number where relationship occurs */
+    column?: number;
+    /** How this edge was created */
+    provenance?: 'tree-sitter' | 'scip' | 'parser' | 'heuristic';
+}
+/**
+ * Metadata about a tracked file
+ */
+export interface FileRecord {
+    /** File path relative to project root */
+    path: string;
+    /** Content hash for change detection */
+    contentHash: string;
+    /** Detected language */
+    language: Language;
+    /** File size in bytes */
+    size: number;
+    /** Last modification timestamp */
+    modifiedAt: number;
+    /** When last indexed */
+    indexedAt: number;
+    /** Number of nodes extracted */
+    nodeCount: number;
+    /** Any extraction errors */
+    errors?: ExtractionError[];
+}
+/**
+ * Result from parsing a source file
+ */
+export interface ExtractionResult {
+    /** Extracted nodes */
+    nodes: Node[];
+    /** Extracted edges */
+    edges: Edge[];
+    /** References that couldn't be resolved yet */
+    unresolvedReferences: UnresolvedReference[];
+    /** Any errors during extraction */
+    errors: ExtractionError[];
+    /** Extraction duration in milliseconds */
+    durationMs: number;
+}
+/**
+ * Error during code extraction
+ */
+export interface ExtractionError {
+    /** Error message */
+    message: string;
+    /** File path where the error occurred */
+    filePath?: string;
+    /** Line number if available */
+    line?: number;
+    /** Column number if available */
+    column?: number;
+    /** Error severity */
+    severity: 'error' | 'warning';
+    /** Error code for categorization */
+    code?: string;
+}
+/**
+ * Kinds an unresolved reference can carry. `function_ref` is internal-only —
+ * a function name used as a VALUE (callback registration, #756). It never
+ * becomes an edge kind: resolution maps it to a `references` edge targeting
+ * function/method nodes only (see `matchFunctionRef`).
+ */
+export type ReferenceKind = EdgeKind | 'function_ref';
+/**
+ * A reference that couldn't be resolved during extraction
+ */
+export interface UnresolvedReference {
+    /** ID of the node containing the reference */
+    fromNodeId: string;
+    /** Name being referenced */
+    referenceName: string;
+    /** Type of reference (call, type, import, etc.) */
+    referenceKind: ReferenceKind;
+    /** Location of the reference */
+    line: number;
+    column: number;
+    /** File path where reference occurs (denormalized for performance) */
+    filePath?: string;
+    /** Language of the source file (denormalized for performance) */
+    language?: Language;
+    /** Possible qualified names it might resolve to */
+    candidates?: string[];
+    /**
+     * Optional metadata bag for language-/extractor-specific annotations on
+     * unresolved references. Used by VBA to carry
+     * `synthesizedBy: 'vba-form-binding'` on the form → sibling-`.cls`
+     * reference so downstream resolvers can render the provenance inline.
+     * Mirrors `Edge.metadata` and `Node.metadata` shapes
+     * (`Record<string, unknown>`).
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * A subgraph containing a subset of the knowledge graph
+ */
+export interface Subgraph {
+    /** Nodes in this subgraph */
+    nodes: Map<string, Node>;
+    /** Edges in this subgraph */
+    edges: Edge[];
+    /** Root node IDs (entry points) */
+    roots: string[];
+    /**
+     * Retrieval confidence for context-style queries. `'low'` means the query
+     * resolved only to isolated common-word matches (no entry point corroborated
+     * by 2+ distinct query terms) — callers should surface an honest handoff to
+     * explore/trace rather than present the results as comprehensive. Undefined
+     * for graph traversals that don't run the search-ranking path.
+     */
+    confidence?: 'high' | 'low';
+}
+/**
+ * Options for graph traversal
+ */
+export interface TraversalOptions {
+    /** Maximum depth to traverse (default: Infinity) */
+    maxDepth?: number;
+    /** Edge types to follow (default: all) */
+    edgeKinds?: EdgeKind[];
+    /** Node types to include (default: all) */
+    nodeKinds?: NodeKind[];
+    /** Direction of traversal */
+    direction?: 'outgoing' | 'incoming' | 'both';
+    /** Maximum nodes to return */
+    limit?: number;
+    /** Whether to include the starting node */
+    includeStart?: boolean;
+}
+/**
+ * Options for searching the graph
+ */
+export interface SearchOptions {
+    /** Node types to search */
+    kinds?: NodeKind[];
+    /** Languages to include */
+    languages?: Language[];
+    /** File path patterns to include */
+    includePatterns?: string[];
+    /** File path patterns to exclude */
+    excludePatterns?: string[];
+    /** Maximum results to return */
+    limit?: number;
+    /** Offset for pagination */
+    offset?: number;
+    /** Whether search is case-sensitive */
+    caseSensitive?: boolean;
+}
+/**
+ * A search result with relevance scoring
+ */
+export interface SearchResult {
+    /** Matching node */
+    node: Node;
+    /** Relevance score (0-1) */
+    score: number;
+    /** Matched text snippets for highlighting */
+    highlights?: string[];
+}
+/**
+ * Context information for code understanding
+ */
+export interface Context {
+    /** Primary node being examined */
+    focal: Node;
+    /** Nodes containing the focal node (file, class, etc.) */
+    ancestors: Node[];
+    /** Nodes directly contained by focal node */
+    children: Node[];
+    /** Incoming references (who calls/uses this) */
+    incomingRefs: Array<{
+        node: Node;
+        edge: Edge;
+    }>;
+    /** Outgoing references (what this calls/uses) */
+    outgoingRefs: Array<{
+        node: Node;
+        edge: Edge;
+    }>;
+    /** Related type information */
+    types: Node[];
+    /** Relevant imports */
+    imports: Node[];
+}
+/**
+ * A block of code with context
+ */
+export interface CodeBlock {
+    /** The code content */
+    content: string;
+    /** File path */
+    filePath: string;
+    /** Starting line */
+    startLine: number;
+    /** Ending line */
+    endLine: number;
+    /** Language for syntax highlighting */
+    language: Language;
+    /** Associated node if extracted */
+    node?: Node;
+}
+/**
+ * Database schema version info
+ */
+export interface SchemaVersion {
+    /** Current schema version */
+    version: number;
+    /** When schema was created/updated */
+    appliedAt: number;
+    /** Description of this version */
+    description?: string;
+}
+/**
+ * Statistics about the knowledge graph
+ */
+export interface GraphStats {
+    /** Total number of nodes */
+    nodeCount: number;
+    /** Total number of edges */
+    edgeCount: number;
+    /** Number of tracked files */
+    fileCount: number;
+    /** Node counts by kind */
+    nodesByKind: Record<NodeKind, number>;
+    /** Edge counts by kind */
+    edgesByKind: Record<EdgeKind, number>;
+    /** File counts by language */
+    filesByLanguage: Record<Language, number>;
+    /** Database size in bytes */
+    dbSizeBytes: number;
+    /** Last update timestamp */
+    lastUpdated: number;
+}
+/**
+ * Input for building task context
+ */
+export type TaskInput = string | {
+    title: string;
+    description?: string;
+};
+/**
+ * Options for building task context
+ */
+export interface BuildContextOptions {
+    /** Maximum number of nodes to include (default: 50) */
+    maxNodes?: number;
+    /** Maximum number of code blocks to include (default: 10) */
+    maxCodeBlocks?: number;
+    /** Maximum characters per code block (default: 2000) */
+    maxCodeBlockSize?: number;
+    /** Whether to include code blocks (default: true) */
+    includeCode?: boolean;
+    /** Output format (default: 'markdown') */
+    format?: 'markdown' | 'json';
+    /** Number of semantic search results (default: 5) */
+    searchLimit?: number;
+    /** Graph traversal depth from entry points (default: 2) */
+    traversalDepth?: number;
+    /** Minimum semantic similarity score (default: 0.3) */
+    minScore?: number;
+}
+/**
+ * Full context for a task, ready for Claude
+ */
+export interface TaskContext {
+    /** The original query/task */
+    query: string;
+    /** Subgraph of relevant nodes and edges */
+    subgraph: Subgraph;
+    /** Entry point nodes (from semantic search) */
+    entryPoints: Node[];
+    /** Code blocks extracted from key nodes */
+    codeBlocks: CodeBlock[];
+    /** Files involved in this context */
+    relatedFiles: string[];
+    /** Brief summary of the context */
+    summary: string;
+    /** Statistics about the context */
+    stats: {
+        /** Number of nodes included */
+        nodeCount: number;
+        /** Number of edges included */
+        edgeCount: number;
+        /** Number of files touched */
+        fileCount: number;
+        /** Number of code blocks included */
+        codeBlockCount: number;
+        /** Total characters in code blocks */
+        totalCodeSize: number;
+    };
+}
+/**
+ * Options for finding relevant context
+ */
+export interface FindRelevantContextOptions {
+    /** Number of semantic search results (default: 5) */
+    searchLimit?: number;
+    /** Graph traversal depth (default: 2) */
+    traversalDepth?: number;
+    /** Maximum nodes in result (default: 50) */
+    maxNodes?: number;
+    /** Minimum semantic similarity score (default: 0.3) */
+    minScore?: number;
+    /** Edge types to follow in traversal */
+    edgeKinds?: EdgeKind[];
+    /** Node types to include */
+    nodeKinds?: NodeKind[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/ui/glyphs.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Glyph selection for CLI output.
+ *
+ * On Windows, console output is interpreted via the active output
+ * codepage. PowerShell 5.1 and cmd.exe default to OEM codepages
+ * (CP437, CP936, ...), so UTF-8 bytes written to the console render
+ * as mojibake (see #168). The shimmer worker is hit hardest because
+ * it uses `fs.writeSync(1, ...)` (raw bytes, no TTY-aware encoding
+ * conversion) to keep animation smooth while the main thread is
+ * blocked in SQLite. To stay readable everywhere, we fall back to
+ * ASCII glyphs whenever the terminal is not known to handle UTF-8.
+ *
+ * Detection is intentionally simple:
+ *   - `CODEGRAPH_ASCII=1`  -> ASCII (escape hatch for any terminal)
+ *   - `CODEGRAPH_UNICODE=1` -> Unicode (opt-in on Windows)
+ *   - Windows              -> ASCII by default
+ *   - Linux kernel console (`TERM=linux`) -> ASCII
+ *   - Everything else      -> Unicode
+ */
+export declare function supportsUnicode(): boolean;
+export interface Glyphs {
+    ok: string;
+    err: string;
+    info: string;
+    warn: string;
+    spinner: string[];
+    barFilled: string;
+    barEmpty: string;
+    rail: string;
+    phaseDone: string;
+    dash: string;
+    hLine: string;
+    treeBranch: string;
+    treeLast: string;
+    treePipe: string;
+}
+export declare const UNICODE_GLYPHS: Glyphs;
+export declare const ASCII_GLYPHS: Glyphs;
+export declare function getGlyphs(): Glyphs;
+/** Reset the cached glyph set. Test-only; production code should call `getGlyphs()`. */
+export declare function _resetGlyphsCache(): void;
+//# sourceMappingURL=glyphs.d.ts.map

package/dist/ui/shimmer-progress.d.ts

@@ -0,0 +1,11 @@
+export interface IndexProgress {
+    phase: string;
+    current: number;
+    total: number;
+}
+export interface ShimmerProgress {
+    onProgress: (progress: IndexProgress) => void;
+    stop: () => Promise<void>;
+}
+export declare function createShimmerProgress(): ShimmerProgress;
+//# sourceMappingURL=shimmer-progress.d.ts.map

package/dist/ui/shimmer-worker.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=shimmer-worker.d.ts.map

package/dist/ui/types.d.ts

@@ -0,0 +1,17 @@
+/** Messages from main thread to worker */
+export type ShimmerWorkerMessage = {
+    type: 'update';
+    phase: string;
+    phaseName: string;
+    percent: number;
+    count: number;
+} | {
+    type: 'finish-phase';
+} | {
+    type: 'stop';
+};
+/** Messages from worker to main thread */
+export type ShimmerMainMessage = {
+    type: 'stopped';
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/upgrade/index.d.ts

@@ -0,0 +1,132 @@
+/**
+ * `codegraph upgrade`
+ *
+ * Self-update for the CLI, whatever way it was installed:
+ *
+ *   - **bundle** — the self-contained runtime+app installed by `install.sh`
+ *     (Linux/macOS) or `install.ps1` (Windows). Upgrading re-runs the SAME
+ *     canonical installer script (single source of truth) so the download /
+ *     version-resolution / PATH logic never drifts between first-install and
+ *     upgrade.
+ *   - **npm** — installed via `npm i -g @colbymchenry/codegraph`. Upgrading
+ *     shells out to npm.
+ *   - **npx** — ephemeral; nothing to upgrade (next `npx` fetches latest).
+ *   - **source** — a git checkout running its own `dist/`; `git pull` + rebuild.
+ *
+ * Detection is structural (see `detectInstallMethod`): a bundle carries a
+ * vendored `node` binary and a `bin/codegraph` launcher next to its `lib/`, so
+ * we can recognize it from the running file's path without a marker file.
+ *
+ * Windows wrinkle: a running `node.exe` is locked and can't be deleted, so the
+ * bundle's `current\` dir can't be overwritten in place by the process doing
+ * the upgrade. We therefore spawn a DETACHED helper that waits for this
+ * process to exit (releasing the lock), then runs `install.ps1`. This is the
+ * conventional Windows self-update dance (rustup/nvm-windows do the same).
+ */
+export declare const REPO = "ardelperal/codegraph";
+export declare const NPM_PACKAGE = "codegraph-vba";
+export declare const INSTALL_SH_URL = "https://raw.githubusercontent.com/ardelperal/codegraph/main/install.sh";
+export type InstallMethod = {
+    kind: 'bundle';
+    os: 'unix' | 'windows';
+    bundleRoot: string;
+    installDir: string | null;
+} | {
+    kind: 'npm';
+    scope: 'global' | 'local';
+} | {
+    kind: 'npx';
+} | {
+    kind: 'source';
+    root: string;
+} | {
+    kind: 'unknown';
+    reason: string;
+};
+export interface DetectInput {
+    /** `__filename` of the running CLI module — `<…>/dist/bin/codegraph.js`. */
+    filename: string;
+    platform: NodeJS.Platform;
+    cwd: string;
+    /** Injectable existence probe (defaults to fs.existsSync) — for tests. */
+    exists?: (p: string) => boolean;
+}
+/**
+ * Where the bundle installer keeps its install root, derived from the bundle
+ * dir so an upgrade reuses a custom `CODEGRAPH_INSTALL_DIR`. Returns null when
+ * the layout isn't the one the installer creates (then the installer falls
+ * back to its own default).
+ *
+ *   unix:    <installDir>/versions/<vX.Y.Z>   (bundleRoot)  → <installDir>
+ *   windows: <installDir>\current             (bundleRoot)  → <installDir>
+ */
+export declare function deriveInstallDir(bundleRoot: string, os: 'unix' | 'windows', exists: (p: string) => boolean): string | null;
+export declare function detectInstallMethod(input: DetectInput): InstallMethod;
+export interface Semver {
+    major: number;
+    minor: number;
+    patch: number;
+    pre: string | null;
+}
+export declare function parseSemver(version: string): Semver | null;
+/** Returns >0 if a>b, <0 if a<b, 0 if equal. Throws on unparseable input. */
+export declare function compareVersions(a: string, b: string): number;
+export declare function isUpdateAvailable(current: string, latest: string): boolean;
+/** `0.9.9` / `v0.9.9` → `v0.9.9` (release tags are v-prefixed). */
+export declare function normalizeVersion(v: string): string;
+/** Strip a leading `v`: `v0.9.9` → `0.9.9`. */
+export declare function stripV(v: string): string;
+/**
+ * Parse the release tag out of the `Location` header GitHub returns for
+ * `/releases/latest` → `…/releases/tag/v0.9.9`. Pure so it's unit-tested.
+ */
+export declare function parseLatestTagFromLocation(location: string | undefined): string | null;
+/**
+ * Resolve the latest release tag (e.g. `v0.9.9`).
+ *
+ * Primary: read the redirect `Location` from `github.com/<repo>/releases/latest`
+ * — same trick install.sh uses, because the unauthenticated GitHub API is
+ * rate-limited to 60 req/h/IP and 403s on shared/cloud hosts (issue #325). The
+ * redirect has no such limit. Fall back to the API only if the redirect can't
+ * be read.
+ */
+export declare function resolveLatestVersion(repo?: string, timeoutMs?: number): Promise<string>;
+export interface UpgradeOptions {
+    /** Pin a specific version (positional arg or CODEGRAPH_VERSION). */
+    version?: string;
+    /** Report current vs latest, don't change anything. */
+    check?: boolean;
+    /** Reinstall even if already on the resolved version. */
+    force?: boolean;
+}
+/** Injectable side-effects so the orchestrator stays unit-testable. */
+export interface UpgradeDeps {
+    currentVersion: string;
+    method: InstallMethod;
+    resolveLatest: (pin?: string) => Promise<string>;
+    /** Run a command inheriting stdio; returns its exit code (-1 = spawn failed). */
+    run: (cmd: string, args: string[], env?: NodeJS.ProcessEnv) => number;
+    hasCommand: (cmd: string) => boolean;
+    log: (msg: string) => void;
+    warn: (msg: string) => void;
+    error: (msg: string) => void;
+    platform: NodeJS.Platform;
+}
+/** The honest, additive re-index reminder shown after a successful upgrade. */
+export declare function reindexAdvisory(): string;
+/**
+ * Returns the process exit code (0 = success / nothing to do, 1 = failure).
+ */
+export declare function runUpgrade(opts: UpgradeOptions, deps: UpgradeDeps): Promise<number>;
+/** Build the in-place Windows upgrade script (exported for unit-testing). */
+export declare function buildWindowsUpgradeScript(bundleRoot: string, version: string, arch: string): string;
+/**
+ * True if `cmd` resolves to an executable on PATH. A pure-Node PATH scan — NOT
+ * a spawned `command -v`/`which`: `command` is a shell builtin (no standalone
+ * binary on Debian, though macOS ships one), and `which` isn't guaranteed
+ * present on minimal images, so spawning either is unreliable. Scanning PATH
+ * ourselves behaves identically on every platform.
+ */
+export declare function hasCommand(cmd: string): boolean;
+export declare function defaultRun(cmd: string, args: string[], env?: NodeJS.ProcessEnv): number;
+//# sourceMappingURL=index.d.ts.map