npm - @harness-engineering/graph - Versions diffs - 0.4.0 → 0.4.1 - Mend

@harness-engineering/graph 0.4.0 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/README.md CHANGED Viewed

@@ -73,27 +73,29 @@ const results = fusion.search('authentication handler', { topK: 10 });
 ## Key Classes
-| Class                     | Description                                                                     |
-| ------------------------- | ------------------------------------------------------------------------------- |
-| `GraphStore`              | In-memory graph backed by LokiJS with indexed node/edge collections             |
-| `VectorStore`             | Optional vector index for semantic similarity search (hnswlib)                  |
-| `ContextQL`               | BFS-based graph traversal engine with type filtering and observability pruning  |
-| `project`                 | Projection utility to select specific fields from query results                 |
-| `CodeIngestor`            | Parses TypeScript/JavaScript files into file, class, function, and method nodes |
-| `GitIngestor`             | Extracts commit history and co-change relationships from git                    |
-| `KnowledgeIngestor`       | Ingests ADRs, learnings, and markdown knowledge artifacts                       |
-| `TopologicalLinker`       | Creates structural edges (imports, calls, references) between code nodes        |
-| `FusionLayer`             | Hybrid search combining keyword matching and semantic similarity scores         |
-| `Assembler`               | Phase-aware context assembly with token budgets and coverage reports            |
-| `SyncManager`             | Orchestrates connector syncs with incremental update tracking                   |
-| `GraphEntropyAdapter`     | Detects graph drift and dead code for entropy monitoring                        |
-| `GraphConstraintAdapter`  | Validates dependency rules and layer boundary violations                        |
-| `GraphFeedbackAdapter`    | Computes impact analysis and harness check data from graph state                |
-| `saveGraph` / `loadGraph` | Serializes and deserializes the graph store to/from disk                        |
+| Class                          | Description                                                                          |
+| ------------------------------ | ------------------------------------------------------------------------------------ |
+| `GraphStore`                   | In-memory graph backed by LokiJS with indexed node/edge collections                  |
+| `VectorStore`                  | Optional vector index for semantic similarity search (hnswlib)                       |
+| `ContextQL`                    | BFS-based graph traversal engine with type filtering and observability pruning       |
+| `project`                      | Projection utility to select specific fields from query results                      |
+| `CodeIngestor`                 | Parses TypeScript/JavaScript files into file, class, function, and method nodes      |
+| `GitIngestor`                  | Extracts commit history and co-change relationships from git                         |
+| `KnowledgeIngestor`            | Ingests ADRs, learnings, and markdown knowledge artifacts                            |
+| `TopologicalLinker`            | Creates structural edges (imports, calls, references) between code nodes             |
+| `FusionLayer`                  | Hybrid search combining keyword matching and semantic similarity scores              |
+| `Assembler`                    | Phase-aware context assembly with token budgets and coverage reports                 |
+| `SyncManager`                  | Orchestrates connector syncs with incremental update tracking                        |
+| `GraphEntropyAdapter`          | Detects graph drift and dead code for entropy monitoring                             |
+| `GraphConstraintAdapter`       | Validates dependency rules and layer boundary violations                             |
+| `GraphFeedbackAdapter`         | Computes impact analysis and harness check data from graph state                     |
+| `CascadeSimulator`             | Probability-weighted BFS for cascading failure simulation (`compute_blast_radius`)   |
+| `CompositeProbabilityStrategy` | Default edge probability strategy blending edge type, change frequency, and coupling |
+| `saveGraph` / `loadGraph`      | Serializes and deserializes the graph store to/from disk                             |
 ## Node Types
-24 node types organized by category:
+28 node types organized by category:
 | Category          | Types                                                                                  |
 | ----------------- | -------------------------------------------------------------------------------------- |
@@ -102,19 +104,23 @@ const results = fusion.search('authentication handler', { topK: 10 });
 | **VCS**           | `commit`, `build`, `test_result`                                                       |
 | **Observability** | `span`, `metric`, `log`                                                                |
 | **Structural**    | `layer`, `pattern`, `constraint`, `violation`                                          |
+| **Design**        | `design_token`, `aesthetic_intent`, `design_constraint`                                |
+| **Traceability**  | `requirement`                                                                          |
 Observability types (`span`, `metric`, `log`) are pruned by default in ContextQL queries to reduce noise.
 ## Edge Types
