@unerr-ai/unerr 0.2.1 → 0.2.3

package/dist/intelligence/community-detector.js

@@ -1,184 +0,0 @@
-/**
- * Community Detection — Louvain clustering + profile computation + name inference.
- *
- * M.1: Runs Louvain community detection via graphology on the entity graph.
- * M.2: Computes per-community profiles (cohesion, coupling, dominant kinds).
- * M.3: Infers community names from file paths + entity names.
- * M.6: Recomputation trigger (>10% entity change threshold).
- *
- * Performance: runs once per full index, cached. Recomputed only when
- * entity count changes by >10% from last computation.
- */
-import { createModuleLogger } from "../utils/logger.js";
-const log = createModuleLogger("community-detector");
-let lastEntityCount = 0;
-let cachedResult = null;
-const RECOMPUTE_THRESHOLD = 0.1;
-/**
- * Check if community detection needs recomputation.
- */
-export function needsRecomputation(currentEntityCount) {
-    if (!cachedResult)
-        return true;
-    if (lastEntityCount === 0)
-        return true;
-    const changeRatio = Math.abs(currentEntityCount - lastEntityCount) / lastEntityCount;
-    return changeRatio > RECOMPUTE_THRESHOLD;
-}
-/**
- * Run Louvain community detection on the entity graph.
- */
-export async function detectCommunities(entities, edges) {
-    if (!needsRecomputation(entities.length) && cachedResult) {
-        return cachedResult;
-    }
-    const start = performance.now();
-    const graphologyMod = (await import("graphology"));
-    const Graph = graphologyMod.default ?? graphologyMod;
-    const louvainMod = (await import("graphology-communities-louvain"));
-    const louvain = louvainMod.default ?? louvainMod;
-    const graph = new Graph({ type: "undirected", allowSelfLoops: false });
-    for (const entity of entities) {
-        if (!graph.hasNode(entity.key)) {
-            graph.addNode(entity.key, {
-                kind: entity.kind,
-                name: entity.name,
-                file_path: entity.file_path,
-            });
-        }
-    }
-    const entityKeys = new Set(entities.map((e) => e.key));
-    for (const edge of edges) {
-        if (entityKeys.has(edge.from_key) &&
-            entityKeys.has(edge.to_key) &&
-            edge.from_key !== edge.to_key &&
-            !graph.hasEdge(edge.from_key, edge.to_key)) {
-            try {
-                graph.addEdge(edge.from_key, edge.to_key);
-            }
-            catch {
-                /* edge already exists or invalid — skip */
-            }
-        }
-    }
-    if (graph.order === 0) {
-        const empty = {
-            communities: [],
-            assignments: new Map(),
-            modularity: 0,
-            entityCount: 0,
-            computedAt: new Date().toISOString(),
-        };
-        cachedResult = empty;
-        lastEntityCount = 0;
-        return empty;
-    }
-    const assignments = louvain(graph);
-    const modularity = louvain.assign(graph);
-    const communityMap = new Map();
-    for (const [nodeKey, communityId] of Object.entries(assignments)) {
-        const cid = communityId;
-        if (!communityMap.has(cid))
-            communityMap.set(cid, []);
-        communityMap.get(cid)?.push(nodeKey);
-    }
-    const profiles = [];
-    const assignmentMap = new Map();
-    for (const [communityId, memberKeys] of communityMap) {
-        for (const key of memberKeys) {
-            assignmentMap.set(key, communityId);
-        }
-        const memberEntities = entities.filter((e) => memberKeys.includes(e.key));
-        const kindCounts = new Map();
-        const fileSet = new Set();
-        for (const e of memberEntities) {
-            kindCounts.set(e.kind, (kindCounts.get(e.kind) ?? 0) + 1);
-            fileSet.add(e.file_path);
-        }
-        const dominantKinds = [...kindCounts.entries()]
-            .sort((a, b) => b[1] - a[1])
-            .slice(0, 3)
-            .map(([kind, count]) => ({ kind, count }));
-        const internalEdges = edges.filter((e) => memberKeys.includes(e.from_key) && memberKeys.includes(e.to_key)).length;
-        const externalEdges = edges.filter((e) => (memberKeys.includes(e.from_key) && !memberKeys.includes(e.to_key)) ||
-            (!memberKeys.includes(e.from_key) && memberKeys.includes(e.to_key))).length;
-        const totalPossibleInternal = (memberKeys.length * (memberKeys.length - 1)) / 2;
-        const cohesion = totalPossibleInternal > 0 ? internalEdges / totalPossibleInternal : 0;
-        const coupling = internalEdges + externalEdges > 0
-            ? externalEdges / (internalEdges + externalEdges)
-            : 0;
-        const name = inferCommunityName([...fileSet], memberEntities.map((e) => e.name));
-        profiles.push({
-            id: communityId,
-            name,
-            entityCount: memberKeys.length,
-            entityKeys: memberKeys,
-            dominantKinds,
-            files: [...fileSet],
-            cohesion: Math.round(cohesion * 1000) / 1000,
-            coupling: Math.round(coupling * 1000) / 1000,
-        });
-    }
-    profiles.sort((a, b) => b.entityCount - a.entityCount);
-    const result = {
-        communities: profiles,
-        assignments: assignmentMap,
-        modularity: typeof modularity === "number" ? modularity : 0,
-        entityCount: entities.length,
-        computedAt: new Date().toISOString(),
-    };
-    cachedResult = result;
-    lastEntityCount = entities.length;
-    log.info(`Detected ${profiles.length} communities in ${Math.round(performance.now() - start)}ms (modularity: ${result.modularity.toFixed(3)})`);
-    return result;
-}
-/**
- * Infer a human-readable community name from file paths + entity names.
- */
-function inferCommunityName(files, names) {
-    const dirFreq = new Map();
-    for (const file of files) {
-        const parts = file.split("/").filter(Boolean);
-        for (const part of parts.slice(0, -1)) {
-            if (!["src", "lib", "app", "index"].includes(part)) {
-                dirFreq.set(part, (dirFreq.get(part) ?? 0) + 1);
-            }
-        }
-    }
-    if (dirFreq.size > 0) {
-        const topDir = [...dirFreq.entries()].sort((a, b) => b[1] - a[1])[0];
-        if (topDir && topDir[1] >= files.length * 0.3) {
-            return topDir[0];
-        }
-    }
-    const nameFreq = new Map();
-    for (const name of names) {
-        const tokens = name
-            .replace(/([a-z])([A-Z])/g, "$1 $2")
-            .toLowerCase()
-            .split(/[\s_-]+/);
-        for (const token of tokens) {
-            if (token.length > 2)
-                nameFreq.set(token, (nameFreq.get(token) ?? 0) + 1);
-        }
-    }
-    if (nameFreq.size > 0) {
-        const topToken = [...nameFreq.entries()].sort((a, b) => b[1] - a[1])[0];
-        if (topToken)
-            return topToken[0];
-    }
-    return `community-${files.length}`;
-}
-/**
- * Get cached result (or null if not computed).
- */
-export function getCachedCommunities() {
-    return cachedResult;
-}
-/**
- * Clear cache (for testing).
- */
-export function clearCommunityCache() {
-    cachedResult = null;
-    lastEntityCount = 0;
-}

