@vizalice/codegraph 1.5.0

package/dist/types.d.ts

@@ -0,0 +1,465 @@
+/**
+ * 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).
+ *
+ * The ARRAY ORDER is part of the native kernel's wire contract (kinds cross
+ * the boundary as indexes — see src/extraction/kernel/layout.ts); append new
+ * kinds, never reorder.
+ */
+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", "union"];
+export type NodeKind = (typeof NODE_KINDS)[number];
+/**
+ * Types of edges (relationships) between nodes.
+ *
+ * Runtime-iterable like NODE_KINDS. The ARRAY ORDER is part of the native
+ * kernel's wire contract (kinds cross the boundary as indexes — see
+ * src/extraction/kernel/layout.ts); append new kinds, never reorder.
+ */
+export declare const EDGE_KINDS: readonly ["contains", "calls", "imports", "exports", "extends", "implements", "references", "type_of", "returns", "instantiates", "overrides", "decorates"];
+export type EdgeKind = (typeof EDGE_KINDS)[number];
+/**
+ * Supported programming languages. See NODE_KINDS for why this is a
+ * runtime-iterable const array.
+ */
+export declare const LANGUAGES: readonly ["typescript", "javascript", "tsx", "jsx", "arkts", "python", "go", "rust", "java", "c", "cpp", "csharp", "razor", "php", "ruby", "swift", "kotlin", "dart", "svelte", "vue", "astro", "liquid", "pascal", "scala", "lua", "luau", "objc", "r", "solidity", "nix", "yaml", "twig", "xml", "properties", "cfml", "cfscript", "cfquery", "cobol", "vbnet", "erlang", "terraform", "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;
+}
+/**
+ * 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' | '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[];
+    /**
+     * Tool-generated source, decided at index time from the filename
+     * convention OR a generation banner in the file's header (see
+     * extraction/generated-detection.ts). A relevance hint for ranking, not a
+     * hard filter. Absent on indexes built before schema v9 — treat
+     * `undefined` as "content signal unknown, fall back to the path check".
+     */
+    generated?: boolean;
+}
+/**
+ * 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;
+    /**
+     * Deferred-decode transport (native kernel, bulk-index path): when present,
+     * `nodes`/`edges`/`unresolvedReferences` are EMPTY and the file's tables
+     * ride as flat buffers to be decoded at the store boundary (the store
+     * worker), so the MAIN thread never materializes per-node objects.
+     * `kernelCounts` carries the table sizes for bookkeeping. Decode into a
+     * plain result with `materializeKernelResult` (src/extraction/kernel).
+     */
+    kernelBuffers?: {
+        meta: Uint8Array;
+        nodes: Uint8Array;
+        edges: Uint8Array;
+        refs: Uint8Array;
+        arena: Uint8Array;
+    };
+    kernelCounts?: {
+        nodes: number;
+        edges: number;
+        refs: 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[];
+    /**
+     * `unresolved_refs.id` when this ref was loaded from the database. Post-pass
+     * cleanup (delete-on-resolve / park-as-failed) targets exactly this row.
+     * Without it, cleanup falls back to deleting by (fromNodeId, referenceName,
+     * referenceKind) — which also removes SIBLING rows (same caller calling the
+     * same callee at other lines) that a later batch hasn't attempted yet, so
+     * their edges were silently never created when a batch boundary split the
+     * call sites (#1269).
+     */
+    rowId?: number;
+}
+/**
+ * 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 for relative ranking only — higher is more relevant.
+     * NOT normalized and NOT a 0-1 fraction: the FTS path returns an unbounded
+     * BM25 magnitude (often in the tens or hundreds), while the fuzzy/exact
+     * paths return ~0-1. Use it to order results, not as an absolute percentage.
+     */
+    score: number;
+    /** Matched text snippets for highlighting */
+    highlights?: string[];
+}
+/**
+ * A symbol whose name-segments match prose words from a prompt — the
+ * graph-derived signal behind the front-load hook's medium tier
+ * (CodeGraph.getSegmentMatches). Always verified to exist in `nodes` at the
+ * time it is returned.
+ */
+export interface SegmentMatch {
+    /** Symbol name as indexed (e.g. `OrderStateMachine`). */
+    name: string;
+    /** Kind of the representative definition. */
+    kind: NodeKind;
+    /** File of the representative definition. */
+    filePath: string;
+    /** 1-based start line of the representative definition. */
+    startLine: number;
+    /** The prompt words (normalized) that matched this name's segments. */
+    matchedWords: 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;
+    /** Size of the SQLite `-wal` sidecar in bytes (0 when absent). A WAL far
+     * larger than the DB at rest means killed sessions left it behind (#1431). */
+    walSizeBytes: 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/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,117 @@
+"use strict";
+/**
+ * CodeGraph Type Definitions
+ *
+ * Core types for the semantic knowledge graph system.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LANGUAGES = exports.EDGE_KINDS = exports.NODE_KINDS = void 0;
+// =============================================================================
+// Union Types
+// =============================================================================
+/**
+ * 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).
+ *
+ * The ARRAY ORDER is part of the native kernel's wire contract (kinds cross
+ * the boundary as indexes — see src/extraction/kernel/layout.ts); append new
+ * kinds, never reorder.
+ */
+exports.NODE_KINDS = [
+    'file',
+    'module',
+    'class',
+    'struct',
+    'interface',
+    'trait',
+    'protocol',
+    'function',
+    'method',
+    'property',
+    'field',
+    'variable',
+    'constant',
+    'enum',
+    'enum_member',
+    'type_alias',
+    'namespace',
+    'parameter',
+    'import',
+    'export',
+    'route',
+    'component',
+    'union',
+];
+/**
+ * Types of edges (relationships) between nodes.
+ *
+ * Runtime-iterable like NODE_KINDS. The ARRAY ORDER is part of the native
+ * kernel's wire contract (kinds cross the boundary as indexes — see
+ * src/extraction/kernel/layout.ts); append new kinds, never reorder.
+ */
+exports.EDGE_KINDS = [
+    'contains', // Parent contains child (file→class, class→method)
+    'calls', // Function/method calls another
+    'imports', // File imports from another
+    'exports', // File exports a symbol
+    'extends', // Class/interface extends another
+    'implements', // Class implements interface
+    'references', // Generic reference to another symbol
+    'type_of', // Variable/parameter has type
+    'returns', // Function returns type
+    'instantiates', // Creates instance of class
+    'overrides', // Method overrides parent method
+    'decorates', // Decorator applied to symbol
+];
+/**
+ * Supported programming languages. See NODE_KINDS for why this is a
+ * runtime-iterable const array.
+ */
+exports.LANGUAGES = [
+    'typescript',
+    'javascript',
+    'tsx',
+    'jsx',
+    'arkts',
+    'python',
+    'go',
+    'rust',
+    'java',
+    'c',
+    'cpp',
+    'csharp',
+    'razor',
+    'php',
+    'ruby',
+    'swift',
+    'kotlin',
+    'dart',
+    'svelte',
+    'vue',
+    'astro',
+    'liquid',
+    'pascal',
+    'scala',
+    'lua',
+    'luau',
+    'objc',
+    'r',
+    'solidity',
+    'nix',
+    'yaml',
+    'twig',
+    'xml',
+    'properties',
+    'cfml',
+    'cfscript',
+    'cfquery',
+    'cobol',
+    'vbnet',
+    'erlang',
+    'terraform',
+    'unknown',
+];
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;AAEH,gFAAgF;AAChF,cAAc;AACd,gFAAgF;AAEhF;;;;;;;;;;GAUG;AACU,QAAA,UAAU,GAAG;IACxB,MAAM;IACN,QAAQ;IACR,OAAO;IACP,QAAQ;IACR,WAAW;IACX,OAAO;IACP,UAAU;IACV,UAAU;IACV,QAAQ;IACR,UAAU;IACV,OAAO;IACP,UAAU;IACV,UAAU;IACV,MAAM;IACN,aAAa;IACb,YAAY;IACZ,WAAW;IACX,WAAW;IACX,QAAQ;IACR,QAAQ;IACR,OAAO;IACP,WAAW;IACX,OAAO;CACC,CAAC;AAIX;;;;;;GAMG;AACU,QAAA,UAAU,GAAG;IACxB,UAAU,EAAS,mDAAmD;IACtE,OAAO,EAAY,gCAAgC;IACnD,SAAS,EAAU,4BAA4B;IAC/C,SAAS,EAAU,wBAAwB;IAC3C,SAAS,EAAU,kCAAkC;IACrD,YAAY,EAAO,6BAA6B;IAChD,YAAY,EAAO,sCAAsC;IACzD,SAAS,EAAU,8BAA8B;IACjD,SAAS,EAAU,wBAAwB;IAC3C,cAAc,EAAK,4BAA4B;IAC/C,WAAW,EAAQ,iCAAiC;IACpD,WAAW,EAAQ,8BAA8B;CACzC,CAAC;AAIX;;;GAGG;AACU,QAAA,SAAS,GAAG;IACvB,YAAY;IACZ,YAAY;IACZ,KAAK;IACL,KAAK;IACL,OAAO;IACP,QAAQ;IACR,IAAI;IACJ,MAAM;IACN,MAAM;IACN,GAAG;IACH,KAAK;IACL,QAAQ;IACR,OAAO;IACP,KAAK;IACL,MAAM;IACN,OAAO;IACP,QAAQ;IACR,MAAM;IACN,QAAQ;IACR,KAAK;IACL,OAAO;IACP,QAAQ;IACR,QAAQ;IACR,OAAO;IACP,KAAK;IACL,MAAM;IACN,MAAM;IACN,GAAG;IACH,UAAU;IACV,KAAK;IACL,MAAM;IACN,MAAM;IACN,KAAK;IACL,YAAY;IACZ,MAAM;IACN,UAAU;IACV,SAAS;IACT,OAAO;IACP,OAAO;IACP,QAAQ;IACR,WAAW;IACX,SAAS;CACD,CAAC"}

package/dist/ui/color.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Terminal color detection for CLI output (issue #1281).
+ *
+ * One switch decides whether any codegraph-authored output carries ANSI
+ * color codes. Precedence, strongest first:
+ *
+ *   1. `--no-color` anywhere on the command line   -> off
+ *   2. `--color` anywhere on the command line      -> on
+ *   3. `NO_COLOR` set and non-empty (no-color.org) -> off
+ *   4. `FORCE_COLOR` set and non-empty             -> on ('0'/'false' -> off)
+ *   5. stdout is a TTY and TERM != 'dumb'          -> on
+ *   6. `CI` set and non-empty                      -> on (CI log viewers render ANSI)
+ *   7. otherwise (piped/redirected stdout)         -> off
+ *
+ * This intentionally tracks the detection @clack/prompts inherits from
+ * picocolors closely enough that one run never mixes colored clack frames
+ * with uncolored codegraph lines (or vice versa) for the common cases:
+ * both honor NO_COLOR, --no-color/--color, FORCE_COLOR, TTY, and CI.
+ */
+export declare function ansiColorsEnabled(): boolean;
+//# sourceMappingURL=color.d.ts.map

package/dist/ui/color.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"color.d.ts","sourceRoot":"","sources":["../../src/ui/color.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,iBAAiB,IAAI,OAAO,CAkB3C"}

package/dist/ui/color.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ansiColorsEnabled = ansiColorsEnabled;
+/**
+ * Terminal color detection for CLI output (issue #1281).
+ *
+ * One switch decides whether any codegraph-authored output carries ANSI
+ * color codes. Precedence, strongest first:
+ *
+ *   1. `--no-color` anywhere on the command line   -> off
+ *   2. `--color` anywhere on the command line      -> on
+ *   3. `NO_COLOR` set and non-empty (no-color.org) -> off
+ *   4. `FORCE_COLOR` set and non-empty             -> on ('0'/'false' -> off)
+ *   5. stdout is a TTY and TERM != 'dumb'          -> on
+ *   6. `CI` set and non-empty                      -> on (CI log viewers render ANSI)
+ *   7. otherwise (piped/redirected stdout)         -> off
+ *
+ * This intentionally tracks the detection @clack/prompts inherits from
+ * picocolors closely enough that one run never mixes colored clack frames
+ * with uncolored codegraph lines (or vice versa) for the common cases:
+ * both honor NO_COLOR, --no-color/--color, FORCE_COLOR, TTY, and CI.
+ */
+function ansiColorsEnabled() {
+    if (process.argv.includes('--no-color'))
+        return false;
+    if (process.argv.includes('--color'))
+        return true;
+    const noColor = process.env.NO_COLOR;
+    if (noColor !== undefined && noColor !== '')
+        return false;
+    const forceColor = process.env.FORCE_COLOR;
+    if (forceColor !== undefined && forceColor !== '') {
+        return forceColor !== '0' && forceColor.toLowerCase() !== 'false';
+    }
+    if (process.stdout.isTTY === true && process.env.TERM !== 'dumb')
+        return true;
+    const ci = process.env.CI;
+    if (ci !== undefined && ci !== '')
+        return true;
+    return false;
+}
+//# sourceMappingURL=color.js.map

package/dist/ui/color.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"color.js","sourceRoot":"","sources":["../../src/ui/color.ts"],"names":[],"mappings":";;AAmBA,8CAkBC;AArCD;;;;;;;;;;;;;;;;;;GAkBG;AACH,SAAgB,iBAAiB;IAC/B,IAAI,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC;QAAE,OAAO,KAAK,CAAC;IACtD,IAAI,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC;QAAE,OAAO,IAAI,CAAC;IAElD,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC;IACrC,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,KAAK,EAAE;QAAE,OAAO,KAAK,CAAC;IAE1D,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC;IAC3C,IAAI,UAAU,KAAK,SAAS,IAAI,UAAU,KAAK,EAAE,EAAE,CAAC;QAClD,OAAO,UAAU,KAAK,GAAG,IAAI,UAAU,CAAC,WAAW,EAAE,KAAK,OAAO,CAAC;IACpE,CAAC;IAED,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK,KAAK,IAAI,IAAI,OAAO,CAAC,GAAG,CAAC,IAAI,KAAK,MAAM;QAAE,OAAO,IAAI,CAAC;IAE9E,MAAM,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;IAC1B,IAAI,EAAE,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IAE/C,OAAO,KAAK,CAAC;AACf,CAAC"}