@grafema/util 0.3.0-beta

package/dist/api/GuaranteeAPI.js

@@ -0,0 +1,290 @@
+/**
+ * GuaranteeAPI - CRUD API for contract-based guarantees
+ *
+ * Contract-based guarantees use JSON schema validation instead of Datalog rules.
+ * They have namespaced types: guarantee:queue, guarantee:api, guarantee:permission
+ *
+ * This API complements GuaranteeManager which handles Datalog-based GUARANTEE nodes.
+ */
+import { GuaranteeNode } from '../core/nodes/GuaranteeNode.js';
+// Lazy-loaded Ajv instance to avoid import issues
+let ajvInstance = null;
+async function getAjv() {
+    if (!ajvInstance) {
+        const AjvModule = await import('ajv');
+        // Handle both ESM default export and CJS module.exports
+        const AjvClass = AjvModule.default || AjvModule;
+        // Use Function constructor pattern to avoid TS2351
+        const createAjv = AjvClass;
+        ajvInstance = new createAjv({ allErrors: true });
+    }
+    return ajvInstance;
+}
+/**
+ * GuaranteeAPI - CRUD operations for contract-based guarantees
+ */
+export class GuaranteeAPI {
+    graph;
+    schemaCache;
+    constructor(graph) {
+        this.graph = graph;
+        this.schemaCache = new Map();
+    }
+    /**
+     * Create a new contract-based guarantee
+     */
+    async createGuarantee(input) {
+        // Parse type to get namespace
+        const parsed = GuaranteeNode.parseId(`${input.type}#${input.name}`);
+        if (!parsed) {
+            throw new Error(`Invalid guarantee type: ${input.type}`);
+        }
+        // Create the guarantee node
+        const node = GuaranteeNode.create(parsed.namespace, input.name, {
+            priority: input.priority,
+            status: input.status,
+            owner: input.owner,
+            schema: input.schema,
+            condition: input.condition,
+            description: input.description,
+        });
+        // Validate before saving
+        const errors = GuaranteeNode.validate(node);
+        if (errors.length > 0) {
+            throw new Error(`Invalid guarantee: ${errors.join(', ')}`);
+        }
+        // Save to graph
+        await this.graph.addNode(node);
+        // Create GOVERNS edges if specified
+        if (input.governs && input.governs.length > 0) {
+            for (const targetId of input.governs) {
+                await this.addGoverns(node.id, targetId);
+            }
+        }
+        return node;
+    }
+    /**
+     * Get a guarantee by ID
+     */
+    async getGuarantee(id) {
+        const node = await this.graph.getNode(id);
+        if (!node)
+            return null;
+        // Verify it's a guarantee type
+        if (!GuaranteeNode.isGuaranteeType(node.type)) {
+            return null;
+        }
+        return node;
+    }
+    /**
+     * Find guarantees matching filter
+     */
+    async findGuarantees(filter = {}) {
+        const guarantees = [];
+        const types = this.normalizeTypeFilter(filter.type);
+        for (const type of types) {
+            for await (const node of this.graph.queryNodes({ type })) {
+                const g = node;
+                // Apply additional filters
+                if (filter.priority) {
+                    const priorities = Array.isArray(filter.priority) ? filter.priority : [filter.priority];
+                    if (!priorities.includes(g.priority))
+                        continue;
+                }
+                if (filter.status) {
+                    const statuses = Array.isArray(filter.status) ? filter.status : [filter.status];
+                    if (!statuses.includes(g.status))
+                        continue;
+                }
+                if (filter.owner && g.owner !== filter.owner)
+                    continue;
+                guarantees.push(g);
+            }
+        }
+        return guarantees;
+    }
+    /**
+     * Update a guarantee
+     */
+    async updateGuarantee(id, updates) {
+        const existing = await this.getGuarantee(id);
+        if (!existing) {
+            throw new Error(`Guarantee not found: ${id}`);
+        }
+        // Apply updates
+        const updated = {
+            ...existing,
+            ...updates,
+            updatedAt: Date.now(),
+        };
+        // Validate
+        const errors = GuaranteeNode.validate(updated);
+        if (errors.length > 0) {
+            throw new Error(`Invalid guarantee after update: ${errors.join(', ')}`);
+        }
+        // Delete old and add new (upsert)
+        await this.graph.deleteNode(id);
+        await this.graph.addNode(updated);
+        return updated;
+    }
+    /**
+     * Delete a guarantee
+     */
+    async deleteGuarantee(id) {
+        const existing = await this.getGuarantee(id);
+        if (!existing) {
+            return false;
+        }
+        // Delete GOVERNS edges
+        const edges = await this.graph.getOutgoingEdges(id, ['GOVERNS']);
+        for (const edge of edges) {
+            await this.graph.deleteEdge(edge.src, edge.dst, 'GOVERNS');
+        }
+        // Delete the node
+        await this.graph.deleteNode(id);
+        return true;
+    }
+    /**
+     * Add GOVERNS edge from guarantee to a node
+     */
+    async addGoverns(guaranteeId, nodeId) {
+        // Verify guarantee exists
+        const guarantee = await this.getGuarantee(guaranteeId);
+        if (!guarantee) {
+            throw new Error(`Guarantee not found: ${guaranteeId}`);
+        }
+        // Verify target node exists
+        const targetNode = await this.graph.getNode(nodeId);
+        if (!targetNode) {
+            throw new Error(`Target node not found: ${nodeId}`);
+        }
+        // Create GOVERNS edge
+        await this.graph.addEdge({
+            type: 'GOVERNS',
+            src: guaranteeId,
+            dst: nodeId,
+        });
+    }
+    /**
+     * Remove GOVERNS edge
+     */
+    async removeGoverns(guaranteeId, nodeId) {
+        await this.graph.deleteEdge(guaranteeId, nodeId, 'GOVERNS');
+    }
+    /**
+     * Get nodes governed by a guarantee
+     */
+    async getGoverned(guaranteeId) {
+        const edges = await this.graph.getOutgoingEdges(guaranteeId, ['GOVERNS']);
+        return edges.map(e => e.dst);
+    }
+    /**
+     * Get guarantees governing a node
+     */
+    async getGoverningGuarantees(nodeId) {
+        const edges = await this.graph.getIncomingEdges(nodeId, ['GOVERNS']);
+        const guarantees = [];
+        for (const edge of edges) {
+            const g = await this.getGuarantee(edge.src);
+            if (g)
+                guarantees.push(g);
+        }
+        return guarantees;
+    }
+    /**
+     * Check a guarantee using JSON schema validation
+     * Returns validation results for governed nodes
+     */
+    async checkGuarantee(id) {
+        const guarantee = await this.getGuarantee(id);
+        if (!guarantee) {
+            throw new Error(`Guarantee not found: ${id}`);
+        }
+        const result = {
+            id,
+            name: guarantee.name ?? id,
+            passed: true,
+            errors: [],
+            validatedCount: 0,
+        };
+        // If no schema defined, consider it passing
+        if (!guarantee.schema) {
+            return result;
+        }
+        // Get or compile schema validator
+        let validate = this.schemaCache.get(id);
+        if (!validate) {
+            try {
+                const ajv = await getAjv();
+                validate = ajv.compile(guarantee.schema);
+                this.schemaCache.set(id, validate);
+            }
+            catch (e) {
+                result.passed = false;
+                const message = e instanceof Error ? e.message : String(e);
+                result.errors.push(`Invalid schema: ${message}`);
+                return result;
+            }
+        }
+        // Get governed nodes and validate them
+        const governedIds = await this.getGoverned(id);
+        // At this point validate is guaranteed to be defined (we returned if compile failed)
+        const validator = validate;
+        for (const nodeId of governedIds) {
+            const node = await this.graph.getNode(nodeId);
+            if (!node)
+                continue;
+            result.validatedCount++;
+            const valid = validator(node);
+            if (!valid) {
+                result.passed = false;
+                const errors = validator.errors;
+                if (errors) {
+                    for (const err of errors) {
+                        result.errors.push(`${nodeId}: ${err.instancePath} ${err.message}`);
+                    }
+                }
+            }
+        }
+        return result;
+    }
+    /**
+     * Check all guarantees
+     */
+    async checkAllGuarantees() {
+        const guarantees = await this.findGuarantees();
+        const results = [];
+        let passed = 0;
+        let failed = 0;
+        for (const g of guarantees) {
+            const result = await this.checkGuarantee(g.id);
+            results.push(result);
+            if (result.passed)
+                passed++;
+            else
+                failed++;
+        }
+        return {
+            total: guarantees.length,
+            passed,
+            failed,
+            results,
+        };
+    }
+    /**
+     * Normalize type filter to array of types
+     */
+    normalizeTypeFilter(type) {
+        if (!type) {
+            return GuaranteeNode.getTypes();
+        }
+        return Array.isArray(type) ? type : [type];
+    }
+    /**
+     * Clear schema cache (useful after schema updates)
+     */
+    clearSchemaCache() {
+        this.schemaCache.clear();
+    }
+}
+//# sourceMappingURL=GuaranteeAPI.js.map

