akm-cli 0.9.0-rc.9 → 0.9.0

package/dist/commands/graph/graph.js

@@ -1,489 +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 fs from "node:fs";
-import path from "node:path";
-import { displayRef, parseQualifiedRefInput } from "../../core/asset/resolve-ref.js";
-import { loadConfig } from "../../core/config/config.js";
-import { NotFoundError, UsageError } from "../../core/errors.js";
-import { getDbPath } from "../../core/paths.js";
-import { warn } from "../../core/warn.js";
-import { loadStoredGraphSnapshot } from "../../indexer/db/graph-db.js";
-import { listRelatedPathsForFile } from "../../indexer/graph/graph-boost.js";
-import { runGraphExtractionPass } from "../../indexer/graph/graph-extraction.js";
-import { withIndexWriterLease } from "../../indexer/index-writer-lock.js";
-import { lookup } from "../../indexer/indexer.js";
-import { findSourceForPath, resolveSourceEntries } from "../../indexer/search/search-source.js";
-import { resolveAssetPath } from "../../indexer/walk/path-resolver.js";
-import { closeDatabase, openExistingDatabase, openIndexDatabase } from "../../storage/repositories/index-connection.js";
-import { findEntryIdByRef, getEntryById, getEntryRefRowsForStashRoot, } from "../../storage/repositories/index-entries-repository.js";
-function resolveGraphStashPath(source) {
-    const sources = resolveSourceEntries(undefined, loadConfig());
-    if (sources.length === 0) {
-        throw new NotFoundError("No stash sources are configured.", "STASH_NOT_FOUND");
-    }
-    if (!source || source === "primary")
-        return sources[0].path;
-    const matched = sources.find((entry) => entry.registryId === source || entry.path === source);
-    if (!matched) {
-        throw new NotFoundError(`Source not found: ${source}`, "SOURCE_NOT_FOUND", "Run `akm list` to see source names.");
-    }
-    return matched.path;
-}
-function loadGraph(source) {
-    const stashPath = resolveGraphStashPath(source);
-    let db;
-    try {
-        db = openExistingDatabase();
-        const snapshot = loadStoredGraphSnapshot(stashPath, db);
-        if (!snapshot) {
-            throw new NotFoundError(`Graph data not found for source ${stashPath}.`, "FILE_NOT_FOUND", "Run the improvement flow that refreshes graph extraction data.");
-        }
-        return {
-            graph: {
-                schemaVersion: snapshot.schemaVersion,
-                generatedAt: snapshot.generatedAt,
-                stashRoot: snapshot.stashPath,
-                files: snapshot.files,
-                entities: snapshot.entities,
-                relations: snapshot.relations,
-                ...(snapshot.quality ? { quality: snapshot.quality } : {}),
-                ...(snapshot.telemetry ? { telemetry: snapshot.telemetry } : {}),
-            },
-            stashPath,
-            graphPath: snapshot.graphPath,
-        };
-    }
-    finally {
-        if (db)
-            closeDatabase(db);
-    }
-}
-function countEntitiesByFile(nodes) {
-    const counts = new Map();
-    for (const node of nodes) {
-        const seen = new Set();
-        for (const entity of node.entities) {
-            if (seen.has(entity))
-                continue;
-            seen.add(entity);
-            counts.set(entity, (counts.get(entity) ?? 0) + 1);
-        }
-    }
-    return counts;
-}
-function aggregateEntityStats(nodes) {
-    const stats = new Map();
-    for (const node of nodes) {
-        const seen = new Set();
-        for (const entity of node.entities) {
-            if (seen.has(entity))
-                continue;
-            seen.add(entity);
-            const existing = stats.get(entity);
-            const nodeConf = typeof node.confidence === "number" && Number.isFinite(node.confidence) ? node.confidence : undefined;
-            if (existing) {
-                existing.fileCount += 1;
-                if (nodeConf !== undefined && (existing.confidence === undefined || nodeConf > existing.confidence)) {
-                    existing.confidence = nodeConf;
-                }
-            }
-            else {
-                stats.set(entity, { fileCount: 1, ...(nodeConf !== undefined ? { confidence: nodeConf } : {}) });
-            }
-        }
-    }
-    return stats;
-}
-export function akmGraphSummary(options) {
-    const { graph, stashPath, graphPath } = loadGraph(options?.source);
-    return {
-        schemaVersion: 1,
-        shape: "graph-summary",
-        stashPath,
-        graphPath,
-        generatedAt: graph.generatedAt,
-        fileCount: graph.files.length,
-        entityCount: Array.isArray(graph.entities) ? graph.entities.length : countEntitiesByFile(graph.files).size,
-        relationCount: Array.isArray(graph.relations)
-            ? graph.relations.length
-            : graph.files.reduce((sum, node) => sum + node.relations.length, 0),
-        ...(graph.quality ? { quality: graph.quality } : {}),
-        ...(graph.telemetry ? { telemetry: graph.telemetry } : {}),
-    };
-}
-export function akmGraphEntities(options) {
-    const { graph, stashPath, graphPath } = loadGraph(options?.source);
-    const limit = options?.limit;
-    if (limit !== undefined && (!Number.isFinite(limit) || limit <= 0)) {
-        throw new UsageError("--limit must be a positive integer.", "INVALID_FLAG_VALUE");
-    }
-    const stats = aggregateEntityStats(graph.files);
-    const entities = [...stats.entries()]
-        .map(([name, info]) => ({
-        name,
-        fileCount: info.fileCount,
-        ...(info.confidence !== undefined ? { confidence: info.confidence } : {}),
-    }))
-        .sort((a, b) => b.fileCount - a.fileCount || a.name.localeCompare(b.name));
-    const sliced = typeof limit === "number" ? entities.slice(0, limit) : entities;
-    return {
-        schemaVersion: 1,
-        shape: "graph-entities",
-        stashPath,
-        graphPath,
-        generatedAt: graph.generatedAt,
-        total: entities.length,
-        entities: sliced,
-    };
-}
-export function akmGraphRelations(options) {
-    const { graph, stashPath, graphPath } = loadGraph(options?.source);
-    const limit = options?.limit;
-    if (limit !== undefined && (!Number.isFinite(limit) || limit <= 0)) {
-        throw new UsageError("--limit must be a positive integer.", "INVALID_FLAG_VALUE");
-    }
-    const counts = new Map();
-    for (const node of graph.files) {
-        for (const rel of node.relations) {
-            const key = `${rel.from}\u0000${rel.to}\u0000${rel.type ?? ""}`;
-            const relConf = typeof rel.confidence === "number" && Number.isFinite(rel.confidence) ? rel.confidence : undefined;
-            const existing = counts.get(key);
-            if (existing) {
-                existing.count += 1;
-                if (relConf !== undefined && (existing.confidence === undefined || relConf > existing.confidence)) {
-                    existing.confidence = relConf;
-                }
-            }
-            else {
-                counts.set(key, {
-                    from: rel.from,
-                    to: rel.to,
-                    ...(rel.type ? { type: rel.type } : {}),
-                    count: 1,
-                    ...(relConf !== undefined ? { confidence: relConf } : {}),
-                });
-            }
-        }
-    }
-    const relations = [...counts.values()].sort((a, b) => b.count - a.count || a.from.localeCompare(b.from) || a.to.localeCompare(b.to));
-    const sliced = typeof limit === "number" ? relations.slice(0, limit) : relations;
-    return {
-        schemaVersion: 1,
-        shape: "graph-relations",
-        stashPath,
-        graphPath,
-        generatedAt: graph.generatedAt,
-        total: relations.length,
-        relations: sliced,
-    };
-}
-export function akmGraphExport(options) {
-    if (!options.out?.trim()) {
-        throw new UsageError("`akm graph export` requires --out <path>.", "MISSING_REQUIRED_ARGUMENT");
-    }
-    const format = options.format ?? "json";
-    if (format !== "json" && format !== "jsonl") {
-        throw new UsageError("--format must be one of: json, jsonl.", "INVALID_FLAG_VALUE");
-    }
-    const { graph, stashPath, graphPath } = loadGraph(options.source);
-    const outPath = path.resolve(options.out);
-    fs.mkdirSync(path.dirname(outPath), { recursive: true });
-    const payload = format === "json"
-        ? `${JSON.stringify(graph, null, 2)}\n`
-        : `${[
-            ...graph.files.flatMap((file) => file.entities.map((entity) => JSON.stringify({ kind: "entity", entity, file: file.path }))),
-            ...graph.files.flatMap((file) => file.relations.map((relation) => JSON.stringify({ kind: "relation", ...relation, file: file.path }))),
-        ].join("\n")}\n`;
-    fs.writeFileSync(outPath, payload, "utf8");
-    return {
-        schemaVersion: 1,
-        shape: "graph-export",
-        stashPath,
-        graphPath,
-        outPath,
-        format,
-        bytes: Buffer.byteLength(payload, "utf8"),
-    };
-}
-export async function akmGraphRelated(options) {
-    const ref = options.ref.trim();
-    if (!ref) {
-        throw new UsageError("`akm graph related` requires <ref>.", "MISSING_REQUIRED_ARGUMENT");
-    }
-    const limit = options.limit;
-    if (limit !== undefined && (!Number.isFinite(limit) || limit <= 0)) {
-        throw new UsageError("--limit must be a positive integer.", "INVALID_FLAG_VALUE");
-    }
-    const target = await resolveGraphTarget(ref, options.source);
-    const { graph, stashPath, graphPath } = loadGraph(target.stashPath);
-    let db;
-    const related = (() => {
-        try {
-            db = openExistingDatabase();
-            return listRelatedPathsForFile(stashPath, target.filePath, limit ?? 5, db);
-        }
-        finally {
-            if (db)
-                closeDatabase(db);
-        }
-    })();
-    return {
-        schemaVersion: 1,
-        shape: "graph-related",
-        stashPath,
-        graphPath,
-        generatedAt: graph.generatedAt,
-        ref: target.ref,
-        path: target.filePath,
-        total: related.length,
-        related,
-        ...(related.length === 0 ? { tip: "No related graph neighbors were found for this asset." } : {}),
-    };
-}
-function normalizeGraphName(value) {
-    return value.trim().toLowerCase();
-}
-function buildRefByPath(stashRoot, db) {
-    const rows = getEntryRefRowsForStashRoot(db, stashRoot);
-    const map = new Map();
-    for (const row of rows) {
-        if (map.has(row.file_path))
-            continue;
-        try {
-            const entry = JSON.parse(row.entry_json);
-            if (typeof entry.type === "string" && typeof entry.name === "string") {
-                // F4b output-spelling flip: emit the 0.9.0 conceptId grammar.
-                map.set(row.file_path, { ref: displayRef({ type: entry.type, name: entry.name }), type: entry.type });
-            }
-        }
-        catch {
-            // ignore corrupt entry_json
-        }
-    }
-    return map;
-}
-export function akmGraphEntity(options) {
-    const name = options.name?.trim();
-    if (!name) {
-        throw new UsageError("`akm graph entity` requires <name>.", "MISSING_REQUIRED_ARGUMENT");
-    }
-    const limit = options.limit;
-    if (limit !== undefined && (!Number.isFinite(limit) || limit <= 0)) {
-        throw new UsageError("--limit must be a positive integer.", "INVALID_FLAG_VALUE");
-    }
-    const { graph, stashPath, graphPath } = loadGraph(options.source);
-    const target = normalizeGraphName(name);
-    let db;
-    let refByPath;
-    try {
-        db = openExistingDatabase();
-        refByPath = buildRefByPath(stashPath, db);
-    }
-    finally {
-        if (db)
-            closeDatabase(db);
-    }
-    const matches = [];
-    for (const node of graph.files) {
-        const found = node.entities.some((entity) => normalizeGraphName(entity) === target);
-        if (!found)
-            continue;
-        const lookup = refByPath.get(node.path);
-        const conf = typeof node.confidence === "number" && Number.isFinite(node.confidence) ? node.confidence : undefined;
-        matches.push({
-            ...(lookup?.ref ? { ref: lookup.ref } : {}),
-            path: node.path,
-            type: node.type,
-            ...(conf !== undefined ? { confidence: conf } : {}),
-        });
-    }
-    matches.sort((a, b) => {
-        const ca = a.confidence ?? 0;
-        const cb = b.confidence ?? 0;
-        if (cb !== ca)
-            return cb - ca;
-        return a.path.localeCompare(b.path);
-    });
-    const sliced = typeof limit === "number" ? matches.slice(0, limit) : matches;
-    return {
-        schemaVersion: 1,
-        shape: "graph-entity",
-        stashPath,
-        graphPath,
-        generatedAt: graph.generatedAt,
-        entity: name,
-        total: matches.length,
-        matches: sliced,
-    };
-}
-export function akmGraphOrphans(options) {
-    const limit = options?.limit;
-    if (limit !== undefined && (!Number.isFinite(limit) || limit <= 0)) {
-        throw new UsageError("--limit must be a positive integer.", "INVALID_FLAG_VALUE");
-    }
-    const { graph, stashPath, graphPath } = loadGraph(options?.source);
-    let db;
-    let refByPath;
-    try {
-        db = openExistingDatabase();
-        refByPath = buildRefByPath(stashPath, db);
-    }
-    finally {
-        if (db)
-            closeDatabase(db);
-    }
-    const orphans = [];
-    for (const node of graph.files) {
-        if ((node.status ?? (node.entities.length > 0 ? "extracted" : "empty")) === "extracted")
-            continue;
-        const lookup = refByPath.get(node.path);
-        orphans.push({
-            ...(lookup?.ref ? { ref: lookup.ref } : {}),
-            path: node.path,
-            type: node.type,
-            ...(node.status ? { status: node.status } : {}),
-            ...(node.reason ? { reason: node.reason } : {}),
-        });
-    }
-    orphans.sort((a, b) => a.type.localeCompare(b.type) || a.path.localeCompare(b.path));
-    const sliced = typeof limit === "number" ? orphans.slice(0, limit) : orphans;
-    return {
-        schemaVersion: 1,
-        shape: "graph-orphans",
-        stashPath,
-        graphPath,
-        generatedAt: graph.generatedAt,
-        totalConsidered: graph.files.length,
-        total: orphans.length,
-        orphans: sliced,
-    };
-}
-/**
- * Re-run graph extraction, optionally scoped to specific asset refs.
- *
- * When `refs` is provided, only those files are re-extracted (incremental).
- * When no refs are given, the full eligible set is re-extracted.
- */
-export async function akmGraphUpdate(options) {
-    const config = options.config ?? loadConfig();
-    const sources = resolveSourceEntries(options.stashDir, config);
-    if (sources.length === 0) {
-        throw new NotFoundError("No stash sources are configured.", "STASH_NOT_FOUND");
-    }
-    if (options.source && options.source !== "primary") {
-        const matched = sources.find((s) => s.registryId === options.source || s.path === options.source);
-        if (!matched) {
-            throw new NotFoundError(`Source not found: ${options.source}`, "SOURCE_NOT_FOUND", "Run `akm list` to see source names.");
-        }
-    }
-    const scoped = Array.isArray(options.refs) && options.refs.length > 0;
-    return withIndexWriterLease({ purpose: "graph-update" }, async () => {
-        let candidatePaths;
-        if (scoped && options.refs) {
-            // Resolve each ref to an absolute file path while the writer lease is held
-            // so the scoped graph write sees the same index snapshot it resolved from.
-            const dbPath = getDbPath();
-            let db;
-            const resolvedPaths = new Set();
-            try {
-                db = openIndexDatabase(dbPath);
-                for (const ref of options.refs) {
-                    const trimmed = ref.trim();
-                    if (!trimmed)
-                        continue;
-                    const entryId = findEntryIdByRef(db, trimmed);
-                    if (entryId === undefined) {
-                        warn(`[graph] ref not found in index, skipping: ${trimmed}`);
-                        continue;
-                    }
-                    const row = getEntryById(db, entryId);
-                    if (!row?.filePath) {
-                        warn(`[graph] could not resolve path for ref, skipping: ${trimmed}`);
-                        continue;
-                    }
-                    resolvedPaths.add(row.filePath);
-                }
-            }
-            finally {
-                if (db)
-                    closeDatabase(db);
-            }
-            if (resolvedPaths.size === 0) {
-                warn("[graph] none of the provided refs resolved to indexed paths — no extraction performed.");
-                return {
-                    shape: "graph-update",
-                    ok: true,
-                    filesExtracted: 0,
-                    entitiesUpserted: 0,
-                    relationsUpserted: 0,
-                    durationMs: 0,
-                    scoped: true,
-                };
-            }
-            candidatePaths = resolvedPaths;
-        }
-        const extractionFn = options.graphExtractionFn ?? runGraphExtractionPass;
-        const passOptions = candidatePaths ? { candidatePaths } : {};
-        let db;
-        const startMs = Date.now();
-        try {
-            db = openIndexDatabase(getDbPath());
-            const onProgress = (event) => {
-                if (!event.currentPath)
-                    return;
-                const file = path.basename(event.currentPath);
-                warn(`[graph] extracting ${event.processed}/${event.total} ${file}`);
-            };
-            const result = await extractionFn({
-                config,
-                sources,
-                signal: undefined,
-                db,
-                reEnrich: false,
-                onProgress,
-                options: passOptions,
-            });
-            const durationMs = Date.now() - startMs;
-            return {
-                shape: "graph-update",
-                ok: true,
-                filesExtracted: result.quality.extractedFiles,
-                entitiesUpserted: result.quality.entityCount,
-                relationsUpserted: result.quality.relationCount,
-                durationMs,
-                scoped,
-            };
-        }
-        finally {
-            if (db)
-                closeDatabase(db);
-        }
-    });
-}
-async function resolveGraphTarget(ref, source) {
-    const parsedRef = parseQualifiedRefInput(ref);
-    const filePath = (await resolveAssetPath(parsedRef, {
-        mode: "index-first",
-        honorOrigin: true,
-    })) ?? (await lookup(parsedRef))?.filePath;
-    if (!filePath) {
-        throw new NotFoundError(`Asset not found for ref: ${ref}`);
-    }
-    const allSources = resolveSourceEntries(undefined, loadConfig());
-    const matchedSource = findSourceForPath(filePath, allSources);
-    const inferredStashPath = matchedSource?.path;
-    const stashPath = source ? resolveGraphStashPath(source) : inferredStashPath;
-    if (!stashPath) {
-        throw new NotFoundError(`Could not determine stash source for ref: ${ref}`, "SOURCE_NOT_FOUND");
-    }
-    if (!filePath.startsWith(path.resolve(stashPath) + path.sep) && path.resolve(filePath) !== path.resolve(stashPath)) {
-        throw new UsageError(`Resolved asset ${ref} is not inside source ${source ?? stashPath}.`, "INVALID_SOURCE_VALUE", "Pass --source for the asset's source, or omit it to infer from the resolved asset path.");
-    }
-    return {
-        ref,
-        parsedRef,
-        filePath,
-        stashPath,
-    };
-}

