fluent-graph

Dependency visibility and impact analysis for ServiceNow Fluent SDK projects.

The Problem

You're refactoring a ServiceNow custom table. You delete a field. You deploy.

Production breaks.

14 client scripts fail. 3 business rules error out. 2 dashboards go blank.

You discover the breaking changes at runtime in production.

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.

npx @yesprasad/fluent-graph blast incident

🔥 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)

Now you know before you deploy.

Installation

Requires Node.js 18+ and an existing Fluent SDK project with @servicenow/sdk installed.

Global install:

npm install -g @yesprasad/fluent-graph

Or use without installing:

npx @yesprasad/fluent-graph analyze

Commands

Analyze — full project lineage map

fluent-graph analyze

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

  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

Also writes fluent-graph.json to your project root for CI/CD or tooling use.

Blast — impact analysis for a specific artifact

fluent-graph blast <table_or_artifact_name>

Example:

fluent-graph blast x_1566039_seventh_customer

[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             │
└────────────────────────────────┴───────────────────┴──────────────────────────────┘

⚠️  PRE-DEPLOYMENT SUMMARY
  Total Impacted: 3 artifacts

Validate — catch structural issues before deploy

fluent-graph validate

Runs a set of structural checks across the whole project and reports issues by severity:

🔍 STRUCTURAL VALIDATION
════════════════════════════════════════════

  ERROR [FG-001] "cs_incident_onload" references field "priorty" on table
         "incident" but no such field exists
         File: client-scripts/cs-incident-onload.now.ts
         Suggestion: Did you mean "priority"?

WARNING [FG-002] cs_a and cs_b (order: 100) both fire "onChange" on
         "incident" — nondeterministic execution order

════════════════════════════════════════════
1 error, 1 warning

Checks include:

• FG-001 — script references a field that doesn't exist on the target table (with Levenshtein-based "did you mean" suggestions)
• FG-002 — two scripts on the same table/event/order, so execution order is nondeterministic
• FG-003 — a reference points to a table that isn't in the local project or known platform tables
• FG-004 — two artifacts with the same name on the same table — the last one defined silently wins
• FG-005 — an artifact is marked for deletion but other active artifacts still depend on it

fluent-graph validate exits non-zero on errors, so it's a natural CI gate:

fluent-graph validate --severity error

Use --format json for machine-readable output and --severity <error|warning|info> to control the noise floor.

Context — minimal, AI-ready context for a table

fluent-graph context <table_name>

Extracts just what an LLM (or a human) needs to reason about one table — its fields, attached scripts, business rules, what depends on it, what it depends on, and a blast-radius summary — instead of dumping the entire fluent-graph.json:

🧠 CONTEXT FOR: incident
════════════════════════════════════════════════

📋 Fields (3)
📋 Attached scripts (4)
🔗 Dependents (2 tables reference incident)
↗ References from incident (1)
🔥 Blast radius: 4 direct, 2 transitive — MEDIUM

📊 TOKEN METRICS
This context     1,204 tokens
Full graph      18,340 tokens
Saved           17,136 tokens
Reduction       93%

This is meant to be piped straight into an AI coding assistant or agent prompt — fluent-graph context incident --format json gives you a compact, structured payload instead of pasting the full graph and burning context window.

Options:

• --depth <n> — how many hops of dependents/references to include (default 1)
• --no-fields / --no-scripts / --no-blast — trim sections you don't need
• --show-metrics — see the per-section token breakdown and the exact JSON payload that would be sent to an LLM
• -f, --format <table|json>

CI/CD Integration

# .github/workflows/fluent-check.yml
- name: Analyze lineage
  run: npx @yesprasad/fluent-graph analyze

- name: Validate structural issues
  run: npx @yesprasad/fluent-graph validate --severity error

- name: Fail on identity conflicts
  run: |
    if grep -q '"action": "CONFLICT"' fluent-graph.json; then
      echo "❌ Identity conflicts detected"
      exit 1
    fi

Limitations

• Tested against @servicenow/[email protected]
• 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

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.

Author

Eshwar Sowbhagya Prasad Yaddanapudi

Questions or issues? Open an issue on GitHub