@yesprasad/fluent-graph 0.1.0

package/dist/extractor/edges.d.ts

@@ -0,0 +1,11 @@
+import type { ArtifactEdge, ArtifactNode } from '../types/graphs';
+/**
+ * UNIVERSAL EDGE EXTRACTOR
+ *
+ * Strategy:
+ * 1. For every record, scan ALL properties
+ * 2. If a property looks like a reference (RecordId or string table name), create an edge
+ * 3. No hardcoded artifact types
+ */
+export declare function extractReferenceEdges(records: any, allNodes: ArtifactNode[]): ArtifactEdge[];
+export declare function extractCompositionEdges(records: any): ArtifactEdge[];

package/dist/extractor/edges.js

@@ -0,0 +1,120 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractReferenceEdges = extractReferenceEdges;
+exports.extractCompositionEdges = extractCompositionEdges;
+/**
+ * UNIVERSAL EDGE EXTRACTOR
+ *
+ * Strategy:
+ * 1. For every record, scan ALL properties
+ * 2. If a property looks like a reference (RecordId or string table name), create an edge
+ * 3. No hardcoded artifact types
+ */
+function extractReferenceEdges(records, allNodes) {
+    const edges = [];
+    for (const record of records.query()) {
+        const fromId = record.getId()?.getValue()?.toString();
+        const props = record.setProperties || {};
+        const recordTable = record.getTable()?.toString();
+        // === STRATEGY 1: SCHEMA RELATIONSHIPS ===
+        // Extract reference fields from sys_dictionary records
+        if (recordTable === 'sys_dictionary') {
+            const internalType = props.internal_type?.getValue?.()?.toString();
+            const refTable = props.reference?.getValue?.()?.toString();
+            const elementName = props.element?.getValue?.()?.toString();
+            if (internalType === 'reference' && refTable) {
+                const targetNode = allNodes.find(n => n.name === refTable);
+                edges.push({
+                    from: fromId,
+                    to: targetNode?.id || `platform:${refTable}`,
+                    via: elementName || 'reference',
+                    type: 'schema_relationship'
+                });
+            }
+        }
+        // === STRATEGY 2: LOGIC ATTACHMENTS ===
+        // Any artifact with 'table' or 'collection' property
+        const tableRef = props.table?.getValue?.()?.toString() ||
+            props.collection?.getValue?.()?.toString();
+        if (tableRef) {
+            const targetNode = allNodes.find(n => n.name === tableRef);
+            edges.push({
+                from: fromId,
+                to: targetNode?.id || `platform:${tableRef}`,
+                via: props.table ? 'table' : 'collection',
+                type: 'dependency',
+                targetTable: tableRef // Added: Set targetTable for consistency (fixes fallback in display for platform tables)
+            });
+        }
+        // === STRATEGY 3: ACL NAME PARSING ===
+        // sys_security_acl uses 'name' field like 'task.description'
+        if (recordTable === 'sys_security_acl') {
+            const aclName = props.name?.getValue?.()?.toString();
+            if (aclName && aclName.includes('.')) {
+                const [targetTable] = aclName.split('.');
+                const targetNode = allNodes.find(n => n.name === targetTable);
+                edges.push({
+                    from: fromId,
+                    to: targetNode?.id || `platform:${targetTable}`,
+                    via: 'name',
+                    type: 'dependency',
+                    targetTable
+                });
+            }
+        }
+        // === STRATEGY 4: UNIVERSAL REFERENCE SCAN ===
+        // Scan ALL properties for RecordId types (sys_id references)
+        for (const [key, val] of Object.entries(props)) {
+            // Added: Handle arrays of RecordId (e.g., roles: [role1, role2]) to create multiple edges
+            if (Array.isArray(val)) {
+                val.forEach((item) => {
+                    if (item && item.constructor?.name === 'RecordId') {
+                        const targetId = item.getValue?.()?.toString();
+                        const targetTable = item.getTable?.()?.toString();
+                        if (targetId && targetTable !== 'sys_db_object') {
+                            edges.push({
+                                from: fromId,
+                                to: targetId,
+                                via: key,
+                                type: 'dependency',
+                                targetTable
+                            });
+                        }
+                    }
+                });
+            }
+            else if (val && val.constructor?.name === 'RecordId') {
+                const targetId = val.getValue?.()?.toString();
+                const targetTable = val.getTable?.()?.toString();
+                if (targetId && targetTable !== 'sys_db_object') {
+                    edges.push({
+                        from: fromId,
+                        to: targetId,
+                        via: key,
+                        type: 'dependency',
+                        targetTable
+                    });
+                }
+            }
+        }
+    }
+    return edges;
+}
+function extractCompositionEdges(records) {
+    const edges = [];
+    for (const record of records.query()) {
+        const parentId = record.getId()?.getValue()?.toString();
+        const children = record.getRelated?.() || [];
+        for (const child of children) {
+            const childId = child.getId()?.getValue()?.toString();
+            if (childId && parentId) {
+                edges.push({
+                    from: parentId,
+                    to: childId,
+                    type: 'composition'
+                });
+            }
+        }
+    }
+    return edges;
+}

