@yesprasad/fluent-graph 0.2.0 → 0.2.1

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 (2) hide show
  1. package/README.md +66 -301
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -2,8 +2,6 @@
2
2
 
3
3
  **Dependency visibility and impact analysis for ServiceNow Fluent SDK projects.**
4
4
 
5
- **Catch breaking changes before deployment by mapping hidden relationships between tables, fields, scripts, and UI actions.**
6
-
7
5
  ---
8
6
 
9
7
  ## The Problem
@@ -14,286 +12,120 @@ You're refactoring a ServiceNow custom table. You delete a field. You deploy.
14
12
 
15
13
  14 client scripts fail. 3 business rules error out. 2 dashboards go blank.
16
14
 
17
- **You realise the breaking changes at runtime in production instance.**
15
+ **You discover the breaking changes at runtime in production.**
18
16
 
19
17
  ---
18
+
20
19
  ## The Solution
21
- **Welcome to Fluent-Graph**
22
20
 
23
- `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.
21
+ `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.
22
+
23
+ ```bash
24
+ npx @yesprasad/fluent-graph blast incident
25
+ ```
24
26
 
25
- run - npx @yesprasad/fluent-graph blast incident
26
- **Output:**
27
27
  ```
28
28
  🔥 BLAST RADIUS ANALYSIS
29
29
  Target: incident
30
30
 
31
31
  ⚠️ 3 artifacts will break if you modify this table:
32
- • bank_incident_onload (Client Script)
33
- • cs_incident_onload (Client Script)
34
- • cs_incident_onchange_caller (Client Script)
32
+ • bank_incident_onload (Client Script)
33
+ • cs_incident_onload (Client Script)
34
+ • cs_incident_onchange_caller (Client Script)
35
35
  ```
36
36
 
37
- 🔥 **Now you know before you deploy.**
37
+ **Now you know before you deploy.**
38
38
 
39
39
  ---
40
40
 
41
-
42
- ## What It Does
43
-
44
- - **Extracts artifact lineage** from SDK projects (tables, columns, scripts, business rules)
45
- - **Detects identity conflicts** (duplicate `$id` declarations across files)
46
- - **Maps relationships** (foreign keys, table extensions, logic attachments)
47
- - **Generates blast-radius reports** (what breaks if you change X?)
48
- - **Outputs machine-readable JSON** for CI/CD integration
49
-
50
- ---
51
41
  ## Installation
52
42
 
53
- **Prerequisites:**
54
- - Node.js 18+
55
- - An existing ServiceNow Fluent SDK project with `@servicenow/sdk` installed
43
+ Requires Node.js 18+ and an existing Fluent SDK project with `@servicenow/sdk` installed.
56
44
 
57
- **Install globally:**
45
+ **Global install:**
58
46
  ```bash
59
47
  npm install -g @yesprasad/fluent-graph
60
48
  ```
61
- **basic CLI usage:**
62
- ```bash
63
- fluent-graph analyze
64
- fluent-graph blast <table_name or artifact_name>
65
- ```
66
49
 
67
- **Or use directly with npx (no installation needed):**
50
+ **Or use without installing:**
68
51
  ```bash
69
- cd your-fluent-project
70
- npx @yesprasad/fluent-graph extract
52
+ npx @yesprasad/fluent-graph analyze
71
53
  ```
72
54
 
73
- **Verify installation:**
74
- ```bash
75
- fluent-graph --version
76
- ```
77
55
  ---
78
56
 
79
- ## Usage
57
+ ## Commands
58
+
59
+ ### Analyze — full project lineage map
60
+
61
+ ```bash
62
+ fluent-graph analyze
63
+ ```
80
64
 
65
+ Scans your project and prints a grouped summary of all artifacts and their relationships:
81
66
 
