@yesprasad/fluent-graph 0.1.0

package/LICENSE

@@ -0,0 +1,36 @@
+---
+## 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.
+
+---
+
+## Acknowledgments
+
+ServiceNow SDK team for building the Fluent DSL compiler
+MIT License
+
+Copyright (c) 2024 ServiceNow Inc.
+
+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.
+
+---

package/README.md

@@ -0,0 +1,447 @@
+# 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.
+
+---
+
+## 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
+
+**Install globally:**
+```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):**
+```bash
+cd your-fluent-project
+npx fluent-graph extract
+```
+
+**Verify installation:**
+```bash
+fluent-graph --version
+```
+---
+
+## Usage
+
+
+**Output:**
+```
+✔ ✅ 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
+✔ 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
+
+```
+
+**Generated file:** `fluent-graph.json` (in project root)
+
+---
+
+### Blast Radius Analysis
+
+Analyze the impact of changing a specific table:
+
+```bash
+fluent-graph blast incident
+```
+
+**Output:**
+```
+[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
+```
+
+---
+
+## 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"
+    }
+  ]
+}
+```
+
+### 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
+```
+
+### 2. CI/CD Integration
+```yaml
+# .github/workflows/fluent-check.yml
+- name: Extract lineage
+  run: npx fluent-graph analyze
+
+- name: Check for conflicts
+  run: |
+    if grep -q '"action": "CONFLICT"' fluent-graph.json; then
+      echo "❌ Identity conflicts detected"
+      exit 1
+    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
+```
+
+---
+
+## 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.
+
+---
+
+## Acknowledgments
+
+ServiceNow SDK team for building the Fluent DSL compiler
+MIT License
+
+Copyright (c) 2024 ServiceNow Inc.
+
+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.
+
+---
+
+**Questions or issues?** Open an issue on GitHub or reach out directly.

package/bin/fluent-graph.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+//Simple shim that loads the compiled CLI
+try {
+  require('../dist/cli/index.js');
+} catch (err) {
+  console.error('fluent-graph failed to start.');
+  console.error(err);
+  process.exit(1);
+}

package/dist/cli/commands/blast.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare const blastCommand: Command;