package/dist/extractor/index.d.ts

@@ -0,0 +1,2 @@
+import type { LineageGraph } from '../types/graphs';
+export declare function extractLineageGraph(project: any): Promise<LineageGraph>;

package/dist/extractor/index.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractLineageGraph = extractLineageGraph;
+const nodes_1 = require("./nodes");
+const edges_1 = require("./edges");
+const metadata_1 = require("./metadata");
+async function extractLineageGraph(project) {
+    // Get raw records from the ServiceNow SDK Project
+    const records = await project.getRecords();
+    const rootDir = project.getRootDir();
+    // 1. Extract Nodes (Includes dynamic attributes like order, when, active)
+    const nodes = (0, nodes_1.extractNodes)(records, rootDir);
+    // 2. Extract Edges (Requires node list for implicit string-to-table resolution)
+    const referenceEdges = (0, edges_1.extractReferenceEdges)(records, nodes);
+    const compositionEdges = (0, edges_1.extractCompositionEdges)(records);
+    const edges = [...referenceEdges, ...compositionEdges];
+    // 3. Generate Summary Metadata
+    const metadata = (0, metadata_1.generateMetadata)(project, records.query().length, referenceEdges.length, compositionEdges.length);
+    return {
+        metadata,
+        nodes,
+        edges
+    };
+}

package/dist/extractor/metadata.d.ts

@@ -0,0 +1,6 @@
+import type { GraphMetadata } from '../types/graphs';
+/**
+ * Generates the Global Graph Summary.
+ * provide architectural context for the extracted lineage.
+ */
+export declare function generateMetadata(project: any, recordCount: number, referenceCount: number, compositionCount: number): GraphMetadata;

package/dist/extractor/metadata.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateMetadata = generateMetadata;
+/**
+ * Generates the Global Graph Summary.
+ * provide architectural context for the extracted lineage.
+ */
+function generateMetadata(project, recordCount, referenceCount, compositionCount) {
+    // These calls safely interact with the SDK Project Proxy
+    const config = project.getConfig() || {};
+    const pkg = project.getPackage() || {};
+    return {
+        projectRoot: project.getRootDir() || process.cwd(),
+        /**
+         * Identification:
+         * Essential for determining the "Home Scope" of the graph.
+         */
+        scopeId: config.scopeId || 'unknown',
+        scopeName: config.scope || 'Global',
+        /**
+         * Quantitative Metrics:
+         * recordCount represents the Vertex count (Nodes).
+         * referenceCount + compositionCount represents the Edge density.
+         */
+        recordCount,
+        referenceCount,
+        compositionCount,
+        /**
+         * Temporal & Environment context:
+         * Helps the CLI determine if the graph file is stale.
+         */
+        generatedAt: new Date().toISOString(),
+        sdkVersion: pkg.dependencies?.['@servicenow/sdk'] ||
+            pkg.devDependencies?.['@servicenow/sdk'] ||
+            'unknown'
+    };
+}

package/dist/extractor/nodes.d.ts

@@ -0,0 +1,2 @@
+import type { ArtifactNode } from '../types/graphs';
+export declare function extractNodes(records: any, projectRoot: string): ArtifactNode[];

package/dist/extractor/nodes.js