82
- **Output:**
83
67
  ```
84
68
  ✔ Workspace SDK loaded
85
69
  ✔ Project loaded
86
70
  ✔ Graph built: 181 nodes, 141 edges
87
71
 
88
72
  📊 LINEAGE MAP
89
- ────────────────────────────────────────────────────────────
90
-
91
- 📦 DATA SCHEMA
92
- ┌─────────────────────────────────────────────┬───────────────┐
93
- │ Table │ Status │
94
- ├─────────────────────────────────────────────┼───────────────┤
95
- │ x_1566039_seventh_critical_account │ [ACTIVE] │
96
- │ x_1566039_seventh_critical_account_incident_ext │ [ACTIVE] │
97
- │ x_1566039_seventh_customer │ [ACTIVE] │
98
- │ x_1566039_seventh_account │ [ACTIVE] │
99
- │ x_1566039_seventh_fraud_alert │ [ACTIVE] │
100
- │ x_1566039_seventh_risk_score │ [ACTIVE] │
101
- │ x_1566039_seventh_call_case │ [ACTIVE] │
102
- │ x_1566039_seventh_compliance_flag │ [ACTIVE] │
103
- │ x_1566039_seventh_account_extension │ [ACTIVE] │
104
- └─────────────────────────────────────────────┴───────────────┘
105
-
106
- 🔗 SCHEMA RELATIONSHIPS (Reference Fields)
107
- ┌─────────────────────────────────────────────┬───────────────────┬─────────────────────────────┐
108
- │ Table │ Field │ Target Table │
109
- ├─────────────────────────────────────────────┼───────────────────┼─────────────────────────────┤
110
- │ x_1566039_seventh_critical_account │ assigned_team │ sys_user_group │
111
- │ x_1566039_seventh_critical_account_incident_ext │ bank_account │ x_bank_critical_account │
112
- │ x_1566039_seventh_account │ owner │ x_1566039_seventh_customer │
113
- │ x_1566039_seventh_fraud_alert │ account │ x_1566039_seventh_account │
114
- │ x_1566039_seventh_risk_score │ account │ x_1566039_seventh_account │
115
- │ x_1566039_seventh_call_case │ customer │ x_1566039_seventh_customer │
116
- │ x_1566039_seventh_compliance_flag │ customer │ x_1566039_seventh_customer │
117
- │ x_1566039_seventh_account_extension │ linked_account │ x_1566039_seventh_account │
118
- └─────────────────────────────────────────────┴───────────────────┴─────────────────────────────┘
119
-
120
- ⚙️ LOGIC ATTACHMENTS (Scripts & Actions)
121
- ┌─────────┬────────────────────────────────────┬───────────────────────────────────────────────┬──────────────┬──────────────────┐
122
- │ (index) │ Name │ Table │ Type │ Artifact Type │
123
- ├─────────┼────────────────────────────────────┼───────────────────────────────────────────────┼──────────────┼──────────────────┤
124
- │ 0 │ bank_incident_onload │ incident │ [onLoad] │ script client │
125
- │ 1 │ bank_account_onchange │ x_1566039_seventh_critical_account │ [onChange] │ script client │
126
- │ 2 │ cs_task_onload │ task │ [onLoad] │ script client │
127
- │ 3 │ cs_task_onchange_priority │ x_1566039_seventh_critical_account_incident_ext │ [onChange] │ script client │
128
- │ 4 │ cs_incident_onload │ incident │ [onLoad] │ script client │
129
- │ 5 │ cs_incident_onchange_caller │ incident │ [onChange] │ script client │
130
- │ 6 │ cs_account_onchange_type │ x_1566039_seventh_account │ [onChange] │ script client │
131
- │ 7 │ cs_alert_onload │ x_1566039_seventh_fraud_alert │ [onLoad] │ script client │
132
- │ 8 │ cs_risk_onchange_score │ x_1566039_seventh_risk_score │ [onChange] │ script client │
133
- │ 9 │ Auto-close empty Change Requests │ change_request │ [action] │ script │
134
- │ 10 │ View car info │ x_snc_ts_custom_cars │ [action] │ ui action │
135
- │ 11 │ SampleScriptInclude │ [global] │ [action] │ script include │
136
- └─────────┴────────────────────────────────────┴───────────────────────────────────────────────┴──────────────┴──────────────────┘
137
-
138
- 🔒 SECURITY & ACCESS (ACLs)
139
- ┌──────────────────────────────┬───────────────────────┬───────────────────────────┐
140
- │ ACL │ Level / Roles │ Table │
141
- ├──────────────────────────────┼───────────────────────┼───────────────────────────┤
142
- │ DELETE on task.description │ Field-level,
143
- Roles: 58794a2b937f4c0eba394fce1515930e, ae7beff0df584bd7a39fac26deaf20b7 │ task │
144
- └──────────────────────────────┴───────────────────────┴───────────────────────────┘
145
73
 
146
- 🧠 PROJECT INSIGHTS
147
- • Total User Artifacts: 23
148
- • User Artifacts Breakdown:
149
- {
150
- "sys_script_client": 9,
151
- "sys_db_object": 10,
152
- "sys_script": 1,
153
- "sys_security_acl": 1,
154
- "sys_ui_action": 1,
155
- "sys_script_include": 1
156
- }
157
- • Platform Dependencies: 9
158
- • Internal References: 132
159
- • Total Artifacts: 181
160
- • Total Relationships: 141
74
+ Client Script 9 artifacts
75
+ Table 10 artifacts
76
+ Business Rule 1 artifact
77
+ Flow Definition 1 artifact
78
+ Catalog Item 2 artifacts
79
+ Acl 1 artifact
80
+ Ui Action 1 artifact
161
81
 
82
+ 🧠 PROJECT INSIGHTS
83
+ Total User Artifacts: 35
84
+ Platform Dependencies: 9
85
+ Total Relationships: 141
162
86
  ```
