@yesprasad/fluent-graph 0.1.0 → 0.2.1

package/LICENSE

@@ -22,7 +22,7 @@ Built with focus on making ServiceNow Pro Developer Fluent development with now-
 
 ## Acknowledgments
 
-ServiceNow SDK team for building the Fluent DSL compiler
+ServiceNow SDK team for building the now-sdk and Fluent DSL compiler
 MIT License
 
 Copyright (c) 2024 ServiceNow Inc.

package/README.md

@@ -1,319 +1,131 @@
 # fluent-graph
 
-**Build-time lineage extraction and impact analysis for ServiceNow Fluent SDK projects.**
-
-`fluent-graph` observes the ServiceNow SDK's internal compilation process to extract dependency graphs, detect identity conflicts, and perform blast-radius analysis—without modifying your source code or re-parsing Fluent DSL.
+**Dependency visibility and impact analysis for ServiceNow Fluent SDK projects.**
 
 ---
 
-## What It Does
+## The Problem
+
+You're refactoring a ServiceNow custom table. You delete a field. You deploy.
+
+**Production breaks.**
 
-- **Extracts artifact lineage** from SDK projects (tables, columns, scripts, business rules)
-- **Detects identity conflicts** (duplicate `$id` declarations across files)
-- **Maps relationships** (foreign keys, table extensions, logic attachments)
-- **Generates blast-radius reports** (what breaks if you change X?)
-- **Outputs machine-readable JSON** for CI/CD integration
+14 client scripts fail. 3 business rules error out. 2 dashboards go blank.
+
+**You discover the breaking changes at runtime in production.**
 
 ---
-## Installation
 
-**Prerequisites:**
-- Node.js 18+
-- An existing ServiceNow Fluent SDK project with `@servicenow/sdk` installed
+## The Solution
+
+`fluent-graph` maps every dependency in your Fluent SDK project — tables, fields, scripts, business rules, flows, catalog items — so you know what breaks *before* you deploy.
 
-**Install globally:**
 ```bash
-npm install -g @yesprasad/fluent-graph
+npx @yesprasad/fluent-graph blast incident
 ```
-**basic CLI usage:**
-```bash
-fluent-graph analyze
-fluent-graph blast <table_name or artifact_name>
+
+```
+🔥 BLAST RADIUS ANALYSIS
+Target: incident
+
+⚠️  3 artifacts will break if you modify this table:
+  • bank_incident_onload          (Client Script)
+  • cs_incident_onload            (Client Script)
+  • cs_incident_onchange_caller   (Client Script)
 ```
 
-**Or use directly with npx (no installation needed):**
+**Now you know before you deploy.**
+
+---
+
+## Installation
+
+Requires Node.js 18+ and an existing Fluent SDK project with `@servicenow/sdk` installed.
+
+**Global install:**
 ```bash
-cd your-fluent-project
-npx fluent-graph extract
+npm install -g @yesprasad/fluent-graph
 ```
 
-**Verify installation:**
+**Or use without installing:**
 ```bash
