@yesprasad/fluent-graph 0.2.2 → 0.2.3

package/dist/extractor/edges.js

@@ -1,136 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.extractReferenceEdges = extractReferenceEdges;
-exports.extractCompositionEdges = extractCompositionEdges;
-/**
- * UNIVERSAL EDGE EXTRACTOR
- *
- * Strategy:
- * 1. Property-based schema relationship detection (internal_type=reference)
- * 2. Logic attachment via table/collection property
- * 3. ACL name parsing — detected via registry plugin name
- * 4. Universal RecordId scan across all properties
- */
-function extractReferenceEdges(records, allNodes, registry) {
-    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 ===
-        // Detect by properties: any record with internal_type=reference and a reference property
-        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
-            });
-        }
-        // === STRATEGY 3: ACL NAME PARSING ===
-        // Detect ACL records by plugin name (registry-derived) rather than hardcoded table name
-        if (registry.getPluginName(recordTable) === 'AclPlugin') {
-            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 and Record types (sys_id references).
-        // RecordId: getValue() = sys_id, getTable() = table name.
-        // Record:   getId().getValue() = sys_id; table resolved via allNodes lookup.
-        //           Used by SDK for cross-artifact references like flow_designer_flow on CatalogItem.
-        for (const [key, val] of Object.entries(props)) {
-            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 && registry.getPluginName(targetTable) !== 'TablePlugin') {
-                            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 && registry.getPluginName(targetTable) !== 'TablePlugin') {
-                    edges.push({
-                        from: fromId,
-                        to: targetId,
-                        via: key,
-                        type: 'dependency',
-                        targetTable
-                    });
-                }
-            }
-            else if (val && val.constructor?.name === 'Record') {
-                const targetId = val.getId?.()?.getValue?.()?.toString();
-                if (targetId) {
-                    const targetNode = allNodes.find(n => n.id === targetId);
-                    if (targetNode && registry.getPluginName(targetNode.table) !== 'TablePlugin') {
-                        edges.push({
-                            from: fromId,
-                            to: targetId,
-                            via: key,
-                            type: 'dependency',
-                            targetTable: targetNode.table
-                        });
-                    }
-                }
-            }
-        }
-    }
-    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

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

package/dist/extractor/index.js

@@ -1,24 +0,0 @@
-"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, registry) {
-    // 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, registry);
-    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

@@ -1,6 +0,0 @@
-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

@@ -1,37 +0,0 @@
-"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

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

package/dist/extractor/nodes.js

@@ -1,64 +0,0 @@
-"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

@@ -1,7 +0,0 @@
-import { ArtifactTypeRegistry } from '../sdk/registry';
-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, registry?: ArtifactTypeRegistry): Promise<LineageGraph>;

package/dist/graph/extractor.js

@@ -1,36 +0,0 @@
-"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");
-const registry_1 = require("../sdk/registry");
-/**
- * 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, registry) {
-    const records = project.getRecords();
-    const projectRoot = project.getRootDir();
-    const reg = registry ?? new registry_1.ArtifactTypeRegistry();
-    // 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, reg);
-    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/output/writer.d.ts

@@ -1,9 +0,0 @@
-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

@@ -1,28 +0,0 @@
-"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

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

package/dist/sdk/detector.js

@@ -1,32 +0,0 @@
-"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

@@ -1,7 +0,0 @@
-import { ArtifactTypeRegistry } from './registry';
-export interface WorkspaceSDK {
-    buildCore: any;
-    sdkapi: any;
-    registry: ArtifactTypeRegistry;
-}
-export declare function loadWorkspaceSDK(sdkPath: string): WorkspaceSDK;

package/dist/sdk/loader.js

@@ -1,19 +0,0 @@
-"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"));
-const registry_1 = require("./registry");
-function loadWorkspaceSDK(sdkPath) {
-    const requireFromWorkspace = (0, module_1.createRequire)(path_1.default.join(sdkPath, 'package.json'));
-    const registry = new registry_1.ArtifactTypeRegistry();
-    registry.load(sdkPath);
-    return {
-        buildCore: requireFromWorkspace('@servicenow/sdk-build-core'),
-        sdkapi: requireFromWorkspace('@servicenow/sdk-api'),
-        registry,
-    };
-}

package/dist/sdk/registry.d.ts

@@ -1,30 +0,0 @@
-interface TableInfo {
-    table: string;
-    pluginName: string;
-    isChild: boolean;
-    parentTable?: string;
-    parentVia?: string;
-    children: string[];
-}
-export declare class ArtifactTypeRegistry {
-    private tables;
-    load(sdkPath: string): void;
-    private register;
-    /**
-     * Parse the top-level relationships map:
-     * { parentTable: { childTable: { via, descendant, relationships: { grandchild: ... } } } }
-     */
-    private parseRelationships;
-    private processChildren;
-    get(table: string): TableInfo | undefined;
-    getPluginName(table: string): string;
-    getDisplayGroupName(table: string): string;
-    isChild(table: string): boolean;
-    getParentTable(table: string): string | undefined;
-    getChildren(table: string): string[];
-    getTablesByPlugin(pluginName: string): string[];
-    getAllPluginNames(): string[];
-    getAllTables(): string[];
-    isKnown(table: string): boolean;
-}
-export {};