-17 edge types organized by category:
+24 edge types organized by category:
-| Category      | Types                                                                                     |
-| ------------- | ----------------------------------------------------------------------------------------- |
-| **Code**      | `contains`, `imports`, `calls`, `implements`, `inherits`, `references`                    |
-| **Knowledge** | `applies_to`, `caused_by`, `resolved_by`, `documents`, `violates`, `specifies`, `decided` |
-| **VCS**       | `co_changes_with`, `triggered_by`, `failed_in`                                            |
-| **Execution** | `executed_by`, `measured_by`                                                              |
+| Category         | Types                                                                                     |
+| ---------------- | ----------------------------------------------------------------------------------------- |
+| **Code**         | `contains`, `imports`, `calls`, `implements`, `inherits`, `references`                    |
+| **Knowledge**    | `applies_to`, `caused_by`, `resolved_by`, `documents`, `violates`, `specifies`, `decided` |
+| **VCS**          | `co_changes_with`, `triggered_by`, `failed_in`                                            |
+| **Execution**    | `executed_by`, `measured_by`                                                              |
+| **Design**       | `uses_token`, `declares_intent`, `violates_design`, `platform_binding`                    |
+| **Traceability** | `requires`, `verified_by`, `tested_by`                                                    |
 Edges carry an optional `confidence` score (0-1) used by the FusionLayer for ranking.

package/dist/index.d.mts CHANGED Viewed