package/dist/intelligence/computation-scheduler.js

@@ -1,75 +0,0 @@
-/**
- * Resource-Aware Computation Scheduler — defers heavy ops under pressure.
- *
- * Checks heap usage before running expensive computations (Louvain, full
- * health grade, convention detection). If heap >75%, defers to next idle period.
- */
-import { createModuleLogger } from "../utils/logger.js";
-import { getResourceSnapshot, } from "./indexer/resource-monitor.js";
-const log = createModuleLogger("computation-scheduler");
-const pendingQueue = [];
-let isProcessing = false;
-/**
- * Schedule a computation respecting resource limits.
- * Critical = always runs. Normal = defers if heap >75%. Background = defers if heap >60%.
- */
-export async function scheduleComputation(id, priority, fn) {
-    const snap = getResourceSnapshot();
-    if (priority === "critical") {
-        await fn();
-        return true;
-    }
-    if (priority === "normal" && snap.degradationLevel >= 2) {
-        log.info(`Deferring ${id}: heap pressure level ${snap.degradationLevel}`);
-        pendingQueue.push({ id, priority, fn });
-        return false;
-    }
-    if (priority === "background" && snap.degradationLevel >= 1) {
-        log.info(`Deferring background ${id}: heap pressure level ${snap.degradationLevel}`);
-        pendingQueue.push({ id, priority, fn });
-        return false;
-    }
-    await fn();
-    return true;
-}
-/**
- * Process pending computations when resources free up.
- */
-export async function processPending() {
-    if (isProcessing || pendingQueue.length === 0)
-        return 0;
-    isProcessing = true;
-    let processed = 0;
-    const snap = getResourceSnapshot();
-    if (snap.degradationLevel >= 2) {
-        isProcessing = false;
-        return 0;
-    }
-    while (pendingQueue.length > 0) {
-        const current = getResourceSnapshot();
-        if (current.degradationLevel >= 2)
-            break;
-        const task = pendingQueue.shift();
-        try {
-            await task.fn();
-            processed++;
-        }
-        catch (err) {
-            log.warn(`Scheduled computation ${task.id} failed: ${err instanceof Error ? err.message : String(err)}`);
-        }
-    }
-    isProcessing = false;
-    return processed;
-}
-/**
- * Get pending computation count.
- */
-export function getPendingCount() {
-    return pendingQueue.length;
-}
-/**
- * Clear all pending computations.
- */
-export function clearPending() {
-    pendingQueue.length = 0;
-}

