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:

npm install -g @yesprasad/fluent-graph

basic CLI usage:

fluent-graph analyze
fluent-graph blast <table_name or artifact_name>

Or use directly with npx (no installation needed):

cd your-fluent-project
npx fluent-graph extract

Verify installation:

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:

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:

{
  "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

fluent-graph blast incident > pre-deploy-report.txt

2. CI/CD Integration

# .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/[email protected]. 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

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

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.