@@ -176,6 +176,8 @@ declare class GraphStore {
     addEdge(edge: GraphEdge): void;
     batchAddEdges(edges: readonly GraphEdge[]): void;
     getEdges(query: EdgeQuery): GraphEdge[];
+    /** Pick the most selective index to start from. */
+    private selectCandidates;
     getNeighbors(nodeId: string, direction?: 'outbound' | 'inbound' | 'both'): GraphNode[];
     get nodeCount(): number;
     get edgeCount(): number;
@@ -252,6 +254,9 @@ declare class ContextQL {
 declare function project(nodes: readonly GraphNode[], spec: ProjectionSpec | undefined): Partial<GraphNode>[];
+type NodeCategory = 'tests' | 'docs' | 'code' | 'other';
+/** Classify a graph node into an impact category. */
+declare function classifyNodeCategory(node: GraphNode): NodeCategory;
 interface ImpactGroups {
     readonly tests: readonly GraphNode[];
     readonly docs: readonly GraphNode[];
@@ -1030,6 +1035,91 @@ declare class ConflictPredictor {
     private generateVerdict;
 }
-declare const VERSION = "0.2.0";
+interface ProbabilityStrategy {
+    /** Compute failure propagation probability for a single edge (0..1). */
+    getEdgeProbability(edge: GraphEdge, fromNode: GraphNode, toNode: GraphNode): number;
+}
+interface CascadeSimulationOptions {
+    /** Minimum cumulative probability to continue traversal. Default: 0.05 */
+    readonly probabilityFloor?: number;
+    /** Maximum BFS depth. Default: 10 */
+    readonly maxDepth?: number;
+    /** Filter to specific edge types. Default: all edge types. */
+    readonly edgeTypes?: readonly string[];
+    /** Pluggable probability strategy. Default: CompositeProbabilityStrategy. */
+    readonly strategy?: ProbabilityStrategy;
+}
+interface CascadeNode {
+    readonly nodeId: string;
+    readonly name: string;
+    readonly path?: string;
+    readonly type: string;
+    readonly cumulativeProbability: number;
+    readonly depth: number;
+    readonly incomingEdge: string;
+    readonly parentId: string;
+}
+interface CascadeLayer {
+    readonly depth: number;
+    readonly nodes: readonly CascadeNode[];
+    readonly categoryBreakdown: {
+        readonly code: number;
+        readonly tests: number;
+        readonly docs: number;
+        readonly other: number;
+    };
+}
+interface CascadeResult {
+    readonly sourceNodeId: string;
+    readonly sourceName: string;
+    readonly layers: readonly CascadeLayer[];
+    readonly flatSummary: readonly CascadeNode[];
+    readonly summary: {
+        readonly totalAffected: number;
+        readonly maxDepthReached: number;
+        readonly highRisk: number;
+        readonly mediumRisk: number;
+        readonly lowRisk: number;
+        readonly categoryBreakdown: {
+            readonly code: number;
+            readonly tests: number;
+            readonly docs: number;
+            readonly other: number;
+        };
+        readonly amplificationPoints: readonly string[];
+        readonly truncated: boolean;
+    };
+}
+/**
+ * Default probability strategy blending three signals:
+ * - 50% edge type base weight
+ * - 30% normalized change frequency of target node
+ * - 20% normalized coupling strength of target node
+ */
+declare class CompositeProbabilityStrategy implements ProbabilityStrategy {
+    private readonly changeFreqMap;
+    private readonly couplingMap;
+    static readonly BASE_WEIGHTS: Record<string, number>;
+    private static readonly FALLBACK_WEIGHT;
+    private static readonly EDGE_TYPE_BLEND;
+    private static readonly CHANGE_FREQ_BLEND;
+    private static readonly COUPLING_BLEND;
+    constructor(changeFreqMap: Map<string, number>, couplingMap: Map<string, number>);
+    getEdgeProbability(edge: GraphEdge, _fromNode: GraphNode, toNode: GraphNode): number;
+}
+declare class CascadeSimulator {
+    private readonly store;
+    constructor(store: GraphStore);
+    simulate(sourceNodeId: string, options?: CascadeSimulationOptions): CascadeResult;
+    private seedQueue;
+    private runBfs;
+    private expandNode;
+    private buildDefaultStrategy;
+    private buildResult;
+}
+declare const VERSION = "0.4.0";
-export { type AnomalyDetectionOptions, type AnomalyReport, type ArticulationPoint, type AskGraphResult, type AssembledContext, Assembler, CIConnector, CURRENT_SCHEMA_VERSION, type ClassificationResult, CodeIngestor, type ConflictDetail, type ConflictPrediction, ConflictPredictor, type ConflictSeverity, ConfluenceConnector, type ConnectorConfig, ContextQL, type ContextQLParams, type ContextQLResult, DesignConstraintAdapter, DesignIngestor, type DesignStrictness, type DesignViolation, EDGE_TYPES, type EdgeQuery, type EdgeType, EntityExtractor, EntityResolver, FusionLayer, type FusionResult, GitIngestor, type GitRunner, GraphAnomalyAdapter, type GraphBudget, GraphComplexityAdapter, type GraphComplexityHotspot, type GraphComplexityResult, type GraphConnector, GraphConstraintAdapter, GraphCouplingAdapter, type GraphCouplingFileData, type GraphCouplingResult, 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, INTENTS, type ImpactGroups, type IndependenceCheckParams, type IndependenceResult, type IngestResult, type Intent, IntentClassifier, JiraConnector, KnowledgeIngestor, type LinkResult, NODE_TYPES, type NodeQuery, type NodeType, OBSERVABILITY_TYPES, type OverlapDetail, type PairResult, type ProjectionSpec, type RequirementCoverage, RequirementIngestor, type ResolvedEntity, ResponseFormatter, SlackConnector, type SourceLocation, type StatisticalOutlier, SyncManager, type SyncMetadata, type TaskDefinition, TaskIndependenceAnalyzer, TopologicalLinker, type TraceabilityOptions, type TraceabilityResult, type TracedFile, VERSION, type VectorSearchResult, VectorStore, askGraph, groupNodesByImpact, linkToCode, loadGraph, project, queryTraceability, saveGraph };
+export { type AnomalyDetectionOptions, type AnomalyReport, type ArticulationPoint, type AskGraphResult, type AssembledContext, Assembler, CIConnector, CURRENT_SCHEMA_VERSION, type CascadeLayer, type CascadeNode, type CascadeResult, type CascadeSimulationOptions, CascadeSimulator, type ClassificationResult, CodeIngestor, CompositeProbabilityStrategy, type ConflictDetail, type ConflictPrediction, ConflictPredictor, type ConflictSeverity, ConfluenceConnector, type ConnectorConfig, ContextQL, type ContextQLParams, type ContextQLResult, DesignConstraintAdapter, DesignIngestor, type DesignStrictness, type DesignViolation, EDGE_TYPES, type EdgeQuery, type EdgeType, EntityExtractor, EntityResolver, FusionLayer, type FusionResult, GitIngestor, type GitRunner, GraphAnomalyAdapter, type GraphBudget, GraphComplexityAdapter, type GraphComplexityHotspot, type GraphComplexityResult, type GraphConnector, GraphConstraintAdapter, GraphCouplingAdapter, type GraphCouplingFileData, type GraphCouplingResult, 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, INTENTS, type ImpactGroups, type IndependenceCheckParams, type IndependenceResult, type IngestResult, type Intent, IntentClassifier, JiraConnector, KnowledgeIngestor, type LinkResult, NODE_TYPES, type NodeCategory, type NodeQuery, type NodeType, OBSERVABILITY_TYPES, type OverlapDetail, type PairResult, type ProbabilityStrategy, type ProjectionSpec, type RequirementCoverage, RequirementIngestor, type ResolvedEntity, ResponseFormatter, SlackConnector, type SourceLocation, type StatisticalOutlier, SyncManager, type SyncMetadata, type TaskDefinition, TaskIndependenceAnalyzer, TopologicalLinker, type TraceabilityOptions, type TraceabilityResult, type TracedFile, VERSION, type VectorSearchResult, VectorStore, askGraph, classifyNodeCategory, groupNodesByImpact, linkToCode, loadGraph, project, queryTraceability, saveGraph };

package/dist/index.d.ts CHANGED Viewed

@@ -176,6 +176,8 @@ declare class GraphStore {
     addEdge(edge: GraphEdge): void;
     batchAddEdges(edges: readonly GraphEdge[]): void;
     getEdges(query: EdgeQuery): GraphEdge[];
+    /** Pick the most selective index to start from. */
+    private selectCandidates;
     getNeighbors(nodeId: string, direction?: 'outbound' | 'inbound' | 'both'): GraphNode[];
     get nodeCount(): number;
     get edgeCount(): number;
@@ -252,6 +254,9 @@ declare class ContextQL {
 declare function project(nodes: readonly GraphNode[], spec: ProjectionSpec | undefined): Partial<GraphNode>[];
+type NodeCategory = 'tests' | 'docs' | 'code' | 'other';
+/** Classify a graph node into an impact category. */
+declare function classifyNodeCategory(node: GraphNode): NodeCategory;
 interface ImpactGroups {
     readonly tests: readonly GraphNode[];
     readonly docs: readonly GraphNode[];
@@ -1030,6 +1035,91 @@ declare class ConflictPredictor {
     private generateVerdict;
 }
-declare const VERSION = "0.2.0";
+interface ProbabilityStrategy {
+    /** Compute failure propagation probability for a single edge (0..1). */
+    getEdgeProbability(edge: GraphEdge, fromNode: GraphNode, toNode: GraphNode): number;
+}
+interface CascadeSimulationOptions {
+    /** Minimum cumulative probability to continue traversal. Default: 0.05 */
+    readonly probabilityFloor?: number;
+    /** Maximum BFS depth. Default: 10 */
+    readonly maxDepth?: number;
+    /** Filter to specific edge types. Default: all edge types. */
+    readonly edgeTypes?: readonly string[];
+    /** Pluggable probability strategy. Default: CompositeProbabilityStrategy. */
+    readonly strategy?: ProbabilityStrategy;
+}
+interface CascadeNode {
+    readonly nodeId: string;
+    readonly name: string;
+    readonly path?: string;
+    readonly type: string;
+    readonly cumulativeProbability: number;
+    readonly depth: number;
+    readonly incomingEdge: string;
+    readonly parentId: string;
+}
+interface CascadeLayer {
+    readonly depth: number;
+    readonly nodes: readonly CascadeNode[];
+    readonly categoryBreakdown: {
+        readonly code: number;
+        readonly tests: number;
+        readonly docs: number;
+        readonly other: number;
+    };
+}
+interface CascadeResult {
+    readonly sourceNodeId: string;
+    readonly sourceName: string;
+    readonly layers: readonly CascadeLayer[];
+    readonly flatSummary: readonly CascadeNode[];
+    readonly summary: {
+        readonly totalAffected: number;
+        readonly maxDepthReached: number;
+        readonly highRisk: number;
+        readonly mediumRisk: number;
+        readonly lowRisk: number;
+        readonly categoryBreakdown: {
+            readonly code: number;
+            readonly tests: number;
+            readonly docs: number;
+            readonly other: number;
+        };
+        readonly amplificationPoints: readonly string[];
+        readonly truncated: boolean;
+    };
+}
+/**
+ * Default probability strategy blending three signals:
+ * - 50% edge type base weight
+ * - 30% normalized change frequency of target node
+ * - 20% normalized coupling strength of target node
+ */
+declare class CompositeProbabilityStrategy implements ProbabilityStrategy {
+    private readonly changeFreqMap;
+    private readonly couplingMap;
+    static readonly BASE_WEIGHTS: Record<string, number>;
+    private static readonly FALLBACK_WEIGHT;
+    private static readonly EDGE_TYPE_BLEND;
+    private static readonly CHANGE_FREQ_BLEND;
+    private static readonly COUPLING_BLEND;
+    constructor(changeFreqMap: Map<string, number>, couplingMap: Map<string, number>);
+    getEdgeProbability(edge: GraphEdge, _fromNode: GraphNode, toNode: GraphNode): number;
+}
+declare class CascadeSimulator {
+    private readonly store;
+    constructor(store: GraphStore);
+    simulate(sourceNodeId: string, options?: CascadeSimulationOptions): CascadeResult;
+    private seedQueue;
+    private runBfs;
+    private expandNode;
+    private buildDefaultStrategy;
+    private buildResult;
+}
+declare const VERSION = "0.4.0";
-export { type AnomalyDetectionOptions, type AnomalyReport, type ArticulationPoint, type AskGraphResult, type AssembledContext, Assembler, CIConnector, CURRENT_SCHEMA_VERSION, type ClassificationResult, CodeIngestor, type ConflictDetail, type ConflictPrediction, ConflictPredictor, type ConflictSeverity, ConfluenceConnector, type ConnectorConfig, ContextQL, type ContextQLParams, type ContextQLResult, DesignConstraintAdapter, DesignIngestor, type DesignStrictness, type DesignViolation, EDGE_TYPES, type EdgeQuery, type EdgeType, EntityExtractor, EntityResolver, FusionLayer, type FusionResult, GitIngestor, type GitRunner, GraphAnomalyAdapter, type GraphBudget, GraphComplexityAdapter, type GraphComplexityHotspot, type GraphComplexityResult, type GraphConnector, GraphConstraintAdapter, GraphCouplingAdapter, type GraphCouplingFileData, type GraphCouplingResult, 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, INTENTS, type ImpactGroups, type IndependenceCheckParams, type IndependenceResult, type IngestResult, type Intent, IntentClassifier, JiraConnector, KnowledgeIngestor, type LinkResult, NODE_TYPES, type NodeQuery, type NodeType, OBSERVABILITY_TYPES, type OverlapDetail, type PairResult, type ProjectionSpec, type RequirementCoverage, RequirementIngestor, type ResolvedEntity, ResponseFormatter, SlackConnector, type SourceLocation, type StatisticalOutlier, SyncManager, type SyncMetadata, type TaskDefinition, TaskIndependenceAnalyzer, TopologicalLinker, type TraceabilityOptions, type TraceabilityResult, type TracedFile, VERSION, type VectorSearchResult, VectorStore, askGraph, groupNodesByImpact, linkToCode, loadGraph, project, queryTraceability, saveGraph };
+export { type AnomalyDetectionOptions, type AnomalyReport, type ArticulationPoint, type AskGraphResult, type AssembledContext, Assembler, CIConnector, CURRENT_SCHEMA_VERSION, type CascadeLayer, type CascadeNode, type CascadeResult, type CascadeSimulationOptions, CascadeSimulator, type ClassificationResult, CodeIngestor, CompositeProbabilityStrategy, type ConflictDetail, type ConflictPrediction, ConflictPredictor, type ConflictSeverity, ConfluenceConnector, type ConnectorConfig, ContextQL, type ContextQLParams, type ContextQLResult, DesignConstraintAdapter, DesignIngestor, type DesignStrictness, type DesignViolation, EDGE_TYPES, type EdgeQuery, type EdgeType, EntityExtractor, EntityResolver, FusionLayer, type FusionResult, GitIngestor, type GitRunner, GraphAnomalyAdapter, type GraphBudget, GraphComplexityAdapter, type GraphComplexityHotspot, type GraphComplexityResult, type GraphConnector, GraphConstraintAdapter, GraphCouplingAdapter, type GraphCouplingFileData, type GraphCouplingResult, 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, INTENTS, type ImpactGroups, type IndependenceCheckParams, type IndependenceResult, type IngestResult, type Intent, IntentClassifier, JiraConnector, KnowledgeIngestor, type LinkResult, NODE_TYPES, type NodeCategory, type NodeQuery, type NodeType, OBSERVABILITY_TYPES, type OverlapDetail, type PairResult, type ProbabilityStrategy, type ProjectionSpec, type RequirementCoverage, RequirementIngestor, type ResolvedEntity, ResponseFormatter, SlackConnector, type SourceLocation, type StatisticalOutlier, SyncManager, type SyncMetadata, type TaskDefinition, TaskIndependenceAnalyzer, TopologicalLinker, type TraceabilityOptions, type TraceabilityResult, type TracedFile, VERSION, type VectorSearchResult, VectorStore, askGraph, classifyNodeCategory, groupNodesByImpact, linkToCode, loadGraph, project, queryTraceability, saveGraph };