package/dist/api/GuaranteeAPI.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GuaranteeAPI.js","sourceRoot":"","sources":["../../src/api/GuaranteeAPI.ts"],"names":[],"mappings":"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"}

package/dist/config/ConfigLoader.d.ts

@@ -0,0 +1,214 @@
+import type { ServiceDefinition, RoutingRule } from '@grafema/types';
+/**
+ * Grafema configuration schema.
+ *
+ * YAML Location: .grafema/config.yaml (preferred) or .grafema/config.json (deprecated)
+ *
+ * Example config.yaml:
+ *
+ * ```yaml
+ * # Plugins for each analysis phase
+ * plugins:
+ *   indexing:
+ *     - JSModuleIndexer
+ *   analysis:
+ *     - CoreV2Analyzer
+ *     - ExpressRouteAnalyzer
+ *   enrichment:
+ *     - ExportEntityLinker
+ *   validation:
+ *     - EvalBanValidator
+ *
+ * # Optional: Explicit service definitions (bypass auto-discovery)
+ * services:
+ *   - name: "backend"
+ *     path: "apps/backend"        # Relative to project root
+ *     entryPoint: "src/index.ts"  # Optional, auto-detected if omitted
+ *   - name: "frontend"
+ *     path: "apps/frontend"
+ * ```
+ *
+ * If 'services' is not specified or empty, auto-discovery is used (SimpleProjectDiscovery).
+ * If 'services' is specified and non-empty, auto-discovery plugins are skipped entirely.
+ */
+export interface GrafemaConfig {
+    /**
+     * Config schema version (major.minor.patch, no pre-release tag).
+     * Must be compatible with the running Grafema version.
+     * If omitted, no version check is performed (backward compatibility).
+     *
+     * @example "0.2.5"
+     */
+    version?: string;
+    plugins: {
+        discovery?: string[];
+        indexing: string[];
+        analysis: string[];
+        enrichment: string[];
+        validation: string[];
+    };
+    /**
+     * Optional explicit services for manual configuration.
+     * If provided and non-empty, auto-discovery is skipped.
+     */
+    services: ServiceDefinition[];
+    /**
+     * Glob patterns for files to include during indexing (optional).
+     * See OrchestratorConfig.include for documentation.
+     */
+    include?: string[];
+    /**
+     * Glob patterns for files to exclude during indexing (optional).
+     * See OrchestratorConfig.exclude for documentation.
+     */
+    exclude?: string[];
+    /**
+     * Routing rules for cross-service URL mapping (REG-256).
+     * Describes how infrastructure (nginx, gateway) transforms URLs between services.
+     *
+     * @example
+     * ```yaml
+     * routing:
+     *   - from: frontend
+     *     to: backend
+     *     stripPrefix: /api
+     *   - from: frontend
+     *     to: auth-service
+     *     stripPrefix: /auth
+     * ```
+     */
+    routing?: RoutingRule[];
+    /**
+     * Enable strict mode for fail-fast debugging.
+     * When true, analysis fails if enrichers cannot resolve references.
+     * When false (default), graceful degradation with warnings.
+     *
+     * Can be overridden via CLI: --strict
+     */
+    strict?: boolean;
+    /**
+     * Multi-root workspace configuration (REG-76).
+     * Allows indexing multiple directories as a single unified graph.
+     * Each root is prefixed in semantic IDs to prevent collisions.
+     *
+     * @example
+     * ```yaml
+     * workspace:
+     *   roots:
+     *     - ./backend
+     *     - ./frontend
+     *     - ./shared
+     * ```
+     */
+    workspace?: WorkspaceConfig;
+    /**
+     * URI configuration for grafema:// identifiers.
+     * Used by MCP and CLI for compact<->URI conversion.
+     */
+    uri?: {
+        /** URI authority (e.g., "github.com/owner/repo"). Auto-detected if omitted. */
+        authority?: string;
+    };
+}
+/**
+ * Multi-root workspace configuration.
+ * Each root directory is indexed separately but produces a unified graph.
+ * Root names (basename of path) are prefixed to file paths in semantic IDs.
+ */
+export interface WorkspaceConfig {
+    /**
+     * List of root directories to include in the workspace.
+     * Paths are relative to the project root (where .grafema/ is located).
+     * Each root's basename is used as prefix in semantic IDs.
+     */
+    roots: string[];
+}
+/**
+ * Default plugin configuration.
+ * Matches current DEFAULT_PLUGINS in analyze.ts and config.ts (MCP).
+ */
+export declare const DEFAULT_CONFIG: GrafemaConfig;
+/**
+ * Load Grafema config from project directory.
+ *
+ * Priority:
+ * 1. config.yaml (preferred)
+ * 2. config.json (deprecated, fallback)
+ * 3. DEFAULT_CONFIG (if neither exists)
+ *
+ * Warnings:
+ * - Logs deprecation warning if config.json is used
+ * - Logs parse errors but doesn't throw (returns defaults)
+ *
+ * @param projectPath - Absolute path to project root
+ * @param logger - Optional logger for warnings (defaults to console.warn)
+ * @returns Parsed config or defaults
+ */
+export declare function loadConfig(projectPath: string, logger?: {
+    warn: (msg: string) => void;
+}): GrafemaConfig;
+/**
+ * Validate config version compatibility with running Grafema version.
+ * THROWS on error (fail loudly per project convention).
+ *
+ * Compares major.minor.patch (pre-release tags are stripped).
+ * If config has no version field, validation passes silently (backward compat).
+ *
+ * @param configVersion - Version string from config file (may be undefined)
+ * @param currentVersion - Override for testing (defaults to GRAFEMA_VERSION)
+ */
+export declare function validateVersion(configVersion: unknown, currentVersion?: string): void;
+/**
+ * Validate services array structure.
+ * THROWS on error (fail loudly per Linus review).
+ *
+ * @param services - Parsed services array (may be undefined)
+ * @param projectPath - Project root for path validation
+ */
+export declare function validateServices(services: unknown, projectPath: string): void;
+/**
+ * Validate workspace configuration (REG-76).
+ * THROWS on error (fail loudly per project convention).
+ *
+ * Validation rules:
+ * 1. workspace.roots must be an array if provided
+ * 2. Each root must be a non-empty string
+ * 3. Each root path must exist and be a directory
+ * 4. Root basenames must be unique (to prevent semantic ID collisions)
+ *
+ * @param workspace - Parsed workspace config (may be undefined)
+ * @param projectPath - Project root for path validation
+ */
+export declare function validateWorkspace(workspace: unknown, projectPath: string): void;
+/**
+ * Validate routing rules structure (REG-256).
+ * THROWS on error (fail loudly per project convention).
+ *
+ * Validation rules:
+ * 1. Must be an array if provided
+ * 2. Each rule must have 'from' and 'to' as non-empty strings
+ * 3. 'stripPrefix' must start with '/' if provided
+ * 4. 'addPrefix' must start with '/' if provided
+ * 5. 'from' and 'to' must reference services defined in the services array
+ *
+ * @param routing - Parsed routing rules (may be undefined)
+ * @param services - Parsed services array (for cross-validation)
+ */
+export declare function validateRouting(routing: unknown, services: ServiceDefinition[]): void;
+/**
+ * Validate include/exclude patterns.
+ * THROWS on error (fail loudly per project convention).
+ *
+ * Validation rules:
+ * 1. Must be arrays if provided
+ * 2. Array elements must be non-empty strings
+ * 3. Warn (don't error) if include array is empty (would exclude everything)
+ *
+ * @param include - Parsed include patterns (may be undefined)
+ * @param exclude - Parsed exclude patterns (may be undefined)
+ * @param logger - Logger for warnings
+ */
+export declare function validatePatterns(include: unknown, exclude: unknown, logger: {
+    warn: (msg: string) => void;
+}): void;
+//# sourceMappingURL=ConfigLoader.d.ts.map

