npm - @yesprasad/fluent-graph - Versions diffs - 0.2.0 → 0.2.2 - Mend

@yesprasad/fluent-graph 0.2.0 → 0.2.2

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 (7) hide show

package/README.md +66 -301
package/dist/cli/commands/blast.js +74 -25
package/dist/cli/commands/extract.js +41 -15
package/dist/cli/index.js +15 -2
package/dist/index.d.ts +1 -0
package/dist/index.js +1 -0
package/package.json +1 -1

package/README.md CHANGED Viewed

@@ -2,8 +2,6 @@
 **Dependency visibility and impact analysis for ServiceNow Fluent SDK projects.**
-**Catch breaking changes before deployment by mapping hidden relationships between tables, fields, scripts, and UI actions.**
 ---
 ## The Problem
@@ -14,286 +12,120 @@ You're refactoring a ServiceNow custom table. You delete a field. You deploy.
 14 client scripts fail. 3 business rules error out. 2 dashboards go blank.
-**You realise the breaking changes at runtime in production instance.**
+**You discover the breaking changes at runtime in production.**
 ---
 ## The Solution
-**Welcome to Fluent-Graph**
-`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.
+`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.
+```bash
+npx @yesprasad/fluent-graph blast incident
+```
-run - npx @yesprasad/fluent-graph blast incident
-**Output:**
 ```
 🔥 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)
+  • bank_incident_onload          (Client Script)
+  • cs_incident_onload            (Client Script)
+  • cs_incident_onchange_caller   (Client Script)
 ```
-🔥 **Now you know before you deploy.**
+**Now you know before you deploy.**
 ---
-## What It Does
-- **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
----
 ## Installation
-**Prerequisites:**
-- Node.js 18+
-- An existing ServiceNow Fluent SDK project with `@servicenow/sdk` installed
+Requires Node.js 18+ and an existing Fluent SDK project with `@servicenow/sdk` installed.
-**Install globally:**
+**Global install:**
 ```bash
 npm install -g @yesprasad/fluent-graph
 ```
-**basic CLI usage:**
-```bash
-fluent-graph analyze
-fluent-graph blast <table_name or artifact_name>
-```
-**Or use directly with npx (no installation needed):**
+**Or use without installing:**
 ```bash
-cd your-fluent-project
-npx @yesprasad/fluent-graph extract
+npx @yesprasad/fluent-graph analyze
 ```
-**Verify installation:**
-```bash
-fluent-graph --version
-```
 ---