package/dist/intelligence/confidence-propagation.js

@@ -1,47 +0,0 @@
-/**
- * Confidence Propagation — MIN across traversed edges, edge source counts.
- *
- * When traversing the graph (e.g., blast radius), the confidence of the
- * result is the MINIMUM confidence of any edge in the traversal path.
- * One heuristic edge makes the whole path heuristic.
- */
-const CONFIDENCE_ORDER = {
-    "compiler-verified": 3,
-    structural: 2,
-    heuristic: 1,
-};
-/**
- * Propagate confidence across a path of edges.
- * Result confidence = MIN of all edge confidences in the path.
- */
-export function propagateConfidence(edgeConfidences) {
-    if (edgeConfidences.length === 0) {
-        return { level: "structural", edgeSources: {}, pathLength: 0 };
-    }
-    let minLevel = "compiler-verified";
-    const sources = {};
-    for (const conf of edgeConfidences) {
-        sources[conf] = (sources[conf] ?? 0) + 1;
-        if (CONFIDENCE_ORDER[conf] < CONFIDENCE_ORDER[minLevel]) {
-            minLevel = conf;
-        }
-    }
-    return {
-        level: minLevel,
-        edgeSources: sources,
-        pathLength: edgeConfidences.length,
-    };
-}
-/**
- * Get the numeric confidence score for a propagated result.
- */
-export function confidenceToScore(level) {
-    switch (level) {
-        case "compiler-verified":
-            return 1.0;
-        case "structural":
-            return 0.85;
-        case "heuristic":
-            return 0.5;
-    }
-}

package/dist/intelligence/convention-detector.js