package/dist/config/ConfigLoader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConfigLoader.d.ts","sourceRoot":"","sources":["../../src/config/ConfigLoader.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAGrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,OAAO,EAAE;QACP,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;QACrB,QAAQ,EAAE,MAAM,EAAE,CAAC;QACnB,QAAQ,EAAE,MAAM,EAAE,CAAC;QACnB,UAAU,EAAE,MAAM,EAAE,CAAC;QACrB,UAAU,EAAE,MAAM,EAAE,CAAC;KACtB,CAAC;IACF;;;OAGG;IACH,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAE9B;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IAEnB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IAEnB;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,EAAE,WAAW,EAAE,CAAC;IAExB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;;;;;;;;;;;;OAaG;IACH,SAAS,CAAC,EAAE,eAAe,CAAC;IAE5B;;;OAGG;IACH,GAAG,CAAC,EAAE;QACJ,+EAA+E;QAC/E,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,CAAC;CACH;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;;GAGG;AACH,eAAO,MAAM,cAAc,EAAE,aA0C5B,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,UAAU,CACxB,WAAW,EAAE,MAAM,EACnB,MAAM,GAAE;IAAE,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;CAAY,GAChD,aAAa,CAsFf;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC7B,aAAa,EAAE,OAAO,EACtB,cAAc,CAAC,EAAE,MAAM,GACtB,IAAI,CAyBN;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI,CAqE7E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI,CA+D/E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,iBAAiB,EAAE,GAAG,IAAI,CA8DrF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE;IAAE,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,GACtC,IAAI,CAkCN"}