-fluent-graph --version
+npx @yesprasad/fluent-graph analyze
 ```
+
 ---
 
-## Usage
+## Commands
 
+### Analyze — full project lineage map
 
-**Output:**
+```bash
+fluent-graph analyze
 ```
-✔ ✅ SDK detected at /node_modules/@servicenow/sdk
-✔ Workspace SDK loaded
-✔ Project loaded
-✔ Graph built: 181 nodes, 141 edges
 
-📊 LINEAGE MAP
-────────────────────────────────────────────────────────────
-
-📦 DATA SCHEMA
-┌─────────────────────────────────────────────┬───────────────┐
-│ Table                                       │ Status        │
-├─────────────────────────────────────────────┼───────────────┤
-│ x_1566039_seventh_critical_account         │ [ACTIVE]      │
-│ x_1566039_seventh_critical_account_incident_ext │ [ACTIVE] │
-│ x_1566039_seventh_customer                 │ [ACTIVE]      │
-│ x_1566039_seventh_account                  │ [ACTIVE]      │
-│ x_1566039_seventh_fraud_alert              │ [ACTIVE]      │
-│ x_1566039_seventh_risk_score               │ [ACTIVE]      │
-│ x_1566039_seventh_call_case                │ [ACTIVE]      │
-│ x_1566039_seventh_compliance_flag          │ [ACTIVE]      │
-│ x_1566039_seventh_account_extension        │ [ACTIVE]      │
-└─────────────────────────────────────────────┴───────────────┘
-
-🔗 SCHEMA RELATIONSHIPS (Reference Fields)
-┌─────────────────────────────────────────────┬───────────────────┬─────────────────────────────┐
-│ Table                                       │ Field             │ Target Table                │
-├─────────────────────────────────────────────┼───────────────────┼─────────────────────────────┤
-│ x_1566039_seventh_critical_account          │ assigned_team     │ sys_user_group              │
-│ x_1566039_seventh_critical_account_incident_ext │ bank_account  │ x_bank_critical_account     │
-│ x_1566039_seventh_account                   │ owner             │ x_1566039_seventh_account   │
-│ x_1566039_seventh_risk_score                │ account           │ x_1566039_seventh_account   │
-└─────────────────────────────────────────────┴───────────────────┴─────────────────────────────┘
-
-⚙️ LOGIC ATTACHMENTS (Scripts & Actions)
-┌─────────┬────────────────────────────────────┬───────────────────────────────────────────────┬──────────────┬──────────────────┐
-│ (index) │ Name                               │ Table                                         │ Type         │ Artifact Type    │
-├─────────┼────────────────────────────────────┼───────────────────────────────────────────────┼──────────────┼──────────────────┤
-│ 0       │ bank_incident_onload               │ incident                                      │ [onLoad]     │ script client    │
-│ 1       │ bank_account_onchange              │ x_1566039_seventh_critical_account          │ [onChange]   │ script client    │
-│ 2       │ cs_task_onload                     │ task                                          │ [onLoad]     │ script client    │
-│ 3       │ cs_task_onchange_priority          │ x_1566039_seventh_critical_account_incident_ext │ [onChange] │ script client    │
-│ 4       │ cs_alert_onload                    │ x_1566039_seventh_fraud_alert                 │ [onLoad]     │ script client    │
-│ 5       │ cs_risk_onchange_score             │ x_1566039_seventh_risk_score                  │ [onChange]   │ script client    │
-│ 6       │ Auto-close empty Change Requests   │ change_request                                │ [action]     │ script           │
-│ 7      │ View car info                      │ x_snc_ts_custom_cars                           │ [action]     │ ui action        │
-│ 8      │ SampleScriptInclude                │ [global]                                      │ [action]     │ script include   │
-└─────────┴────────────────────────────────────┴───────────────────────────────────────────────┴──────────────┴──────────────────┘
-
-🔒 SECURITY & ACCESS (ACLs)
-┌──────────────────────────────┬───────────────────────┬───────────────────────────┐
-│ ACL                           │ Level / Roles         │ Table                     │
-├──────────────────────────────┼───────────────────────┼───────────────────────────┤
-│ DELETE on task.description    │ Field-level, Roles: ✔ ✅ SDK detected at /node_modules/@servicenow/sdk
+Scans your project and prints a grouped summary of all artifacts and their relationships:
+
+```
 ✔ Workspace SDK loaded
 ✔ Project loaded
 ✔ Graph built: 181 nodes, 141 edges
 
 📊 LINEAGE MAP
