@opencodehub/ingestion 0.1.0

package/dist/pipeline/phases/communities.js

@@ -0,0 +1,412 @@
+/**
+ * Communities phase — cluster callable symbols with the Leiden algorithm.
+ *
+ * We build an undirected, weighted graph whose nodes are every `Function`,
+ * `Method`, `Class`, `Interface`, `Struct`, and `Trait` in the workspace.
+ * Edge weights:
+ *   - `CALLS`        → 1.0 (strongest intra-feature signal)
+ *   - `HAS_METHOD`   → 0.5 (co-location by ownership)
+ *
+ * Files, folders, routes, tools, modules, communities, and processes are
+ * intentionally excluded so the clustering reflects *behavioural* coupling
+ * rather than filesystem neighbourhoods.
+ *
+ * The Leiden call is parameterised with a fixed `randomSeed` so two runs on
+ * the same input graph produce identical community assignments. If the
+ * external Leiden integration produces zero communities (e.g. the graph was
+ * trivially empty or the library's shape changed), we fall back to a
+ * deterministic connected-components labeler and emit a warning.
+ *
+ * Community names are synthesised from the top-3 most-frequent identifier
+ * tokens across the community's members (splitting on camelCase, snake_case,
+ * and dots; filtering against a small English stop-word list). A fallback of
+ * `community-<id>` is used when no tokens survive.
+ */
+import { Graph as GraphtyGraph, leiden } from "@graphty/algorithms";
+import { makeNodeId } from "@opencodehub/core-types";
+import { resolveIncrementalView } from "./incremental-helper.js";
+import { INCREMENTAL_SCOPE_PHASE_NAME } from "./incremental-scope.js";
+import { MRO_PHASE_NAME } from "./mro.js";
+import { STRUCTURE_PHASE_NAME } from "./structure.js";
+export const COMMUNITIES_PHASE_NAME = "communities";
+/**
+ * Node kinds eligible for community clustering.
+ */
+const CLUSTERABLE_KINDS = new Set([
+    "Function",
+    "Method",
+    "Class",
+    "Interface",
+    "Struct",
+    "Trait",
+    "Constructor",
+]);
+const LEIDEN_SEED = 42;
+export const communitiesPhase = {
+    name: COMMUNITIES_PHASE_NAME,
+    deps: [MRO_PHASE_NAME, STRUCTURE_PHASE_NAME, INCREMENTAL_SCOPE_PHASE_NAME],
+    async run(ctx) {
+        return runCommunities(ctx);
+    },
+};
+function runCommunities(ctx) {
+    // ---- : incremental carry-forward short-circuit. ---------------
+    //
+    // Leiden is deterministic given a fixed seed AND a fixed input graph,
+    // but its partition is sensitive to every edge weight — running on a
+    // sparsified subgraph drifts in the general case. For the determinism
+    // gate (`--full` vs `--incremental` at the same commit must byte-equal)
+    // we take the conservative path: when the incremental view is active,
+    // carry forward every Community node + MEMBER_OF edge from the prior
+    // graph verbatim, and skip Leiden entirely. The post-parse callable
+    // graph is byte-identical to the prior run under no-semantic-change, so
+    // re-running Leiden would produce the same partition anyway; skipping
+    // the work is a pure speedup. If the closure introduces new callables
+    // whose community assignment matters, the 30% safety valve in
+    // incremental-scope flips mode back to "full" and Leiden runs normally.
+    const view = resolveIncrementalView(ctx);
+    if (view.active &&
+        view.previousGraph?.edges !== undefined &&
+        view.previousGraph.nodes !== undefined) {
+        let carriedMembers = 0;
+        let carriedCommunities = 0;
+        for (const n of view.previousGraph.nodes) {
+            if (n.kind !== "Community")
+                continue;
+            ctx.graph.addNode(n);
+            carriedCommunities += 1;
+        }
+        for (const e of view.previousGraph.edges) {
+            if (e.type !== "MEMBER_OF")
+                continue;
+            ctx.graph.addEdge({
+                from: e.from,
+                to: e.to,
+                type: e.type,
+                confidence: e.confidence,
+                ...(e.reason !== undefined ? { reason: e.reason } : {}),
+            });
+            carriedMembers += 1;
+        }
+        return {
+            communityCount: carriedCommunities,
+            memberCount: carriedMembers,
+            unclusteredCount: 0,
+            usedFallback: false,
+        };
+    }
+    // ---- Collect eligible nodes + their names for later labeling. ---------
+    const memberNameById = new Map();
+    for (const n of ctx.graph.nodes()) {
+        if (CLUSTERABLE_KINDS.has(n.kind))
+            memberNameById.set(n.id, n.name);
+    }
+    const memberIds = [...memberNameById.keys()].sort();
+    if (memberIds.length === 0) {
+        return { communityCount: 0, memberCount: 0, unclusteredCount: 0, usedFallback: false };
+    }
+    // ---- Build weighted undirected graph for Leiden. ----------------------
+    // We aggregate weights across parallel edges (CALLS + HAS_METHOD between
+    // the same pair collapse to a single weight).
+    const edgeWeights = new Map();
+    const clusterableSet = new Set(memberIds);
+    for (const e of ctx.graph.edges()) {
+        if (e.type !== "CALLS" && e.type !== "HAS_METHOD")
+            continue;
+        const from = e.from;
+        const to = e.to;
+        if (!clusterableSet.has(from) || !clusterableSet.has(to))
+            continue;
+        if (from === to)
+            continue; // self-loops carry no clustering information.
+        const weight = e.type === "CALLS" ? 1.0 : 0.5;
+        // Key by sorted endpoints for undirected semantics.
+        const a = from < to ? from : to;
+        const b = from < to ? to : from;
+        const key = `${a}\u0000${b}`;
+        edgeWeights.set(key, (edgeWeights.get(key) ?? 0) + weight);
+    }
+    // Build the graphty graph; add nodes in sorted order for a deterministic
+    // initial partition (every node starts in its own community, indexed by
+    // insertion order).
+    const gtyGraph = new GraphtyGraph({ directed: false, allowSelfLoops: false });
+    for (const id of memberIds)
+        gtyGraph.addNode(id);
+    // Sort edges for deterministic insertion order.
+    const sortedKeys = [...edgeWeights.keys()].sort();
+    for (const key of sortedKeys) {
+        const idx = key.indexOf("\u0000");
+        if (idx < 0)
+            continue;
+        const a = key.slice(0, idx);
+        const b = key.slice(idx + 1);
+        const w = edgeWeights.get(key) ?? 1;
+        gtyGraph.addEdge(a, b, w);
+    }
+    // ---- Run Leiden (or fall back to connected components). ---------------
+    let communityById = new Map();
+    let usedFallback = false;
+    try {
+        const result = leiden(gtyGraph, { resolution: 1.0, randomSeed: LEIDEN_SEED });
+        if (result.communities && result.communities.size > 0) {
+            communityById = new Map(result.communities);
+        }
+        else {
+            usedFallback = true;
+        }
+    }
+    catch (err) {
+        ctx.onProgress?.({
+            phase: COMMUNITIES_PHASE_NAME,
+            kind: "warn",
+            message: `communities: leiden failed (${err.message}); falling back to connected components`,
+        });
+        usedFallback = true;
+    }
+    if (usedFallback) {
+        communityById = connectedComponents(memberIds, edgeWeights);
+    }
+    // ---- Canonicalise community ids. --------------------------------------
+    // The raw Leiden ids are arbitrary integers and might vary in their
+    // numeric value between invocations even when the partitioning is the
+    // same. Rekey each group by its lexicographically smallest member id —
+    // this is stable as long as the partition itself is.
+    const groupsByRaw = new Map();
+    for (const id of memberIds) {
+        const raw = communityById.get(id);
+        if (raw === undefined)
+            continue;
+        const existing = groupsByRaw.get(raw);
+        if (existing !== undefined)
+            existing.push(id);
+        else
+            groupsByRaw.set(raw, [id]);
+    }
+    // Sort each group, then sort groups by their first member for canonical
+    // iteration order.
+    const canonicalGroups = [];
+    let canonicalCounter = 0;
+    const sortedGroupHeads = [];
+    for (const [raw, members] of groupsByRaw) {
+        members.sort();
+        const head = members[0];
+        if (head !== undefined)
+            sortedGroupHeads.push({ head, raw });
+    }
+    sortedGroupHeads.sort((a, b) => (a.head < b.head ? -1 : a.head > b.head ? 1 : 0));
+    for (const g of sortedGroupHeads) {
+        const members = groupsByRaw.get(g.raw) ?? [];
+        canonicalGroups.push({ canonicalId: canonicalCounter, members });
+        canonicalCounter += 1;
+    }
+    // ---- Emit Community nodes + MEMBER_OF edges. --------------------------
+    let memberCount = 0;
+    let unclusteredCount = 0;
+    for (const group of canonicalGroups) {
+        const { canonicalId, members } = group;
+        // Skip degenerate clusters (singletons and 2-member pairs) — they
+        // clutter the graph without adding meaningful functional-area signal.
+        // Count them as unclustered instead. A threshold of 3 matches the
+        // smallest cluster size that can form a non-trivial topology.
+        if (members.length < 3) {
+            unclusteredCount += members.length;
+            continue;
+        }
+        const names = members
+            .map((m) => memberNameById.get(m))
+            .filter((n) => n !== undefined);
+        const keywords = topKeywords(names);
+        const communityNodeId = makeNodeId("Community", "<global>", `community-${canonicalId}`);
+        const communityNode = {
+            id: communityNodeId,
+            kind: "Community",
+            name: `community-${canonicalId}`,
+            filePath: "<global>",
+            symbolCount: members.length,
+            cohesion: cohesion(members, edgeWeights),
+            ...(keywords.length > 0
+                ? {
+                    inferredLabel: keywords.slice(0, 3).join("-"),
+                    keywords,
+                }
+                : {}),
+        };
+        ctx.graph.addNode(communityNode);
+        for (const member of members) {
+            ctx.graph.addEdge({
+                from: member,
+                to: communityNodeId,
+                type: "MEMBER_OF",
+                confidence: 1.0,
+                reason: usedFallback ? "connected-component" : "leiden",
+            });
+            memberCount += 1;
+        }
+    }
+    return {
+        communityCount: canonicalGroups.filter((g) => g.members.length >= 3).length,
+        memberCount,
+        unclusteredCount,
+        usedFallback,
+    };
+}
+/**
+ * Tokenise a list of identifier-like names and return the top-N most
+ * frequent tokens, lowercased and stop-word filtered, sorted by descending
+ * count with alphabetical tiebreak.
+ */
+function topKeywords(names) {
+    const STOP = new Set([
+        "get",
+        "set",
+        "is",
+        "has",
+        "the",
+        "a",
+        "an",
+        "to",
+        "from",
+        "of",
+        "for",
+        "on",
+        "in",
+        "at",
+        "by",
+        "and",
+        "or",
+        "not",
+        "with",
+        "new",
+        "my",
+        "do",
+        "run",
+        "it",
+        "init",
+        "fn",
+        "func",
+    ]);
+    const counts = new Map();
+    for (const n of names) {
+        for (const tok of tokenise(n)) {
+            const lower = tok.toLowerCase();
+            if (lower.length < 3)
+                continue;
+            if (STOP.has(lower))
+                continue;
+            counts.set(lower, (counts.get(lower) ?? 0) + 1);
+        }
+    }
+    const ranked = [...counts.entries()].sort((a, b) => {
+        if (a[1] !== b[1])
+            return b[1] - a[1];
+        return a[0] < b[0] ? -1 : 1;
+    });
+    return ranked.slice(0, 5).map(([tok]) => tok);
+}
+function tokenise(name) {
+    // Split on non-alphanumeric separators and camelCase boundaries.
+    const parts = [];
+    let current = "";
+    for (let i = 0; i < name.length; i += 1) {
+        const ch = name[i];
+        const isUpper = ch >= "A" && ch <= "Z";
+        const isLower = ch >= "a" && ch <= "z";
+        const isDigit = ch >= "0" && ch <= "9";
+        if (!isUpper && !isLower && !isDigit) {
+            if (current.length > 0)
+                parts.push(current);
+            current = "";
+            continue;
+        }
+        if (isUpper && current.length > 0) {
+            const prev = current[current.length - 1];
+            const prevLower = prev >= "a" && prev <= "z";
+            if (prevLower) {
+                parts.push(current);
+                current = "";
+            }
+        }
+        current += ch;
+    }
+    if (current.length > 0)
+        parts.push(current);
+    return parts;
+}
+/**
+ * Average weight per (unordered) intra-community edge as a very rough
+ * cohesion score. Does not normalise by community size; MVP-grade signal.
+ */
+function cohesion(members, edgeWeights) {
+    if (members.length < 2)
+        return 0;
+    const set = new Set(members);
+    let total = 0;
+    let count = 0;
+    for (const [key, w] of edgeWeights) {
+        const idx = key.indexOf("\u0000");
+        if (idx < 0)
+            continue;
+        const a = key.slice(0, idx);
+        const b = key.slice(idx + 1);
+        if (set.has(a) && set.has(b)) {
+            total += w;
+            count += 1;
+        }
+    }
+    if (count === 0)
+        return 0;
+    return total / count;
+}
+/**
+ * Deterministic weakly-connected-components labeler. Used when Leiden
+ * integration fails or returns an empty partition.
+ */
+function connectedComponents(nodes, edgeWeights) {
+    const parent = new Map();
+    for (const n of nodes)
+        parent.set(n, n);
+    function find(x) {
+        let cur = x;
+        while (parent.get(cur) !== cur) {
+            const p = parent.get(cur);
+            parent.set(cur, parent.get(p));
+            cur = parent.get(cur);
+        }
+        return cur;
+    }
+    function union(a, b) {
+        const ra = find(a);
+        const rb = find(b);
+        if (ra === rb)
+            return;
+        // Lexicographically smaller id wins — pinned for determinism.
+        if (ra < rb)
+            parent.set(rb, ra);
+        else
+            parent.set(ra, rb);
+    }
+    for (const key of [...edgeWeights.keys()].sort()) {
+        const idx = key.indexOf("\u0000");
+        if (idx < 0)
+            continue;
+        const a = key.slice(0, idx);
+        const b = key.slice(idx + 1);
+        if (parent.has(a) && parent.has(b))
+            union(a, b);
+    }
+    const rootToIndex = new Map();
+    const out = new Map();
+    let next = 0;
+    for (const n of nodes) {
+        const r = find(n);
+        let idx = rootToIndex.get(r);
+        if (idx === undefined) {
+            idx = next;
+            next += 1;
+            rootToIndex.set(r, idx);
+        }
+        out.set(n, idx);
+    }
+    return out;
+}
+//# sourceMappingURL=communities.js.map

