toolnet-memory 0.2.0

package/dist/src/code-intelligence/architecture/clusters.js

@@ -0,0 +1,322 @@
+import { createHash, } from "node:crypto";
+const EDGE_WEIGHT = {
+    CALL_REFERENCE: 7,
+    CALLS: 3,
+    IMPORTS: 4,
+    USES_TYPE: 4,
+    WRITES: 5,
+    INHERITS: 7,
+    IMPLEMENTS: 7,
+    ROUTE: 4,
+    TESTS: 1,
+};
+function hash(value) {
+    return createHash("sha256")
+        .update(value)
+        .digest("hex")
+        .slice(0, 12);
+}
+function normalize(value) {
+    return value.replaceAll("\\", "/");
+}
+function subsystemOf(filePath) {
+    const path = normalize(filePath);
+    const parts = path.split("/")
+        .filter(Boolean);
+    if (parts[0] === "src" &&
+        parts[1]) {
+        return `src/${parts[1]}`;
+    }
+    if (parts[0] === "packages" &&
+        parts[1]) {
+        return `packages/${parts[1]}`;
+    }
+    if (parts[0] === "tests") {
+        return "tests";
+    }
+    if (parts[0] === "bin") {
+        return "bin";
+    }
+    return parts[0] ?? "root";
+}
+function clusterLabel(subsystem) {
+    const value = subsystem
+        .replace(/^src\//, "")
+        .replace(/^packages\//, "");
+    const map = {
+        "code-intelligence": "Code Intelligence",
+        memory: "Memory",
+        storage: "Storage",
+        retrieval: "Retrieval",
+        runtime: "Runtime",
+        mcp: "MCP",
+        hooks: "Hooks",
+        security: "Security",
+        snapshot: "Snapshots",
+        production: "Production",
+        capture: "Capture",
+        processor: "Processor",
+        core: "Core",
+        tests: "Tests",
+        bin: "CLI",
+        sdk: "SDK",
+        cli: "CLI",
+    };
+    return (map[value] ??
+        value);
+}
+export class ClusterDetector {
+    graph;
+    constructor(graph) {
+        this.graph = graph;
+    }
+    detect(projectId) {
+        const symbols = this.graph.allSymbols(projectId);
+        const edges = this.graph.allEdges(projectId);
+        const symbolById = new Map(symbols.map((symbol) => [
+            symbol.id,
+            symbol,
+        ]));
+        const files = [
+            ...new Set(symbols.map((symbol) => normalize(symbol.filePath))),
+        ].sort();
+        const pairMap = new Map();
+        const makeKey = (a, b) => {
+            const sorted = [a, b].sort();
+            return `${sorted[0]}\u0000${sorted[1]}`;
+        };
+        for (const edge of edges) {
+            const from = symbolById.get(edge.from);
+            const to = symbolById.get(edge.to);
+            if (!from ||
+                !to) {
+                continue;
+            }
+            const a = normalize(from.filePath);
+            const b = normalize(to.filePath);
+            if (a === b) {
+                continue;
+            }
+            const weight = EDGE_WEIGHT[edge.type] ?? 0;
+            if (weight <= 0) {
+                continue;
+            }
+            const key = makeKey(a, b);
+            const existing = pairMap.get(key);
+            if (existing) {
+                existing.weight +=
+                    weight;
+            }
+            else {
+                pairMap.set(key, {
+                    a: [a, b].sort()[0],
+                    b: [a, b].sort()[1],
+                    weight,
+                });
+            }
+        }
+        /*
+         * 1. Base grouping = architectural subsystem.
+         */
+        const subsystemFiles = new Map();
+        for (const file of files) {
+            const subsystem = subsystemOf(file);
+            const group = subsystemFiles.get(subsystem) ?? [];
+            group.push(file);
+            subsystemFiles.set(subsystem, group);
+        }
+        /*
+         * 2. Split very large subsystems by strong internal connectivity.
+         *
+         * Không để code-intelligence 70+ files trở thành một khối mù.
+         */
+        const groups = [];
+        for (const [subsystem, subsystemGroup,] of subsystemFiles) {
+            subsystemGroup.sort();
+            if (subsystemGroup.length <=
+                30) {
+                groups.push({
+                    subsystem,
+                    files: subsystemGroup,
+                });
+                continue;
+            }
+            const fileSet = new Set(subsystemGroup);
+            const adjacency = new Map();
+            for (const file of subsystemGroup) {
+                adjacency.set(file, new Set());
+            }
+            for (const pair of pairMap.values()) {
+                if (!fileSet.has(pair.a) ||
+                    !fileSet.has(pair.b)) {
+                    continue;
+                }
+                /*
+                 * Strong internal relationship only.
+                 */
+                if (pair.weight >=
+                    8) {
+                    adjacency.get(pair.a)?.add(pair.b);
+                    adjacency.get(pair.b)?.add(pair.a);
+                }
+            }
+            const visited = new Set();
+            const components = [];
+            for (const start of subsystemGroup) {
+                if (visited.has(start)) {
+                    continue;
+                }
+                const queue = [start];
+                const component = [];
+                visited.add(start);
+                while (queue.length >
+                    0) {
+                    const current = queue.shift();
+                    component.push(current);
+                    for (const neighbor of adjacency.get(current) ?? []) {
+                        if (visited.has(neighbor)) {
+                            continue;
+                        }
+                        visited.add(neighbor);
+                        queue.push(neighbor);
+                    }
+                }
+                components.push(component.sort());
+            }
+            /*
+             * Strong components >=2 become own clusters.
+             * Singleton files remain one residual subsystem cluster.
+             */
+            const residual = [];
+            for (const component of components) {
+                if (component.length >=
+                    2) {
+                    groups.push({
+                        subsystem,
+                        files: component,
+                    });
+                }
+                else {
+                    residual.push(...component);
+                }
+            }
+            if (residual.length >
+                0) {
+                groups.push({
+                    subsystem: `${subsystem}/residual`,
+                    files: residual.sort(),
+                });
+            }
+        }
+        /*
+         * 3. Merge tiny cross-subsystem groups only
+         * when coupling is extremely strong.
+         */
+        let working = groups.map((group) => ({
+            subsystem: group.subsystem,
+            files: [...group.files],
+        }));
+        for (let pass = 0; pass < 3; pass++) {
+            let merged = false;
+            outer: for (let i = 0; i <
+                working.length; i++) {
+                const a = working[i];
+                if (!a ||
+                    a.files.length >
+                        3) {
+                    continue;
+                }
+                for (let j = 0; j <
+                    working.length; j++) {
+                    if (i === j) {
+                        continue;
+                    }
+                    const b = working[j];
+                    if (!b) {
+                        continue;
+                    }
+                    let connection = 0;
+                    const setA = new Set(a.files);
+                    const setB = new Set(b.files);
+                    for (const pair of pairMap.values()) {
+                        const crosses = (setA.has(pair.a) &&
+                            setB.has(pair.b)) ||
+                            (setA.has(pair.b) &&
+                                setB.has(pair.a));
+                        if (crosses) {
+                            connection +=
+                                pair.weight;
+                        }
+                    }
+                    if (connection >=
+                        20) {
+                        b.files =
+                            [
+                                ...new Set([
+                                    ...b.files,
+                                    ...a.files,
+                                ]),
+                            ].sort();
+                        working.splice(i, 1);
+                        merged =
+                            true;
+                        break outer;
+                    }
+                }
+            }
+            if (!merged) {
+                break;
+            }
+        }
+        /*
+         * 4. Compute metrics.
+         */
+        const result = [];
+        for (const group of working) {
+            const set = new Set(group.files);
+            let internalWeight = 0;
+            let externalWeight = 0;
+            for (const pair of pairMap.values()) {
+                const inA = set.has(pair.a);
+                const inB = set.has(pair.b);
+                if (inA &&
+                    inB) {
+                    internalWeight +=
+                        pair.weight;
+                }
+                else if (inA ||
+                    inB) {
+                    externalWeight +=
+                        pair.weight;
+                }
+            }
+            const total = internalWeight +
+                externalWeight;
+            const baseSubsystem = group.subsystem
+                .replace(/\/residual$/, "");
+            const labelBase = clusterLabel(baseSubsystem);
+            const label = group.subsystem.endsWith("/residual")
+                ? `${labelBase} Misc`
+                : labelBase;
+            result.push({
+                id: `cluster-${hash(`${group.subsystem}:${group.files.join("|")}`)}`,
+                label,
+                subsystem: baseSubsystem,
+                files: group.files,
+                size: group.files.length,
+                internalWeight,
+                externalWeight,
+                cohesion: total > 0
+                    ? Number((internalWeight /
+                        total).toFixed(4))
+                    : 0,
+            });
+        }
+        return result
+            .sort((a, b) => b.size -
+            a.size ||
+            b.cohesion -
+                a.cohesion ||
+            a.label.localeCompare(b.label));
+    }
+}

package/dist/src/code-intelligence/architecture/entry-points.js

@@ -0,0 +1,150 @@
+function normalize(value) {
+    return value
+        .replaceAll("\\", "/")
+        .toLowerCase();
+}
+export class EntryPointDetector {
+    graph;
+    constructor(graph) {
+        this.graph = graph;
+    }
+    detect(projectId) {
+        const symbols = this.graph.allSymbols(projectId);
+        const edges = this.graph.allEdges(projectId);
+        const results = [];
+        for (const symbol of symbols) {
+            /*
+             * Route là entry semantic.
+             * Các loại còn lại chỉ xét FILE node.
+             */
+            if (symbol.type !== "route" &&
+                symbol.type !== "file") {
+                continue;
+            }
+            const result = this.classify(symbol, edges);
+            if (result) {
+                results.push({
+                    symbolId: symbol.id,
+                    filePath: symbol.filePath,
+                    name: symbol.name,
+                    kind: result.kind,
+                    score: result.score,
+                    reasons: result.reasons,
+                });
+            }
+        }
+        /*
+         * Một file chỉ giữ entry tốt nhất.
+         * Route vẫn giữ riêng theo symbol.
+         */
+        const bestByKey = new Map();
+        for (const item of results) {
+            const key = item.kind === "route"
+                ? item.symbolId
+                : item.filePath;
+            const existing = bestByKey.get(key);
+            if (!existing ||
+                item.score >
+                    existing.score) {
+                bestByKey.set(key, item);
+            }
+        }
+        return [
+            ...bestByKey.values(),
+        ]
+            .sort((a, b) => b.score -
+            a.score ||
+            a.filePath.localeCompare(b.filePath));
+    }
+    classify(symbol, edges) {
+        const path = normalize(symbol.filePath);
+        const reasons = [];
+        if (symbol.type ===
+            "route") {
+            return {
+                kind: "route",
+                score: 100,
+                reasons: [
+                    "HTTP route",
+                ],
+            };
+        }
+        let kind = null;
+        let score = 0;
+        if (path.startsWith("bin/")) {
+            kind =
+                "cli";
+            score =
+                100;
+            reasons.push("bin executable");
+        }
+        else if (/(^|\/)(cli)\.[^.]+$/
+            .test(path)) {
+            kind =
+                "cli";
+            score =
+                90;
+            reasons.push("CLI entry file");
+        }
+        else if (/(^|\/)(main|server)\.[^.]+$/
+            .test(path)) {
+            kind =
+                "main";
+            score =
+                90;
+            reasons.push("main/server file");
+        }
+        else if (path.includes("/runtime/") &&
+            /(^|\/)(bootstrap|index)\.[^.]+$/
+                .test(path)) {
+            kind =
+                "runtime";
+            score =
+                75;
+            reasons.push("runtime bootstrap");
+        }
+        else if (/(^|\/)index\.[^.]+$/
+            .test(path)) {
+            /*
+             * Chỉ package/public index có tín hiệu
+             * dependency thực sự.
+             */
+            const incoming = edges.filter((edge) => edge.to ===
+                symbol.id &&
+                edge.type !==
+                    "DEFINES").length;
+            const outgoing = edges.filter((edge) => edge.from ===
+                symbol.id &&
+                edge.type !==
+                    "DEFINES").length;
+            if (path.startsWith("packages/") ||
+                incoming === 0 ||
+                outgoing > 0) {
+                kind =
+                    "package";
+                score =
+                    path.startsWith("packages/")
+                        ? 70
+                        : 55;
+                reasons.push("package/public index");
+            }
+        }
+        if (!kind) {
+            return null;
+        }
+        const incoming = edges.filter((edge) => edge.to ===
+            symbol.id &&
+            edge.type !==
+                "DEFINES").length;
+        if (incoming === 0) {
+            score +=
+                10;
+            reasons.push("no incoming dependency");
+        }
+        return {
+            kind,
+            score,
+            reasons,
+        };
+    }
+}

package/dist/src/code-intelligence/architecture/hotspots.js

@@ -0,0 +1,136 @@
+const EDGE_WEIGHT = {
+    CALL_REFERENCE: 6,
+    CALLS: 4,
+    IMPORTS: 3,
+    USES_TYPE: 4,
+    WRITES: 5,
+    ROUTE: 4,
+    TESTS: 1,
+    INHERITS: 5,
+    IMPLEMENTS: 5,
+    DEFINES: 0.25,
+};
+export class HotspotAnalyzer {
+    graph;
+    constructor(graph) {
+        this.graph = graph;
+    }
+    analyze(projectId) {
+        const symbols = this.graph.allSymbols(projectId);
+        const edges = this.graph.allEdges(projectId);
+        const symbolById = new Map(symbols.map((symbol) => [
+            symbol.id,
+            symbol,
+        ]));
+        const files = new Map();
+        const get = (filePath) => {
+            let value = files.get(filePath);
+            if (!value) {
+                value = {
+                    symbols: 0,
+                    incoming: 0,
+                    outgoing: 0,
+                    weightedIncoming: 0,
+                    weightedOutgoing: 0,
+                    writes: 0,
+                    callReferences: 0,
+                    crossFile: 0,
+                };
+                files.set(filePath, value);
+            }
+            return value;
+        };
+        for (const symbol of symbols) {
+            get(symbol.filePath).symbols++;
+        }
+        for (const edge of edges) {
+            const from = symbolById.get(edge.from);
+            const to = symbolById.get(edge.to);
+            if (!from ||
+                !to) {
+                continue;
+            }
+            const weight = EDGE_WEIGHT[edge.type] ?? 1;
+            const source = get(from.filePath);
+            const target = get(to.filePath);
+            source.outgoing++;
+            target.incoming++;
+            source.weightedOutgoing +=
+                weight;
+            target.weightedIncoming +=
+                weight;
+            if (edge.type ===
+                "WRITES") {
+                source.writes++;
+            }
+            if (edge.type ===
+                "CALL_REFERENCE") {
+                source.callReferences++;
+            }
+            if (from.filePath !==
+                to.filePath) {
+                source.crossFile++;
+                target.crossFile++;
+            }
+        }
+        const scored = [
+            ...files.entries(),
+        ]
+            .map(([filePath, value,]) => {
+            const score = Number((value.symbols *
+                0.4 +
+                value.weightedIncoming *
+                    1.75 +
+                value.weightedOutgoing *
+                    0.65 +
+                value.crossFile *
+                    1.5 +
+                value.writes *
+                    3 +
+                value.callReferences *
+                    2).toFixed(2));
+            const reasons = [];
+            if (value.incoming >=
+                10) {
+                reasons.push("high incoming dependency");
+            }
+            if (value.crossFile >=
+                10) {
+                reasons.push("high cross-file coupling");
+            }
+            if (value.callReferences >=
+                5) {
+                reasons.push("many exact call references");
+            }
+            if (value.writes > 0) {
+                reasons.push("contains write relationships");
+            }
+            if (value.symbols >=
+                10) {
+                reasons.push("high symbol density");
+            }
+            return {
+                filePath,
+                score,
+                symbols: value.symbols,
+                incoming: value.incoming,
+                outgoing: value.outgoing,
+                reasons,
+            };
+        })
+            .filter((item) => item.score > 0)
+            .sort((a, b) => b.score -
+            a.score ||
+            a.filePath.localeCompare(b.filePath));
+        if (scored.length === 0) {
+            return [];
+        }
+        /*
+         * Top 15%, tối đa 30.
+         * Repo nhỏ vẫn giữ tối thiểu 1 hotspot.
+         */
+        const limit = Math.max(1, Math.min(30, Math.ceil(scored.length *
+            0.15)));
+        return scored.slice(0, limit);
+    }
+}

package/dist/src/code-intelligence/architecture/index.js

@@ -0,0 +1,6 @@
+export * from "./types.js";
+export * from "./entry-points.js";
+export * from "./hotspots.js";
+export * from "./layers.js";
+export * from "./clusters.js";
+export * from "./architecture-engine.js";