package/dist/commands/improve/extract-watch.js

@@ -1,140 +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 { akmExtract } from "./extract.js";
-const DEFAULT_DEBOUNCE_MS = 2000;
-/** Small look-back window for the default trigger's `akmExtract` call. */
-const DEFAULT_TRIGGER_SINCE = "10m";
-/**
- * Does `filePath` look like a real session file under one of the configured
- * roots? True only when the path is under a root AND matches that harness's
- * on-disk session-file shape:
- *   - claude-code: `<root>/<project>/<id>.jsonl`
- *   - opencode:    `<root>/<project>/<id>.json`
- * Anything out-of-root, or in-root with the wrong extension, returns false.
- */
-export function isSessionFile(filePath, roots) {
-    return matchHarness(filePath, roots) !== undefined;
-}
-/** Normalize a path for prefix comparison (ensure a trailing separator). */
-function withSep(dir) {
-    return dir.endsWith("/") ? dir : `${dir}/`;
-}
-/**
- * Resolve which harness a path belongs to by longest-prefix match against the
- * configured roots, then validate the file shape for that harness. Returns the
- * harness name, or `undefined` when the path is out-of-root or not a session
- * file. Longest-prefix match guards against the (in practice impossible) case
- * of nested roots.
- */
-export function matchHarness(filePath, roots) {
-    let best;
-    let bestLen = -1;
-    for (const target of roots) {
-        for (const root of target.roots) {
-            const prefix = withSep(root);
-            if (filePath.startsWith(prefix) && prefix.length > bestLen) {
-                best = { harnessName: target.harnessName };
-                bestLen = prefix.length;
-            }
-        }
-    }
-    if (!best)
-        return undefined;
-    // Validate the file shape for the resolved harness.
-    if (best.harnessName === "claude-code") {
-        return filePath.endsWith(".jsonl") ? best.harnessName : undefined;
-    }
-    if (best.harnessName === "opencode") {
-        return filePath.endsWith(".json") ? best.harnessName : undefined;
-    }
-    // Unknown harness: accept any file under its root.
-    return best.harnessName;
-}
-/**
- * Start the watch-mode core. Returns a handle whose `stop()` tears everything
- * down. The event source is injected, so this never touches the real
- * filesystem itself.
- */
-export function akmExtractWatch(options) {
-    const { roots, eventSource, debounceMs = DEFAULT_DEBOUNCE_MS, setTimeoutFn = setTimeout, clearTimeoutFn = clearTimeout, isSessionFile: isSessionFileFn = isSessionFile, } = options;
-    const onTrigger = options.onTrigger ??
-        (async (harnessName) => {
-            await akmExtract({ type: harnessName, since: DEFAULT_TRIGGER_SINCE, force: false });
-        });
-    let stopped = false;
-    // Pending debounce timers, keyed by harness name.
-    const pendingTimers = new Map();
-    // Harnesses with an in-flight trigger, and whether a re-run is queued.
-    const inFlight = new Set();
-    const rerunPending = new Set();
-    function runTrigger(harnessName) {
-        if (stopped)
-            return;
-        if (inFlight.has(harnessName)) {
-            // A trigger is already running for this harness; coalesce into a single
-            // re-run after it resolves rather than launching a concurrent extract.
-            rerunPending.add(harnessName);
-            return;
-        }
-        inFlight.add(harnessName);
-        // Invoke synchronously so a synchronous `onTrigger` observes its effect
-        // before control returns (tests advance the clock then assert inline).
-        // Wrap the (possibly async) result in a promise to drive the in-flight
-        // guard's release without forcing the trigger itself into a microtask.
-        let result;
-        try {
-            result = onTrigger(harnessName);
-        }
-        catch (err) {
-            // One failed extract must never kill the watcher (mirrors the non-fatal
-            // handling in collectSessionEvents).
-            console.error(`[akm] extract --watch trigger for "${harnessName}" failed:`, err);
-            inFlight.delete(harnessName);
-            if (rerunPending.delete(harnessName) && !stopped)
-                runTrigger(harnessName);
-            return;
-        }
-        Promise.resolve(result)
-            .catch((err) => {
-            console.error(`[akm] extract --watch trigger for "${harnessName}" failed:`, err);
-        })
-            .finally(() => {
-            inFlight.delete(harnessName);
-            if (rerunPending.delete(harnessName) && !stopped) {
-                runTrigger(harnessName);
-            }
-        });
-    }
-    function onEvent(e) {
-        if (stopped)
-            return;
-        if (!isSessionFileFn(e.path, roots))
-            return;
-        const harnessName = matchHarness(e.path, roots);
-        if (!harnessName)
-            return;
-        const existing = pendingTimers.get(harnessName);
-        if (existing !== undefined)
-            clearTimeoutFn(existing);
-        const timer = setTimeoutFn(() => {
-            pendingTimers.delete(harnessName);
-            if (!stopped)
-                runTrigger(harnessName);
-        }, debounceMs);
-        pendingTimers.set(harnessName, timer);
-    }
-    const unsubscribe = eventSource.subscribe(onEvent);
-    return {
-        stop() {
-            if (stopped)
-                return;
-            stopped = true;
-            unsubscribe();
-            for (const timer of pendingTimers.values())
-                clearTimeoutFn(timer);
-            pendingTimers.clear();
-            rerunPending.clear();
-        },
-    };
-}