@yasserkhanorg/impact-gate 2.0.0

package/dist/knowledge/kg_bridge.js

@@ -0,0 +1,388 @@
+"use strict";
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadKnowledgeGraph = loadKnowledgeGraph;
+exports.classifyProjectType = classifyProjectType;
+exports.transformKGToFamilies = transformKGToFamilies;
+exports.loadDiffOverlay = loadDiffOverlay;
+exports.diffOverlayToChangedFiles = diffOverlayToChangedFiles;
+/**
+ * Bridge between Understand-Anything's knowledge graph and impact-gate' route families.
+ * Transforms KG nodes/edges into RouteFamilyManifest so existing pipeline works unchanged.
+ */
+const fs_1 = require("fs");
+const path_1 = require("path");
+const logger_js_1 = require("../logger.js");
+const cluster_utils_js_1 = require("./cluster_utils.js");
+const UA_DIR = '.understand-anything';
+const KG_FILE = 'knowledge-graph.json';
+const DIFF_FILE = 'diff-overlay.json';
+const FRONTEND_FRAMEWORKS = new Set([
+    'react', 'vue', 'angular', 'svelte', 'next', 'nextjs', 'next.js',
+    'nuxt', 'nuxtjs', 'gatsby', 'remix', 'astro', 'solid', 'solidjs',
+    'preact', 'lit', 'stencil', 'qwik',
+]);
+const BACKEND_FRAMEWORKS = new Set([
+    'express', 'fastify', 'koa', 'hapi', 'nest', 'nestjs',
+    'django', 'flask', 'fastapi', 'rails', 'spring', 'gin', 'echo', 'fiber',
+    'actix', 'axum', 'rocket', 'phoenix', 'laravel',
+]);
+/**
+ * Loads the knowledge graph from .understand-anything/knowledge-graph.json
+ * or from a custom path when provided.
+ */
+function loadKnowledgeGraph(projectRoot, customPath) {
+    const kgPath = customPath || (0, path_1.join)(projectRoot, UA_DIR, KG_FILE);
+    if (!(0, fs_1.existsSync)(kgPath)) {
+        return null;
+    }
+    try {
+        const raw = JSON.parse((0, fs_1.readFileSync)(kgPath, 'utf-8'));
+        if (!raw.nodes || !Array.isArray(raw.nodes) || !raw.edges || !Array.isArray(raw.edges)) {
+            logger_js_1.logger.warn('Knowledge graph missing required nodes/edges arrays');
+            return null;
+        }
+        if (!raw.project) {
+            logger_js_1.logger.warn('Knowledge graph missing project metadata');
+            return null;
+        }
+        // Field-level validation: filter out invalid nodes rather than rejecting the whole graph
+        const MAX_STRING_LEN = 1000;
+        const validNodes = raw.nodes.filter((node) => {
+            if (typeof node.id !== 'string' || typeof node.name !== 'string') {
+                logger_js_1.logger.warn(`Dropping KG node with missing/invalid id or name: ${JSON.stringify(node).slice(0, 200)}`);
+                return false;
+            }
+            if (node.filePath !== undefined) {
+                if (typeof node.filePath !== 'string') {
+                    logger_js_1.logger.warn(`Dropping KG node "${node.id}": filePath is not a string`);
+                    return false;
+                }
+                if (node.filePath.startsWith('/')) {
+                    logger_js_1.logger.warn(`Dropping KG node "${node.id}": absolute filePath rejected`);
+                    return false;
+                }
+                if (node.filePath.includes('..')) {
+                    logger_js_1.logger.warn(`Dropping KG node "${node.id}": path traversal in filePath rejected`);
+                    return false;
+                }
+                if (node.filePath.includes('\0')) {
+                    logger_js_1.logger.warn(`Dropping KG node "${node.id}": null byte in filePath rejected`);
+                    return false;
+                }
+            }
+            return true;
+        });
+        // Truncate excessively long strings
+        for (const node of validNodes) {
+            if (node.name.length > MAX_STRING_LEN) {
+                node.name = node.name.slice(0, MAX_STRING_LEN);
+            }
+            if (node.description && node.description.length > MAX_STRING_LEN) {
+                node.description = node.description.slice(0, MAX_STRING_LEN);
+            }
+        }
+        raw.nodes = validNodes;
+        return raw;
+    }
+    catch (error) {
+        logger_js_1.logger.warn(`Failed to load knowledge graph: ${error instanceof Error ? error.message : String(error)}`);
+        return null;
+    }
+}
+/**
+ * Classifies project type based on KG framework metadata.
+ */
+function classifyProjectType(kg) {
+    const frameworks = kg.project.frameworks.map((f) => f.toLowerCase());
+    const hasFrontend = frameworks.some((f) => FRONTEND_FRAMEWORKS.has(f));
+    const hasBackend = frameworks.some((f) => BACKEND_FRAMEWORKS.has(f));
+    if (hasFrontend && hasBackend)
+        return 'fullstack';
+    if (hasBackend)
+        return 'backend';
+    return 'frontend';
+}
+/**
+ * Core bridge: transforms KG into a RouteFamilyManifest.
+ *
+ * Strategy:
+ * - Frontend: cluster UI-layer nodes into families by module/component groups
+ * - Backend: cluster API-layer nodes, follow calls edges into Service→Data layers
+ * - Priority: P0 = high fan-in nodes, P1 = moderate, P2 = leaf/utility
+ * - userFlows: derived from KG tour steps referencing family nodes
+ */
+function transformKGToFamilies(kg) {
+    const projectType = classifyProjectType(kg);
+    const nodeMap = new Map(kg.nodes.map((n) => [n.id, n]));
+    const edgesByTarget = groupEdges(kg.edges, 'target');
+    // Build clusters based on project type
+    const clusters = buildClusters(kg, projectType, nodeMap);
+    // Transform clusters into route families
+    const families = [];
+    for (const [clusterId, nodeIds] of clusters) {
+        const nodes = nodeIds.map((id) => nodeMap.get(id)).filter((n) => n !== undefined);
+        if (nodes.length === 0)
+            continue;
+        const family = buildFamilyFromCluster(clusterId, nodes, projectType, nodeMap, edgesByTarget);
+        if (family) {
+            families.push(family);
+        }
+    }
+    // Derive userFlows from KG tour steps
+    if (kg.tour && kg.tour.length > 0) {
+        assignTourFlows(families, kg.tour, nodeMap);
+    }
+    // Sort by priority (P0 first) then alphabetically
+    families.sort((a, b) => {
+        const pOrder = { P0: 0, P1: 1, P2: 2 };
+        const pa = pOrder[a.priority || 'P2'];
+        const pb = pOrder[b.priority || 'P2'];
+        if (pa !== pb)
+            return pa - pb;
+        return a.id.localeCompare(b.id);
+    });
+    return {
+        families,
+        source: 'knowledge-graph',
+    };
+}
+/**
+ * Loads the diff overlay from .understand-anything/diff-overlay.json
+ */
+function loadDiffOverlay(projectRoot) {
+    const overlayPath = (0, path_1.join)(projectRoot, UA_DIR, DIFF_FILE);
+    if (!(0, fs_1.existsSync)(overlayPath)) {
+        return null;
+    }
+    try {
+        const raw = JSON.parse((0, fs_1.readFileSync)(overlayPath, 'utf-8'));
+        if (!raw.changes || !Array.isArray(raw.changes)) {
+            return null;
+        }
+        return raw;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Maps diff overlay changes to file paths using KG node resolution.
+ */
+function diffOverlayToChangedFiles(overlay, kg) {
+    const nodeMap = new Map(kg.nodes.map((n) => [n.id, n]));
+    const files = new Set();
+    for (const change of overlay.changes) {
+        // Use filePath from change if available
+        if (change.filePath) {
+            files.add(change.filePath);
+            continue;
+        }
+        // Fall back to KG node's filePath
+        const node = nodeMap.get(change.nodeId);
+        if (node?.filePath) {
+            files.add(node.filePath);
+        }
+    }
+    return [...files];
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+function groupEdges(edges, key) {
+    const map = new Map();
+    for (const edge of edges) {
+        const val = edge[key];
+        if (!map.has(val))
+            map.set(val, []);
+        map.get(val).push(edge);
+    }
+    return map;
+}
+/**
+ * Build clusters of related nodes to become families.
+ * Frontend: group by route/page/component modules
+ * Backend: group by API endpoint handlers + their service dependencies
+ */
+function buildClusters(kg, projectType, nodeMap) {
+    const clusters = new Map();
+    // Strategy 1: Use KG layers to find anchor nodes
+    const layerMap = new Map();
+    if (kg.layers) {
+        for (const layer of kg.layers) {
+            layerMap.set(layer.name, new Set(layer.nodeIds));
+        }
+    }
+    // Strategy 2: Group by module/component/route nodes
+    const anchorKinds = projectType === 'backend'
+        ? new Set(['module', 'route', 'class', 'function'])
+        : new Set(['component', 'route', 'module', 'class']);
+    const anchorLayers = projectType === 'backend'
+        ? new Set(['api', 'service'])
+        : new Set(['ui']);
+    for (const node of kg.nodes) {
+        // Skip test/infra nodes as cluster anchors
+        if (node.layer === 'test' || node.layer === 'infra')
+            continue;
+        const isAnchorKind = anchorKinds.has(node.kind);
+        const isAnchorLayer = !node.layer || anchorLayers.has(node.layer);
+        if (!isAnchorKind || !isAnchorLayer)
+            continue;
+        // Derive cluster ID from node path or name
+        const clusterId = (0, cluster_utils_js_1.deriveClusterId)(node);
+        if (!clusterId)
+            continue;
+        if (!clusters.has(clusterId)) {
+            clusters.set(clusterId, []);
+        }
+        clusters.get(clusterId).push(node.id);
+    }
+    // If no clusters found, fall back to file-based grouping
+    if (clusters.size === 0) {
+        for (const node of kg.nodes) {
+            if (!node.filePath || node.layer === 'test' || node.layer === 'infra')
+                continue;
+            const clusterId = (0, cluster_utils_js_1.deriveClusterIdFromPath)(node.filePath);
+            if (!clusterId)
+                continue;
+            if (!clusters.has(clusterId)) {
+                clusters.set(clusterId, []);
+            }
+            clusters.get(clusterId).push(node.id);
+        }
+    }
+    return clusters;
+}
+// deriveClusterId and deriveClusterIdFromPath imported from cluster_utils.ts
+function computePriority(nodes) {
+    const maxFanIn = Math.max(...nodes.map((n) => n.fanIn || 0));
+    if (maxFanIn >= 10)
+        return 'P0';
+    if (maxFanIn >= 4)
+        return 'P1';
+    return 'P2';
+}
+function buildFamilyFromCluster(clusterId, nodes, projectType, nodeMap, edgesByTarget) {
+    const webappPaths = new Set();
+    const serverPaths = new Set();
+    const routes = [];
+    const apiEndpoints = [];
+    for (const node of nodes) {
+        if (!node.filePath)
+            continue;
+        const layer = node.layer;
+        if (layer === 'api' || layer === 'service' || layer === 'data') {
+            serverPaths.add(`${node.filePath}*`);
+        }
+        else if (layer === 'ui') {
+            webappPaths.add(`${node.filePath}*`);
+        }
+        else {
+            // Auto-assign based on project type
+            if (projectType === 'backend') {
+                serverPaths.add(`${node.filePath}*`);
+            }
+            else {
+                webappPaths.add(`${node.filePath}*`);
+            }
+        }
+        // Extract routes from route nodes
+        if (node.kind === 'route') {
+            const routePath = node.metadata?.path;
+            if (routePath) {
+                routes.push(routePath);
+                // Extract API endpoint info
+                const method = node.metadata?.method || 'GET';
+                apiEndpoints.push({ method: method.toUpperCase(), path: routePath, description: node.description });
+            }
+            else {
+                routes.push(`/${clusterId}`);
+            }
+        }
+    }
+    // If no routes extracted, generate a default
+    if (routes.length === 0) {
+        routes.push(`/${clusterId}`);
+    }
+    // Collect related test file paths by following 'tests' edges
+    const specDirs = new Set();
+    for (const node of nodes) {
+        const testEdges = (edgesByTarget.get(node.id) || []).filter((e) => e.type === 'tests');
+        for (const edge of testEdges) {
+            const testNode = nodeMap.get(edge.source);
+            if (testNode?.filePath) {
+                // Use directory of test file
+                const dir = testNode.filePath.replace(/\\/g, '/').split('/').slice(0, -1).join('/');
+                if (dir)
+                    specDirs.add(`${dir}/*`);
+            }
+        }
+    }
+    const priority = computePriority(nodes);
+    // Determine test type based on content
+    let testType;
+    if (webappPaths.size > 0 && serverPaths.size > 0) {
+        testType = 'both';
+    }
+    else if (serverPaths.size > 0 && apiEndpoints.length > 0) {
+        testType = 'api';
+    }
+    else if (webappPaths.size > 0) {
+        testType = 'ui';
+    }
+    const family = {
+        id: clusterId,
+        routes: [...new Set(routes)],
+        priority,
+    };
+    if (webappPaths.size > 0)
+        family.webappPaths = [...webappPaths];
+    if (serverPaths.size > 0)
+        family.serverPaths = [...serverPaths];
+    if (specDirs.size > 0)
+        family.specDirs = [...specDirs];
+    if (apiEndpoints.length > 0)
+        family.apiEndpoints = apiEndpoints;
+    if (testType)
+        family.testType = testType;
+    return family;
+}
+function assignTourFlows(families, tour, nodeMap) {
+    if (!tour)
+        return;
+    // Build a map of nodeId → family for quick lookup
+    const nodeToFamily = new Map();
+    for (const family of families) {
+        // Resolve family nodes from paths
+        for (const [nodeId, node] of nodeMap) {
+            if (!node.filePath)
+                continue;
+            const matchesPaths = [
+                ...(family.webappPaths || []),
+                ...(family.serverPaths || []),
+            ];
+            for (const pattern of matchesPaths) {
+                const prefix = pattern.replace(/\*$/, '');
+                if (node.filePath.startsWith(prefix)) {
+                    nodeToFamily.set(nodeId, family);
+                    break;
+                }
+            }
+        }
+    }
+    // Assign tour steps as user flows
+    for (const step of tour.sort((a, b) => a.order - b.order)) {
+        for (const nodeId of step.nodeIds) {
+            const family = nodeToFamily.get(nodeId);
+            if (family) {
+                if (!family.userFlows)
+                    family.userFlows = [];
+                const flowDesc = `${step.title}: ${step.description}`;
+                if (!family.userFlows.includes(flowDesc)) {
+                    family.userFlows.push(flowDesc);
+                }
+            }
+        }
+    }
+}

package/dist/knowledge/kg_types.d.ts

@@ -0,0 +1,75 @@
+/**
+ * TypeScript interfaces matching Understand-Anything's knowledge-graph.json schema.
+ * These types enable the bridge between UA's knowledge graph and impact-gate' route families.
+ */
+export type KGNodeKind = 'file' | 'function' | 'class' | 'module' | 'concept' | 'component' | 'route' | 'hook' | 'type' | 'variable';
+export type KGEdgeType = 'imports' | 'exports' | 'calls' | 'implements' | 'extends' | 'uses' | 'renders' | 'routes_to' | 'provides' | 'consumes' | 'tests' | 'configures' | 'depends_on' | 'contains' | 'composed_of' | 'handles' | 'emits' | 'listens_to';
+export type KGLayerName = 'ui' | 'api' | 'service' | 'data' | 'config' | 'test' | 'infra' | 'shared';
+export interface KGNode {
+    id: string;
+    kind: KGNodeKind;
+    name: string;
+    filePath?: string;
+    layer?: KGLayerName;
+    description?: string;
+    tags?: string[];
+    /** Fan-in: number of other nodes referencing this one */
+    fanIn?: number;
+    /** Fan-out: number of nodes this one references */
+    fanOut?: number;
+    metadata?: Record<string, unknown>;
+}
+export interface KGEdge {
+    source: string;
+    target: string;
+    type: KGEdgeType;
+    weight?: number;
+    metadata?: Record<string, unknown>;
+}
+export interface KGLayer {
+    name: KGLayerName;
+    nodeIds: string[];
+    description?: string;
+}
+export interface KGTourStep {
+    id: string;
+    title: string;
+    description: string;
+    nodeIds: string[];
+    order: number;
+}
+export interface KGProject {
+    name: string;
+    description?: string;
+    frameworks: string[];
+    languages: string[];
+    entryPoints?: string[];
+    rootDir?: string;
+}
+export interface KnowledgeGraph {
+    version: string;
+    project: KGProject;
+    nodes: KGNode[];
+    edges: KGEdge[];
+    layers?: KGLayer[];
+    tour?: KGTourStep[];
+}
+export interface DiffOverlayChange {
+    nodeId: string;
+    changeType: 'added' | 'modified' | 'removed';
+    filePath?: string;
+    description?: string;
+}
+export interface DiffOverlay {
+    version: string;
+    baseSha?: string;
+    headSha?: string;
+    changes: DiffOverlayChange[];
+    affectedEdges?: Array<{
+        source: string;
+        target: string;
+        type: KGEdgeType;
+        impact: 'added' | 'modified' | 'removed';
+    }>;
+}
+//# sourceMappingURL=kg_types.d.ts.map

package/dist/knowledge/kg_types.d.ts.map

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

package/dist/knowledge/kg_types.js

@@ -0,0 +1,4 @@
+"use strict";
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/knowledge/route_families.d.ts

@@ -0,0 +1,98 @@
+export type FeaturePriority = 'P0' | 'P1' | 'P2';
+export type AssertionType = 'state-change' | 'cross-user' | 'persistence' | 'negative' | 'permission' | 'data-integrity' | 'error-handling';
+export interface AssertionPattern {
+    type: AssertionType;
+    pattern: string;
+}
+export interface RouteFeature {
+    id: string;
+    routes?: string[];
+    webappPaths?: string[];
+    serverPaths?: string[];
+    specDirs?: string[];
+    cypressSpecDirs?: string[];
+    tags?: string[];
+    priority?: FeaturePriority;
+    userFlows?: string[];
+    assertionPatterns?: AssertionPattern[];
+}
+export interface ApiEndpoint {
+    method: string;
+    path: string;
+    description?: string;
+}
+export type TestType = 'ui' | 'api' | 'both';
+export interface RouteFamily {
+    id: string;
+    routes: string[];
+    pageObjects?: string[];
+    components?: string[];
+    webappPaths?: string[];
+    serverPaths?: string[];
+    specDirs?: string[];
+    cypressSpecDirs?: string[];
+    tags?: string[];
+    priority?: FeaturePriority;
+    userFlows?: string[];
+    features?: RouteFeature[];
+    apiEndpoints?: ApiEndpoint[];
+    testType?: TestType;
+    assertionPatterns?: AssertionPattern[];
+}
+export interface RouteFamilyManifest {
+    families: RouteFamily[];
+    source: string;
+}
+export interface FileBinding {
+    file: string;
+    bindings: Array<{
+        family: string;
+        feature?: string;
+    }>;
+}
+export interface RouteFamilyConfig {
+    manifestPath?: string;
+    strict?: boolean;
+}
+export declare function matchesGlob(filePath: string, pattern: string): boolean;
+export declare function matchesAnyPattern(filePath: string, patterns: string[]): boolean;
+export declare function loadRouteFamilyManifest(testsRoot: string, config?: RouteFamilyConfig): RouteFamilyManifest | null;
+export declare function bindFilesToFamilies(changedFiles: string[], manifest: RouteFamilyManifest): FileBinding[];
+export declare function getFamilyById(manifest: RouteFamilyManifest, familyId: string): RouteFamily | undefined;
+export declare function getFeatureById(family: RouteFamily, featureId: string): RouteFeature | undefined;
+export declare function getSpecDirsForBinding(manifest: RouteFamilyManifest, binding: {
+    family: string;
+    feature?: string;
+}): string[];
+export declare function getCypressSpecDirsForBinding(manifest: RouteFamilyManifest, binding: {
+    family: string;
+    feature?: string;
+}): string[];
+export declare function getPriorityForBinding(manifest: RouteFamilyManifest, binding: {
+    family: string;
+    feature?: string;
+}): FeaturePriority;
+export declare function getUserFlowsForBinding(manifest: RouteFamilyManifest, binding: {
+    family: string;
+    feature?: string;
+}): string[];
+export declare function getRoutesForBinding(manifest: RouteFamilyManifest, binding: {
+    family: string;
+    feature?: string;
+}): string[];
+export declare function getAssertionPatternsForBinding(manifest: RouteFamilyManifest, binding: {
+    family: string;
+    feature?: string;
+}): AssertionPattern[];
+export declare function clearManifestCache(): void;
+/**
+ * Build heuristic route families from changed files when no manifest exists.
+ * Groups files by their top-level directory to create rough family groupings.
+ * Results are lower confidence but allow analysis to proceed without training.
+ */
+export declare function buildHeuristicFamilies(changedFiles: string[], testsRoot: string): RouteFamilyManifest;
+/**
+ * Serialize a RouteFamilyManifest to clean JSON, stripping empty optional fields.
+ */
+export declare function serializeManifest(manifest: RouteFamilyManifest): string;
+//# sourceMappingURL=route_families.d.ts.map

package/dist/knowledge/route_families.d.ts.map

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