-────────────────────────────────────────────────────────────
-
-📦 DATA SCHEMA
-┌─────────────────────────────────────────────┬───────────────┐
-│ Table                                       │ Status        │
-├─────────────────────────────────────────────┼───────────────┤
-│ x_1566039_seventh_critical_account         │ [ACTIVE]      │
-│ x_1566039_seventh_critical_account_incident_ext │ [ACTIVE] │
-│ x_1566039_seventh_customer                 │ [ACTIVE]      │
-│ x_1566039_seventh_account                  │ [ACTIVE]      │
-│ x_1566039_seventh_fraud_alert              │ [ACTIVE]      │
-│ x_1566039_seventh_risk_score               │ [ACTIVE]      │
-│ x_1566039_seventh_call_case                │ [ACTIVE]      │
-│ x_1566039_seventh_compliance_flag          │ [ACTIVE]      │
-│ x_1566039_seventh_account_extension        │ [ACTIVE]      │
-└─────────────────────────────────────────────┴───────────────┘
-
-🔗 SCHEMA RELATIONSHIPS (Reference Fields)
-┌─────────────────────────────────────────────┬───────────────────┬─────────────────────────────┐
-│ Table                                       │ Field             │ Target Table                │
-├─────────────────────────────────────────────┼───────────────────┼─────────────────────────────┤
-│ x_1566039_seventh_critical_account          │ assigned_team     │ sys_user_group              │
-│ x_1566039_seventh_critical_account_incident_ext │ bank_account  │ x_bank_critical_account     │
-│ x_1566039_seventh_account                   │ owner             │ x_1566039_seventh_customer  │
-│ x_1566039_seventh_fraud_alert               │ account           │ x_1566039_seventh_account   │
-│ x_1566039_seventh_risk_score                │ account           │ x_1566039_seventh_account   │
-│ x_1566039_seventh_call_case                 │ customer          │ x_1566039_seventh_customer  │
-│ x_1566039_seventh_compliance_flag           │ customer          │ x_1566039_seventh_customer  │
-│ x_1566039_seventh_account_extension         │ linked_account    │ x_1566039_seventh_account   │
-└─────────────────────────────────────────────┴───────────────────┴─────────────────────────────┘
-
-⚙️ LOGIC ATTACHMENTS (Scripts & Actions)
-┌─────────┬────────────────────────────────────┬───────────────────────────────────────────────┬──────────────┬──────────────────┐
-│ (index) │ Name                               │ Table                                         │ Type         │ Artifact Type    │
-├─────────┼────────────────────────────────────┼───────────────────────────────────────────────┼──────────────┼──────────────────┤
-│ 0       │ bank_incident_onload               │ incident                                      │ [onLoad]     │ script client    │
-│ 1       │ bank_account_onchange              │ x_1566039_seventh_critical_account          │ [onChange]   │ script client    │
-│ 2       │ cs_task_onload                     │ task                                          │ [onLoad]     │ script client    │
-│ 3       │ cs_task_onchange_priority          │ x_1566039_seventh_critical_account_incident_ext │ [onChange] │ script client    │
-│ 4       │ cs_incident_onload                 │ incident                                      │ [onLoad]     │ script client    │
-│ 5       │ cs_incident_onchange_caller        │ incident                                      │ [onChange]   │ script client    │
-│ 6       │ cs_account_onchange_type           │ x_1566039_seventh_account                     │ [onChange]   │ script client    │
-│ 7       │ cs_alert_onload                    │ x_1566039_seventh_fraud_alert                 │ [onLoad]     │ script client    │
-│ 8       │ cs_risk_onchange_score             │ x_1566039_seventh_risk_score                  │ [onChange]   │ script client    │
-│ 9       │ Auto-close empty Change Requests   │ change_request                                │ [action]     │ script           │
-│ 10      │ View car info                      │ x_snc_ts_custom_cars                           │ [action]     │ ui action        │
-│ 11      │ SampleScriptInclude                │ [global]                                      │ [action]     │ script include   │
-└─────────┴────────────────────────────────────┴───────────────────────────────────────────────┴──────────────┴──────────────────┘
-
-🔒 SECURITY & ACCESS (ACLs)
-┌──────────────────────────────┬───────────────────────┬───────────────────────────┐
-│ ACL                           │ Level / Roles         │ Table                     │
-├──────────────────────────────┼───────────────────────┼───────────────────────────┤
-│ DELETE on task.description    │ Field-level, 
-Roles: 58794a2b937f4c0eba394fce1515930e, ae7beff0df584bd7a39fac26deaf20b7 │ task │
-└──────────────────────────────┴───────────────────────┴───────────────────────────┘
 
-🧠 PROJECT INSIGHTS
- • Total User Artifacts: 23
- • User Artifacts Breakdown: 
-   {
-     "sys_script_client": 9,
-     "sys_db_object": 10,
-     "sys_script": 1,
-     "sys_security_acl": 1,
-     "sys_ui_action": 1,
-     "sys_script_include": 1
-   }
- • Platform Dependencies: 9
- • Internal References:   132
- • Total Artifacts:       181
- • Total Relationships:   141
+  Client Script          9 artifacts
+  Table                 10 artifacts
+  Business Rule          1 artifact
+  Flow Definition        1 artifact
+  Catalog Item           2 artifacts
+  Acl                    1 artifact
+  Ui Action              1 artifact
 