163
87
 
164
- **Generated file:** `fluent-graph.json` (in project root)
88
+ Also writes `fluent-graph.json` to your project root for CI/CD or tooling use.
165
89
 
166
90
  ---
167
91
 
168
- ### Blast Radius Analysis
169
-
170
- Analyze the impact of changing a specific table:
92
+ ### Blast — impact analysis for a specific artifact
171
93
 
172
94
  ```bash
173
- fluent-graph blast incident
95
+ fluent-graph blast <table_or_artifact_name>
174
96
  ```
175
97
 
176
- **Output:**
98
+ Example:
99
+ ```bash
100
+ fluent-graph blast x_1566039_seventh_customer
177
101
  ```
178
- [FLUENT-GRAPH] BLAST RADIUS REPORT
179
- Target: incident [sys_db_object]
180
- SysID: 26441130e60544259e930cb385f74fca
181
- =========================================================================================
182
-
183
- ┌──────────────────────────┬─────────────────┬──────────────────────────────┬─────────────────────────────────┬──────────────────────┐
184
- │ Impacted Artifact │ Type │ File │ Reason │ State │
185
- ├──────────────────────────┼─────────────────┼──────────────────────────────┼─────────────────────────────────┼──────────────────────┤
186
- │ bank_incident_onload │ client_script │ src/fluent/bank_small_... │ ⚡ Logic Attachment [onLoad] │ INSERT_OR_UPDATE │
187
- │ cs_incident_onload │ client_script │ src/fluent/client-scripts... │ ⚡ Logic Attachment [onLoad] │ INSERT_OR_UPDATE │
188
- │ cs_incident_onchange_... │ client_script │ src/fluent/client-scripts... │ ⚡ Logic Attachment [onChange] │ INSERT_OR_UPDATE │
189
- └──────────────────────────┴─────────────────┴──────────────────────────────┴─────────────────────────────────┴──────────────────────┘
190
102
 