-## Usage
+## Commands
+### Analyze — full project lineage map
+```bash
+fluent-graph analyze
+```
+Scans your project and prints a grouped summary of all artifacts and their relationships:
-**Output:**
 ```
 ✔ 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
-### 1. Pre-Deployment Impact Analysis
-```bash
-fluent-graph blast incident > pre-deploy-report.txt
-```
+## CI/CD Integration
-### 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"
@@ -301,92 +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-10 seconds    |
-| Large        | 500-1000  | 10-20 seconds   |
-| Enterprise   | 1000+     | 20-30 seconds   |
-*Times measured on MacBook Air M1, 16GB RAM and approximated*
 ## 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
----
-### 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
 ---
@@ -405,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/cli/commands/blast.js CHANGED Viewed

@@ -56,6 +56,7 @@ exports.blastCommand = new commander_1.Command('blast')
     .option('--include-deleted', 'Include deleted artifacts in the analysis')
     .option('--no-banner', 'Skip banner (inherited)')
     .action(async (targetTableName, options) => {
+    const isJson = options.format === 'json';
     try {
         const graphFilePath = path.isAbsolute(options.graph)
             ? options.graph
@@ -67,7 +68,12 @@ exports.blastCommand = new commander_1.Command('blast')
             registry.load(sdkDetection.sdkPath);
         }
         if (!fs.existsSync(graphFilePath)) {
-            console.error(chalk_1.default.red(`\n❌ Error: Graph file not found at ${graphFilePath}`));
+            if (isJson) {
+                console.log(JSON.stringify({ error: `Graph file not found at ${graphFilePath}`, code: 'GRAPH_NOT_FOUND' }));
+            }
+            else {
+                console.error(chalk_1.default.red(`\n❌ Error: Graph file not found at ${graphFilePath}`));
+            }
             process.exit(1);
         }
         const lineageGraph = JSON.parse(fs.readFileSync(graphFilePath, 'utf8'));
@@ -77,28 +83,40 @@ exports.blastCommand = new commander_1.Command('blast')
         const isBaseTable = !targetNode;
         const isTargetReferenced = lineageGraph.edges.some(edge => edge.to === targetNodeId || edge.targetTable === targetTableName);
         if (!targetNode && !isTargetReferenced) {
-            console.log(chalk_1.default.red(`\n❌ Target "${targetTableName}" not found or referenced`));
-            console.log(chalk_1.default.yellow('\n💡 Available custom tables:'));
             const customTables = lineageGraph.nodes
                 .filter(node => registry.getPluginName(node.table) === 'TablePlugin' && !registry.isChild(node.table) && node.action !== 'DELETE')
                 .map(node => node.name)
                 .sort();
-            customTables.forEach(tableName => console.log(chalk_1.default.gray(' • ') + chalk_1.default.white(tableName)));
-            console.log(chalk_1.default.yellow('\n💡 Referenced platform tables:'));
             const platformTables = [...new Set(lineageGraph.edges
                     .filter(edge => edge.to.startsWith('platform:'))
                     .map(edge => edge.to.split(':')[1]))].sort();
-            platformTables.forEach(tableName => console.log(chalk_1.default.gray(' • ') + chalk_1.default.magenta(tableName)));
+            if (isJson) {
+                console.log(JSON.stringify({
+                    error: `Target "${targetTableName}" not found or referenced`,
+                    code: 'TARGET_NOT_FOUND',
+                    availableCustomTables: customTables,
+                    availablePlatformTables: platformTables,
+                }));
+            }
+            else {
+                console.log(chalk_1.default.red(`\n❌ Target "${targetTableName}" not found or referenced`));
+                console.log(chalk_1.default.yellow('\n💡 Available custom tables:'));
+                customTables.forEach(tableName => console.log(chalk_1.default.gray(' • ') + chalk_1.default.white(tableName)));
+                console.log(chalk_1.default.yellow('\n💡 Referenced platform tables:'));
+                platformTables.forEach(tableName => console.log(chalk_1.default.gray(' • ') + chalk_1.default.magenta(tableName)));
+            }
             process.exit(1);
         }
         // ── STEP 2: Display header ───────────────────────────────────────────────
-        console.log(chalk_1.default.yellow.bold('\n🔥 BLAST RADIUS ANALYSIS'));
-        console.log(chalk_1.default.gray('═'.repeat(80)));
-        console.log(chalk_1.default.gray('Target:   ') + chalk_1.default.white(targetTableName) + (isBaseTable ? chalk_1.default.yellow(' [Base Table]') : ''));
-        if (!isBaseTable) {
-            console.log(chalk_1.default.gray('File:     ') + chalk_1.default.gray(targetNode.source.file));
+        if (!isJson) {
+            console.log(chalk_1.default.yellow.bold('\n🔥 BLAST RADIUS ANALYSIS'));
+            console.log(chalk_1.default.gray('═'.repeat(80)));
+            console.log(chalk_1.default.gray('Target:   ') + chalk_1.default.white(targetTableName) + (isBaseTable ? chalk_1.default.yellow(' [Base Table]') : ''));
+            if (!isBaseTable) {
+                console.log(chalk_1.default.gray('File:     ') + chalk_1.default.gray(targetNode.source.file));
+            }
+            console.log(chalk_1.default.gray('═'.repeat(80)));
         }
-        console.log(chalk_1.default.gray('═'.repeat(80)));
         // ── STEP 3: BFS traversal ────────────────────────────────────────────────
         const maxDepth = options.directOnly ? 1 : Math.max(1, parseInt(options.depth, 10) || 10);
         const traversal = (0, traversal_1.traverseBlastRadius)(lineageGraph, targetTableName, maxDepth);
@@ -119,23 +137,49 @@ exports.blastCommand = new commander_1.Command('blast')
         const directImpact = displayed.filter(tn => tn.hop === 1);
         const transitiveImpact = displayed.filter(tn => tn.hop > 1);
         if (displayed.length === 0) {
-            console.log(chalk_1.default.green('\n✅ Zero dependencies detected in local project.\n'));
+            if (isJson) {
+                console.log(JSON.stringify({
+                    target: targetTableName,
+                    isBaseTable,
+                    totalImpacted: 0,
+                    direct: 0,
+                    transitive: 0,
+                    maxHopReached: 0,
+                    cyclesPrevented: traversal.cyclesPrevented,
+                    riskLevel: 'LOW',
+                    impacts: [],
+                }, null, 2));
+            }
+            else {
+                console.log(chalk_1.default.green('\n✅ Zero dependencies detected in local project.\n'));
+            }
             return;
         }
         // ── STEP 5: Output ───────────────────────────────────────────────────────
         switch (options.format) {
             case 'json': {
-                const output = displayed.map(tn => ({
-                    artifact: tn.node.name,
-                    type: registry.getDisplayGroupName(tn.node.table).toLowerCase(),
-                    file: tn.node.source.file,
-                    hop: tn.hop,
-                    path: tn.path,
-                    via: tn.viaEdge.via ?? tn.viaEdge.type,
-                    edgeType: tn.viaEdge.type,
-                    state: tn.node.action,
-                }));
-                console.log(JSON.stringify(output, null, 2));
+                const totalCount = displayed.length;
+                const riskLevel = totalCount < 3 ? 'LOW' : totalCount < 8 ? 'MEDIUM' : 'HIGH';
+                console.log(JSON.stringify({
+                    target: targetTableName,
+                    isBaseTable,
+                    totalImpacted: totalCount,
+                    direct: directImpact.length,
+                    transitive: transitiveImpact.length,
+                    maxHopReached: traversal.maxHopReached,
+                    cyclesPrevented: traversal.cyclesPrevented,
+                    riskLevel,
+                    impacts: displayed.map(tn => ({
+                        artifact: tn.node.name,
+                        type: registry.getDisplayGroupName(tn.node.table).toLowerCase(),
+                        file: tn.node.source.file,
+                        hop: tn.hop,
+                        path: tn.path,
+                        via: tn.viaEdge.via ?? tn.viaEdge.type,
+                        edgeType: tn.viaEdge.type,
+                        state: tn.node.action,
+                    })),
+                }, null, 2));
                 break;
             }
             case 'csv': {
@@ -233,7 +277,12 @@ exports.blastCommand = new commander_1.Command('blast')
         }
     }
     catch (error) {
-        console.error(chalk_1.default.red('\n❌ Error:'), error.message);
+        if (isJson) {
+            console.log(JSON.stringify({ error: error.message ?? 'Unexpected error', code: 'UNEXPECTED_ERROR' }));
+        }
+        else {
+            console.error(chalk_1.default.red('\n❌ Error:'), error.message);
+        }
         process.exit(1);
     }
 });

package/dist/cli/commands/extract.js CHANGED Viewed

@@ -20,30 +20,37 @@ const display_1 = require("../utils/display");
 exports.extractCommand = new commander_1.Command('analyze')
     .description('Analyze and extract dependency graph from the current project')
     .option('-o, --output <path>', 'Output file path', 'fluent-graph.json')
+    .option('-f, --format <type>', 'Output format: table, json', 'table')
     .option('-q, --quiet', 'Suppress console output')
     .option('--no-display', 'Skip visual display')
     .option('--no-banner', 'Skip banner (inherited)')
     .action(async (options) => {
+    const isJson = options.format === 'json';
     let spinner;
     try {
         const currentWorkingDir = process.cwd();
         // Step 1: Detect ServiceNow SDK Environment
-        if (!options.quiet) {
+        if (!options.quiet && !isJson) {
             spinner = (0, ora_1.default)('Detecting ServiceNow SDK...').start();
         }
         const sdkDetectionResult = await (0, detector_1.detectSDK)(currentWorkingDir);
         if (!sdkDetectionResult.found) {
             if (spinner)
                 spinner.fail('SDK not found');
-            console.error(chalk_1.default.red('\n❌ Error:'), sdkDetectionResult.error);
-            console.log(chalk_1.default.yellow('\n💡 Make sure you\'re in a ServiceNow Fluent project directory'));
+            if (isJson) {
+                console.log(JSON.stringify({ error: sdkDetectionResult.error, code: 'SDK_NOT_FOUND' }));
+            }
+            else {
+                console.error(chalk_1.default.red('\n❌ Error:'), sdkDetectionResult.error);
+                console.log(chalk_1.default.yellow('\n💡 Make sure you\'re in a ServiceNow Fluent project directory'));
+            }
             process.exit(1);
         }
         if (spinner) {
             spinner.succeed(`✅ SDK detected at ${chalk_1.default.gray(sdkDetectionResult.sdkPath)}`);
         }
         // Step 2: Dynamically Load Workspace SDK
-        if (!options.quiet) {
+        if (!options.quiet && !isJson) {
             spinner = (0, ora_1.default)('Loading workspace SDK...').start();
         }
         const workspaceSDK = (0, loader_1.loadWorkspaceSDK)(sdkDetectionResult.sdkPath);
@@ -51,7 +58,7 @@ exports.extractCommand = new commander_1.Command('analyze')
             spinner.succeed('Workspace SDK loaded');
         }
         // Step 3: Instantiate the Project Proxy
-        if (!options.quiet) {
+        if (!options.quiet && !isJson) {
             spinner = (0, ora_1.default)('Loading project configuration...').start();
         }
         const projectInstance = new workspaceSDK.sdkapi.Project({ rootDir: currentWorkingDir });
@@ -59,10 +66,19 @@ exports.extractCommand = new commander_1.Command('analyze')
             spinner.succeed('Project loaded');
         }
         // Step 4: Extract Lineage Graph
-        if (!options.quiet) {
+        if (!options.quiet && !isJson) {
             spinner = (0, ora_1.default)('Building dependency graph...').start();
         }
+        // In JSON mode, redirect SDK diagnostic noise (e.g. "Record defined N times")
+        // from stdout to stderr so stdout stays pure JSON for agent/tool consumption.
+        let restoreStdout;
+        if (isJson) {
+            const original = process.stdout.write.bind(process.stdout);
+            process.stdout.write = process.stderr.write.bind(process.stderr);
+            restoreStdout = () => { process.stdout.write = original; };
+        }
         const lineageGraph = await (0, extractor_1.extractLineageGraph)(projectInstance, workspaceSDK.registry);
+        restoreStdout?.();
         if (spinner) {
             spinner.succeed(`Graph built: ${chalk_1.default.cyan(lineageGraph.nodes.length)} nodes, ${chalk_1.default.cyan(lineageGraph.edges.length)} edges`);
         }
@@ -71,19 +87,29 @@ exports.extractCommand = new commander_1.Command('analyze')
             ? options.output
             : path_1.default.join(currentWorkingDir, options.output);
         (0, writer_1.writeGraph)(lineageGraph, outputFilePath);
-        if (!options.quiet) {
-            console.log(chalk_1.default.green('\n✅ Analysis complete'));
-            console.log(chalk_1.default.gray('   Location:     ') + chalk_1.default.white(outputFilePath));
-            console.log(chalk_1.default.gray('   Complexity:   ') + chalk_1.default.cyan((lineageGraph.edges.length / lineageGraph.nodes.length).toFixed(2)) + chalk_1.default.gray(' edges/node'));
-            console.log(chalk_1.default.gray('   Generated at: ') + chalk_1.default.gray(new Date().toLocaleTimeString()));
+        if (isJson) {
+            // Pure JSON on stdout: the full lineage graph, ready for agent/tool consumption.
+            console.log(JSON.stringify(lineageGraph, null, 2));
         }
-        // Step 6: Visual Lineage Map
-        if (options.display && !options.quiet) {
-            (0, display_1.displayLineageMap)(lineageGraph, workspaceSDK.registry);
+        else {
+            if (!options.quiet) {
+                console.log(chalk_1.default.green('\n✅ Analysis complete'));
+                console.log(chalk_1.default.gray('   Location:     ') + chalk_1.default.white(outputFilePath));
+                console.log(chalk_1.default.gray('   Complexity:   ') + chalk_1.default.cyan((lineageGraph.edges.length / lineageGraph.nodes.length).toFixed(2)) + chalk_1.default.gray(' edges/node'));
+                console.log(chalk_1.default.gray('   Generated at: ') + chalk_1.default.gray(new Date().toLocaleTimeString()));
+            }
+            // Step 6: Visual Lineage Map
+            if (options.display && !options.quiet) {
+                (0, display_1.displayLineageMap)(lineageGraph, workspaceSDK.registry);
+            }
         }
     }
     catch (error) {
-        if (error instanceof Error) {
+        if (isJson) {
+            const msg = error instanceof Error ? error.message : 'Unexpected error';
+            console.log(JSON.stringify({ error: msg, code: 'EXTRACTION_FAILED' }));
+        }
+        else if (error instanceof Error) {
             console.error(chalk_1.default.red('\n❌ Error:'), error.message);
             if (process.env.DEBUG) {
                 console.error(chalk_1.default.gray('\nStack trace:'));

package/dist/cli/index.js CHANGED Viewed

@@ -15,8 +15,21 @@ const packageJsonContent = fs_1.default.readFileSync(packageJsonPath, 'utf-8');
 const packageJson = JSON.parse(packageJsonContent);
 // ===== 2. Initialize CLI program =====
 const program = new commander_1.Command();
-// Show banner on first run (unless --no-banner or --quiet flag)
-const showBanner = !process.argv.includes('--no-banner') && !process.argv.includes('--quiet');
+// Show banner on first run (unless --no-banner / --quiet, or JSON output requested).
+// JSON consumers (agents, scripts) need stdout to be pure JSON, so the banner is
+// suppressed whenever `--format json` (or `-f json`) is present.
+const wantsJsonOutput = (() => {
+    const argv = process.argv;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--format' || a === '-f')
+            return argv[i + 1] === 'json';
+        if (a === '--format=json' || a === '-f=json')
+            return true;
+    }
+    return false;
+})();
+const showBanner = !process.argv.includes('--no-banner') && !process.argv.includes('--quiet') && !wantsJsonOutput;
 if (showBanner) {
     (0, banner_1.displayBanner)();
 }

package/dist/index.d.ts CHANGED Viewed

@@ -1,2 +1,3 @@
 export * from './extractor';
 export * from './types/graphs';
+export * from './blast/traversal';

package/dist/index.js CHANGED Viewed

@@ -16,3 +16,4 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./extractor"), exports);
 __exportStar(require("./types/graphs"), exports);
+__exportStar(require("./blast/traversal"), exports);

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@yesprasad/fluent-graph",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Dependency visibility and impact analysis for ServiceNow Fluent SDK projects",
   "bin": {
     "fluent-graph": "./bin/fluent-graph.js"