@@ -0,0 +1,64 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractNodes = extractNodes;
+const path_1 = __importDefault(require("path"));
+/**
+ * UNIVERSAL NODE EXTRACTOR
+ *
+ * Strategy:
+ * - Extract ALL primitive attributes (strings, numbers, booleans)
+ * - Ignore complex objects (they become edges)
+ * - Preserve metadata like 'element', 'name', 'type' for display logic
+ */
+function sanitizeAttributes(props) {
+    const clean = {};
+    for (const [key, val] of Object.entries(props)) {
+        if (!val)
+            continue;
+        try {
+            // Extract the primitive value if it's a SDK wrapper
+            const plainValue = typeof val.getValue === 'function'
+                ? val.getValue()
+                : val;
+            // Only keep primitives and arrays of primitives
+            if (typeof plainValue !== 'object' || plainValue === null || Array.isArray(plainValue)) {
+                clean[key] = plainValue;
+            }
+        }
+        catch (e) {
+            continue;
+        }
+    }
+    return clean;
+}
+function extractNodes(records, projectRoot) {
+    const nodes = [];
+    for (const record of records.query()) {
+        const props = record.setProperties || {};
+        const idValue = record.getId()?.getValue()?.toString() || '';
+        const tableName = record.getTable()?.toString() || '';
+        // Determine a human-readable name
+        const name = props.name?.getValue?.()?.toString() ||
+            props.label?.getValue?.()?.toString() ||
+            props.sys_name?.getValue?.()?.toString() ||
+            idValue;
+        // Capture file source (relative to project root)
+        const rawFile = record.getOriginalFilePath()?.toString() || '';
+        const relativeFile = rawFile ? path_1.default.relative(projectRoot, rawFile) : '';
+        nodes.push({
+            id: idValue,
+            table: tableName,
+            action: record.getAction(),
+            name,
+            attributes: sanitizeAttributes(props),
+            source: {
+                file: relativeFile,
+                type: record.getOriginalSource()?.getKindName?.() || 'SourceFile'
+            }
+        });
+    }
+    return nodes;
+}

package/dist/graph/extractor.d.ts

@@ -0,0 +1,6 @@
+import type { LineageGraph } from '../types/graphs';
+/**
+ * The Orchestrator: Converts raw SDK records into a formal Directed Graph.
+ * It treats every artifact as a node and every relationship as an iterable edge.
+ */
+export declare function extractLineageGraph(project: any): Promise<LineageGraph>;

package/dist/graph/extractor.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractLineageGraph = extractLineageGraph;
+const nodes_1 = require("../extractor/nodes");
+const edges_1 = require("../extractor/edges");
+const metadata_1 = require("../extractor/metadata");
+/**
+ * The Orchestrator: Converts raw SDK records into a formal Directed Graph.
+ * It treats every artifact as a node and every relationship as an iterable edge.
+ */
+async function extractLineageGraph(project) {
+    const records = project.getRecords();
+    const projectRoot = project.getRootDir();
+    // 1. PHASE ONE: Vertex Extraction (Nodes)
+    // We only extract the "winning" records to avoid conflict noise.
+    // This creates the list of local artifacts.
+    const nodes = (0, nodes_1.extractNodes)(records, projectRoot);
+    // 2. PHASE TWO: Edge Extraction (Relationships)
+    // We pass the 'nodes' array into extractReferenceEdges.
+    // This allows the edge extractor to differentiate between:
+    // a) A reference to a local table (e.g. x_1566039_seventh_account)
+    // b) A reference to a platform table (e.g. platform:incident)
+    const refEdges = (0, edges_1.extractReferenceEdges)(records, nodes);
+    const compEdges = (0, edges_1.extractCompositionEdges)(records);
+    const allEdges = [...refEdges, ...compEdges];
+    // 3. PHASE THREE: Metadata & Context
+    // Calculate graph-wide statistics and SDK versioning.
+    const metadata = (0, metadata_1.generateMetadata)(project, nodes.length, refEdges.length, compEdges.length);
+    return {
+        metadata,
+        nodes,
+        edges: allEdges
+    };
+}

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./extractor"), exports);
+__exportStar(require("./types/graphs"), exports);

package/dist/output/writer.d.ts

@@ -0,0 +1,9 @@
+import type { LineageGraph } from '../types/graphs';
+/**
+ * Write lineage graph to JSON file
+ */
+export declare function writeGraph(graph: LineageGraph, outputPath: string): void;
+/**
+ * Generate default output filename with timestamp
+ */
+export declare function getDefaultOutputPath(projectRoot: string): string;

package/dist/output/writer.js

@@ -0,0 +1,28 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writeGraph = writeGraph;
+exports.getDefaultOutputPath = getDefaultOutputPath;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+/**
+ * Write lineage graph to JSON file
+ */
+function writeGraph(graph, outputPath) {
+    const formatted = JSON.stringify(graph, null, 2);
+    // Ensure directory exists
+    const dir = path_1.default.dirname(outputPath);
+    if (!fs_1.default.existsSync(dir)) {
+        fs_1.default.mkdirSync(dir, { recursive: true });
+    }
+    fs_1.default.writeFileSync(outputPath, formatted, 'utf-8');
+}
+/**
+ * Generate default output filename with timestamp
+ */
+function getDefaultOutputPath(projectRoot) {
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    return path_1.default.join(projectRoot, `fluent-graph-${timestamp}.json`);
+}

package/dist/sdk/detector.d.ts