191
- ⚠️ PRE-DEPLOYMENT SUMMARY
192
- - Total Impacted: 3 artifacts
193
- - Breakdown:
194
- • client_script: 3
195
103
  ```
104
+ [FLUENT-GRAPH] BLAST RADIUS REPORT
105
+ Target: x_1566039_seventh_customer
196
106
 
197
- ---
107
+ ┌────────────────────────────────┬───────────────────┬──────────────────────────────┐
108
+ │ Impacted Artifact │ Type │ Reason │
109
+ ├────────────────────────────────┼───────────────────┼──────────────────────────────┤
110
+ │ x_1566039_seventh_account │ table │ Reference field: owner │
111
+ │ x_1566039_seventh_call_case │ table │ Reference field: customer │
112
+ │ cs_account_onchange_type │ client_script │ Logic attachment │
113
+ └────────────────────────────────┴───────────────────┴──────────────────────────────┘
198
114
 
199
- ## Output Format
200
-
201
- The generated `fluent-graph.json` contains:
202
-
203
- ```json
204
- {
205
- "metadata": {
206
- "projectRoot": "/path/to/project",
207
- "scopeId": "59760b6f783848bd981362d6b1d0c7ed",
208
- "scopeName": "x_1566039_seventh",
209
- "recordCount": 171,
210
- "referenceCount": 15,
211
- "compositionCount": 111,
212
- "generatedAt": "2025-01-04T16:32:54.130Z",
213
- "sdkVersion": "4.1.0"
214
- },
215
- "nodes": [
216
- {
217
- "id": "6eed3050f8214b6194056935182d9fa5",
218
- "table": "sys_db_object",
219
- "name": "x_1566039_seventh_customer",
220
- "label": "Customer",
221
- "action": "INSERT_OR_UPDATE",
222
- "attributes": {
223
- "access": "public",
224
- "is_extendable": false,
225
- "read_access": true
226
- },
227
- "source": {
228
- "file": "src/fluent/bank_small_artifacts.now.ts",
229
- "type": "VariableStatement"
230
- }
231
- }
232
- ],
233
- "edges": [
234
- {
235
- "from": "4da5b7b689ae43e69b3db1bfe1dd0cd5",
236
- "to": "0fc60d0f1c35401580488c83440a4d81",
237
- "via": "owner",
238
- "type": "reference",
239
- "targetTable": "x_1566039_seventh_customer"
240
- }
241
- ]
242
- }
115
+ ⚠️ PRE-DEPLOYMENT SUMMARY
116
+ Total Impacted: 3 artifacts
243
117
  ```
244
118
 
245
- ### Node Types
246
-
247
- | `table` Value | Description |
248
- |---------------|-------------|
249
- | `sys_db_object` | Database table definition |
250
- | `sys_dictionary` | Column/field definition |
251
- | `sys_script_client` | Client script (onLoad, onChange, etc.) |
252
- | `sys_script` | Business rule |
253
- | `sys_choice` | Choice list value |
254
-
255
- ### Edge Types
256
-
257
- | `type` | Description |
258
- |--------|-------------|
259
- | `reference` | Foreign key or logic attachment |
260
- | `composition` | Parent-child relationship (e.g., table → columns) |
261
-
262
119
  ---
263
120
 
264
- ## How It Works
265
-
266
- `fluent-graph` does **not** parse your TypeScript/Fluent code directly.
267
-
268
- Instead, it:
269
-
270
- 1. **Locates the SDK** installed in `node_modules/@servicenow/sdk`
271
- 2. **Loads your Fluent project** using the SDK's internal `Project` API
272
- 3. **Observes SDK compilation** to extract already-parsed artifacts
273
- 4. **Builds a dependency graph** from SDK-provided metadata
274
- 5. **Outputs structured JSON** for analysis or automation
275
-
276
- This approach:
277
- - ✅ Works across SDK versions (no brittle AST parsing)
278
- - ✅ Captures runtime behavior (e.g., dynamic references)
279
- - ✅ Stays synchronized with SDK semantics
280
-
281
- ---
282
-
283
- ## Use Cases
284
-
285
- ### 1. Pre-Deployment Impact Analysis
286
- ```bash
287
- fluent-graph blast incident > pre-deploy-report.txt
288
- ```
121
+ ## CI/CD Integration
289
122
 
290
- ### 2. CI/CD Integration
291
123
  ```yaml
292
124
  # .github/workflows/fluent-check.yml
293
- - name: Extract lineage
294
- run: npx fluent-graph analyze
125
+ - name: Analyze lineage
126
+ run: npx @yesprasad/fluent-graph analyze
295
127
 
296
- - name: Check for conflicts
128
+ - name: Fail on identity conflicts
297
129
  run: |
298
130
  if grep -q '"action": "CONFLICT"' fluent-graph.json; then
299
131
  echo "❌ Identity conflicts detected"
@@ -301,92 +133,19 @@ fluent-graph blast incident > pre-deploy-report.txt
301
133
  fi
