@harness-engineering/graph 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,581 @@
+import { z } from 'zod';
+
+declare const NODE_TYPES: readonly ["repository", "module", "file", "class", "interface", "function", "method", "variable", "adr", "decision", "learning", "failure", "issue", "document", "skill", "conversation", "commit", "build", "test_result", "span", "metric", "log", "layer", "pattern", "constraint", "violation"];
+type NodeType = (typeof NODE_TYPES)[number];
+declare const EDGE_TYPES: readonly ["contains", "imports", "calls", "implements", "inherits", "references", "applies_to", "caused_by", "resolved_by", "documents", "violates", "specifies", "decided", "co_changes_with", "triggered_by", "failed_in", "executed_by", "measured_by"];
+type EdgeType = (typeof EDGE_TYPES)[number];
+declare const OBSERVABILITY_TYPES: ReadonlySet<NodeType>;
+interface SourceLocation {
+    readonly fileId: string;
+    readonly startLine: number;
+    readonly endLine: number;
+    readonly startColumn?: number;
+    readonly endColumn?: number;
+}
+interface GraphNode {
+    readonly id: string;
+    readonly type: NodeType;
+    readonly name: string;
+    readonly path?: string;
+    readonly location?: SourceLocation;
+    readonly content?: string;
+    readonly hash?: string;
+    readonly metadata: Record<string, unknown>;
+    readonly embedding?: readonly number[];
+    readonly lastModified?: string;
+}
+interface GraphEdge {
+    readonly from: string;
+    readonly to: string;
+    readonly type: EdgeType;
+    readonly confidence?: number;
+    readonly metadata?: Record<string, unknown>;
+}
+interface ContextQLParams {
+    readonly rootNodeIds: readonly string[];
+    readonly maxDepth?: number;
+    readonly includeTypes?: readonly NodeType[];
+    readonly excludeTypes?: readonly NodeType[];
+    readonly includeEdges?: readonly EdgeType[];
+    readonly bidirectional?: boolean;
+    readonly pruneObservability?: boolean;
+}
+interface ContextQLResult {
+    readonly nodes: readonly GraphNode[];
+    readonly edges: readonly GraphEdge[];
+    readonly stats: {
+        readonly totalTraversed: number;
+        readonly totalReturned: number;
+        readonly pruned: number;
+        readonly depthReached: number;
+    };
+}
+interface ProjectionSpec {
+    readonly fields: readonly (keyof GraphNode)[];
+}
+interface IngestResult {
+    readonly nodesAdded: number;
+    readonly nodesUpdated: number;
+    readonly edgesAdded: number;
+    readonly edgesUpdated: number;
+    readonly errors: readonly string[];
+    readonly durationMs: number;
+}
+interface GraphMetadata {
+    readonly schemaVersion: number;
+    readonly lastScanTimestamp: string;
+    readonly nodeCount: number;
+    readonly edgeCount: number;
+}
+declare const CURRENT_SCHEMA_VERSION = 1;
+declare const GraphNodeSchema: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodEnum<["repository", "module", "file", "class", "interface", "function", "method", "variable", "adr", "decision", "learning", "failure", "issue", "document", "skill", "conversation", "commit", "build", "test_result", "span", "metric", "log", "layer", "pattern", "constraint", "violation"]>;
+    name: z.ZodString;
+    path: z.ZodOptional<z.ZodString>;
+    location: z.ZodOptional<z.ZodObject<{
+        fileId: z.ZodString;
+        startLine: z.ZodNumber;
+        endLine: z.ZodNumber;
+        startColumn: z.ZodOptional<z.ZodNumber>;
+        endColumn: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        fileId: string;
+        startLine: number;
+        endLine: number;
+        startColumn?: number | undefined;
+        endColumn?: number | undefined;
+    }, {
+        fileId: string;
+        startLine: number;
+        endLine: number;
+        startColumn?: number | undefined;
+        endColumn?: number | undefined;
+    }>>;
+    content: z.ZodOptional<z.ZodString>;
+    hash: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    embedding: z.ZodOptional<z.ZodArray<z.ZodNumber, "many">>;
+    lastModified: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    type: "function" | "repository" | "module" | "file" | "class" | "interface" | "method" | "variable" | "adr" | "decision" | "learning" | "failure" | "issue" | "document" | "skill" | "conversation" | "commit" | "build" | "test_result" | "span" | "metric" | "log" | "layer" | "pattern" | "constraint" | "violation";
+    name: string;
+    metadata: Record<string, unknown>;
+    path?: string | undefined;
+    location?: {
+        fileId: string;
+        startLine: number;
+        endLine: number;
+        startColumn?: number | undefined;
+        endColumn?: number | undefined;
+    } | undefined;
+    content?: string | undefined;
+    hash?: string | undefined;
+    embedding?: number[] | undefined;
+    lastModified?: string | undefined;
+}, {
+    id: string;
+    type: "function" | "repository" | "module" | "file" | "class" | "interface" | "method" | "variable" | "adr" | "decision" | "learning" | "failure" | "issue" | "document" | "skill" | "conversation" | "commit" | "build" | "test_result" | "span" | "metric" | "log" | "layer" | "pattern" | "constraint" | "violation";
+    name: string;
+    metadata: Record<string, unknown>;
+    path?: string | undefined;
+    location?: {
+        fileId: string;
+        startLine: number;
+        endLine: number;
+        startColumn?: number | undefined;
+        endColumn?: number | undefined;
+    } | undefined;
+    content?: string | undefined;
+    hash?: string | undefined;
+    embedding?: number[] | undefined;
+    lastModified?: string | undefined;
+}>;
+declare const GraphEdgeSchema: z.ZodObject<{
+    from: z.ZodString;
+    to: z.ZodString;
+    type: z.ZodEnum<["contains", "imports", "calls", "implements", "inherits", "references", "applies_to", "caused_by", "resolved_by", "documents", "violates", "specifies", "decided", "co_changes_with", "triggered_by", "failed_in", "executed_by", "measured_by"]>;
+    confidence: z.ZodOptional<z.ZodNumber>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    type: "contains" | "imports" | "calls" | "implements" | "inherits" | "references" | "applies_to" | "caused_by" | "resolved_by" | "documents" | "violates" | "specifies" | "decided" | "co_changes_with" | "triggered_by" | "failed_in" | "executed_by" | "measured_by";
+    from: string;
+    to: string;
+    metadata?: Record<string, unknown> | undefined;
+    confidence?: number | undefined;
+}, {
+    type: "contains" | "imports" | "calls" | "implements" | "inherits" | "references" | "applies_to" | "caused_by" | "resolved_by" | "documents" | "violates" | "specifies" | "decided" | "co_changes_with" | "triggered_by" | "failed_in" | "executed_by" | "measured_by";
+    from: string;
+    to: string;
+    metadata?: Record<string, unknown> | undefined;
+    confidence?: number | undefined;
+}>;
+
+interface NodeQuery {
+    readonly type?: NodeType;
+    readonly name?: string;
+    readonly path?: string;
+}
+interface EdgeQuery {
+    readonly from?: string;
+    readonly to?: string;
+    readonly type?: EdgeType;
+}
+declare class GraphStore {
+    private readonly db;
+    private nodes;
+    private edges;
+    constructor();
+    addNode(node: GraphNode): void;
+    batchAddNodes(nodes: readonly GraphNode[]): void;
+    getNode(id: string): GraphNode | null;
+    findNodes(query: NodeQuery): GraphNode[];
+    removeNode(id: string): void;
+    addEdge(edge: GraphEdge): void;
+    batchAddEdges(edges: readonly GraphEdge[]): void;
+    getEdges(query: EdgeQuery): GraphEdge[];
+    getNeighbors(nodeId: string, direction?: 'outbound' | 'inbound' | 'both'): GraphNode[];
+    get nodeCount(): number;
+    get edgeCount(): number;
+    clear(): void;
+    save(dirPath: string): Promise<void>;
+    load(dirPath: string): Promise<boolean>;
+    private stripLokiMeta;
+}
+
+/**
+ * Result returned from a vector similarity search.
+ */
+interface VectorSearchResult {
+    id: string;
+    score: number;
+}
+/**
+ * A brute-force in-memory vector store that supports add, remove, and
+ * top-K cosine-similarity search.
+ */
+declare class VectorStore {
+    private readonly dimensions;
+    private readonly vectors;
+    constructor(dimensions: number);
+    /** Number of vectors currently stored. */
+    get size(): number;
+    /** Add a vector with the given id. Throws if dimensions do not match. */
+    add(id: string, vector: readonly number[]): void;
+    /** Remove a vector by id. Returns true if the vector existed. */
+    remove(id: string): boolean;
+    /** Check whether a vector with the given id exists. */
+    has(id: string): boolean;
+    /** Remove all stored vectors. */
+    clear(): void;
+    /**
+     * Return the top-K most similar vectors to the query, sorted by descending
+     * cosine similarity score.  If the store contains fewer than topK vectors,
+     * all available results are returned.
+     */
+    search(query: readonly number[], topK: number): VectorSearchResult[];
+    /** Serialize the store to a plain object for persistence. */
+    serialize(): {
+        dimensions: number;
+        vectors: Array<{
+            id: string;
+            vector: number[];
+        }>;
+    };
+    /** Deserialize a previously-serialized store. */
+    static deserialize(data: {
+        dimensions: number;
+        vectors: Array<{
+            id: string;
+            vector: number[];
+        }>;
+    }): VectorStore;
+}
+
+interface SerializedGraph {
+    readonly nodes: readonly GraphNode[];
+    readonly edges: readonly GraphEdge[];
+}
+declare function saveGraph(dirPath: string, nodes: readonly GraphNode[], edges: readonly GraphEdge[]): Promise<void>;
+declare function loadGraph(dirPath: string): Promise<SerializedGraph | null>;
+
+declare class ContextQL {
+    private readonly store;
+    constructor(store: GraphStore);
+    execute(params: ContextQLParams): ContextQLResult;
+}
+
+declare function project(nodes: readonly GraphNode[], spec: ProjectionSpec | undefined): Partial<GraphNode>[];
+
+/**
+ * Ingests TypeScript/JavaScript files into the graph via regex-based parsing.
+ * Future: upgrade to tree-sitter for full AST parsing.
+ */
+declare class CodeIngestor {
+    private readonly store;
+    constructor(store: GraphStore);
+    ingest(rootDir: string): Promise<IngestResult>;
+    private findSourceFiles;
+    private extractSymbols;
+    /**
+     * Find the closing brace for a construct starting at the given line.
+     * Uses a simple brace-counting heuristic. Returns 1-indexed line number.
+     */
+    private findClosingBrace;
+    /**
+     * Second pass: for each function/method, check if its file content calls any other
+     * known function/method. Creates approximate "calls" edges via regex matching.
+     */
+    private extractCallsEdges;
+    private escapeRegex;
+    private extractImports;
+    private resolveImportPath;
+    private detectLanguage;
+}
+
+type GitRunner = (rootDir: string, args: string[]) => Promise<string>;
+/**
+ * Ingests git history into the graph, creating commit nodes,
+ * triggered_by edges (file -> commit), and co_changes_with edges
+ * for files frequently modified together.
+ */
+declare class GitIngestor {
+    private readonly store;
+    private readonly gitRunner?;
+    constructor(store: GraphStore, gitRunner?: GitRunner | undefined);
+    ingest(rootDir: string): Promise<IngestResult>;
+    private runGit;
+    private parseGitLog;
+    private computeCoChanges;
+}
+
+interface LinkResult {
+    readonly edgesAdded: number;
+    readonly cycles: readonly string[][];
+}
+/**
+ * Post-ingestion linker that:
+ * 1. Groups files into module nodes based on directory structure
+ * 2. Detects circular dependencies in the import graph
+ */
+declare class TopologicalLinker {
+    private readonly store;
+    constructor(store: GraphStore);
+    link(): LinkResult;
+    private detectCycles;
+}
+
+declare class KnowledgeIngestor {
+    private readonly store;
+    constructor(store: GraphStore);
+    ingestADRs(adrDir: string): Promise<IngestResult>;
+    ingestLearnings(projectPath: string): Promise<IngestResult>;
+    ingestFailures(projectPath: string): Promise<IngestResult>;
+    ingestAll(projectPath: string, opts?: {
+        adrDir?: string;
+    }): Promise<IngestResult>;
+    private linkToCode;
+    private findMarkdownFiles;
+}
+
+type HttpClient = (url: string, options?: {
+    headers?: Record<string, string>;
+}) => Promise<{
+    ok: boolean;
+    status?: number;
+    json(): Promise<unknown>;
+}>;
+interface ConnectorConfig {
+    apiKeyEnv?: string;
+    baseUrlEnv?: string;
+    schedule?: string;
+    lookbackDays?: number;
+    filters?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+interface GraphConnector {
+    readonly name: string;
+    readonly source: string;
+    ingest(store: GraphStore, config: ConnectorConfig): Promise<IngestResult>;
+}
+interface SyncMetadata {
+    connectors: Record<string, {
+        lastSyncTimestamp: string;
+        lastResult: IngestResult;
+    }>;
+}
+
+declare function linkToCode(store: GraphStore, content: string, sourceNodeId: string, edgeType: EdgeType, options?: {
+    checkPaths?: boolean;
+}): number;
+
+declare class SyncManager {
+    private readonly store;
+    private readonly registrations;
+    private readonly metadataPath;
+    constructor(store: GraphStore, graphDir: string);
+    registerConnector(connector: GraphConnector, config: ConnectorConfig): void;
+    sync(connectorName: string): Promise<IngestResult>;
+    syncAll(): Promise<IngestResult>;
+    getMetadata(): Promise<SyncMetadata>;
+    private loadMetadata;
+    private saveMetadata;
+}
+
+declare class JiraConnector implements GraphConnector {
+    readonly name = "jira";
+    readonly source = "jira";
+    private readonly httpClient;
+    constructor(httpClient?: HttpClient);
+    ingest(store: GraphStore, config: ConnectorConfig): Promise<IngestResult>;
+}
+
+declare class SlackConnector implements GraphConnector {
+    readonly name = "slack";
+    readonly source = "slack";
+    private readonly httpClient;
+    constructor(httpClient?: HttpClient);
+    ingest(store: GraphStore, config: ConnectorConfig): Promise<IngestResult>;
+}
+
+declare class ConfluenceConnector implements GraphConnector {
+    readonly name = "confluence";
+    readonly source = "confluence";
+    private readonly httpClient;
+    constructor(httpClient?: HttpClient);
+    ingest(store: GraphStore, config: ConnectorConfig): Promise<IngestResult>;
+}
+
+declare class CIConnector implements GraphConnector {
+    readonly name = "ci";
+    readonly source = "github-actions";
+    private readonly httpClient;
+    constructor(httpClient?: HttpClient);
+    ingest(store: GraphStore, config: ConnectorConfig): Promise<IngestResult>;
+}
+
+interface FusionResult {
+    readonly nodeId: string;
+    readonly node: GraphNode;
+    readonly score: number;
+    readonly signals: {
+        readonly keyword: number;
+        readonly semantic: number;
+    };
+}
+declare class FusionLayer {
+    private readonly store;
+    private readonly vectorStore;
+    private readonly keywordWeight;
+    private readonly semanticWeight;
+    constructor(store: GraphStore, vectorStore?: VectorStore, keywordWeight?: number, semanticWeight?: number);
+    search(query: string, topK?: number, queryEmbedding?: readonly number[]): FusionResult[];
+    private extractKeywords;
+    private keywordScore;
+    private singleKeywordScore;
+}
+
+interface GraphDriftData {
+    readonly staleEdges: ReadonlyArray<{
+        docNodeId: string;
+        codeNodeId: string;
+        edgeType: string;
+        codeLastModified?: string | undefined;
+        docLastModified?: string | undefined;
+    }>;
+    readonly missingTargets: readonly string[];
+    readonly freshEdges: number;
+}
+interface GraphDeadCodeData {
+    readonly reachableNodeIds: ReadonlySet<string>;
+    readonly unreachableNodes: ReadonlyArray<{
+        id: string;
+        type: string;
+        name: string;
+        path?: string | undefined;
+    }>;
+    readonly entryPoints: readonly string[];
+}
+interface GraphSnapshotSummary {
+    readonly nodeCount: number;
+    readonly edgeCount: number;
+    readonly nodesByType: Record<string, number>;
+    readonly edgesByType: Record<string, number>;
+}
+declare class GraphEntropyAdapter {
+    private readonly store;
+    constructor(store: GraphStore);
+    /**
+     * Find all `documents` edges and classify them as stale or missing-target.
+     *
+     * 1. Find all `documents` edges in the graph
+     * 2. For each edge, check if the target code node still exists in the store
+     * 3. If target doesn't exist -> add to missingTargets
+     * 4. If target exists -> compare lastModified timestamps to determine staleness
+     */
+    computeDriftData(): GraphDriftData;
+    /**
+     * BFS from entry points to find reachable vs unreachable code nodes.
+     *
+     * 1. Entry points: file nodes named `index.ts` or with metadata `entryPoint: true`
+     * 2. BFS following `imports` and `calls` edges (outbound only)
+     * 3. Unreachable = code nodes NOT in visited set
+     */
+    computeDeadCodeData(): GraphDeadCodeData;
+    /**
+     * Count all nodes and edges by type.
+     */
+    computeSnapshotSummary(): GraphSnapshotSummary;
+}
+
+interface AssembledContext {
+    readonly nodes: readonly GraphNode[];
+    readonly edges: readonly GraphEdge[];
+    readonly tokenEstimate: number;
+    readonly intent: string;
+    readonly truncated: boolean;
+}
+interface GraphBudget {
+    readonly total: number;
+    readonly allocations: Record<string, number>;
+    readonly density: Record<string, number>;
+}
+interface GraphFilterResult {
+    readonly phase: string;
+    readonly nodes: readonly GraphNode[];
+    readonly filePaths: readonly string[];
+}
+interface GraphCoverageReport {
+    readonly documented: readonly string[];
+    readonly undocumented: readonly string[];
+    readonly coveragePercentage: number;
+    readonly totalCodeNodes: number;
+}
+declare class Assembler {
+    private readonly store;
+    private readonly vectorStore;
+    private fusionLayer;
+    constructor(store: GraphStore, vectorStore?: VectorStore);
+    private getFusionLayer;
+    /**
+     * Assemble context relevant to an intent string within a token budget.
+     */
+    assembleContext(intent: string, tokenBudget?: number): AssembledContext;
+    /**
+     * Compute a token budget allocation across node types.
+     */
+    computeBudget(totalTokens: number, phase?: string): GraphBudget;
+    /**
+     * Filter graph nodes relevant to a development phase.
+     */
+    filterForPhase(phase: string): GraphFilterResult;
+    /**
+     * Generate a markdown repository map from graph structure.
+     */
+    generateMap(): string;
+    /**
+     * Check documentation coverage of code nodes.
+     */
+    checkCoverage(): GraphCoverageReport;
+}
+
+interface GraphDependencyData {
+    readonly nodes: readonly string[];
+    readonly edges: ReadonlyArray<{
+        from: string;
+        to: string;
+        importType: 'static' | 'dynamic' | 'type-only';
+        line: number;
+    }>;
+}
+interface GraphLayerViolation {
+    file: string;
+    imports: string;
+    fromLayer: string;
+    toLayer: string;
+    reason: 'WRONG_LAYER';
+    line: number;
+}
+interface LayerDef {
+    name: string;
+    patterns: string[];
+    allowedDependencies: string[];
+}
+declare class GraphConstraintAdapter {
+    private readonly store;
+    constructor(store: GraphStore);
+    computeDependencyGraph(): GraphDependencyData;
+    computeLayerViolations(layers: LayerDef[], rootDir: string): GraphLayerViolation[];
+    private resolveLayer;
+}
+
+interface GraphImpactData {
+    readonly affectedTests: ReadonlyArray<{
+        testFile: string;
+        coversFile: string;
+    }>;
+    readonly affectedDocs: ReadonlyArray<{
+        docFile: string;
+        documentsFile: string;
+    }>;
+    readonly impactScope: number;
+}
+interface GraphHarnessCheckData {
+    readonly graphExists: boolean;
+    readonly nodeCount: number;
+    readonly edgeCount: number;
+    readonly constraintViolations: number;
+    readonly undocumentedFiles: number;
+    readonly unreachableNodes: number;
+}
+declare class GraphFeedbackAdapter {
+    private readonly store;
+    constructor(store: GraphStore);
+    computeImpactData(changedFiles: string[]): GraphImpactData;
+    computeHarnessCheckData(): GraphHarnessCheckData;
+}
+
+declare const VERSION = "0.1.0";
+
+export { type AssembledContext, Assembler, CIConnector, CURRENT_SCHEMA_VERSION, CodeIngestor, ConfluenceConnector, type ConnectorConfig, ContextQL, type ContextQLParams, type ContextQLResult, EDGE_TYPES, type EdgeQuery, type EdgeType, FusionLayer, type FusionResult, GitIngestor, type GitRunner, type GraphBudget, type GraphConnector, GraphConstraintAdapter, type GraphCoverageReport, type GraphDeadCodeData, type GraphDependencyData, type GraphDriftData, type GraphEdge, GraphEdgeSchema, GraphEntropyAdapter, GraphFeedbackAdapter, type GraphFilterResult, type GraphHarnessCheckData, type GraphImpactData, type GraphLayerViolation, type GraphMetadata, type GraphNode, GraphNodeSchema, type GraphSnapshotSummary, GraphStore, type HttpClient, type IngestResult, JiraConnector, KnowledgeIngestor, type LinkResult, NODE_TYPES, type NodeQuery, type NodeType, OBSERVABILITY_TYPES, type ProjectionSpec, SlackConnector, type SourceLocation, SyncManager, type SyncMetadata, TopologicalLinker, VERSION, type VectorSearchResult, VectorStore, linkToCode, loadGraph, project, saveGraph };