+🧠 PROJECT INSIGHTS
+  Total User Artifacts: 35
+  Platform Dependencies: 9
+  Total Relationships:  141
 ```
 
-**Generated file:** `fluent-graph.json` (in project root)
+Also writes `fluent-graph.json` to your project root for CI/CD or tooling use.
 
 ---
 
-### Blast Radius Analysis
-
-Analyze the impact of changing a specific table:
+### Blast — impact analysis for a specific artifact
 
 ```bash
-fluent-graph blast incident
+fluent-graph blast <table_or_artifact_name>
 ```
 
-**Output:**
+Example:
+```bash
+fluent-graph blast x_1566039_seventh_customer
 ```
-[FLUENT-GRAPH] BLAST RADIUS REPORT
-Target:   incident [sys_db_object]
-SysID:    26441130e60544259e930cb385f74fca
-=========================================================================================
-
-┌──────────────────────────┬─────────────────┬──────────────────────────────┬─────────────────────────────────┬──────────────────────┐
-│ Impacted Artifact        │ Type            │ File                         │ Reason                          │ State                │
-├──────────────────────────┼─────────────────┼──────────────────────────────┼─────────────────────────────────┼──────────────────────┤
-│ bank_incident_onload     │ client_script   │ src/fluent/bank_small_...    │ ⚡ Logic Attachment [onLoad]    │ INSERT_OR_UPDATE     │
-│ cs_incident_onload       │ client_script   │ src/fluent/client-scripts... │ ⚡ Logic Attachment [onLoad]    │ INSERT_OR_UPDATE     │
-│ cs_incident_onchange_... │ client_script   │ src/fluent/client-scripts... │ ⚡ Logic Attachment [onChange]  │ INSERT_OR_UPDATE     │
-└──────────────────────────┴─────────────────┴──────────────────────────────┴─────────────────────────────────┴──────────────────────┘
 
-⚠️  PRE-DEPLOYMENT SUMMARY
-- Total Impacted: 3 artifacts
-- Breakdown:
-  • client_script: 3
 ```
+[FLUENT-GRAPH] BLAST RADIUS REPORT
+Target: x_1566039_seventh_customer
 
----
+┌────────────────────────────────┬───────────────────┬──────────────────────────────┐
+│ Impacted Artifact              │ Type              │ Reason                       │
+├────────────────────────────────┼───────────────────┼──────────────────────────────┤
+│ x_1566039_seventh_account      │ table             │ Reference field: owner       │
+│ x_1566039_seventh_call_case    │ table             │ Reference field: customer    │
+│ cs_account_onchange_type       │ client_script     │ Logic attachment             │
+└────────────────────────────────┴───────────────────┴──────────────────────────────┘
 
-## Output Format
-
-The generated `fluent-graph.json` contains:
-
-```json
-{
-  "metadata": {
-    "projectRoot": "/path/to/project",
-    "scopeId": "59760b6f783848bd981362d6b1d0c7ed",
-    "scopeName": "x_1566039_seventh",
-    "recordCount": 171,
-    "referenceCount": 15,
-    "compositionCount": 111,
-    "generatedAt": "2025-01-04T16:32:54.130Z",
-    "sdkVersion": "4.1.0"
-  },
-  "nodes": [
-    {
-      "id": "6eed3050f8214b6194056935182d9fa5",
-      "table": "sys_db_object",
-      "name": "x_1566039_seventh_customer",
-      "label": "Customer",
-      "action": "INSERT_OR_UPDATE",
-      "attributes": {
-        "access": "public",
-        "is_extendable": false,
-        "read_access": true
-      },
-      "source": {
-        "file": "src/fluent/bank_small_artifacts.now.ts",
-        "type": "VariableStatement"
-      }
-    }
-  ],
-  "edges": [
-    {
-      "from": "4da5b7b689ae43e69b3db1bfe1dd0cd5",
-      "to": "0fc60d0f1c35401580488c83440a4d81",
-      "via": "owner",
-      "type": "reference",
-      "targetTable": "x_1566039_seventh_customer"
-    }
-  ]
-}
+⚠️  PRE-DEPLOYMENT SUMMARY
+  Total Impacted: 3 artifacts
 ```
 