package/dist/pipeline/phases/communities.js.map

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

package/dist/pipeline/phases/complexity.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Complexity phase — annotate Function / Method / Constructor nodes with
+ * cyclomatic complexity, maximum nesting depth, NLOC, and Halstead volume.
+ *
+ * Runs after `parse` (it needs the definitions and their line ranges) and
+ * before any phase that depends on complexity-derived signals (none yet at
+ * MVP, but e.g. risk scoring will). The phase re-parses each source file
+ * once with the same grammar used by `parse`, then walks the subtree of each
+ * callable definition to compute:
+ *
+ *   - `cyclomaticComplexity`: 1 + the number of decision points in the body
+ *     (branches, loops, short-circuit boolean operators, catch clauses, etc.
+ *     — per-language lists below).
+ *   - `nestingDepth`: maximum depth of nested block/statement nodes inside
+ *     the body. An unnested body reports 0.
+ *   - `nloc`: count of non-blank, non-comment-only physical lines between
+ *     the definition's `startLine` and `endLine` (inclusive).
+ *   - `halsteadVolume`: (N1+N2) * log2(n1+n2) Halstead volume computed from
+ *     leaf-token operator vs operand counts. Requires the provider to
+ *     declare a `halsteadOperatorKinds` list; omitted when absent.
+ *
+ * The phase mutates the shared {@link KnowledgeGraph} by re-adding each
+ * callable node with the extra fields set; {@link KnowledgeGraph.addNode}
+ * keeps the entry with more defined fields, so the annotated version wins.
+ *
+ * Determinism:
+ *   - Files are iterated in sorted order.
+ *   - Within each file, definitions are iterated in (startLine, qualifiedName)
+ *     order — identical to the tiebreak the parse phase uses.
+ *   - Tree-sitter cursor walks are deterministic per grammar.
+ *
+ * Robustness:
+ *   - A missing file, empty body, or re-parse error increments `skipped`
+ *     rather than throwing.
+ *   - Providers without a `complexityDefinitionKinds` table cause that
+ *     language's callables to be skipped with a single debug note — no
+ *     throw.
+ */
+import type { NodeId } from "@opencodehub/core-types";
+import type { PipelinePhase } from "../types.js";
+export declare const COMPLEXITY_PHASE_NAME: "complexity";
+export interface ComplexityOutput {
+    readonly symbolsAnnotated: number;
+    /** Callables whose complexity could not be computed (missing file, empty
+     *  body, re-parse failure). Surfaced for diagnostics; never fatal. */
+    readonly skipped: number;
+}
+export declare const complexityPhase: PipelinePhase<ComplexityOutput>;
+export type { NodeId };
+//# sourceMappingURL=complexity.d.ts.map

package/dist/pipeline/phases/complexity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"complexity.d.ts","sourceRoot":"","sources":["../../../src/pipeline/phases/complexity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAIH,OAAO,KAAK,EAAa,MAAM,EAAY,MAAM,yBAAyB,CAAC;AAK3E,OAAO,KAAK,EAAmB,aAAa,EAAE,MAAM,aAAa,CAAC;AAIlE,eAAO,MAAM,qBAAqB,EAAG,YAAqB,CAAC;AAE3D,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC;0EACsE;IACtE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,eAAO,MAAM,eAAe,EAAE,aAAa,CAAC,gBAAgB,CAc3D,CAAC;AAuyBF,YAAY,EAAE,MAAM,EAAE,CAAC"}