package/dist/sdk/registry.js

@@ -1,128 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ArtifactTypeRegistry = void 0;
-const module_1 = require("module");
-const path_1 = __importDefault(require("path"));
-class ArtifactTypeRegistry {
-    constructor() {
-        this.tables = new Map();
-    }
-    load(sdkPath) {
-        try {
-            const requireFromWorkspace = (0, module_1.createRequire)(path_1.default.join(sdkPath, 'package.json'));
-            const buildPlugins = requireFromWorkspace('@servicenow/sdk-build-plugins');
-            for (const [, value] of Object.entries(buildPlugins)) {
-                const plugin = value;
-                if (!plugin?.config?.name)
-                    continue;
-                const pluginName = plugin.config.name;
-                const tables = Object.keys(plugin.config.records || {}).filter(k => k !== '*');
-                if (tables.length === 0)
-                    continue;
-                for (const table of tables) {
-                    this.register(table, pluginName);
-                }
-                try {
-                    const rels = plugin.getRelationships();
-                    if (rels && typeof rels === 'object') {
-                        this.parseRelationships(rels, pluginName);
-                    }
-                }
-                catch {
-                    // safe to skip — needs compiler context
-                }
-            }
-        }
-        catch {
-            // sdk-build-plugins unavailable; registry stays empty, fallback behavior applies
-        }
-    }
-    register(table, pluginName) {
-        if (!this.tables.has(table)) {
-            this.tables.set(table, { table, pluginName, isChild: false, children: [] });
-        }
-    }
-    /**
-     * Parse the top-level relationships map:
-     * { parentTable: { childTable: { via, descendant, relationships: { grandchild: ... } } } }
-     */
-    parseRelationships(rels, pluginName) {
-        for (const [parentTable, childDefs] of Object.entries(rels)) {
-            this.register(parentTable, pluginName);
-            if (childDefs && typeof childDefs === 'object') {
-                this.processChildren(childDefs, pluginName, parentTable);
-            }
-        }
-    }
-    processChildren(childDefs, pluginName, parentTable) {
-        for (const [key, def] of Object.entries(childDefs)) {
-            // Skip meta-keys and self-referential entries
-            if (key === 'via' || key === 'descendant' || key === 'relationships')
-                continue;
-            if (key === parentTable)
-                continue;
-            const childTable = key;
-            this.register(childTable, pluginName);
-            const entry = this.tables.get(childTable);
-            if (!entry.isChild) {
-                entry.isChild = true;
-                entry.parentTable = parentTable;
-                if (def && typeof def === 'object' && typeof def.via === 'string') {
-                    entry.parentVia = def.via;
-                }
-            }
-            // Add to parent's children list
-            const parentEntry = this.tables.get(parentTable);
-            if (parentEntry && !parentEntry.children.includes(childTable)) {
-                parentEntry.children.push(childTable);
-            }
-            // Recurse into nested relationships
-            if (def && typeof def === 'object' && def.relationships && typeof def.relationships === 'object') {
-                this.processChildren(def.relationships, pluginName, childTable);
-            }
-        }
-    }
-    get(table) {
-        return this.tables.get(table);
-    }
-    getPluginName(table) {
-        return this.tables.get(table)?.pluginName ?? 'Record';
-    }
-    getDisplayGroupName(table) {
-        const entry = this.tables.get(table);
-        if (!entry)
-            return 'Other';
-        return entry.pluginName
-            .replace(/Plugin$/, '')
-            .replace(/([a-z])([A-Z])/g, '$1 $2')
-            .replace(/^./, c => c.toUpperCase())
-            .trim();
-    }
-    isChild(table) {
-        return this.tables.get(table)?.isChild ?? false;
-    }
-    getParentTable(table) {
-        return this.tables.get(table)?.parentTable;
-    }
-    getChildren(table) {
-        return this.tables.get(table)?.children ?? [];
-    }
-    getTablesByPlugin(pluginName) {
-        return [...this.tables.values()]
-            .filter(t => t.pluginName === pluginName)
-            .map(t => t.table);
-    }
-    getAllPluginNames() {
-        return [...new Set([...this.tables.values()].map(t => t.pluginName))].sort();
-    }
-    getAllTables() {
-        return [...this.tables.keys()];
-    }
-    isKnown(table) {
-        return this.tables.has(table);
-    }
-}
-exports.ArtifactTypeRegistry = ArtifactTypeRegistry;

package/dist/types/graphs.d.ts

@@ -1,35 +0,0 @@
-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

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