akm-cli 0.9.16 → 0.9.17-alpha.10

package/dist/indexer/graph/graph-boost.js

@@ -1,427 +0,0 @@
-// This Source Code Form is subject to the terms of the Mozilla Public
-// License, v. 2.0. If a copy of the MPL was not distributed with this
-// file, You can obtain one at https://mozilla.org/MPL/2.0/.
-import { loadStoredGraphMeta, loadStoredGraphSnapshot } from "../db/graph-db.js";
-function normalizeGraphName(value) {
-    return value.trim().toLowerCase();
-}
-let cachedParsedGraph;
-/**
- * Clear the module-level parsed-graph cache.
- *
- * The cache keeps the most recently parsed `ParsedGraphContext` keyed by
- * (stashPath, generatedAt) tuples so back-to-back search invocations within
- * the same process don't re-read the SQLite snapshot from disk. The cache
- * persists across calls — which is the desired behaviour in production but
- * pathological for tests that swap the underlying stash directory between
- * test cases without bumping `generatedAt`. Such tests can observe stale
- * graph nodes from a previous test's stash.
- *
- * Tests (and any tooling that swaps stash backings) should call this between
- * setups to guarantee the next `loadGraphBoostContext` reads fresh state.
- * Recommended placement: `beforeEach` for test files that mutate graph
- * state, or after `deleteStoredGraph` / `replaceStoredGraph` calls that
- * intentionally invalidate the cache.
- */
-export function resetGraphBoostCache() {
-    cachedParsedGraph = undefined;
-}
-function resolveGraphBoostWeights(config) {
-    const configured = config?.search?.graphBoost;
-    return {
-        directBoostPerEntity: configured?.directBoostPerEntity ?? GRAPH_DIRECT_BOOST_PER_ENTITY,
-        directBoostCap: configured?.directBoostCap ?? GRAPH_DIRECT_BOOST_CAP,
-        hopBoostPerEntity: configured?.hopBoostPerEntity ?? GRAPH_HOP_BOOST_PER_ENTITY,
-        hopBoostCap: configured?.hopBoostCap ?? GRAPH_HOP_BOOST_CAP,
-        maxHops: Math.min(Math.max(configured?.maxHops ?? GRAPH_MAX_HOPS, 1), GRAPH_MAX_HOPS_HARD_CAP),
-        confidenceMode: configured?.confidenceMode ?? GRAPH_CONFIDENCE_MODE,
-        confidenceWeight: configured?.confidenceWeight ?? GRAPH_CONFIDENCE_WEIGHT,
-    };
-}
-/**
- * Per-entry weights, exposed as constants so tests can read them and so the
- * single-source-of-truth for "how much does the graph contribute" is here
- * rather than inlined into `db-search.ts`. Kept conservative — the goal is
- * a useful tiebreaker, not domination of the lexical signal.
- */
-export const GRAPH_DIRECT_BOOST_PER_ENTITY = 0.25;
-export const GRAPH_DIRECT_BOOST_CAP = 0.75;
-export const GRAPH_HOP_BOOST_PER_ENTITY = 0.1;
-export const GRAPH_HOP_BOOST_CAP = 0.3;
-export const GRAPH_MAX_HOPS = 1;
-export const GRAPH_CONFIDENCE_MODE = "blend";
-export const GRAPH_CONFIDENCE_WEIGHT = 0.2;
-const GRAPH_MAX_HOPS_HARD_CAP = 3;
-function normalizeConfidence(raw) {
-    if (typeof raw !== "number" || !Number.isFinite(raw))
-        return undefined;
-    return Math.max(0, Math.min(1, raw));
-}
-function combineConfidence(...parts) {
-    let out;
-    for (const part of parts) {
-        const value = normalizeConfidence(part);
-        if (value === undefined)
-            continue;
-        out = out === undefined ? value : out * value;
-    }
-    return out;
-}
-function toConfidenceMultiplier(rawConfidence, weights) {
-    const confidence = normalizeConfidence(rawConfidence) ?? 1;
-    const blendWeight = Math.max(0, Math.min(1, weights.confidenceWeight));
-    return 1 - blendWeight + blendWeight * confidence;
-}
-/**
- * Load the graph file for a stash root and pre-compute everything that's
- * shared across all entries scored for one query. Returns `null` when:
- *   - No graph snapshot exists in SQLite.
- *   - The query produces no token-level entity matches (no boost is
- *     possible, so we skip the per-entry overhead entirely).
- */
-export function loadGraphBoostContext(stashRoot, query, config, db) {
-    const stashRoots = Array.isArray(stashRoot) ? stashRoot : [stashRoot];
-    const parsed = readParsedGraphContext(stashRoots, db);
-    if (!parsed)
-        return null;
-    const weights = resolveGraphBoostWeights(config);
-    const queryTokens = query
-        .toLowerCase()
-        .split(/[\s\-_/]+/)
-        .filter((t) => t.length >= 2);
-    if (queryTokens.length === 0)
-        return null;
-    // Build a flat union of all extracted entities across the corpus. This
-    // is small (capped per-asset at extract time) and lets the per-entry
-    // path do a single set membership test.
-    const allEntities = new Set();
-    for (const node of parsed.graph.files) {
-        for (const entity of node.entities)
-            allEntities.add(entity);
-    }
-    // An entity matches the query when any of its sub-tokens equals or
-    // contains a query token. Matching is case-insensitive; the graph keeps
-    // canonical display strings and we normalize only for comparisons here.
-    const matchedEntities = new Set();
-    for (const entity of allEntities) {
-        const normalizedEntity = normalizeGraphName(entity);
-        const entityTokens = normalizedEntity.split(/[\s\-_/]+/).filter(Boolean);
-        for (const qt of queryTokens) {
-            if (normalizedEntity === qt ||
-                normalizedEntity.includes(qt) ||
-                entityTokens.some((et) => et === qt || et.includes(qt))) {
-                matchedEntities.add(entity);
-                break;
-            }
-        }
-    }
-    if (matchedEntities.size === 0)
-        return null;
-    const connectedEntities = new Set();
-    const connectedConfidence = new Map();
-    const visited = new Set();
-    let frontier = new Map();
-    for (const entity of matchedEntities) {
-        const seed = parsed.entityConfidence.get(entity) ?? 1;
-        frontier.set(entity, seed);
-        visited.add(entity);
-    }
-    for (let hop = 1; hop <= weights.maxHops; hop += 1) {
-        const next = new Map();
-        for (const [entity, pathConfidence] of frontier.entries()) {
-            const neighbors = parsed.adjacency.get(entity);
-            if (!neighbors)
-                continue;
-            for (const [neighbor, edgeConfidence] of neighbors.entries()) {
-                const neighborPathConfidence = Math.max(0, Math.min(1, pathConfidence * edgeConfidence));
-                const currentBest = connectedConfidence.get(neighbor) ?? 0;
-                if (neighborPathConfidence > currentBest)
-                    connectedConfidence.set(neighbor, neighborPathConfidence);
-                if (visited.has(neighbor))
-                    continue;
-                visited.add(neighbor);
-                next.set(neighbor, Math.max(next.get(neighbor) ?? 0, neighborPathConfidence));
-                connectedEntities.add(neighbor);
-            }
-        }
-        if (next.size === 0)
-            break;
-        frontier = next;
-    }
-    return {
-        graph: parsed.graph,
-        nodesByPath: parsed.nodesByPath,
-        matchedEntities,
-        connectedEntities,
-        connectedConfidence,
-        entityConfidence: parsed.entityConfidence,
-        adjacency: parsed.adjacency,
-        weights,
-    };
-}
-/**
- * Compute the graph-boost contribution for a single scored entry.
- *
- * The return value is added directly into `boostSum` in `searchDatabase`'s
- * existing scoring loop — same units, same cap policy. Returns `0` when
- * the entry's file isn't in the graph or when no entity overlap exists.
- */
-export function computeGraphBoost(context, filePath) {
-    const node = context.nodesByPath.get(filePath);
-    if (!node)
-        return 0;
-    let directBoostRaw = 0;
-    let hopBoostRaw = 0;
-    for (const entity of node.entities) {
-        if (context.matchedEntities.has(entity)) {
-            const directConfidence = combineConfidence(node.confidence, context.entityConfidence.get(entity));
-            directBoostRaw +=
-                context.weights.directBoostPerEntity * toConfidenceMultiplier(directConfidence, context.weights);
-        }
-        else if (context.connectedEntities.has(entity)) {
-            const hopConfidence = combineConfidence(node.confidence, context.entityConfidence.get(entity), context.connectedConfidence.get(entity));
-            hopBoostRaw += context.weights.hopBoostPerEntity * toConfidenceMultiplier(hopConfidence, context.weights);
-        }
-    }
-    const directBoost = Math.min(context.weights.directBoostCap, directBoostRaw);
-    const hopBoost = Math.min(context.weights.hopBoostCap, hopBoostRaw);
-    return directBoost + hopBoost;
-}
-export function collectGraphRelatedHit(context, filePath) {
-    const node = context.nodesByPath.get(filePath);
-    if (!node)
-        return null;
-    const entities = [];
-    for (const entity of node.entities) {
-        if (context.matchedEntities.has(entity)) {
-            entities.push({
-                name: entity,
-                kind: "matched",
-                ...(context.entityConfidence.get(entity) !== undefined
-                    ? { confidence: context.entityConfidence.get(entity) }
-                    : {}),
-            });
-            continue;
-        }
-        if (context.connectedEntities.has(entity)) {
-            entities.push({
-                name: entity,
-                kind: "connected",
-                ...(context.connectedConfidence.get(entity) !== undefined
-                    ? { confidence: context.connectedConfidence.get(entity) }
-                    : {}),
-            });
-        }
-    }
-    if (entities.length === 0)
-        return null;
-    const relatedNames = new Set(entities.map((entity) => entity.name));
-    const relations = node.relations
-        .filter((relation) => relatedNames.has(relation.from) || relatedNames.has(relation.to))
-        .map((relation) => ({
-        from: relation.from,
-        to: relation.to,
-        ...(relation.type ? { type: relation.type } : {}),
-        ...(normalizeConfidence(relation.confidence) !== undefined
-            ? { confidence: normalizeConfidence(relation.confidence) }
-            : {}),
-    }));
-    return {
-        path: filePath,
-        type: node.type,
-        entities: entities.sort((a, b) => a.name.localeCompare(b.name)),
-        relations,
-    };
-}
-/**
- * Find graph files that share entities with the given file.
- *
- * Implementation: SQL self-join on graph_file_entities, scoped by stash_root,
- * grouped by file_path, ordered by shared-entity count desc. Touches ~50-200
- * rows instead of loading the entire snapshot into memory. Cold-call latency
- * drops from ~30-60ms (full snapshot parse) to ~2-5ms on typical stashes.
- *
- * #624-P1: the graph tables are keyed on (stash_root, file_path, body_hash) —
- * NOT entries.id — so candidates are identified by file_path (the unique index
- * idx_graph_files_path guarantees one graph_files row per path).
- *
- * The returned `ref` field carries the canonical indexed `concept_id`, never a
- * value re-derived from presentation fields. It is undefined
- * when the graph row has no matching entry with current indexed provenance.
- */
-export function listRelatedPathsForFile(stashRoot, filePath, limit = 5, db) {
-    if (!db) {
-        // Fallback: opening a transient DB here is not currently a use case (all
-        // callers pass a handle), so degrade to empty rather than reopening.
-        return [];
-    }
-    // Confirm the target file has a graph row; without it there is nothing to
-    // relate. (Identity is file_path within the stash — one row per path.)
-    const row = db
-        .prepare("SELECT 1 AS present FROM graph_files WHERE stash_root = ? AND file_path = ? LIMIT 1")
-        .get(stashRoot, filePath);
-    if (row === undefined)
-        return [];
-    const effectiveLimit = Math.max(1, limit);
-    // Shared-entity count per candidate file_path. The target's entities are the
-    // rows for `filePath`; candidates are any OTHER file_path in the stash that
-    // shares a normalized entity.
-    const candidateRows = db
-        .prepare(`SELECT gf.file_path   AS file_path,
-              gf.file_type   AS file_type,
-              COUNT(*)       AS shared
-          FROM graph_file_entities target
-          JOIN graph_file_entities e
-            ON e.stash_root = target.stash_root
-           AND e.entity_norm = target.entity_norm
-           AND e.file_path  != target.file_path
-          JOIN graph_files gf
-            ON gf.stash_root = e.stash_root
-           AND gf.file_path = e.file_path
-           AND gf.body_hash = e.body_hash
-        WHERE target.file_path  = ?
-          AND target.stash_root = ?
-        GROUP BY gf.file_path
-        ORDER BY shared DESC, gf.file_path ASC
-        LIMIT ?`)
-        .all(filePath, stashRoot, effectiveLimit);
-    if (candidateRows.length === 0)
-        return [];
-    const candidatePaths = candidateRows.map((r) => r.file_path);
-    const placeholders = candidatePaths.map(() => "?").join(",");
-    // Pull the shared entity names (joined by normalized casing) for display.
-    const sharedRows = db
-        .prepare(`SELECT e.file_path AS file_path, e.entity AS entity
-         FROM graph_file_entities e
-         JOIN graph_file_entities target
-           ON target.stash_root = e.stash_root
-           AND target.entity_norm = e.entity_norm
-         WHERE e.file_path IN (${placeholders})
-           AND e.stash_root = ?
-           AND target.file_path = ?
-           AND target.stash_root = ?`)
-        .all(...candidatePaths, stashRoot, filePath, stashRoot);
-    const sharedByPath = new Map();
-    for (const row of sharedRows) {
-        let bucket = sharedByPath.get(row.file_path);
-        if (!bucket) {
-            bucket = new Set();
-            sharedByPath.set(row.file_path, bucket);
-        }
-        bucket.add(row.entity);
-    }
-    // Relation count for each candidate (relations where either endpoint
-    // matches one of the shared entities).
-    const relationCountByPath = new Map();
-    const relationRows = db
-        .prepare(`SELECT file_path, from_entity, to_entity
-         FROM graph_file_relations
-        WHERE file_path IN (${placeholders})
-          AND stash_root = ?`)
-        .all(...candidatePaths, stashRoot);
-    for (const row of relationRows) {
-        const shared = sharedByPath.get(row.file_path);
-        if (!shared)
-            continue;
-        if (shared.has(row.from_entity) || shared.has(row.to_entity)) {
-            relationCountByPath.set(row.file_path, (relationCountByPath.get(row.file_path) ?? 0) + 1);
-        }
-    }
-    // This related list is scoped to one source root, so the user-facing ref is
-    // the indexed bundle-less conceptId.
-    const refByPath = new Map();
-    try {
-        const entryRows = db
-            .prepare(`SELECT file_path, concept_id FROM entries
-          WHERE file_path IN (${placeholders})`)
-            .all(...candidatePaths);
-        for (const row of entryRows) {
-            refByPath.set(row.file_path, row.concept_id);
-        }
-    }
-    catch {
-        /* ignore — refs are best-effort */
-    }
-    return candidateRows.map((row) => {
-        const sharedSet = sharedByPath.get(row.file_path) ?? new Set();
-        const sharedEntities = [...sharedSet].sort((a, b) => a.localeCompare(b));
-        const ref = refByPath.get(row.file_path);
-        return {
-            ...(ref ? { ref } : {}),
-            path: row.file_path,
-            type: row.file_type,
-            sharedEntities,
-            relationCount: relationCountByPath.get(row.file_path) ?? 0,
-        };
-    });
-}
-/**
- * Load and normalize graph data from SQLite once, then reuse it across all
- * per-entry boost lookups in the current query.
- */
-function readParsedGraphContext(stashRoots, db) {
-    const sortedRoots = [...new Set(stashRoots)].sort((a, b) => a.localeCompare(b));
-    if (sortedRoots.length === 0)
-        return null;
-    const metas = sortedRoots
-        .map((stashRoot) => loadStoredGraphMeta(stashRoot, db))
-        .filter((meta) => meta !== null);
-    if (metas.length === 0)
-        return null;
-    const cacheKey = metas.map((meta) => `${meta.stashPath}\u0000${meta.generatedAt}`).join("\u0001");
-    if (cachedParsedGraph && cachedParsedGraph.cacheKey === cacheKey)
-        return cachedParsedGraph.context;
-    const snapshots = metas
-        .map((meta) => loadStoredGraphSnapshot(meta.stashPath, db))
-        .filter((snapshot) => snapshot !== null);
-    if (snapshots.length === 0)
-        return null;
-    const graph = {
-        schemaVersion: Math.max(...snapshots.map((snapshot) => snapshot.schemaVersion)),
-        generatedAt: snapshots
-            .map((snapshot) => snapshot.generatedAt)
-            .sort()
-            .at(-1) ?? new Date(0).toISOString(),
-        stashRoot: snapshots[0]?.stashPath ?? "",
-        files: snapshots.flatMap((snapshot) => snapshot.files),
-        entities: [...new Set(snapshots.flatMap((snapshot) => snapshot.entities))],
-        relations: snapshots.flatMap((snapshot) => snapshot.relations),
-    };
-    const nodesByPath = new Map();
-    const entityConfidence = new Map();
-    const adjacency = new Map();
-    function setBestEntityConfidence(entity, confidence) {
-        const normalized = normalizeConfidence(confidence);
-        if (normalized === undefined)
-            return;
-        const current = entityConfidence.get(entity);
-        if (current === undefined || normalized > current)
-            entityConfidence.set(entity, normalized);
-    }
-    function setBestEdgeConfidence(from, to, confidence) {
-        const normalized = normalizeConfidence(confidence);
-        if (!adjacency.has(from))
-            adjacency.set(from, new Map());
-        const neighbors = adjacency.get(from);
-        if (!neighbors)
-            return;
-        const current = neighbors.get(to);
-        const next = normalized ?? 1;
-        if (current === undefined || next > current)
-            neighbors.set(to, next);
-    }
-    for (const node of graph.files) {
-        nodesByPath.set(node.path, node);
-        for (const entity of node.entities) {
-            setBestEntityConfidence(entity, node.confidence);
-        }
-        for (const rel of node.relations) {
-            const edgeConfidence = combineConfidence(node.confidence, rel.confidence);
-            setBestEdgeConfidence(rel.from, rel.to, edgeConfidence);
-            setBestEdgeConfidence(rel.to, rel.from, edgeConfidence);
-        }
-    }
-    const context = { graph, nodesByPath, entityConfidence, adjacency };
-    cachedParsedGraph = { cacheKey, context };
-    return context;
-}