302
134
  ```
303
135
 
304
- ### 3. Documentation Generation
305
- Parse `fluent-graph.json` to auto-generate:
306
- - Schema diagrams
307
- - Dependency matrices
308
- - Change impact reports
309
-
310
136
  ---
311
137
 
312
- ## Performance
313
-
314
- Typical extraction times on SDK 4.1.x:
315
-
316
- | Project Size | Artifacts | Extraction Time |
317
- |--------------|-----------|-----------------|
318
- | Small | 50-100 | < 5 seconds |
319
- | Medium | 100-500 | 5-10 seconds |
320
- | Large | 500-1000 | 10-20 seconds |
321
- | Enterprise | 1000+ | 20-30 seconds |
322
-
323
- *Times measured on MacBook Air M1, 16GB RAM and approximated*
324
-
325
-
326
138
  ## Limitations
327
139
 
328
- ### Current Version (v0.1)
329
-
330
- - **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.
331
-
332
- - **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.
333
-
334
- - **No UI visualization:** Output is JSON-only. Use external tools (e.g., D3.js, Mermaid) to render graphs.
335
-
336
- - **Single-project scope:** Does not analyze cross-scope dependencies (e.g., references to `global` tables outside your app scope).
337
-
338
- ---
339
-
340
- ## Roadmap
341
-
342
- - [ ] Improve FK edge extraction: Currently misses some ReferenceColumn relationships when table nodes don't exist
343
- - [ ] Add ACL/UI Policy/UI Action support to blast radius
344
- - [ ] Support SDK 4.0.x (test against 3 versions: 4.0, 4.1, 4.2)
345
- - [ ] HTML report with interactive D3.js graph visualization
346
- - [ ] `--watch` mode: Re-extract on file changes during development
347
- - [ ] Cross-scope analysis: Detect dependencies on global/platform apps
348
- - [ ] Adding unit test cases
349
-
350
- ---
351
-
352
- ### Development Setup
353
- ```bash
354
- git clone https://github.com/yesprasad/fluent-graph
355
- cd fluent-graph
356
- npm install
357
- npm run build
358
-
359
- # Test against example project
360
- cd ../your-fluent-project
361
- npx /path/to/fluent-graph/dist/cli/index.js extract
362
- ```
363
-
364
- ### Running Tests
365
- ```bash
366
- npm test # Add Unit tests
367
- npm run test:integration # Test against real SDK project
368
- ```
140
+ - Tested against `@servicenow/sdk@4.5.x`
141
+ - No UI visualization — output is JSON and terminal only
142
+ - Single-project scope — does not trace cross-scope dependencies
369
143
 
370
144
  ---
371
145
 
372
146
  ## License
373
- MIT License
374
-
375
- Copyright (c) 2026 Eshwar Sowbhagya Prasad Yaddanapudi.
376
- 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:
377
-
378
- The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
379
-
380
- 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.
381
-
382
-
383
- ---
384
-
385
- ## Author
386
-
387
- **Eshwar Sowbhagya Prasad Yaddanapudi**
388
147
 
389
- Built with focus on making ServiceNow Pro Developer Fluent development with now-sdk safer, faster, and more transparent.
148
+ MIT License — Copyright (c) 2026 Eshwar Sowbhagya Prasad Yaddanapudi
390
149
 
391
150
  ---
392
151
 
@@ -405,4 +164,10 @@ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLI
405
164
 
406
165
  ---
407
166
 
408
- **Questions or issues?** Open an issue on GitHub or reach out directly.
167
+ **Questions or issues?** Open an issue on GitHub or reach out directly.
168
+
169
+ ## Author
170
+
171
+ **Eshwar Sowbhagya Prasad Yaddanapudi**
172
+
173
+ Questions or issues? [Open an issue on GitHub](https://github.com/yesprasad/fluent-graph/issues)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@yesprasad/fluent-graph",
3
- "version": "0.2.0",
3
+ "version": "0.2.1",
4
4
  "description": "Dependency visibility and impact analysis for ServiceNow Fluent SDK projects",
5
5
  "bin": {
6
6
  "fluent-graph": "./bin/fluent-graph.js"