-### Node Types
-
-| `table` Value | Description |
-|---------------|-------------|
-| `sys_db_object` | Database table definition |
-| `sys_dictionary` | Column/field definition |
-| `sys_script_client` | Client script (onLoad, onChange, etc.) |
-| `sys_script` | Business rule |
-| `sys_choice` | Choice list value |
-
-### Edge Types
-
-| `type` | Description |
-|--------|-------------|
-| `reference` | Foreign key or logic attachment |
-| `composition` | Parent-child relationship (e.g., table → columns) |
-
----
-
-## How It Works
-
-`fluent-graph` does **not** parse your TypeScript/Fluent code directly.
-
-Instead, it:
-
-1. **Locates the SDK** installed in `node_modules/@servicenow/sdk`
-2. **Loads your Fluent project** using the SDK's internal `Project` API
-3. **Observes SDK compilation** to extract already-parsed artifacts
-4. **Builds a dependency graph** from SDK-provided metadata
-5. **Outputs structured JSON** for analysis or automation
-
-This approach:
-- ✅ Works across SDK versions (no brittle AST parsing)
-- ✅ Captures runtime behavior (e.g., dynamic references)
-- ✅ Stays synchronized with SDK semantics
-
 ---
 
-## Use Cases
+## CI/CD Integration
 
-### 1. Pre-Deployment Impact Analysis
-```bash
-fluent-graph blast incident > pre-deploy-report.txt
-```
-
-### 2. CI/CD Integration
 ```yaml
 # .github/workflows/fluent-check.yml
-- name: Extract lineage
-  run: npx fluent-graph analyze
+- name: Analyze lineage
+  run: npx @yesprasad/fluent-graph analyze
 
-- name: Check for conflicts
+- name: Fail on identity conflicts
   run: |
     if grep -q '"action": "CONFLICT"' fluent-graph.json; then
       echo "❌ Identity conflicts detected"
@@ -321,111 +133,19 @@ fluent-graph blast incident > pre-deploy-report.txt
     fi
 ```
 
-### 3. Documentation Generation
-Parse `fluent-graph.json` to auto-generate:
-- Schema diagrams
-- Dependency matrices
-- Change impact reports
-
 ---
 
-## Performance
-
-Typical extraction times on SDK 4.1.x:
-
-| Project Size | Artifacts | Extraction Time |
-|--------------|-----------|-----------------|
-| Small        | 50-100    | < 5 seconds     |
-| Medium       | 100-500   | 5-15 seconds    |
-| Large        | 500-1000  | 15-30 seconds   |
-| Enterprise   | 1000+     | 30-60 seconds   |
-
-*Times measured on MacBook Air M1, 16GB RAM*
-
-**Note:** First run is slower (SDK initialization). Subsequent runs are faster.
-
 ## Limitations
 
-### Current Version (v0.1)
-
-- **Schema relationships detection incomplete:** The extractor currently captures foreign key relationships declared in `sys_dictionary` records, but some Fluent DSL references (e.g., `ReferenceColumn` in Table definitions) may not appear in edges if the SDK's internal representation doesn't expose them during the observed compilation phase.
-
-- **Tested against SDK 4.1.x only:** While the architecture is designed to handle SDK evolution, version-specific parsing has only been validated with `@servicenow/sdk@4.1.0`. Newer or older versions may produce incomplete graphs.
-
-- **No UI visualization:** Output is JSON-only. Use external tools (e.g., D3.js, Mermaid) to render graphs.
-
-- **Single-project scope:** Does not analyze cross-scope dependencies (e.g., references to `global` tables outside your app scope).
-
----
-
-## Roadmap
-
-- [ ] Improve FK edge extraction: Currently misses some ReferenceColumn relationships when table nodes don't exist
-- [ ] Add ACL/UI Policy/UI Action support to blast radius
-- [ ] Support SDK 4.0.x (test against 3 versions: 4.0, 4.1, 4.2)
-- [ ] HTML report with interactive D3.js graph visualization
-- [ ] `--watch` mode: Re-extract on file changes during development
-- [ ] Cross-scope analysis: Detect dependencies on global/platform apps
-- [ ] Adding unit test cases
-
----
-
-## Contributing
-
-This is an early-stage tool built to solve real problems in Fluent development. Contributions are welcome, especially:
-
-### Areas We Need Help
-
-1. **SDK Version Testing**
-   - Test against SDK 4.0.x, 4.2.x, 5.0.x
-   - Document breaking changes in graph structure
-   
-2. **Edge Extraction Improvements**
-   - Capture more FK relationships from Fluent DSL
-   - Handle complex reference scenarios (polymorphic refs, etc.)
-   
-3. **Artifact Type Coverage**
-   - Add support for: Workflows, Flow Designer, Notifications
-   - Validate ACL/UI Policy detection
-
-### Development Setup
-```bash
-git clone https://github.com/yesprasad/fluent-graph
-cd fluent-graph
-npm install
-npm run build
-
-# Test against example project
-cd ../your-fluent-project
-npx /path/to/fluent-graph/dist/cli/index.js extract
-```
-
-### Running Tests
-```bash
-npm test                 # Add Unit tests
-npm run test:integration # Test against real SDK project
-```
+- Tested against `@servicenow/sdk@4.5.x`
+- No UI visualization — output is JSON and terminal only
+- Single-project scope — does not trace cross-scope dependencies
 
 ---
 
 ## License