package/dist/indexer/graph/graph-dedup.js

@@ -1,95 +0,0 @@
-// This Source Code Form is subject to the terms of the Mozilla Public
-// License, v. 2.0. If a copy of the MPL was not distributed with this
-// file, You can obtain one at https://mozilla.org/MPL/2.0/.
-function normalizeRelationType(raw) {
-    const normalized = raw?.trim().toLowerCase().replace(/\s+/g, " ") ?? "";
-    if (!normalized)
-        return "";
-    if (normalized === "use" || normalized === "utilizes")
-        return "uses";
-    if (normalized === "depend on" || normalized === "depends")
-        return "depends on";
-    if (normalized === "integrates" || normalized === "integration with")
-        return "integrates with";
-    return normalized;
-}
-function normalizeConfidence(raw) {
-    if (typeof raw !== "number" || !Number.isFinite(raw))
-        return undefined;
-    return Math.max(0, Math.min(1, raw));
-}
-/**
- * Merge and deduplicate entities and relations from multiple per-asset
- * GraphExtraction results into one canonical graph.
- *
- * Entities are keyed on their lowercased, trimmed form. The first-seen
- * casing is preserved as canonical. Relations are keyed on
- * `(from, to, type)` (all lowercased). Dangling relations — those whose
- * `from` or `to` is absent from the deduplicated entity set — are dropped.
- */
-export function deduplicateGraph(extractions, assetRefs) {
-    const entityCanonical = new Map();
-    const entitySources = new Map();
-    for (let i = 0; i < extractions.length; i++) {
-        const ref = assetRefs?.[i] ?? "unknown";
-        for (const raw of extractions[i].entities) {
-            const trimmed = raw.trim();
-            if (!trimmed)
-                continue;
-            const normalized = trimmed.toLowerCase();
-            if (!entityCanonical.has(normalized)) {
-                entityCanonical.set(normalized, trimmed);
-                entitySources.set(normalized, [ref]);
-            }
-            else {
-                const srcs = entitySources.get(normalized);
-                if (srcs && !srcs.includes(ref))
-                    srcs.push(ref);
-            }
-        }
-    }
-    const entities = Array.from(entityCanonical.values());
-    const entityNormSet = new Set(entityCanonical.keys());
-    const relSeenKey = new Map();
-    const relationIndexByKey = new Map();
-    const relations = [];
-    for (let i = 0; i < extractions.length; i++) {
-        const ref = assetRefs?.[i] ?? "unknown";
-        for (const rel of extractions[i].relations) {
-            const fromNorm = rel.from.trim().toLowerCase();
-            const toNorm = rel.to.trim().toLowerCase();
-            const typeNorm = normalizeRelationType(rel.type);
-            if (!entityNormSet.has(fromNorm) || !entityNormSet.has(toNorm))
-                continue;
-            const key = `${fromNorm}\0${toNorm}\0${typeNorm}`;
-            if (!relSeenKey.has(key)) {
-                relSeenKey.set(key, [ref]);
-                const canonical = {
-                    from: entityCanonical.get(fromNorm) ?? rel.from,
-                    to: entityCanonical.get(toNorm) ?? rel.to,
-                };
-                if (typeNorm)
-                    canonical.type = typeNorm;
-                const confidence = normalizeConfidence(rel.confidence);
-                if (confidence !== undefined)
-                    canonical.confidence = confidence;
-                relationIndexByKey.set(key, relations.length);
-                relations.push(canonical);
-            }
-            else {
-                const srcs = relSeenKey.get(key);
-                if (srcs && !srcs.includes(ref))
-                    srcs.push(ref);
-                const idx = relationIndexByKey.get(key);
-                const nextConfidence = normalizeConfidence(rel.confidence);
-                if (idx !== undefined && nextConfidence !== undefined) {
-                    const current = normalizeConfidence(relations[idx]?.confidence) ?? 0;
-                    if (nextConfidence > current && relations[idx])
-                        relations[idx].confidence = nextConfidence;
-                }
-            }
-        }
-    }
-    const relationSources = new Map(relSeenKey);
-    return { entities, relations, entitySources, relationSources };
-}