@automaton-labs/aib 0.0.6 → 0.0.8

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

@@ -0,0 +1,793 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildUsagesDetail = buildUsagesDetail;
+exports.readUsagesDetail = readUsagesDetail;
+exports.readUsagesDetailOptions = readUsagesDetailOptions;
+exports.readOptionalUsagesDetail = readOptionalUsagesDetail;
+exports.copyUsageDetailSummaryFields = copyUsageDetailSummaryFields;
+exports.attachUsagesViewAll = attachUsagesViewAll;
+exports.stripUsagesViewRecords = stripUsagesViewRecords;
+exports.formatUsagesDetailResponseAgentText = formatUsagesDetailResponseAgentText;
+exports.formatUsagesDetailAgentText = formatUsagesDetailAgentText;
+exports.displayPath = displayPath;
+exports.isObject = isObject;
+exports.readString = readString;
+exports.readStringArray = readStringArray;
+const fs = __importStar(require("node:fs"));
+const node_crypto_1 = require("node:crypto");
+const errors_1 = require("../shared/errors");
+const agent_text_1 = require("../shared/agent-text");
+const path_display_1 = require("../config/path-display");
+const path_display_2 = require("../config/path-display");
+const inspect_format_1 = require("./inspect-format");
+const inspect_usages_evidence_1 = require("./inspect-usages-evidence");
+const session_workspace_1 = require("./session-workspace");
+function buildUsagesDetail(cwd, artifact, focus, options, keepViewRecord = false) {
+    const result = options.detail === "code"
+        ? buildUsagesCodeDetail(cwd, artifact, focus, options)
+        : buildUsagesLocationsDetail(cwd, artifact, focus, options);
+    attachUsagesDetailView(cwd, result, keepViewRecord);
+    return result;
+}
+function readUsagesDetail(cwd, value) {
+    return parseUsagesDetail(value ?? (0, session_workspace_1.readSessionStringPref)(cwd, "inspect.usages.detail", "locations"));
+}
+function readUsagesDetailOptions(cwd, input) {
+    const all = input.all === true;
+    const locationLimit = all
+        ? Number.MAX_SAFE_INTEGER
+        : input.limit ?? (0, session_workspace_1.readSessionNumberPref)(cwd, "inspect.usages.maxLocations", 12);
+    const codeBlockLimit = all
+        ? Number.MAX_SAFE_INTEGER
+        : input.limit ?? (0, session_workspace_1.readSessionNumberPref)(cwd, "inspect.usages.maxCodeBlocks", 8);
+    return {
+        detail: readUsagesDetail(cwd, input.detail),
+        locationLimit,
+        codeBlockLimit,
+        maxCodeLines: input.maxCodeLines ?? (0, session_workspace_1.readSessionNumberPref)(cwd, "inspect.code.maxNonEmptyLines", 120),
+        all
+    };
+}
+function readOptionalUsagesDetail(value) {
+    return typeof value === "string" ? value : null;
+}
+function parseUsagesDetail(value) {
+    const normalized = value.trim().toLowerCase();
+    if (normalized === "location") {
+        return "locations";
+    }
+    if (normalized === "locations" || normalized === "code" || normalized === "summary") {
+        return normalized;
+    }
+    throw new errors_1.CliError("INVALID_USAGES_DETAIL", "usages detail expects summary, locations, or code.", {
+        detail: value
+    });
+}
+function copyUsageDetailSummaryFields(from, to) {
+    for (const field of ["summary", "saved", "next", "input", "targetLocalUsagesHidden"]) {
+        if (from[field] !== undefined) {
+            to[field] = from[field];
+        }
+    }
+    const reverseModuleClosure = (0, inspect_usages_evidence_1.projectReverseModuleClosureEvidence)(from.reverseModuleClosure);
+    if (reverseModuleClosure) {
+        to.reverseModuleClosure = reverseModuleClosure;
+    }
+}
+function attachUsagesDetailView(cwd, result, keepViewRecord) {
+    const items = Array.isArray(result.__viewItems) ? result.__viewItems.filter(isObject) : [];
+    delete result.__viewItems;
+    if (items.length === 0) {
+        return;
+    }
+    const record = compactViewObject({
+        version: 1,
+        kind: "usages",
+        source: "inspect",
+        detail: readString(result.detail) ?? "locations",
+        target: readString(result.target) ?? "",
+        items
+    });
+    const saved = (0, session_workspace_1.saveSessionResultViewJson)(cwd, createShortResultId(record), record);
+    if (!saved) {
+        return;
+    }
+    result.view = saved.saved;
+    if (keepViewRecord) {
+        result.__viewRecord = record;
+    }
+}
+function attachUsagesViewAll(cwd, rows) {
+    const records = rows
+        .map((row) => isObject(row.__viewRecord) ? row.__viewRecord : null)
+        .filter((record) => record !== null && readString(record.kind) === "usages");
+    if (records.length <= 1) {
+        return;
+    }
+    const details = Array.from(new Set(records
+        .map((record) => readString(record.detail) ?? "")
+        .filter((detail) => detail !== "")));
+    const items = records.flatMap((record) => Array.isArray(record.items) ? record.items.filter(isObject) : []);
+    if (items.length === 0) {
+        return;
+    }
+    const record = compactViewObject({
+        version: 1,
+        kind: "usages",
+        source: "inspect",
+        detail: details.length === 1 ? details[0] : "mixed",
+        items
+    });
+    const saved = (0, session_workspace_1.saveSessionResultViewJson)(cwd, createShortResultId(record), record);
+    if (!saved) {
+        return;
+    }
+    for (const row of rows) {
+        if (isObject(row.__viewRecord) && readString(row.__viewRecord.kind) === "usages") {
+            row.viewAllUsages = saved.saved;
+        }
+    }
+}
+function stripUsagesViewRecords(rows) {
+    for (const row of rows) {
+        delete row.__viewRecord;
+        delete row.__viewItems;
+    }
+}
+function createShortResultId(record) {
+    return `res_${(0, node_crypto_1.createHash)("sha256").update(JSON.stringify(record)).digest("hex").slice(0, 8)}`;
+}
+function compactViewObject(value) {
+    const compacted = {};
+    for (const [key, item] of Object.entries(value)) {
+        if (item !== undefined && item !== "") {
+            compacted[key] = item;
+        }
+    }
+    return compacted;
+}
+function formatUsagesDetailResponseAgentText(cwd, result, fallback) {
+    if (Array.isArray(result.results)) {
+        const lines = [];
+        const rows = result.results.filter(isObject);
+        let pendingMixedRows = [];
+        const flushMixedRows = () => {
+            if (pendingMixedRows.length === 0) {
+                return;
+            }
+            const text = (0, inspect_format_1.formatInspectMixedAgentText)({ results: pendingMixedRows });
+            if (text) {
+                lines.push(text);
+            }
+            pendingMixedRows = [];
+        };
+        for (const row of rows) {
+            const detail = readString(row.detail);
+            if (detail === "locations" || detail === "code") {
+                flushMixedRows();
+                const text = formatUsagesDetailAgentText(cwd, row);
+                if (text) {
+                    lines.push(text);
+                }
+                continue;
+            }
+            if (readString(row.op) === "usages") {
+                flushMixedRows();
+                const summaryText = formatUsagesSummaryAgentText(row);
+                if (summaryText) {
+                    lines.push(summaryText);
+                }
+                continue;
+            }
+            pendingMixedRows.push(row);
+        }
+        flushMixedRows();
+        appendUsageDetailViewAllLines(lines, rows);
+        return lines.length > 0 ? lines.join("\n\n") : null;
+    }
+    const detail = readString(result.detail);
+    if (detail === "locations" || detail === "code") {
+        return formatUsagesDetailAgentText(cwd, result);
+    }
+    return (0, agent_text_1.readAgentText)(fallback);
+}
+function appendUsageDetailViewAllLines(lines, rows) {
+    const views = Array.from(new Set(rows
+        .map((row) => readString(row.viewAllUsages) ?? "")
+        .filter((view) => view !== "")));
+    if (views.length === 0) {
+        return;
+    }
+    const homogeneousUsages = rows.every((row) => readString(row.op) === "usages");
+    lines.push(homogeneousUsages
+        ? `view all: ${views[0]}`
+        : ["view all:", `usages: ${views[0]}`].join("\n"));
+}
+function formatUsagesSummaryAgentText(row) {
+    const lines = [];
+    const target = readString(row.target);
+    lines.push(target ? `usages ${target}` : "usages");
+    const summary = readString(row.summary);
+    if (summary) {
+        lines.push(summary);
+    }
+    appendTargetLocalUsagesHint(lines, row);
+    const items = Array.isArray(row.items) ? row.items.filter(isObject) : [];
+    for (const item of items) {
+        const entity = readString(item.entity) ?? "";
+        const itemSummary = readString(item.summary) ?? "";
+        lines.push(`${entity}: ${itemSummary}`.trim());
+        const usedBy = Array.isArray(item.usedBy) ? item.usedBy.filter((value) => typeof value === "string") : [];
+        lines.push(...usedBy);
+    }
+    return lines.length > 1 ? lines.join("\n") : null;
+}
+function buildUsagesLocationsDetail(cwd, artifact, focus, options) {
+    const sourceItems = filterUsageArtifactItems(artifact, focus);
+    const hiddenViewItems = [];
+    const items = sourceItems.map((item) => {
+        const entityDisplay = usageItemDisplay(item);
+        let visibleLocations = 0;
+        let hiddenLocations = 0;
+        const hiddenUsedBy = [];
+        const usedBy = Array.isArray(item.usedBy) ? item.usedBy.filter(isObject).flatMap((usage) => {
+            const locations = Array.isArray(usage.locations) ? usage.locations.filter(isObject) : [];
+            const fileDisplay = displayPath(cwd, readString(usage.file) ?? "");
+            const hiddenForUsage = [];
+            const visible = locations.flatMap((location) => {
+                const line = typeof location.line === "number" ? location.line : 0;
+                const container = isObject(location.container) ? symbolDisplayName(location.container) : "";
+                if (visibleLocations >= options.locationLimit) {
+                    hiddenLocations += 1;
+                    hiddenForUsage.push({
+                        line,
+                        ...(container !== "" ? { container } : {})
+                    });
+                    hiddenViewItems.push(compactViewObject({
+                        name: entityDisplay,
+                        text: container ? `${fileDisplay}:${line} ${container}` : `${fileDisplay}:${line}`
+                    }));
+                    return [];
+                }
+                visibleLocations += 1;
+                return [{
+                        line,
+                        ...(container !== "" ? { container } : {}),
+                        ...(isObject(location.boundary) ? { boundary: location.boundary } : {})
+                    }];
+            });
+            if (hiddenForUsage.length > 0) {
+                hiddenUsedBy.push({
+                    file: fileDisplay,
+                    locations: hiddenForUsage
+                });
+            }
+            return visible.length > 0
+                ? [{
+                        file: fileDisplay,
+                        locations: visible
+                    }]
+                : [];
+        }) : [];
+        const displayItem = {
+            entity: entityDisplay,
+            referenceCount: numberOrZero(item.referenceCount),
+            ...(numberOrZero(item.boundaryReferenceCount) > 0
+                ? { boundaryReferenceCount: numberOrZero(item.boundaryReferenceCount) }
+                : {}),
+            usedBy,
+            ...(hiddenLocations > 0 ? { hidden: `+ ${hiddenLocations} more locations` } : {})
+        };
+        const hiddenItem = hiddenUsedBy.length > 0
+            ? {
+                entity: entityDisplay,
+                referenceCount: hiddenLocations,
+                usedBy: hiddenUsedBy
+            }
+            : null;
+        return {
+            displayItem,
+            hiddenItem
+        };
+    });
+    const displayItems = items.map((item) => item.displayItem);
+    const reverseModuleClosure = (0, inspect_usages_evidence_1.projectReverseModuleClosureEvidence)(artifact.reverseModuleClosure);
+    return {
+        op: "usages",
+        detail: "locations",
+        target: displayPath(cwd, readString(artifact.targetPath) ?? ""),
+        summary: readString(artifact.summary) ?? "",
+        referenceCount: numberOrZero(artifact.referenceCount),
+        itemCount: numberOrZero(artifact.itemCount),
+        fileCount: numberOrZero(artifact.fileCount),
+        scopeLabel: usageScopeLabel(cwd, artifact),
+        targetMode: readString(artifact.targetMode) ?? "",
+        queryMode: readString(artifact.queryMode) ?? "",
+        targetLocalUsagesHidden: artifact.targetLocalUsagesHidden === true,
+        ...(reverseModuleClosure ? { reverseModuleClosure } : {}),
+        unused: usageUnusedItems(sourceItems),
+        items: displayItems,
+        ...(hiddenViewItems.length > 0 ? { __viewItems: hiddenViewItems } : {})
+    };
+}
+function buildUsagesCodeDetail(cwd, artifact, focus, options) {
+    const maxLines = options.maxCodeLines;
+    const blocks = [];
+    const seen = new Set();
+    const visibleByEntity = new Map();
+    const hiddenByEntity = new Map();
+    const hiddenViewItems = [];
+    const sourceItems = filterUsageArtifactItems(artifact, focus);
+    for (const item of sourceItems) {
+        const entity = usageItemDisplay(item);
+        const usedBy = Array.isArray(item.usedBy) ? item.usedBy.filter(isObject) : [];
+        for (const usage of usedBy) {
+            const file = readString(usage.file);
+            if (!file) {
+                continue;
+            }
+            const locations = Array.isArray(usage.locations) ? usage.locations.filter(isObject) : [];
+            for (const location of locations) {
+                const container = isObject(location.container) ? location.container : null;
+                const range = container && isObject(container.range) ? container.range : null;
+                const start = range && isObject(range.start) ? range.start : null;
+                const end = range && isObject(range.end) ? range.end : null;
+                if (!start || !end || typeof start.line !== "number" || typeof start.character !== "number" || typeof end.line !== "number" || typeof end.character !== "number") {
+                    continue;
+                }
+                const key = `${entity}:${file}:${start.line}:${start.character}:${end.line}:${end.character}`;
+                if (seen.has(key)) {
+                    continue;
+                }
+                seen.add(key);
+                const visibleCount = visibleByEntity.get(entity) ?? 0;
+                const code = sliceFileByRange(file, start.line, start.character, end.line, end.character);
+                const line = start.line + 1;
+                const viewBlock = {
+                    entity,
+                    file: displayPath(cwd, file),
+                    container: container ? symbolDisplayName(container) : "",
+                    line,
+                    code
+                };
+                if (visibleCount >= options.codeBlockLimit) {
+                    hiddenByEntity.set(entity, (hiddenByEntity.get(entity) ?? 0) + 1);
+                    hiddenViewItems.push(compactViewObject({
+                        name: entity,
+                        text: formatUsageCodeViewBlockText(viewBlock, false).join("\n").trim()
+                    }));
+                    continue;
+                }
+                visibleByEntity.set(entity, visibleCount + 1);
+                const nonEmptyLines = countNonEmptyLines(code);
+                const omittedMessage = `code omitted: ${nonEmptyLines} non-empty lines; exceeds inspect.code.maxNonEmptyLines=${maxLines}`;
+                if (nonEmptyLines > maxLines) {
+                    hiddenViewItems.push(compactViewObject({
+                        name: entity,
+                        text: formatUsageCodeViewBlockText(viewBlock, false).join("\n").trim()
+                    }));
+                }
+                blocks.push({
+                    entity,
+                    file: displayPath(cwd, file),
+                    container: container ? symbolDisplayName(container) : "",
+                    line,
+                    ...(nonEmptyLines <= maxLines
+                        ? { code }
+                        : {
+                            omitted: omittedMessage,
+                            compactCode: compactCodePreview(code)
+                        })
+                });
+            }
+        }
+    }
+    const reverseModuleClosure = (0, inspect_usages_evidence_1.projectReverseModuleClosureEvidence)(artifact.reverseModuleClosure);
+    return {
+        op: "usages",
+        detail: "code",
+        target: displayPath(cwd, readString(artifact.targetPath) ?? ""),
+        summary: readString(artifact.summary) ?? "",
+        referenceCount: numberOrZero(artifact.referenceCount),
+        itemCount: numberOrZero(artifact.itemCount),
+        fileCount: numberOrZero(artifact.fileCount),
+        scopeLabel: usageScopeLabel(cwd, artifact),
+        targetMode: readString(artifact.targetMode) ?? "",
+        queryMode: readString(artifact.queryMode) ?? "",
+        targetLocalUsagesHidden: artifact.targetLocalUsagesHidden === true,
+        ...(reverseModuleClosure ? { reverseModuleClosure } : {}),
+        unused: usageUnusedItems(sourceItems),
+        blocks,
+        hiddenBlocks: Array.from(hiddenByEntity.entries()).map(([entity, hidden]) => ({
+            entity,
+            hidden: `+ ${hidden} more code blocks`
+        })),
+        ...(hiddenViewItems.length > 0 ? { __viewItems: hiddenViewItems } : {})
+    };
+}
+function filterUsageArtifactItems(artifact, focus) {
+    const items = Array.isArray(artifact.items) ? artifact.items.filter(isObject) : [];
+    if (focus.length === 0) {
+        return items;
+    }
+    const normalizedFocus = new Set(focus.map((item) => item.trim()).filter(Boolean));
+    return items.filter((item) => {
+        const name = usageItemName(item);
+        const display = usageItemDisplay(item);
+        return normalizedFocus.has(name) || normalizedFocus.has(display);
+    });
+}
+function usageItemName(item) {
+    return isObject(item.entity) ? readString(item.entity.name) ?? "" : "";
+}
+function usageItemDisplay(item) {
+    return isObject(item.entity) ? symbolDisplayName(item.entity) : "";
+}
+function usageUnusedItems(items) {
+    return items
+        .filter((item) => numberOrZero(item.referenceCount) === 0)
+        .map((item) => usageItemDisplay(item))
+        .filter((item) => item !== "");
+}
+function usageScopeLabel(cwd, artifact) {
+    const scopes = readStringArray(artifact.usageScopes) ?? [];
+    if (scopes.length === 0) {
+        return "project";
+    }
+    if (scopes.length === 1) {
+        return displayPath(cwd, scopes[0]);
+    }
+    return `${scopes.length} scopes`;
+}
+function compactCodePreview(code) {
+    const lines = code.trim().split(/\r?\n/).map((line) => line.trimEnd()).filter((line) => line.trim() !== "");
+    const first = lines[0] ?? "";
+    if (!first) {
+        return "";
+    }
+    const braceIndex = first.indexOf("{");
+    if (braceIndex >= 0) {
+        return `${first.slice(0, braceIndex + 1)}...}`;
+    }
+    return `${first} ...`;
+}
+function compactStringList(items, limit, suffix) {
+    const visible = items.slice(0, limit);
+    const hidden = items.length - visible.length;
+    return hidden > 0 ? `${visible.join(", ")}, + ${hidden} ${suffix}` : visible.join(", ");
+}
+function numberOrZero(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+function symbolDisplayName(symbol) {
+    const pathValue = Array.isArray(symbol.path)
+        ? symbol.path.filter((item) => typeof item === "string" && item.trim() !== "")
+        : [];
+    if (pathValue.length > 0) {
+        return pathValue.join(".");
+    }
+    return readString(symbol.name) ?? "";
+}
+function formatUsagesDetailAgentText(cwd, result) {
+    const detail = readString(result.detail);
+    if (numberOrZero(result.referenceCount) === 0) {
+        const target = readString(result.target);
+        const scope = readString(result.scopeLabel) ?? "project";
+        const lines = [target ? `usages ${target}` : "usages", `0 refs in ${scope}`];
+        appendTargetLocalUsagesHint(lines, result);
+        const itemCount = numberOrZero(result.itemCount);
+        if ((readString(result.targetMode) === "directory" || readString(result.queryMode) !== "explicit") && itemCount > 0) {
+            lines.push(`symbols checked: ${itemCount}`);
+        }
+        return lines.join("\n");
+    }
+    const lines = [`usages ${detail ?? "detail"}`];
+    appendTargetLocalUsagesHint(lines, result);
+    if (detail === "code") {
+        const blocks = Array.isArray(result.blocks) ? result.blocks.filter(isObject) : [];
+        const { ownerGroups, standalone } = groupUsageRowsByOwner(blocks, (block) => readString(block.entity) ?? "");
+        for (const [owner, ownerBlocks] of ownerGroups) {
+            lines.push("");
+            lines.push(`// ${owner}:`);
+            for (const [entity, entityBlocks] of groupBy(ownerBlocks, (block) => splitUsageEntityReference(readString(block.entity) ?? "").name)) {
+                if (entity) {
+                    lines.push(`// ${entity}`);
+                }
+                lines.push(...formatUsageCodeEntityBlocks(cwd, result, entityBlocks));
+            }
+        }
+        if (standalone.length > 0) {
+            if (ownerGroups.length > 0) {
+                lines.push("");
+            }
+            for (const [entity, entityBlocks] of groupBy(standalone, (block) => readString(block.entity) ?? "")) {
+                if (entity) {
+                    lines.push(`// ${entity}`);
+                }
+                lines.push(...formatUsageCodeEntityBlocks(cwd, result, entityBlocks));
+            }
+        }
+        appendUsageUnusedLines(lines, result);
+        appendUsagesViewLine(lines, result);
+        return lines.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd();
+    }
+    const items = Array.isArray(result.items)
+        ? result.items.filter(isObject).filter((item) => numberOrZero(item.referenceCount) > 0)
+        : [];
+    const { ownerGroups, standalone } = groupUsageRowsByOwner(items, (item) => readString(item.entity) ?? "");
+    for (const [owner, ownerItems] of ownerGroups) {
+        lines.push("");
+        lines.push(`// ${owner}:`);
+        for (const item of ownerItems) {
+            lines.push(...formatUsageLocationsItemText(item, false));
+        }
+    }
+    if (standalone.length > 0 && ownerGroups.length > 0) {
+        lines.push("");
+    }
+    for (const item of standalone) {
+        lines.push(...formatUsageLocationsItemText(item, true));
+    }
+    appendUsageUnusedLines(lines, result);
+    appendUsagesViewLine(lines, result);
+    return lines.join("\n").trimEnd();
+}
+function appendUsagesViewLine(lines, result) {
+    const view = readString(result.view);
+    if (!view) {
+        return;
+    }
+    if (lines.length > 0 && lines[lines.length - 1] !== "") {
+        lines.push("");
+    }
+    lines.push(`view: ${view}`);
+}
+function appendUsageUnusedLines(lines, result) {
+    const unused = Array.isArray(result.unused) ? result.unused.filter((value) => typeof value === "string" && value !== "") : [];
+    if (unused.length === 0) {
+        return;
+    }
+    if (readString(result.queryMode) === "explicit") {
+        lines.push("");
+        lines.push(`unused: ${compactStringList(unused, 2, "more")}`);
+        return;
+    }
+    if (readString(result.targetMode) === "file") {
+        lines.push("");
+        lines.push(`unused symbols: ${unused.length}`);
+    }
+}
+function appendTargetLocalUsagesHint(lines, result) {
+    if (result.targetLocalUsagesHidden === true) {
+        lines.push("target-local usages hidden; use +includeTarget to show");
+    }
+}
+function formatUsageCodeEntityBlocks(cwd, result, entityBlocks) {
+    const lines = [];
+    const fileGroups = groupBy(entityBlocks, (block) => readString(block.file) ?? "");
+    for (const [file, fileBlocks] of fileGroups) {
+        if (file) {
+            lines.push(`// ${file}`);
+        }
+        lines.push(...formatUsageCodeContainerGroups(cwd, fileBlocks));
+    }
+    const entity = readString(entityBlocks[0]?.entity) ?? "";
+    const hidden = readHiddenUsageDetail(result, "hiddenBlocks", entity);
+    if (hidden) {
+        lines.push(`// ${hidden}`);
+    }
+    return lines;
+}
+function formatUsageCodeContainerGroups(cwd, blocks) {
+    const lines = [];
+    const { ownerGroups, standalone } = groupUsageRowsByOwner(blocks, (block) => readString(block.container) ?? "");
+    for (const [owner, ownerBlocks] of ownerGroups) {
+        lines.push(`// ${owner}:`);
+        lines.push(...formatUsageCodeBlocks(cwd, ownerBlocks));
+    }
+    if (standalone.length > 0) {
+        lines.push(...formatUsageCodeBlocks(cwd, standalone));
+    }
+    return lines;
+}
+function formatUsageCodeBlocks(cwd, blocks) {
+    const lines = [];
+    for (const block of blocks) {
+        if (typeof block.code === "string") {
+            lines.push(block.code.trimEnd());
+        }
+        else if (typeof block.omitted === "string") {
+            const omittedMessage = (0, session_workspace_1.useSessionGuidance)(cwd, "inspect.usages.codeOmitted", block.omitted) ?? "code omitted";
+            lines.push(`// ${omittedMessage}`);
+            if (typeof block.compactCode === "string" && block.compactCode !== "") {
+                lines.push(block.compactCode);
+            }
+        }
+        lines.push("");
+    }
+    return lines;
+}
+function formatUsageCodeViewBlockText(block, includeEntity = true) {
+    const lines = [];
+    const entity = readString(block.entity);
+    if (includeEntity && entity) {
+        lines.push(`// ${entity}`);
+    }
+    const file = readString(block.file) ?? "";
+    const line = typeof block.line === "number" ? ` l${block.line}` : "";
+    if (file || line) {
+        lines.push(`// ${file}${line}`.trim());
+    }
+    const code = readString(block.code);
+    if (code) {
+        lines.push(code.trimEnd());
+    }
+    return lines;
+}
+function formatUsageLocationsItemText(item, includeOwner) {
+    const entity = readString(item.entity) ?? "";
+    const reference = splitUsageEntityReference(entity);
+    const lines = [`${includeOwner ? entity : reference.name}:`];
+    const usedBy = Array.isArray(item.usedBy) ? item.usedBy.filter(isObject) : [];
+    for (const usage of usedBy) {
+        const file = readString(usage.file) ?? "";
+        const locations = Array.isArray(usage.locations) ? usage.locations.filter(isObject) : [];
+        if (locations.length === 0) {
+            continue;
+        }
+        if (locations.length === 1) {
+            const [location] = locations;
+            const line = typeof location?.line === "number" ? location.line : 0;
+            const container = readString(location?.container);
+            lines.push(container ? `${file}:${line} ${container}` : `${file}:${line}`);
+            continue;
+        }
+        lines.push(`${file}:`);
+        lines.push(...formatUsageLocationContainerGroups(locations));
+    }
+    const hidden = readString(item.hidden);
+    if (hidden) {
+        lines.push(hidden);
+    }
+    return lines;
+}
+function formatUsageLocationContainerGroups(locations) {
+    const lines = [];
+    const { ownerGroups, standalone } = groupUsageRowsByOwner(locations, (location) => readString(location.container) ?? "");
+    for (const [owner, ownerLocations] of ownerGroups) {
+        lines.push(`// ${owner}:`);
+        for (const location of ownerLocations) {
+            const line = typeof location.line === "number" ? location.line : 0;
+            const container = splitUsageEntityReference(readString(location.container) ?? "").name;
+            lines.push(container ? `${container} l${line}` : `l${line}`);
+        }
+    }
+    for (const location of standalone) {
+        const line = typeof location.line === "number" ? location.line : 0;
+        const container = readString(location.container);
+        lines.push(container ? `${container} l${line}` : `l${line}`);
+    }
+    return lines;
+}
+function readHiddenUsageDetail(result, field, entity) {
+    const rows = Array.isArray(result[field]) ? result[field].filter(isObject) : [];
+    const row = rows.find((item) => readString(item.entity) === entity);
+    return row ? readString(row.hidden) : null;
+}
+function groupUsageRowsByOwner(rows, entityOf) {
+    const ownerGroups = new Map();
+    const standalone = [];
+    for (const row of rows) {
+        const reference = splitUsageEntityReference(entityOf(row));
+        if (!reference.owner) {
+            standalone.push(row);
+            continue;
+        }
+        const group = ownerGroups.get(reference.owner) ?? [];
+        group.push(row);
+        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 groupBy(items, keyFn) {
+    const groups = new Map();
+    for (const item of items) {
+        const key = keyFn(item);
+        const current = groups.get(key) ?? [];
+        current.push(item);
+        groups.set(key, current);
+    }
+    return Array.from(groups.entries());
+}
+function sliceFileByRange(file, startLine, startCharacter, endLine, endCharacter) {
+    const text = fs.readFileSync(file, "utf8");
+    const start = textOffsetAt(text, startLine, startCharacter);
+    const end = textOffsetAt(text, endLine, endCharacter);
+    return text.slice(start, end);
+}
+function textOffsetAt(text, targetLine, targetCharacter) {
+    let line = 0;
+    let offset = 0;
+    while (offset < text.length && line < targetLine) {
+        const code = text.charCodeAt(offset);
+        if (code === 13) {
+            offset += text.charCodeAt(offset + 1) === 10 ? 2 : 1;
+            line += 1;
+        }
+        else if (code === 10) {
+            offset += 1;
+            line += 1;
+        }
+        else {
+            offset += 1;
+        }
+    }
+    return Math.max(0, Math.min(offset + targetCharacter, text.length));
+}
+function countNonEmptyLines(text) {
+    return text.split(/\r?\n/).filter((line) => line.trim() !== "").length;
+}
+function displayPath(cwd, file) {
+    return (0, path_display_1.compactDisplayPath)(cwd, file, (0, path_display_2.buildDisplayPathAliases)(cwd, (0, session_workspace_1.readEffectiveSessionPathAliases)(cwd)));
+}
+function isObject(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function readString(value) {
+    return typeof value === "string" && value.trim() !== "" ? value.trim() : null;
+}
+function readStringArray(value) {
+    if (typeof value === "string" && value.trim() !== "") {
+        return [value.trim()];
+    }
+    if (!Array.isArray(value)) {
+        return null;
+    }
+    return value.filter((item) => typeof item === "string" && item.trim() !== "").map((item) => item.trim());
+}