-MIT License
-
-Copyright (c) 2026 Eshwar Sowbhagya Prasad Yaddanapudi.
-Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
-
----
-
-## Author
-
-**Eshwar Sowbhagya Prasad Yaddanapudi**
-
-Built with focus on making ServiceNow Pro Developer Fluent development with now-sdk safer, faster, and more transparent.
+MIT License — Copyright (c) 2026 Eshwar Sowbhagya Prasad Yaddanapudi
 
 ---
 
@@ -444,4 +164,10 @@ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLI
 
 ---
 
-**Questions or issues?** Open an issue on GitHub or reach out directly.
+**Questions or issues?** Open an issue on GitHub or reach out directly.
+
+## Author
+
+**Eshwar Sowbhagya Prasad Yaddanapudi**
+
+Questions or issues? [Open an issue on GitHub](https://github.com/yesprasad/fluent-graph/issues)

package/dist/blast/traversal.d.ts

@@ -0,0 +1,48 @@
+import type { LineageGraph, ArtifactNode, ArtifactEdge } from '../types/graphs';
+export interface TraversalNode {
+    node: ArtifactNode;
+    hop: number;
+    /** Chain of node names from target → this node (inclusive). */
+    path: string[];
+    /** The edge that caused this node to be discovered. */
+    viaEdge: ArtifactEdge;
+}
+export interface TraversalResult {
+    /** The representative local graph node for the target (non-child preferred), or null if platform. */
+    target: ArtifactNode | null;
+    targetName: string;
+    /** All discovered nodes across all hops, sorted by hop ASC then name ASC. */
+    hops: TraversalNode[];
+    maxHopReached: number;
+    /** Times a visited node was skipped (cycle prevention + same-name deduplication). */
+    cyclesPrevented: number;
+}
+/**
+ * BFS reverse-traversal over the dependency graph.
+ *
+ * KEY DESIGN DECISIONS:
+ *
+ * 1. A logical "entity" is identified by node NAME, not by node ID.
+ *    Multiple physical nodes can share a name (e.g., a table and all its
+ *    field/documentation records are all named "x_my_table"). The BFS
+ *    treats them as one logical node — once any physical node for a name
+ *    is discovered, ALL siblings for that name are immediately marked
+ *    visited so they never appear again.
+ *
+ * 2. The initial target is seeded with ALL physical nodes sharing the
+ *    target name (plus the synthetic "platform:tableName" ID). This
+ *    ensures incoming edges are found regardless of which physical node
+ *    the edge was recorded against.
+ *
+ * 3. Edge matching uses BOTH:
+ *    - edge.to === currentNodeId  (exact physical node)
+ *    - edge.targetTable === currentNodeName  (canonical name — reliable
+ *      for platform nodes and catches mis-targeted edges)
+ *
+ * 4. ALL edge types are traversed. Display filtering is the caller's job.
+ *
+ * @param graph           The loaded LineageGraph.
+ * @param targetTableName The table name the user asked about.
+ * @param maxDepth        Maximum hop depth. Silently clamped to 25.
+ */
+export declare function traverseBlastRadius(graph: LineageGraph, targetTableName: string, maxDepth: number): TraversalResult;