@@ -1,242 +0,0 @@
-/**
- * Convention Detector — automated detection of naming, structural, and
- * import direction conventions from the codebase graph.
- *
- * O.6: Naming conventions (suffix/prefix patterns)
- * O.7: Structure conventions (file organization)
- * O.8: Import direction conventions (layer violations)
- * O.9: Confidence scoring per convention
- * O.10: Persistence to .unerr/conventions/detected.json
- */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-/**
- * Detect naming conventions (suffix/prefix patterns).
- */
-export function detectNamingConventions(entities) {
-    const conventions = [];
-    const suffixCounts = new Map();
-    const prefixCounts = new Map();
-    for (const entity of entities) {
-        if (entity.kind === "function" || entity.kind === "method") {
-            const prefixes = [
-                "get",
-                "set",
-                "is",
-                "has",
-                "create",
-                "update",
-                "delete",
-                "fetch",
-                "handle",
-                "on",
-            ];
-            for (const prefix of prefixes) {
-                if (entity.name.startsWith(prefix) &&
-                    entity.name.length > prefix.length) {
-                    const entry = prefixCounts.get(prefix) ?? {
-                        count: 0,
-                        kind: entity.kind,
-                        examples: [],
-                    };
-                    entry.count++;
-                    if (entry.examples.length < 3)
-                        entry.examples.push(entity.name);
-                    prefixCounts.set(prefix, entry);
-                }
-            }
-        }
-        if (entity.kind === "class" || entity.kind === "interface") {
-            const suffixes = [
-                "Service",
-                "Controller",
-                "Repository",
-                "Handler",
-                "Factory",
-                "Provider",
-                "Manager",
-                "Helper",
-                "Util",
-            ];
-            for (const suffix of suffixes) {
-                if (entity.name.endsWith(suffix)) {
-                    const entry = suffixCounts.get(suffix) ?? {
-                        count: 0,
-                        kind: entity.kind,
-                        examples: [],
-                    };
-                    entry.count++;
-                    if (entry.examples.length < 3)
-                        entry.examples.push(entity.name);
-                    suffixCounts.set(suffix, entry);
-                }
-            }
-        }
-    }
-    for (const [suffix, data] of suffixCounts) {
-        if (data.count >= 3) {
-            const totalOfKind = entities.filter((e) => e.kind === data.kind).length;
-            const adherence = totalOfKind > 0 ? data.count / totalOfKind : 0;
-            conventions.push({
-                id: `naming:suffix:${suffix.toLowerCase()}`,
-                type: "naming",
-                name: `${data.kind}s use "${suffix}" suffix`,
-                pattern: `*${suffix}`,
-                examples: data.examples,
-                adherence: Math.round(adherence * 100) / 100,
-                confidence: Math.min(0.95, 0.5 + data.count * 0.05),
-                entityCount: data.count,
-            });
-        }
-    }
-    for (const [prefix, data] of prefixCounts) {
-        if (data.count >= 5) {
-            const totalFuncs = entities.filter((e) => e.kind === "function" || e.kind === "method").length;
-            const adherence = totalFuncs > 0 ? data.count / totalFuncs : 0;
-            conventions.push({
-                id: `naming:prefix:${prefix}`,
-                type: "naming",
-                name: `Functions use "${prefix}" prefix pattern`,
-                pattern: `${prefix}*`,
-                examples: data.examples,
-                adherence: Math.round(adherence * 100) / 100,
-                confidence: Math.min(0.9, 0.4 + data.count * 0.03),
-                entityCount: data.count,
-            });
-        }
-    }
-    return conventions;
-}
-/**
- * Detect structural conventions (file organization patterns).
- */
-export function detectStructureConventions(entities) {
-    const conventions = [];
-    const dirKinds = new Map();
-    for (const entity of entities) {
-        const parts = entity.file_path.split("/");
-        if (parts.length < 2)
-            continue;
-        const dir = parts.slice(0, -1).join("/");
-        if (!dirKinds.has(dir))
-            dirKinds.set(dir, new Map());
-        const kindMap = dirKinds.get(dir);
-        kindMap.set(entity.kind, (kindMap.get(entity.kind) ?? 0) + 1);
-    }
-    const dirPatterns = new Map();
-    for (const [dir, kinds] of dirKinds) {
-        const dominant = [...kinds.entries()].sort((a, b) => b[1] - a[1])[0];
-        if (dominant && dominant[1] >= 3) {
-            const dirName = dir.split("/").pop() ?? dir;
-            const pattern = `${dirName}→${dominant[0]}`;
-            dirPatterns.set(pattern, (dirPatterns.get(pattern) ?? 0) + 1);
-        }
-    }
-    for (const [pattern, count] of dirPatterns) {
-        if (count >= 2) {
-            const [dirName, kind] = pattern.split("→");
-            conventions.push({
-                id: `structure:${pattern.toLowerCase().replace(/[^a-z0-9]/g, "-")}`,
-                type: "structure",
-                name: `"${dirName}" directories contain primarily ${kind}s`,
-                pattern,
-                examples: [],
-                adherence: 0.8,
-                confidence: Math.min(0.85, 0.5 + count * 0.1),
-                entityCount: count,
-            });
-        }
-    }
-    return conventions;
-}
-/**
- * Detect import direction conventions (layer violations).
- */
-export function detectImportDirectionConventions(entities, edges) {
-    const conventions = [];
-    const layerOrder = [
-        "utils",
-        "lib",
-        "core",
-        "services",
-        "api",
-        "routes",
-        "commands",
-        "entrypoints",
-    ];
-    const importEdges = edges.filter((e) => e.type === "imports");
-    let violations = 0;
-    let total = 0;
-    for (const edge of importEdges) {
-        const fromEntity = entities.find((e) => e.key === edge.from_key);
-        const toEntity = entities.find((e) => e.key === edge.to_key);
-        if (!fromEntity || !toEntity)
-            continue;
-        const fromLayer = getLayerIndex(fromEntity.file_path, layerOrder);
-        const toLayer = getLayerIndex(toEntity.file_path, layerOrder);
-        if (fromLayer >= 0 && toLayer >= 0) {
-            total++;
-            if (toLayer > fromLayer)
-                violations++;
-        }
-    }
-    if (total >= 5) {
-        const adherence = total > 0 ? 1 - violations / total : 1;
-        conventions.push({
-            id: "import-direction:layer-order",
-            type: "import-direction",
-            name: "Imports flow from high-level to low-level (no upward deps)",
-            pattern: "entrypoints→commands→services→core→utils",
-            examples: [],
-            adherence: Math.round(adherence * 100) / 100,
-            confidence: 0.8,
-            entityCount: total,
-        });
-    }
-    return conventions;
-}
-function getLayerIndex(filePath, layers) {
-    for (let i = 0; i < layers.length; i++) {
-        if (filePath.includes(layers[i]))
-            return i;
-    }
-    return -1;
-}
-/**
- * Run all convention detection and return combined report.
- */
-export function detectAllConventions(entities, edges) {
-    const naming = detectNamingConventions(entities);
-    const structure = detectStructureConventions(entities);
-    const imports = detectImportDirectionConventions(entities, edges);
-    return {
-        conventions: [...naming, ...structure, ...imports]
-            .filter((c) => c.confidence >= 0.5)
-            .sort((a, b) => b.confidence - a.confidence),
-        totalEntities: entities.length,
-        analyzedAt: new Date().toISOString(),
-    };
-}
-/**
- * Persist conventions to .unerr/conventions/detected.json.
- */
-export function persistConventions(unerrDir, report) {
-    const convDir = join(unerrDir, "conventions");
-    if (!existsSync(convDir))
-        mkdirSync(convDir, { recursive: true });
-    writeFileSync(join(convDir, "detected.json"), JSON.stringify(report, null, 2), "utf-8");
-}
-/**
- * Load persisted conventions.
- */
-export function loadConventions(unerrDir) {
-    const path = join(unerrDir, "conventions", "detected.json");
-    if (!existsSync(path))
-        return null;
-    try {
-        return JSON.parse(readFileSync(path, "utf-8"));
-    }
-    catch {
-        return null;
-    }
-}