@automaton-labs/aib 0.0.7 → 0.0.8

package/dist/commands/inspect-usages-evidence.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.projectReverseModuleClosureEvidence = projectReverseModuleClosureEvidence;
+const inspect_format_primitives_1 = require("./inspect-format-primitives");
+const STABLE_REVERSE_MODULE_CLOSURE_FIELDS = [
+    "complete",
+    "truncated",
+    "pendingStateCount",
+    "filesScanned",
+    "bytesScanned",
+    "edgeCount",
+    "statesVisited",
+    "programBuildCount",
+    "uncertaintyCount",
+    "uncertaintyTotal",
+    "uncertaintiesTruncated",
+    "uncertainties"
+];
+/** Agent/default JSON receives stable structural evidence, never runtime measurements. */
+function projectReverseModuleClosureEvidence(value) {
+    if (!(0, inspect_format_primitives_1.isObject)(value)) {
+        return null;
+    }
+    const result = {};
+    for (const field of STABLE_REVERSE_MODULE_CLOSURE_FIELDS) {
+        if (value[field] !== undefined) {
+            result[field] = value[field];
+        }
+    }
+    return result;
+}

package/dist/commands/inspect-usages-format.js

@@ -0,0 +1,367 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatUsagesResult = formatUsagesResult;
+exports.formatUsagesAgentText = formatUsagesAgentText;
+exports.appendTargetLocalUsagesHint = appendTargetLocalUsagesHint;
+exports.appendUsageSummaryUnusedLines = appendUsageSummaryUnusedLines;
+exports.groupUsageItemsByOwner = groupUsageItemsByOwner;
+exports.splitUsageEntityReference = splitUsageEntityReference;
+const session_workspace_1 = require("./session-workspace");
+const inspect_format_primitives_1 = require("./inspect-format-primitives");
+const inspect_reference_path_format_1 = require("./inspect-reference-path-format");
+const inspect_usages_evidence_1 = require("./inspect-usages-evidence");
+const USAGES_VISIBLE_ITEM_LIMIT = 12;
+const USAGES_VISIBLE_CONSUMER_LIMIT = 12;
+const USAGES_CONSUMER_SYMBOL_LIMIT = 8;
+function formatUsagesResult(rawResult, config, options, commonFile) {
+    const target = typeof rawResult.targetPath === "string"
+        ? (0, inspect_format_primitives_1.formatFilePath)(rawResult.targetPath, options)
+        : typeof rawResult.sourceFile === "string"
+            ? (0, inspect_format_primitives_1.formatFilePath)(rawResult.sourceFile, options)
+            : commonFile ?? "";
+    const rawItems = Array.isArray(rawResult.items) ? rawResult.items.filter(inspect_format_primitives_1.isObject) : [];
+    const formatter = (0, inspect_reference_path_format_1.createUsagePathFormatter)((0, inspect_reference_path_format_1.collectUsagePaths)(rawItems, target, options));
+    const orderedRawItems = orderUsageItems(rawItems);
+    const consumerFirst = rawResult.targetMode === "directory" && rawResult.queryMode !== "explicit";
+    const response = {
+        ...(0, inspect_format_primitives_1.baseResult)(rawResult, options, commonFile),
+        target: formatter.compactPath(target),
+        summary: typeof rawResult.summary === "string" ? rawResult.summary : `${orderedRawItems.length} symbols`,
+        referenceCount: (0, inspect_format_primitives_1.numberOrZero)(rawResult.referenceCount),
+        itemCount: (0, inspect_format_primitives_1.numberOrZero)(rawResult.itemCount),
+        fileCount: (0, inspect_format_primitives_1.numberOrZero)(rawResult.fileCount),
+        scopeLabel: formatUsageScopeLabel(rawResult, options),
+        targetMode: typeof rawResult.targetMode === "string" ? rawResult.targetMode : "",
+        queryMode: typeof rawResult.queryMode === "string" ? rawResult.queryMode : ""
+    };
+    delete response.file;
+    if (rawResult.excludeTarget === true && rawResult.targetLocalUsagesHidden !== true) {
+        response.scope = "excluding target";
+    }
+    if (rawResult.targetLocalUsagesHidden === true) {
+        response.targetLocalUsagesHidden = true;
+    }
+    const reverseModuleClosure = (0, inspect_usages_evidence_1.projectReverseModuleClosureEvidence)(rawResult.reverseModuleClosure);
+    if (reverseModuleClosure) {
+        response.reverseModuleClosure = reverseModuleClosure;
+    }
+    if (consumerFirst) {
+        const aggregate = formatUsageConsumers(orderedRawItems, config, formatter, options);
+        response.usedBy = aggregate.usedBy;
+        if (aggregate.hiddenConsumers > 0) {
+            response.hiddenConsumers = `+ ${aggregate.hiddenConsumers} files`;
+        }
+    }
+    else {
+        const visibleRawItems = orderedRawItems.slice(0, USAGES_VISIBLE_ITEM_LIMIT);
+        response.items = visibleRawItems.map((item) => formatUsageItem(item, config, formatter, options, rawResult.targetMode === "directory"));
+    }
+    const paths = (0, inspect_reference_path_format_1.usagePathAliasesPayload)(formatter, response);
+    if (paths) {
+        response.paths = paths;
+    }
+    if ((0, inspect_format_primitives_1.isObject)(rawResult.debug)) {
+        response.debug = rawResult.debug;
+    }
+    if (!consumerFirst && orderedRawItems.length > USAGES_VISIBLE_ITEM_LIMIT) {
+        response.hidden = `+ ${orderedRawItems.length - USAGES_VISIBLE_ITEM_LIMIT} symbols`;
+    }
+    if (options.save) {
+        const saved = (0, session_workspace_1.saveSessionOutputJson)(options.cwd, "usages", options.save, rawResult);
+        response.saved = saved.saved;
+        const next = (0, session_workspace_1.useSessionGuidance)(options.cwd, "inspect.usages.focus", `Expand saved usages with: aib inspect usages --from-file ${saved.saved} --focus <name> --detail locations|code`);
+        if (next) {
+            response.next = next;
+        }
+    }
+    return response;
+}
+function orderUsageItems(items) {
+    return [...items].sort((left, right) => (0, inspect_format_primitives_1.numberOrZero)(right.referenceCount) - (0, inspect_format_primitives_1.numberOrZero)(left.referenceCount) ||
+        compareNatural(formatUsageEntityReference(left.entity), formatUsageEntityReference(right.entity)));
+}
+function formatUsageItem(rawItem, config, formatter, options, includeDeclaredIn = false) {
+    const item = {
+        entity: formatUsageEntityReference(rawItem.entity),
+        summary: typeof rawItem.summary === "string" ? rawItem.summary : `${(0, inspect_format_primitives_1.numberOrZero)(rawItem.referenceCount)} refs, ${(0, inspect_format_primitives_1.numberOrZero)(rawItem.fileCount)} files`,
+        usedBy: formatUsageUsedBy(rawItem.usedBy, formatter, options)
+    };
+    if (includeDeclaredIn && typeof rawItem.declaredIn === "string") {
+        item.declaredIn = formatter.compactPath((0, inspect_format_primitives_1.formatFilePath)(rawItem.declaredIn, options));
+    }
+    if (rawItem.role === "member") {
+        item.role = "member";
+    }
+    const boundaryReferenceCount = (0, inspect_format_primitives_1.numberOrZero)(rawItem.boundaryReferenceCount);
+    if (boundaryReferenceCount > 0) {
+        item.boundaryReferenceCount = boundaryReferenceCount;
+        item.moduleBoundaryEvidence = formatModuleBoundaryEvidence(rawItem.usedBy, formatter, options);
+    }
+    return item;
+}
+function formatModuleBoundaryEvidence(rawUsedBy, formatter, options) {
+    if (!Array.isArray(rawUsedBy)) {
+        return [];
+    }
+    const evidence = [];
+    for (const usage of rawUsedBy.filter(inspect_format_primitives_1.isObject)) {
+        const file = typeof usage.file === "string"
+            ? formatter.compactPath((0, inspect_format_primitives_1.formatFilePath)(usage.file, options))
+            : "";
+        const locations = Array.isArray(usage.locations) ? usage.locations.filter(inspect_format_primitives_1.isObject) : [];
+        for (const location of locations) {
+            if (!(0, inspect_format_primitives_1.isObject)(location.boundary)) {
+                continue;
+            }
+            evidence.push({
+                file,
+                line: (0, inspect_format_primitives_1.numberOrZero)(location.line),
+                character: (0, inspect_format_primitives_1.numberOrZero)(location.character),
+                boundary: location.boundary
+            });
+        }
+    }
+    return evidence;
+}
+function formatUsageConsumers(rawItems, config, formatter, options) {
+    const consumers = new Map();
+    for (const rawItem of rawItems) {
+        const entity = formatUsageEntityReference(rawItem.entity);
+        const usedBy = Array.isArray(rawItem.usedBy) ? rawItem.usedBy.filter(inspect_format_primitives_1.isObject) : [];
+        for (const usage of usedBy) {
+            const file = typeof usage.file === "string" ? usage.file : "";
+            if (!file) {
+                continue;
+            }
+            const count = (0, inspect_format_primitives_1.numberOrZero)(usage.count);
+            const current = consumers.get(file) ?? { refs: 0, symbols: new Map() };
+            current.refs += count;
+            current.symbols.set(entity, (current.symbols.get(entity) ?? 0) + count);
+            consumers.set(file, current);
+        }
+    }
+    const ordered = Array.from(consumers.entries())
+        .sort(([leftFile, left], [rightFile, right]) => right.refs - left.refs || leftFile.localeCompare(rightFile));
+    const visible = ordered.slice(0, USAGES_VISIBLE_CONSUMER_LIMIT).map(([file, consumer]) => {
+        const symbols = Array.from(consumer.symbols.entries())
+            .sort(([leftName, leftCount], [rightName, rightCount]) => rightCount - leftCount || compareNatural(leftName, rightName));
+        const visibleSymbols = symbols.slice(0, USAGES_CONSUMER_SYMBOL_LIMIT)
+            .map(([name, count]) => count > 1 ? `${name} x${count}` : name);
+        if (symbols.length > visibleSymbols.length) {
+            visibleSymbols.push(`+ ${symbols.length - visibleSymbols.length} more`);
+        }
+        return {
+            file: formatter.compactPath((0, inspect_format_primitives_1.formatFilePath)(file, options)),
+            summary: `${consumer.refs} ${plural(consumer.refs, "ref")}`,
+            symbols: visibleSymbols
+        };
+    });
+    return {
+        usedBy: visible,
+        hiddenConsumers: Math.max(0, ordered.length - visible.length)
+    };
+}
+function formatUsageUsedBy(rawUsedBy, formatter, options) {
+    if (!Array.isArray(rawUsedBy)) {
+        return [];
+    }
+    const rows = rawUsedBy
+        .filter(inspect_format_primitives_1.isObject)
+        .map((usage) => {
+        const file = typeof usage.file === "string" ? formatter.compactPath((0, inspect_format_primitives_1.formatFilePath)(usage.file, options)) : "";
+        const count = (0, inspect_format_primitives_1.numberOrZero)(usage.count);
+        return file ? `${file} x${count}` : "";
+    })
+        .filter((row) => row !== "");
+    return (0, inspect_reference_path_format_1.groupUsagePathRows)(rows);
+}
+function formatUsageScopeLabel(rawResult, options) {
+    const scopes = Array.isArray(rawResult.usageScopes)
+        ? rawResult.usageScopes.filter((item) => typeof item === "string" && item.trim() !== "")
+        : [];
+    if (scopes.length === 0) {
+        return "project";
+    }
+    if (scopes.length === 1) {
+        return (0, inspect_format_primitives_1.formatFilePath)(scopes[0], options);
+    }
+    return `${scopes.length} scopes`;
+}
+function formatUsagesAgentText(response) {
+    const rows = Array.isArray(response.results) ? response.results.filter(inspect_format_primitives_1.isObject) : [response];
+    if (rows.length === 0) {
+        return null;
+    }
+    const lines = [];
+    for (const row of rows) {
+        const detail = typeof row.detail === "string" ? row.detail : "locations";
+        if ((0, inspect_format_primitives_1.isObject)(row.paths) && Object.keys(row.paths).length > 0) {
+            lines.push("paths:");
+            for (const [token, prefix] of Object.entries(row.paths)) {
+                lines.push(`${token} = ${String(prefix)}`);
+            }
+        }
+        const target = typeof row.target === "string" ? row.target : "";
+        lines.push(target ? `usages ${target}` : "usages");
+        if ((0, inspect_format_primitives_1.numberOrZero)(row.referenceCount) === 0) {
+            lines.push(`0 refs in ${typeof row.scopeLabel === "string" ? row.scopeLabel : "project"}`);
+            appendTargetLocalUsagesHint(lines, row);
+            const itemCount = (0, inspect_format_primitives_1.numberOrZero)(row.itemCount);
+            if ((row.targetMode === "directory" || row.queryMode !== "explicit") && itemCount > 0) {
+                lines.push(`symbols checked: ${itemCount}`);
+            }
+            continue;
+        }
+        if (typeof row.summary === "string") {
+            lines.push(row.summary);
+        }
+        if (typeof row.scope === "string") {
+            lines.push(row.scope);
+        }
+        appendTargetLocalUsagesHint(lines, row);
+        const consumers = Array.isArray(row.usedBy) ? row.usedBy.filter(inspect_format_primitives_1.isObject) : [];
+        for (const consumer of consumers) {
+            const file = typeof consumer.file === "string" ? consumer.file : "";
+            const summary = typeof consumer.summary === "string" ? consumer.summary : "";
+            const symbols = Array.isArray(consumer.symbols)
+                ? consumer.symbols.filter((value) => typeof value === "string")
+                : [];
+            lines.push(`${file}: ${summary}; ${symbols.join(", ")}`.trim());
+        }
+        if (typeof row.hiddenConsumers === "string") {
+            lines.push(row.hiddenConsumers);
+        }
+        const items = Array.isArray(row.items) ? row.items.filter(inspect_format_primitives_1.isObject) : [];
+        lines.push(...formatUsageItemsText(items));
+        appendUsageSummaryUnusedLines(lines, row, items);
+        if (typeof row.hidden === "string") {
+            lines.push(row.hidden);
+        }
+        if (typeof row.view === "string") {
+            lines.push(`view: ${row.view}`);
+        }
+        if (typeof row.saved === "string") {
+            lines.push(`saved: ${row.saved}`);
+        }
+        if (typeof row.next === "string") {
+            lines.push(`next: ${row.next}`);
+        }
+    }
+    return lines.join("\n");
+}
+function appendTargetLocalUsagesHint(lines, row) {
+    if (row.targetLocalUsagesHidden === true) {
+        lines.push("target-local usages hidden; use +includeTarget to show");
+    }
+}
+function appendUsageSummaryUnusedLines(lines, row, items) {
+    const unused = items
+        .filter((item) => {
+        const summary = typeof item.summary === "string" ? item.summary : "";
+        return summary.startsWith("0 refs");
+    })
+        .map((item) => typeof item.entity === "string" ? item.entity : "")
+        .filter((item) => item !== "");
+    if (unused.length === 0) {
+        return;
+    }
+    if (row.queryMode === "explicit") {
+        lines.push(`unused: ${(0, inspect_format_primitives_1.summarizeList)(unused, 2, "more")}`);
+        return;
+    }
+    if (row.targetMode === "file") {
+        lines.push(`unused symbols: ${unused.length}`);
+    }
+}
+function formatUsageItemsText(items) {
+    const lines = [];
+    const usedItems = items.filter((item) => !isZeroRefUsageItem(item));
+    const { ownerGroups, standalone } = groupUsageItemsByOwner(usedItems);
+    for (const [owner, ownerItems] of ownerGroups) {
+        if (lines.length > 0) {
+            lines.push("");
+        }
+        lines.push(`// ${owner}:`);
+        for (const item of ownerItems) {
+            lines.push(...formatSingleUsageItemText(item, false));
+        }
+    }
+    if (standalone.length > 0 && lines.length > 0) {
+        lines.push("");
+    }
+    for (const item of standalone) {
+        lines.push(...formatSingleUsageItemText(item, true));
+    }
+    return lines;
+}
+function isZeroRefUsageItem(item) {
+    if (typeof item.referenceCount === "number") {
+        return item.referenceCount === 0;
+    }
+    const summary = typeof item.summary === "string" ? item.summary : "";
+    return summary.startsWith("0 refs");
+}
+function formatSingleUsageItemText(item, includeOwner) {
+    const entity = typeof item.entity === "string" ? item.entity : "";
+    const reference = splitUsageEntityReference(entity);
+    const name = includeOwner ? entity : reference.name;
+    const declaredIn = typeof item.declaredIn === "string" ? ` [${item.declaredIn}]` : "";
+    const summary = typeof item.summary === "string" ? item.summary : "";
+    const lines = [`${name}${declaredIn}: ${summary}`.trim()];
+    const usedBy = Array.isArray(item.usedBy) ? item.usedBy.filter((value) => typeof value === "string") : [];
+    lines.push(...usedBy);
+    return lines;
+}
+function groupUsageItemsByOwner(items) {
+    const ownerGroups = new Map();
+    const standalone = [];
+    for (const item of items) {
+        const entity = typeof item.entity === "string" ? item.entity : "";
+        const reference = splitUsageEntityReference(entity);
+        if (!reference.owner) {
+            standalone.push(item);
+            continue;
+        }
+        const group = ownerGroups.get(reference.owner) ?? [];
+        group.push(item);
+        ownerGroups.set(reference.owner, group);
+    }
+    return {
+        ownerGroups: Array.from(ownerGroups.entries()),
+        standalone
+    };
+}
+function splitUsageEntityReference(entity) {
+    const index = entity.lastIndexOf(".");
+    if (index <= 0 || index >= entity.length - 1) {
+        return { owner: null, name: entity };
+    }
+    return {
+        owner: entity.slice(0, index),
+        name: entity.slice(index + 1)
+    };
+}
+function formatUsageEntityReference(rawSymbol) {
+    if (!(0, inspect_format_primitives_1.isObject)(rawSymbol)) {
+        return "";
+    }
+    const rawPath = Array.isArray(rawSymbol.path)
+        ? rawSymbol.path.filter((item) => typeof item === "string" && item.trim() !== "")
+        : [];
+    if (rawPath.length > 0) {
+        return rawPath.join(".");
+    }
+    return formatEntityName(rawSymbol);
+}
+function formatEntityName(rawSymbol) {
+    if (!(0, inspect_format_primitives_1.isObject)(rawSymbol)) {
+        return "";
+    }
+    return typeof rawSymbol.name === "string" ? rawSymbol.name : "";
+}
+function plural(count, singular) {
+    return count === 1 ? singular : `${singular}s`;
+}
+function compareNatural(left, right) {
+    return left.localeCompare(right, undefined, { numeric: true });
+}