@@ -0,0 +1,6 @@
+export interface SDKDetectionResult {
+    found: boolean;
+    sdkPath?: string;
+    error?: string;
+}
+export declare const detectSDK: (cwd: string) => Promise<SDKDetectionResult>;

package/dist/sdk/detector.js

@@ -0,0 +1,32 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectSDK = void 0;
+const path_1 = __importDefault(require("path"));
+const fs_1 = __importDefault(require("fs"));
+const detectSDK = async (cwd) => {
+    // Step 1: Check if node_modules exist
+    const nodeModulesPath = path_1.default.join(cwd, 'node_modules');
+    if (!fs_1.default.existsSync(nodeModulesPath)) {
+        return {
+            found: false,
+            error: 'node_modules not found. Run npm install first.'
+        };
+    }
+    // Step 2: Check if @servicenow/sdk exists
+    const sdkPath = path_1.default.join(nodeModulesPath, '@servicenow', 'sdk');
+    if (!fs_1.default.existsSync(sdkPath)) {
+        return {
+            found: false,
+            error: '@servicenow/sdk not found. This is not a ServiceNow Fluent project.'
+        };
+    }
+    // Step 3: Success
+    return {
+        found: true,
+        sdkPath
+    };
+};
+exports.detectSDK = detectSDK;

package/dist/sdk/loader.d.ts

@@ -0,0 +1,5 @@
+export interface WorkspaceSDK {
+    buildCore: any;
+    sdkapi: any;
+}
+export declare function loadWorkspaceSDK(sdkPath: string): WorkspaceSDK;

package/dist/sdk/loader.js

@@ -0,0 +1,15 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadWorkspaceSDK = loadWorkspaceSDK;
+const module_1 = require("module");
+const path_1 = __importDefault(require("path"));
+function loadWorkspaceSDK(sdkPath) {
+    const requireFromWorkspace = (0, module_1.createRequire)(path_1.default.join(sdkPath, 'package.json'));
+    return {
+        buildCore: requireFromWorkspace('@servicenow/sdk-build-core'),
+        sdkapi: requireFromWorkspace('@servicenow/sdk-api'),
+    };
+}

package/dist/types/graphs.d.ts

@@ -0,0 +1,35 @@
+export interface ArtifactNode {
+    id: string;
+    table: string;
+    name: string;
+    label?: string;
+    action: 'INSERT_OR_UPDATE' | 'DELETE';
+    attributes: Record<string, any>;
+    source: {
+        file: string;
+        type: string;
+    };
+}
+export interface ArtifactEdge {
+    from: string;
+    to: string;
+    via?: string;
+    type: 'reference' | 'composition' | 'dependency' | 'inheritance' | 'schema_relationship';
+    targetTable?: string;
+    childTable?: string;
+}
+export interface GraphMetadata {
+    projectRoot: string;
+    scopeId: string;
+    scopeName: string;
+    recordCount: number;
+    referenceCount: number;
+    compositionCount: number;
+    generatedAt: string;
+    sdkVersion: string;
+}
+export interface LineageGraph {
+    nodes: ArtifactNode[];
+    edges: ArtifactEdge[];
+    metadata: GraphMetadata;
+}

package/dist/types/graphs.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@yesprasad/fluent-graph",
+  "version": "0.1.0",
+  "description": "Dependency/ Lineage graph extraction & Blast-radius/ impact analysis for ServiceNow Fluent Artifacts",
+  "bin": {
+    "fluent-graph": "./bin/fluent-graph.js"
+  },
+  "main": "dist/index.js",
+"types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "bin"
+  ],
+  "scripts": {
+    "build": "tsc && chmod +x bin/fluent-graph.js",
+    "dev": "tsx src/cli/index.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "servicenow",
+    "fluent",
+    "lineage",
+    "dependency-graph",
+    "blast-radius",
+    "impact-analysis",
+    "cli"
+  ],
+  "author": "Eshwar Sowbhagya Prasad Yaddanapudi",
+  "repository": {
+  "type": "git",
+  "url": "https://github.com/yesprasad/fluent-graph.git"
+},
+"bugs": {
+  "url": "https://github.com/yesprasad/fluent-graph/issues"
+},
+"homepage": "https://github.com/yesprasad/fluent-graph#readme",
+  "license": "MIT",
+  "type": "commonjs",
+  "dependencies": {
+    "chalk": "^4.1.2",
+    "cli-table3": "^0.6.5",
+    "commander": "^12.0.0",
+    "ora": "^5.4.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
+  },
+  "peerDependencies": {
+    "@servicenow/sdk": "4.1.0"
+  }
+}