@automaton-labs/aib 0.0.6 → 0.0.8

package/dist/commands/declaration-command.js

@@ -0,0 +1,1209 @@
+"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;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tryReadDeclarationExecutionStatus = void 0;
+exports.runDeclarationCommand = runDeclarationCommand;
+exports.readCachedDeclarationExecution = readCachedDeclarationExecution;
+const crypto = __importStar(require("node:crypto"));
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const typescript_1 = __importDefault(require("typescript"));
+const defaults_1 = require("../config/defaults");
+const import_rules_1 = require("../config/import-rules");
+const standalone_import_process_1 = require("../imports/standalone-import-process");
+const agent_text_1 = require("../shared/agent-text");
+const errors_1 = require("../shared/errors");
+const session_workspace_1 = require("./session-workspace");
+const declaration_preview_cache_1 = require("./declaration-preview-cache");
+const declaration_execution_cache_1 = require("./declaration-execution-cache");
+Object.defineProperty(exports, "tryReadDeclarationExecutionStatus", { enumerable: true, get: function () { return declaration_execution_cache_1.tryReadDeclarationExecutionStatus; } });
+const declaration_format_1 = require("./declaration-format");
+async function runDeclarationCommand(cwd, restArgs, rawPayload, options = {}) {
+    const [operationArg = "help", actionArg = "preview", ...actionArgs] = restArgs;
+    if (operationArg === "help" || operationArg === "--help") {
+        return declarationHelp();
+    }
+    const operation = readOperation(operationArg);
+    const action = actionArg ?? "preview";
+    if (action === "help" || action === "--help") {
+        return declarationHelp(operation);
+    }
+    if (action === "apply") {
+        const previewId = actionArgs[0];
+        if (!previewId || previewId.startsWith("--")) {
+            throw new errors_1.CliError("DECLARATION_PREVIEW_ID_REQUIRED", `declaration ${operation} apply expects a preview id.`, {
+                usage: `aib declaration ${operation} apply <previewId>`
+            });
+        }
+        return applyDeclarationPreview(cwd, operation, previewId, options);
+    }
+    if (action !== "preview" && action !== "execute" && action !== "validate") {
+        throw new errors_1.CliError("UNKNOWN_DECLARATION_ACTION", `Unknown declaration ${operation} action: ${action}`, {
+            availableCommands: ["preview", "apply", "execute", "validate", "help"]
+        });
+    }
+    const normalized = normalizePayload(cwd, rawPayload, operation, action === "execute");
+    const result = await runDeclarationPayload(cwd, normalized, action, options);
+    return result;
+}
+function readCachedDeclarationExecution(cwd, executionId) {
+    const status = (0, declaration_execution_cache_1.readDeclarationExecutionStatus)(cwd, executionId);
+    if (status.result && typeof status.result === "object" && !Array.isArray(status.result)) {
+        return (0, agent_text_1.attachAgentText)(status.result, formatDeclarationAgentText(cwd, status.result));
+    }
+    return (0, agent_text_1.attachAgentText)(status, formatDeclarationStatusText(status));
+}
+async function applyDeclarationPreview(cwd, operation, previewId, options) {
+    const record = (0, declaration_preview_cache_1.readDeclarationPreviewRecord)(cwd, previewId);
+    (0, declaration_preview_cache_1.validateDeclarationPreviewFiles)(record);
+    const normalized = normalizePayload(cwd, {
+        ...record.normalizedPayload,
+        execute: true
+    }, operation, true);
+    return runDeclarationPayload(cwd, normalized, "apply", options, previewId);
+}
+async function runDeclarationPayload(cwd, normalized, action, options, previewIdFromApply) {
+    const executionId = normalized.execute ? (0, declaration_execution_cache_1.buildDeclarationExecutionId)() : undefined;
+    const executionStatus = executionId
+        ? (0, declaration_execution_cache_1.createDeclarationExecutionStatus)(cwd, executionId, `declaration.${normalized.operation}.${action}`, normalized.files.length)
+        : undefined;
+    if (executionStatus) {
+        (0, declaration_execution_cache_1.writeDeclarationExecutionStatus)(cwd, executionStatus);
+    }
+    const result = normalized.operation === "remove"
+        ? runRemove(cwd, normalized, executionId, executionStatus)
+        : await runAddMissing(cwd, normalized, executionId, executionStatus, options);
+    const response = compactDeclarationResponse(cwd, normalized, result, action, executionId, previewIdFromApply);
+    if (!normalized.execute && response.ok !== false && (action === "preview" || action === "validate")) {
+        const previewId = (0, declaration_preview_cache_1.buildDeclarationPreviewId)(normalizedPayloadForCache(normalized));
+        const fileHashes = (0, declaration_preview_cache_1.hashFiles)(result.scannedFiles);
+        const previewHash = (0, declaration_preview_cache_1.buildDeclarationPreviewHash)(normalizedPayloadForCache(normalized), fileHashes, response);
+        (0, declaration_preview_cache_1.writeDeclarationPreviewRecord)(cwd, {
+            previewId,
+            previewHash,
+            createdAt: new Date().toISOString(),
+            cwd: path.resolve(cwd),
+            normalizedPayload: normalizedPayloadForCache(normalized),
+            fileHashes,
+            previewResult: response
+        });
+        response.previewId = previewId;
+        response.next = `aib declaration ${normalized.operation} apply ${previewId}`;
+    }
+    if (executionStatus) {
+        executionStatus.status = response.ok === false ? "failed" : "completed";
+        executionStatus.phase = "completed";
+        executionStatus.completedRows = response.ok === false ? result.rows.filter((row) => row.ok).length : normalized.files.length;
+        executionStatus.failedRows = result.rows.filter((row) => row.ok === false).length;
+        executionStatus.notRunRows = Math.max(0, normalized.files.length - result.rows.length);
+        executionStatus.filesWritten = result.filesWritten;
+        executionStatus.rows = result.rows;
+        executionStatus.result = response;
+        if (response.ok === false) {
+            executionStatus.error = readString(response.code) ?? "DECLARATION_FAILED";
+        }
+        (0, declaration_execution_cache_1.writeDeclarationExecutionStatus)(cwd, executionStatus);
+    }
+    return (0, agent_text_1.attachAgentText)(response, formatDeclarationAgentText(cwd, response));
+}
+function runRemove(cwd, normalized, executionId, status) {
+    const rows = [];
+    const filesWritten = [];
+    const removedBySelector = Object.fromEntries(normalized.selectors.map((selector) => [selector, []]));
+    let failedRow;
+    for (const file of normalized.files) {
+        status && persistProgress(cwd, status, rows, filesWritten);
+        const row = planRemoveFile(file, normalized.selectors);
+        rows.push(row);
+        const removed = Array.isArray(row.removed) ? row.removed.filter(isObject) : [];
+        for (const item of removed) {
+            const selector = readString(item.selector);
+            if (selector && removedBySelector[selector]) {
+                removedBySelector[selector].push(item);
+            }
+        }
+        if (normalized.execute && removed.length > 0) {
+            const text = fs.readFileSync(file, "utf8");
+            fs.writeFileSync(file, applyTextEdits(text, removed.map((item) => ({
+                start: numberField(item, "start"),
+                end: numberField(item, "end"),
+                newText: ""
+            }))));
+            filesWritten.push(file);
+        }
+        if (row.ok === false && !failedRow) {
+            failedRow = row;
+        }
+        if (row.ok === false && !(normalized.continueOnFailure && isContinuableRemoveRowFailure(row))) {
+            return {
+                rows,
+                filesWritten,
+                scannedFiles: normalized.files,
+                removedBySelector,
+                failedRow: row
+            };
+        }
+    }
+    return compactObject({
+        rows,
+        filesWritten,
+        scannedFiles: normalized.files,
+        removedBySelector,
+        failedRow
+    });
+}
+async function runAddMissing(cwd, normalized, _executionId, status, options) {
+    const importRules = options.importRules ?? (0, import_rules_1.readConfigImportRules)(cwd);
+    const preferFiles = normalized.prefer.length > 0 ? collectFilesFromInputs(cwd, normalized.prefer, [], { explicitFiles: true }) : [];
+    const excludeFiles = preferFiles.length > 0
+        ? []
+        : collectFilesFromInputs(cwd, normalized.exclude, []);
+    const shouldCheckPreferredSources = normalized.sourceCheckOnly || normalized.cleanupTail;
+    const sourceCheck = shouldCheckPreferredSources
+        ? checkPreferredSources(cwd, normalized.selectors, preferFiles)
+        : { resolution: {}, failures: [] };
+    const validSelectors = shouldCheckPreferredSources && preferFiles.length > 0
+        ? normalized.selectors.filter((selector) => sourceCheck.resolution[selector])
+        : normalized.selectors;
+    if (normalized.sourceCheckOnly) {
+        return {
+            rows: [],
+            filesWritten: [],
+            scannedFiles: [...normalized.files, ...preferFiles],
+            addedBySelector: {},
+            sourceResolution: sourceCheck.resolution,
+            sourceFailures: sourceCheck.failures,
+            skipped: normalized.skipped
+        };
+    }
+    if (normalized.selectors.length > 0 && validSelectors.length === 0) {
+        return {
+            rows: [],
+            filesWritten: [],
+            scannedFiles: [...normalized.files, ...preferFiles],
+            addedBySelector: {},
+            sourceResolution: sourceCheck.resolution,
+            sourceFailures: sourceCheck.failures,
+            skipped: normalized.skipped
+        };
+    }
+    const requestBody = {
+        mode: "declaration",
+        files: normalized.files,
+        selectors: validSelectors,
+        preferFiles,
+        excludeFiles,
+        execute: normalized.execute,
+        importRules: (0, import_rules_1.importRulesToJson)(importRules)
+    };
+    const rawResult = await (options.standaloneImportWorker ?? standalone_import_process_1.runStandaloneImportWorker)({
+        workspaceRoot: cwd,
+        operation: "declaration-add-missing",
+        payload: requestBody,
+        importRules
+    });
+    const rows = Array.isArray(rawResult.rows) ? rawResult.rows.filter(isObject) : [];
+    const filesWritten = Array.isArray(rawResult.filesWritten)
+        ? rawResult.filesWritten.filter((file) => typeof file === "string")
+        : [];
+    const scannedFiles = Array.isArray(rawResult.scannedFiles)
+        ? rawResult.scannedFiles.filter((file) => typeof file === "string")
+        : [...normalized.files, ...preferFiles];
+    const addedBySelector = {};
+    for (const row of rows) {
+        const addedImports = Array.isArray(row.addedImports) ? row.addedImports.filter(isObject) : [];
+        for (const item of addedImports.flatMap((group) => Array.isArray(group.items) ? group.items.filter(isObject) : [group])) {
+            const selector = readString(item.selector);
+            if (selector) {
+                addedBySelector[selector] = [...(addedBySelector[selector] ?? []), row.file];
+            }
+        }
+    }
+    if (status) {
+        persistProgress(cwd, status, rows, filesWritten);
+    }
+    const failedRow = rows.find((row) => row.ok === false);
+    return {
+        rows,
+        filesWritten,
+        scannedFiles,
+        addedBySelector,
+        sourceResolution: sourceCheck.resolution,
+        sourceFailures: sourceCheck.failures,
+        skipped: normalized.skipped,
+        ...(failedRow ? { failedRow } : {})
+    };
+}
+function planRemoveFile(file, selectors) {
+    if (!fs.existsSync(file)) {
+        return { file, ok: false, code: "DECLARATION_TARGET_NOT_FOUND", error: "Target file does not exist." };
+    }
+    if (isDirectory(file)) {
+        return { file, ok: false, code: "DECLARATION_TARGET_IS_DIRECTORY", error: "Target is a directory." };
+    }
+    const text = fs.readFileSync(file, "utf8");
+    const sourceFile = typescript_1.default.createSourceFile(file, text, typescript_1.default.ScriptTarget.Latest, true, scriptKindForFile(file));
+    const declarations = collectTopLevelDeclarations(sourceFile);
+    const removed = [];
+    const notFoundSelectors = [];
+    const failures = [];
+    for (const selector of selectors) {
+        const parsedSelector = parseDeclarationSelector(selector);
+        const matches = declarations.filter((declaration) => declaration.selector === parsedSelector.name &&
+            (!parsedSelector.kind || normalizedDeclarationKind(declaration.kind) === parsedSelector.kind));
+        if (matches.length === 0) {
+            notFoundSelectors.push(selector);
+            continue;
+        }
+        if (matches.length > 1) {
+            failures.push({
+                file,
+                selector,
+                availableSelectors: matches.map((match) => formatDeclarationSelector(match.kind, match.selector)),
+                code: "DECLARATION_REMOVE_AMBIGUOUS",
+                error: `Selector matched ${matches.length} declarations in one file.`
+            });
+            continue;
+        }
+        const match = matches[0];
+        removed.push({
+            selector: parsedSelector.raw,
+            file,
+            line: sourceFile.getLineAndCharacterOfPosition(match.node.getStart(sourceFile)).line + 1,
+            exported: match.exported,
+            kind: match.kind,
+            start: match.start,
+            end: extendToFollowingLineBreak(text, match.end)
+        });
+    }
+    const firstFailure = failures[0];
+    return compactObject({
+        file,
+        ok: failures.length === 0,
+        selectors,
+        removed,
+        notFoundSelectors,
+        failures: failures.length > 0 ? failures : undefined,
+        ...(firstFailure ? {
+            failedSelector: readString(firstFailure.selector),
+            availableSelectors: Array.isArray(firstFailure.availableSelectors) ? firstFailure.availableSelectors : undefined,
+            code: readString(firstFailure.code),
+            error: readString(firstFailure.error)
+        } : {})
+    });
+}
+function planAddMissingFile(file, normalized, exportIndex) {
+    if (!fs.existsSync(file)) {
+        return { file, ok: false, code: "DECLARATION_TARGET_NOT_FOUND", error: "Target file does not exist." };
+    }
+    if (isDirectory(file)) {
+        return { file, ok: false, code: "DECLARATION_TARGET_IS_DIRECTORY", error: "Target is a directory." };
+    }
+    const text = fs.readFileSync(file, "utf8");
+    if (isCommonJsFile(file, text)) {
+        return { file, ok: false, code: "DECLARATION_ADD_MISSING_COMMONJS_UNSUPPORTED", error: "declaration addMissing v1 does not write CommonJS require statements." };
+    }
+    const selectors = normalized.selectors.length > 0 ? normalized.selectors : collectMissingNamesWithTypeScript(file, text);
+    const sourceFile = typescript_1.default.createSourceFile(file, text, typescript_1.default.ScriptTarget.Latest, true, scriptKindForFile(file));
+    const existing = collectExistingBindings(sourceFile);
+    const grouped = new Map();
+    const unchangedSelectors = [];
+    for (const selector of selectors) {
+        if (existing.has(selector) || !containsIdentifier(text, selector)) {
+            unchangedSelectors.push(selector);
+            continue;
+        }
+        const exportedFrom = exportIndex.exports.get(selector);
+        if (!exportedFrom || path.resolve(exportedFrom) === path.resolve(file)) {
+            unchangedSelectors.push(selector);
+            continue;
+        }
+        grouped.set(exportedFrom, [...(grouped.get(exportedFrom) ?? []), selector]);
+    }
+    const insertAt = importInsertOffset(text, sourceFile);
+    const addedImports = [];
+    let importText = "";
+    for (const [source, names] of grouped.entries()) {
+        const moduleSpecifier = relativeModuleSpecifier(file, source);
+        const newText = `import { ${names.sort().join(", ")} } from "${moduleSpecifier}";\n`;
+        importText += newText;
+        for (const selector of names) {
+            addedImports.push({
+                selector,
+                file,
+                source,
+                moduleSpecifier,
+                start: insertAt,
+                end: insertAt,
+                newText
+            });
+        }
+    }
+    return {
+        file,
+        ok: true,
+        selectors,
+        addedImports: importText ? [{
+                selector: [...grouped.values()].flat().join(","),
+                file,
+                start: insertAt,
+                end: insertAt,
+                newText: importText,
+                items: addedImports
+            }] : [],
+        unchangedSelectors
+    };
+}
+function buildExportIndex(cwd, normalized) {
+    const sourceFiles = normalized.prefer.length > 0
+        ? collectFilesFromInputs(cwd, normalized.prefer, [])
+        : collectFilesFromInputs(cwd, [normalized.scope ?? "."], normalized.exclude);
+    const exports = new Map();
+    for (const file of sourceFiles) {
+        if (!fs.existsSync(file) || isDirectory(file)) {
+            continue;
+        }
+        for (const name of collectExportedNames(file)) {
+            if (!exports.has(name)) {
+                exports.set(name, file);
+            }
+        }
+    }
+    return {
+        exports,
+        sourceFiles
+    };
+}
+function normalizePayload(cwd, rawPayload, operation, execute) {
+    if (!rawPayload || typeof rawPayload !== "object" || Array.isArray(rawPayload)) {
+        throw new errors_1.CliError("DECLARATION_PAYLOAD_REQUIRED", `declaration ${operation} expects a JSON or DSL payload.`);
+    }
+    const raw = rawPayload;
+    const payloadOperation = raw.operation ?? operation;
+    if (payloadOperation !== operation) {
+        throw new errors_1.CliError("DECLARATION_OPERATION_MISMATCH", `Payload operation is ${payloadOperation}, but command expects ${operation}.`);
+    }
+    const selectors = readStringArray(raw.selectors);
+    if (operation === "remove" && selectors.length === 0) {
+        throw new errors_1.CliError("DECLARATION_REMOVE_SELECTORS_REQUIRED", "declaration remove expects at least one selector.");
+    }
+    const exclude = readStringArray(raw.exclude);
+    const files = Array.isArray(raw.files) && raw.files.length > 0
+        ? collectFilesFromInputs(cwd, raw.files.filter((item) => typeof item === "string"), exclude, { explicitFiles: true })
+        : typeof raw.scope === "string" && raw.scope.trim() !== ""
+            ? collectFilesFromInputs(cwd, [raw.scope], exclude)
+            : [];
+    if (files.length === 0) {
+        throw new errors_1.CliError("DECLARATION_TARGET_REQUIRED", `declaration ${operation} expects @scope or @files with at least one source file.`);
+    }
+    return {
+        operation,
+        ...(typeof raw.scope === "string" ? { scope: path.resolve(cwd, raw.scope) } : {}),
+        files,
+        selectors,
+        exclude,
+        prefer: readStringArray(raw.prefer),
+        details: raw.details === true,
+        targetKind: Array.isArray(raw.files) && raw.files.length > 0 ? "files" : "scope",
+        execute: execute || raw.execute === true,
+        sourceCheckOnly: raw.sourceCheckOnly === true,
+        cleanupTail: raw.cleanupTail === true,
+        continueOnFailure: raw.continueOnFailure === true,
+        skipped: Array.isArray(raw.skipped) ? raw.skipped.filter(isObject) : []
+    };
+}
+function isContinuableRemoveRowFailure(row) {
+    const failures = Array.isArray(row.failures) ? row.failures.filter(isObject) : [];
+    return failures.length > 0 && failures.every((failure) => readString(failure.code) === "DECLARATION_REMOVE_AMBIGUOUS");
+}
+function checkPreferredSources(cwd, selectors, preferFiles) {
+    if (preferFiles.length === 0 || selectors.length === 0) {
+        return { resolution: {}, failures: [] };
+    }
+    const exportsBySelector = new Map();
+    for (const file of preferFiles) {
+        if (!fs.existsSync(file) || isDirectory(file)) {
+            continue;
+        }
+        for (const name of collectExportedNames(file)) {
+            exportsBySelector.set(name, [...(exportsBySelector.get(name) ?? []), file]);
+        }
+    }
+    const resolution = {};
+    const failures = [];
+    for (const selector of selectors) {
+        const sources = exportsBySelector.get(selector) ?? [];
+        if (sources.length === 1) {
+            resolution[selector] = sources[0];
+            continue;
+        }
+        failures.push(compactObject({
+            selector,
+            code: sources.length > 1 ? "DECLARATION_ADD_MISSING_SOURCE_AMBIGUOUS" : "DECLARATION_ADD_MISSING_SOURCE_NOT_FOUND",
+            error: sources.length > 1
+                ? "Multiple preferred sources export selector."
+                : "No preferred source exports selector.",
+            sources: sources.map((source) => formatRelativePath(cwd, source))
+        }));
+    }
+    return { resolution, failures };
+}
+function compactDeclarationResponse(cwd, normalized, result, action, executionId, previewIdFromApply) {
+    const failedCount = result.rows.filter((row) => row.ok === false).length;
+    const notRunCount = Math.max(0, normalized.files.length - result.rows.length);
+    const filesWritten = result.filesWritten.map((file) => formatRelativePath(cwd, file));
+    const plannedFilesCount = countPlannedFiles(normalized.operation, result.rows);
+    const operation = `declaration.${normalized.operation}.${action}`;
+    const removedBySelector = result.removedBySelector ?? {};
+    const addedBySelector = result.addedBySelector ?? {};
+    const declarationCount = Object.values(removedBySelector).reduce((sum, items) => sum + items.length, 0);
+    const importCount = Object.values(addedBySelector).reduce((sum, items) => sum + items.length, 0);
+    const changedCount = normalized.operation === "remove" ? declarationCount : importCount;
+    const notFound = normalized.operation === "remove"
+        ? buildRemoveNotFound(cwd, normalized, removedBySelector, result.rows)
+        : {};
+    const notFoundCount = Object.keys(notFound).length;
+    const sourceFailures = result.sourceFailures ?? [];
+    const skipped = result.skipped ?? [];
+    const sourceFailureCount = sourceFailures.length;
+    const skippedCount = skipped.length;
+    const resolvedSourceCount = result.sourceResolution ? Object.keys(result.sourceResolution).length : 0;
+    const failures = normalized.operation === "remove"
+        ? collectRemoveFailures(cwd, result.rows)
+        : sourceFailures;
+    const allRemoveSelectorsMissing = normalized.operation === "remove" &&
+        failedCount === 0 &&
+        declarationCount === 0 &&
+        notFoundCount > 0;
+    const hasFailureIssues = failedCount > 0 || sourceFailureCount > 0 || (normalized.execute && skippedCount > 0);
+    const previewPartialAllowed = !normalized.execute &&
+        (action === "preview" || action === "validate") &&
+        hasFailureIssues &&
+        (changedCount > 0 || resolvedSourceCount > 0);
+    const detailArtifact = !normalized.details && (changedCount > 0 || failedCount > 0 || sourceFailureCount > 0 || skippedCount > 0)
+        ? saveDeclarationView(cwd, normalized, result, executionId)
+        : null;
+    return compactObject({
+        ok: allRemoveSelectorsMissing ? false : hasFailureIssues ? previewPartialAllowed : true,
+        operation,
+        executionId,
+        previewId: previewIdFromApply,
+        target: normalized.scope ? formatRelativePath(cwd, normalized.scope) : `${normalized.files.length} ${plural(normalized.files.length, "file")}`,
+        selectorCount: normalized.selectors.length,
+        fileCount: normalized.files.length,
+        targetKind: normalized.targetKind,
+        details: normalized.details === true ? true : undefined,
+        declarationsRemoved: normalized.operation === "remove" ? declarationCount : undefined,
+        importsAdded: normalized.operation === "addMissing" ? importCount : undefined,
+        notFoundCount: notFoundCount > 0 ? notFoundCount : undefined,
+        sourceFailureCount: sourceFailureCount > 0 ? sourceFailureCount : undefined,
+        skippedCount: skippedCount > 0 ? skippedCount : undefined,
+        plannedFilesCount,
+        filesWrittenCount: result.filesWritten.length,
+        failedCount: failedCount > 0 || sourceFailureCount > 0 || allRemoveSelectorsMissing ? Math.max(1, failedCount + sourceFailureCount) : undefined,
+        notRunCount: notRunCount > 0 ? notRunCount : undefined,
+        filesWritten: filesWritten.length > 0 ? compactFiles(filesWritten, 8) : undefined,
+        removed: normalized.operation === "remove" ? selectorCounts(removedBySelector) : undefined,
+        added: normalized.operation === "addMissing" ? selectorCounts(addedBySelector) : undefined,
+        notFound: Object.keys(notFound).length > 0 ? notFound : undefined,
+        sources: result.sourceResolution && Object.keys(result.sourceResolution).length > 0 ? formatSourceResolution(cwd, result.sourceResolution) : undefined,
+        sourceFailures: sourceFailures.length > 0 ? sourceFailures : undefined,
+        skipped: skipped.length > 0 ? skipped : undefined,
+        failures: failures.length > 0 ? failures : undefined,
+        failed: result.failedRow ? formatFailedRow(cwd, result.failedRow) : undefined,
+        view: detailArtifact?.saved,
+        detailsFile: detailArtifact?.file,
+        internal: {
+            requestedSelectors: normalized.selectors,
+            resolvedScope: normalized.scope,
+            resolvedFiles: normalized.files,
+            exclude: normalized.exclude,
+            prefer: normalized.prefer,
+            details: normalized.details === true ? true : undefined,
+            targetKind: normalized.targetKind,
+            scannedFiles: result.scannedFiles,
+            rows: result.rows,
+            notFound,
+            sourceResolution: result.sourceResolution,
+            sourceFailures,
+            skipped,
+            failures,
+            filesWritten: result.filesWritten
+        },
+        code: allRemoveSelectorsMissing ? "DECLARATION_REMOVE_NOT_FOUND" : result.failedRow?.code ?? sourceFailures[0]?.code,
+        next: buildNext(normalized, changedCount, failedCount, result.failedRow)
+    });
+}
+function saveDeclarationView(cwd, normalized, result, executionId) {
+    return (0, session_workspace_1.saveSessionResultViewJson)(cwd, `res_${crypto.randomBytes(4).toString("hex")}`, {
+        kind: "declarationMutation",
+        operation: normalized.operation,
+        executionId,
+        selectors: normalized.selectors,
+        scope: normalized.scope,
+        files: normalized.files,
+        rows: result.rows,
+        sourceResolution: result.sourceResolution,
+        sourceFailures: result.sourceFailures,
+        skipped: result.skipped,
+        filesWritten: result.filesWritten,
+        scannedFiles: result.scannedFiles
+    });
+}
+function formatDeclarationAgentText(cwd, response) {
+    const lines = [];
+    const operation = readString(response.operation) ?? "declaration";
+    const id = readString(response.executionId) ?? readString(response.previewId);
+    const isAddMissing = operation.includes("addMissing");
+    const isPreviewLike = operation.endsWith(".preview") || operation.endsWith(".validate");
+    lines.push(id ? `${operation} ${id}` : operation);
+    const selectorCount = numberField(response, "selectorCount");
+    const changed = numberField(response, isAddMissing ? "importsAdded" : "declarationsRemoved");
+    const affectedFiles = isPreviewLike ? numberField(response, "plannedFilesCount") : numberField(response, "filesWrittenCount");
+    const failed = numberField(response, "failedCount");
+    const notRun = numberField(response, "notRunCount");
+    const notFoundCount = numberField(response, "notFoundCount");
+    const skippedCount = numberField(response, "skippedCount");
+    const allMissingRemove = readString(response.code) === "DECLARATION_REMOVE_NOT_FOUND";
+    if (allMissingRemove) {
+        lines.push("No requested declarations were found.");
+        appendDeclarationNotFoundLines(lines, response);
+        if (readString(response.next)) {
+            lines.push(`next: ${readString(response.next)}`);
+        }
+        return lines.join("\n");
+    }
+    const changedPhrase = isAddMissing
+        ? `${changed} ${plural(changed, "import")} ${isPreviewLike ? "planned" : "added"}`
+        : `${changed} ${plural(changed, "declaration")} ${isPreviewLike ? "found" : "removed"}`;
+    const summaryParts = [`${selectorCount} ${plural(selectorCount, "selector")}`, changedPhrase];
+    if (notFoundCount > 0 && !isAddMissing) {
+        summaryParts.push(`${notFoundCount} ${plural(notFoundCount, "selector")} not found`);
+    }
+    if (skippedCount > 0) {
+        summaryParts.push(`${skippedCount} ${plural(skippedCount, "selector")} skipped`);
+    }
+    if (notRun > 0 && readString(response.targetKind) === "files") {
+        summaryParts.push(`${notRun} ${plural(notRun, "file")} not run`);
+    }
+    if (!isPreviewLike || failed === 0) {
+        summaryParts.push(`${affectedFiles} ${plural(affectedFiles, "file")} ${isPreviewLike ? "will be written" : "written"}`);
+    }
+    lines.push(summaryParts.join(", "));
+    if (response.details === true && isObject(response.internal)) {
+        const rows = Array.isArray(response.internal.rows) ? response.internal.rows.filter(isObject) : [];
+        lines.push(...(0, declaration_format_1.formatDeclarationMutationDetails)(cwd, isAddMissing ? "addMissing" : "remove", rows));
+    }
+    else {
+        const grouped = isObject(response.removed) ? response.removed : isObject(response.added) ? response.added : null;
+        if (grouped && Object.keys(grouped).length > 0) {
+            lines.push(isAddMissing ? (isPreviewLike ? "planned imports:" : "added:") : (isPreviewLike ? "planned removes:" : "removed:"));
+            for (const [selector, count] of Object.entries(grouped)) {
+                lines.push(`${selector}: ${count} ${plural(Number(count), "file")}`);
+            }
+        }
+        else {
+            lines.push(isAddMissing ? (isPreviewLike ? "planned imports: none" : "added: none") : (isPreviewLike ? "planned removes: none" : "removed: none"));
+        }
+    }
+    if (response.details !== true) {
+        appendDeclarationSourcesLines(lines, response);
+        appendDeclarationFailureLines(lines, response);
+        appendDeclarationSkippedLines(lines, response);
+    }
+    if (response.details !== true && !isAddMissing) {
+        appendDeclarationNotFoundLines(lines, response);
+    }
+    if (response.details !== true && readString(response.view)) {
+        lines.push(`view: ${readString(response.view)}`);
+    }
+    if (readString(response.next)) {
+        lines.push(`next: ${readString(response.next)}`);
+    }
+    return lines.join("\n");
+}
+function formatDeclarationStatusText(status) {
+    return `${status.status}, ${status.completedRows}/${status.rowCount} rows\n${status.operation}`;
+}
+function declarationHelp(operation) {
+    const usage = operation
+        ? `aib declaration ${operation} preview --stdin | aib declaration ${operation} execute --stdin | aib declaration ${operation} apply <previewId>`
+        : "aib declaration remove execute --stdin | aib declaration addMissing execute --stdin";
+    return {
+        ok: true,
+        command: operation ? `declaration ${operation}` : "declaration",
+        usage
+    };
+}
+function readOperation(value) {
+    if (value === "remove" || value === "addMissing") {
+        return value;
+    }
+    if (value === "add-missing") {
+        return "addMissing";
+    }
+    throw new errors_1.CliError("UNKNOWN_DECLARATION_COMMAND", `Unknown declaration command: ${value}`, {
+        availableCommands: ["remove", "addMissing", "help"]
+    });
+}
+function persistProgress(cwd, status, rows, filesWritten) {
+    status.completedRows = rows.filter((row) => row.ok).length;
+    status.failedRows = rows.filter((row) => row.ok === false).length;
+    status.filesWritten = filesWritten;
+    status.rows = rows;
+    (0, declaration_execution_cache_1.writeDeclarationExecutionStatus)(cwd, status);
+}
+function normalizedPayloadForCache(normalized) {
+    return compactObject({
+        operation: normalized.operation,
+        scope: normalized.scope,
+        files: normalized.files,
+        selectors: normalized.selectors,
+        exclude: normalized.exclude,
+        prefer: normalized.prefer,
+        details: normalized.details === true ? true : undefined,
+        sourceCheckOnly: normalized.sourceCheckOnly === true ? true : undefined,
+        cleanupTail: normalized.cleanupTail === true ? true : undefined,
+        continueOnFailure: normalized.continueOnFailure === true ? true : undefined,
+        targetKind: normalized.targetKind
+    });
+}
+function collectTopLevelDeclarations(sourceFile) {
+    const declarations = [];
+    for (const statement of sourceFile.statements) {
+        if (typescript_1.default.isFunctionDeclaration(statement) || typescript_1.default.isClassDeclaration(statement) || typescript_1.default.isInterfaceDeclaration(statement) || typescript_1.default.isTypeAliasDeclaration(statement) || typescript_1.default.isEnumDeclaration(statement)) {
+            const name = statement.name?.text;
+            if (name) {
+                declarations.push(buildDeclarationMatch(sourceFile, statement, name, kindForDeclaration(statement)));
+            }
+            continue;
+        }
+        if (typescript_1.default.isVariableStatement(statement)) {
+            if (statement.declarationList.declarations.length !== 1) {
+                for (const declaration of statement.declarationList.declarations) {
+                    const name = typescript_1.default.isIdentifier(declaration.name) ? declaration.name.text : null;
+                    if (name) {
+                        declarations.push({
+                            ...buildDeclarationMatch(sourceFile, statement, name, "variable"),
+                            kind: "variable-group"
+                        });
+                    }
+                }
+                continue;
+            }
+            const declaration = statement.declarationList.declarations[0];
+            const name = typescript_1.default.isIdentifier(declaration.name) ? declaration.name.text : null;
+            if (name) {
+                declarations.push(buildDeclarationMatch(sourceFile, statement, name, "variable"));
+            }
+        }
+    }
+    return declarations;
+}
+function buildDeclarationMatch(sourceFile, node, selector, kind) {
+    return {
+        selector,
+        file: sourceFile.fileName,
+        line: sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1,
+        exported: hasExportModifier(node),
+        kind,
+        start: node.getFullStart(),
+        end: node.end,
+        node
+    };
+}
+function kindForDeclaration(node) {
+    if (typescript_1.default.isFunctionDeclaration(node))
+        return "function";
+    if (typescript_1.default.isClassDeclaration(node))
+        return "class";
+    if (typescript_1.default.isInterfaceDeclaration(node))
+        return "interface";
+    if (typescript_1.default.isTypeAliasDeclaration(node))
+        return "type";
+    if (typescript_1.default.isEnumDeclaration(node))
+        return "enum";
+    return "declaration";
+}
+function hasExportModifier(node) {
+    return Boolean(typescript_1.default.canHaveModifiers(node) && typescript_1.default.getModifiers(node)?.some((modifier) => modifier.kind === typescript_1.default.SyntaxKind.ExportKeyword));
+}
+function collectExportedNames(file) {
+    const text = fs.readFileSync(file, "utf8");
+    const sourceFile = typescript_1.default.createSourceFile(file, text, typescript_1.default.ScriptTarget.Latest, true, scriptKindForFile(file));
+    const names = [];
+    for (const declaration of collectTopLevelDeclarations(sourceFile)) {
+        if (declaration.exported) {
+            names.push(declaration.selector);
+        }
+    }
+    for (const statement of sourceFile.statements) {
+        if (typescript_1.default.isExportDeclaration(statement) && statement.exportClause && typescript_1.default.isNamedExports(statement.exportClause) && !statement.moduleSpecifier) {
+            for (const element of statement.exportClause.elements) {
+                names.push(element.name.text);
+            }
+        }
+    }
+    return [...new Set(names)];
+}
+function collectExistingBindings(sourceFile) {
+    const names = new Set();
+    for (const statement of sourceFile.statements) {
+        for (const declaration of collectTopLevelDeclarations(sourceFile).filter((item) => item.node === statement)) {
+            names.add(declaration.selector);
+        }
+        if (typescript_1.default.isImportDeclaration(statement) && statement.importClause) {
+            if (statement.importClause.name) {
+                names.add(statement.importClause.name.text);
+            }
+            const namedBindings = statement.importClause.namedBindings;
+            if (namedBindings && typescript_1.default.isNamedImports(namedBindings)) {
+                for (const element of namedBindings.elements) {
+                    names.add(element.name.text);
+                }
+            }
+            if (namedBindings && typescript_1.default.isNamespaceImport(namedBindings)) {
+                names.add(namedBindings.name.text);
+            }
+        }
+    }
+    return names;
+}
+function collectMissingNamesWithTypeScript(file, text) {
+    const options = {
+        allowJs: true,
+        checkJs: true,
+        jsx: typescript_1.default.JsxEmit.ReactJSX,
+        module: typescript_1.default.ModuleKind.ESNext,
+        target: typescript_1.default.ScriptTarget.ES2022,
+        noEmit: true
+    };
+    const host = typescript_1.default.createCompilerHost(options);
+    host.readFile = (fileName) => path.resolve(fileName) === path.resolve(file) ? text : fs.existsSync(fileName) ? fs.readFileSync(fileName, "utf8") : undefined;
+    host.fileExists = (fileName) => path.resolve(fileName) === path.resolve(file) || fs.existsSync(fileName);
+    const program = typescript_1.default.createProgram([file], options, host);
+    const diagnostics = program.getSemanticDiagnostics(program.getSourceFile(file));
+    const names = diagnostics
+        .filter((diagnostic) => diagnostic.code === 2304 || diagnostic.code === 2552)
+        .map((diagnostic) => typescript_1.default.flattenDiagnosticMessageText(diagnostic.messageText, "\n"))
+        .map((message) => message.match(/Cannot find name '([^']+)'/)?.[1] ?? message.match(/Did you mean '([^']+)'/)?.[1] ?? "")
+        .filter(Boolean);
+    return [...new Set(names)];
+}
+function collectFilesFromInputs(cwd, inputs, exclude, options = {}) {
+    const excluded = buildExcludeMatcher(cwd, exclude);
+    const files = [];
+    for (const input of inputs) {
+        const resolved = path.resolve(cwd, input);
+        if (hasGlob(input)) {
+            files.push(...collectSourceFiles(cwd).filter((file) => globToRegex(toSlash(input)).test(toSlash(path.relative(cwd, file)))));
+            continue;
+        }
+        if (fs.existsSync(resolved) && fs.statSync(resolved).isDirectory() && options.explicitFiles !== true) {
+            files.push(...collectSourceFiles(resolved));
+            continue;
+        }
+        files.push(resolved);
+    }
+    const collected = [...new Set(files.filter((file) => isSourceFile(file) && !excluded(file)))];
+    return options.explicitFiles === true ? collected : collected.sort();
+}
+function collectSourceFiles(scope) {
+    if (!fs.existsSync(scope)) {
+        return [];
+    }
+    const stat = fs.statSync(scope);
+    if (stat.isFile()) {
+        return isSourceFile(scope) ? [scope] : [];
+    }
+    if (!stat.isDirectory()) {
+        return [];
+    }
+    const files = [];
+    for (const entry of fs.readdirSync(scope, { withFileTypes: true })) {
+        if (["node_modules", ".git", "dist", "out", "build", ".tmp"].includes(entry.name)) {
+            continue;
+        }
+        const child = path.join(scope, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...collectSourceFiles(child));
+        }
+        else if (entry.isFile() && isSourceFile(child)) {
+            files.push(child);
+        }
+    }
+    return files;
+}
+function buildExcludeMatcher(cwd, exclude) {
+    const exact = new Set(exclude.filter((item) => !hasGlob(item)).map((item) => path.resolve(cwd, item)));
+    const globs = exclude.filter(hasGlob).map((item) => globToRegex(toSlash(item)));
+    return (file) => exact.has(path.resolve(file)) || globs.some((glob) => glob.test(toSlash(path.relative(cwd, file))));
+}
+function hasGlob(value) {
+    return value.includes("*");
+}
+function globToRegex(glob) {
+    const escaped = glob.replace(/[.+^${}()|[\]\\]/g, "\\$&")
+        .replace(/\*\*/g, "__AIB_GLOBSTAR__")
+        .replace(/\*/g, "[^/]*");
+    return new RegExp(`^${escaped.replace(/__AIB_GLOBSTAR__/g, ".*")}$`);
+}
+function applyTextEdits(text, edits) {
+    let output = text;
+    const sorted = [...edits].sort((left, right) => right.start - left.start);
+    for (const edit of sorted) {
+        output = `${output.slice(0, edit.start)}${edit.newText}${output.slice(edit.end)}`;
+    }
+    return output;
+}
+function importInsertOffset(text, sourceFile) {
+    let offset = 0;
+    for (const statement of sourceFile.statements) {
+        if (!typescript_1.default.isImportDeclaration(statement)) {
+            break;
+        }
+        offset = extendToFollowingLineBreak(text, statement.end);
+    }
+    return offset;
+}
+function extendToFollowingLineBreak(text, end) {
+    let next = end;
+    while (next < text.length && (text[next] === "\r" || text[next] === "\n")) {
+        next += 1;
+        if (text[next - 1] === "\n") {
+            break;
+        }
+    }
+    return next;
+}
+function relativeModuleSpecifier(fromFile, toFile) {
+    let relative = toSlash(path.relative(path.dirname(fromFile), toFile));
+    relative = relative.replace(/\.(tsx?|jsx?|mjs|cjs)$/i, "");
+    if (!relative.startsWith(".")) {
+        relative = `./${relative}`;
+    }
+    return relative;
+}
+function scriptKindForFile(file) {
+    if (/\.tsx$/i.test(file))
+        return typescript_1.default.ScriptKind.TSX;
+    if (/\.jsx$/i.test(file))
+        return typescript_1.default.ScriptKind.JSX;
+    if (/\.[cm]?js$/i.test(file))
+        return typescript_1.default.ScriptKind.JS;
+    return typescript_1.default.ScriptKind.TS;
+}
+function isSourceFile(file) {
+    return /\.(tsx?|jsx?|mjs|cjs)$/i.test(file) && !file.endsWith(".d.ts");
+}
+function isDirectory(file) {
+    return fs.existsSync(file) && fs.statSync(file).isDirectory();
+}
+function isCommonJsFile(file, text) {
+    return /\.cjs$/i.test(file) || /\bmodule\.exports\b|\bexports\.[A-Za-z_$]/.test(text);
+}
+function containsIdentifier(text, selector) {
+    return new RegExp(`\\b${escapeRegex(selector)}\\b`).test(text);
+}
+function escapeRegex(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function selectorCounts(input) {
+    const output = {};
+    for (const [selector, items] of Object.entries(input)) {
+        if (items.length > 0) {
+            output[selector] = items.length;
+        }
+    }
+    return output;
+}
+function countPlannedFiles(operation, rows) {
+    return rows.filter((row) => {
+        const items = operation === "addMissing" ? row.addedImports : row.removed;
+        return Array.isArray(items) && items.length > 0;
+    }).length;
+}
+function formatFailedRow(cwd, row) {
+    return compactObject({
+        file: formatRelativePath(cwd, row.file),
+        selector: readString(row.failedSelector) ?? (Array.isArray(row.selectors) ? row.selectors[0] : undefined),
+        availableSelectors: Array.isArray(row.availableSelectors) ? row.availableSelectors : undefined,
+        code: row.code,
+        error: row.error
+    });
+}
+function buildNext(normalized, changedCount, failedCount, failedRow) {
+    if (failedCount > 0) {
+        if (failedRow?.code === "DECLARATION_REMOVE_AMBIGUOUS") {
+            const selector = readString(failedRow.failedSelector) ?? "the ambiguous selector";
+            return normalized.targetKind === "scope"
+                ? `Use a qualified selector for ${selector} or exclude the file, then rerun declaration remove for the scope.`
+                : `Use a qualified selector for ${selector} and rerun declaration remove for the remaining files.`;
+        }
+        return normalized.operation === "remove"
+            ? "Fix failed selector/file and rerun declaration remove for remaining targets."
+            : "Fix failed selector/source and rerun declaration addMissing for remaining targets.";
+    }
+    if (changedCount === 0) {
+        return normalized.operation === "remove"
+            ? "Nothing removed. Check selector names or target files."
+            : "No missing imports added. Check selectors, prefer sources, or target files.";
+    }
+    return normalized.operation === "remove"
+        ? "run addMissing with desired selectors"
+        : "verify affected files only if checks report an issue";
+}
+function buildRemoveNotFound(cwd, normalized, removedBySelector, rows) {
+    const okRows = rows.filter((row) => row.ok !== false);
+    const scannedFiles = okRows.length > 0 ? okRows.map((row) => row.file) : normalized.files;
+    const output = {};
+    const failedSelectors = new Set(collectRemoveFailures(cwd, rows).map((failure) => readString(failure.selector)).filter((selector) => Boolean(selector)));
+    for (const selector of normalized.selectors) {
+        if ((removedBySelector[selector] ?? []).length > 0) {
+            continue;
+        }
+        if (failedSelectors.has(selector)) {
+            continue;
+        }
+        output[selector] = compactFiles(scannedFiles.map((file) => formatRelativePath(cwd, file)), 8);
+    }
+    return output;
+}
+function collectRemoveFailures(cwd, rows) {
+    const failures = [];
+    for (const row of rows) {
+        const rowFailures = Array.isArray(row.failures) ? row.failures.filter(isObject) : [];
+        if (rowFailures.length > 0) {
+            for (const failure of rowFailures) {
+                failures.push(formatFailure(cwd, failure, row.file));
+            }
+            continue;
+        }
+        if (row.ok === false) {
+            failures.push(formatFailedRow(cwd, row));
+        }
+    }
+    return failures;
+}
+function formatFailure(cwd, failure, fallbackFile) {
+    return compactObject({
+        file: formatRelativePath(cwd, readString(failure.file) ?? fallbackFile),
+        selector: readString(failure.selector),
+        availableSelectors: Array.isArray(failure.availableSelectors) ? failure.availableSelectors : undefined,
+        code: readString(failure.code),
+        error: readString(failure.error)
+    });
+}
+function formatSourceResolution(cwd, resolution) {
+    const output = {};
+    for (const [selector, source] of Object.entries(resolution)) {
+        output[selector] = formatRelativePath(cwd, source);
+    }
+    return output;
+}
+function appendDeclarationSourcesLines(lines, response) {
+    if (!isObject(response.sources) || Object.keys(response.sources).length === 0) {
+        return;
+    }
+    lines.push("sources:");
+    for (const [selector, source] of Object.entries(response.sources)) {
+        if (typeof source === "string") {
+            lines.push(`${selector} -> ${source}`);
+        }
+    }
+}
+function appendDeclarationFailureLines(lines, response) {
+    const failures = readFailureList(response);
+    if (failures.length === 0) {
+        return;
+    }
+    lines.push("failed:");
+    for (const failure of failures) {
+        const selector = readString(failure.selector) ?? "selector";
+        const file = readString(failure.file);
+        const code = readString(failure.code);
+        if (code === "DECLARATION_REMOVE_AMBIGUOUS") {
+            lines.push(file ? `${selector}: ambiguous in ${file}` : `${selector}: ambiguous`);
+            appendAvailableSelectors(lines, failure);
+            continue;
+        }
+        if (code === "DECLARATION_ADD_MISSING_SOURCE_AMBIGUOUS") {
+            lines.push(`${selector}: multiple preferred sources export selector`);
+            appendFailureSources(lines, failure);
+            continue;
+        }
+        if (code === "DECLARATION_ADD_MISSING_SOURCE_NOT_FOUND") {
+            lines.push(`${selector}: no preferred source exports selector`);
+            continue;
+        }
+        const error = readString(failure.error);
+        lines.push(error ? `${selector}: ${error}` : selector);
+    }
+}
+function readFailureList(response) {
+    const failures = Array.isArray(response.failures) ? response.failures.filter(isObject) : [];
+    const sourceFailures = Array.isArray(response.sourceFailures) ? response.sourceFailures.filter(isObject) : [];
+    if (failures.length > 0 || sourceFailures.length > 0) {
+        return [...failures, ...sourceFailures];
+    }
+    return isObject(response.failed) ? [response.failed] : [];
+}
+function appendAvailableSelectors(lines, failure) {
+    const available = Array.isArray(failure.availableSelectors)
+        ? failure.availableSelectors.filter((item) => typeof item === "string" && item.trim() !== "")
+        : [];
+    if (available.length === 0) {
+        return;
+    }
+    lines.push("Available selectors:");
+    for (const item of available) {
+        lines.push(item);
+    }
+}
+function appendFailureSources(lines, failure) {
+    const sources = Array.isArray(failure.sources)
+        ? failure.sources.filter((item) => typeof item === "string" && item.trim() !== "")
+        : [];
+    if (sources.length === 0) {
+        return;
+    }
+    lines.push("sources:");
+    for (const source of sources) {
+        lines.push(source);
+    }
+}
+function appendDeclarationSkippedLines(lines, response) {
+    const skipped = Array.isArray(response.skipped) ? response.skipped.filter(isObject) : [];
+    if (skipped.length === 0) {
+        return;
+    }
+    lines.push("skipped:");
+    for (const item of skipped) {
+        const selector = readString(item.selector) ?? "selector";
+        const operation = readString(item.operation);
+        const reason = readString(item.reason);
+        lines.push(`${selector}${operation ? ` ${operation}` : ""}${reason ? ` skipped for ${reason}` : " skipped"}`);
+    }
+}
+function appendDeclarationNotFoundLines(lines, response) {
+    if (!isObject(response.notFound) || Object.keys(response.notFound).length === 0) {
+        return;
+    }
+    lines.push("notFound:");
+    for (const [selector, files] of Object.entries(response.notFound)) {
+        const list = Array.isArray(files)
+            ? files.filter((item) => typeof item === "string" && item.trim() !== "")
+            : [];
+        lines.push(`${selector}: ${list.length > 0 ? list.join(", ") : "no matching files"}`);
+    }
+}
+function parseDeclarationSelector(selector) {
+    const trimmed = selector.trim();
+    for (const separator of [defaults_1.DEFAULT_EFFECTIVE_CONFIG.selectorSeparator, ":", "-"]) {
+        const index = trimmed.indexOf(separator);
+        if (index <= 0) {
+            continue;
+        }
+        const maybeKind = declarationKindFromAlias(trimmed.slice(0, index));
+        const name = trimmed.slice(index + separator.length).trim();
+        if (maybeKind && name) {
+            return { raw: trimmed, name, kind: maybeKind };
+        }
+    }
+    return { raw: trimmed, name: trimmed, kind: null };
+}
+function formatDeclarationSelector(kind, name) {
+    const normalizedKind = normalizedDeclarationKind(kind);
+    const alias = declarationAliasForKind(normalizedKind) ?? normalizedKind;
+    return `${alias}${defaults_1.DEFAULT_EFFECTIVE_CONFIG.selectorSeparator}${name}`;
+}
+function declarationKindFromAlias(value) {
+    const normalized = normalizedDeclarationKind(value);
+    if (declarationAliasForKind(normalized) !== null) {
+        return normalized;
+    }
+    const kind = Object.entries(defaults_1.DEFAULT_EFFECTIVE_CONFIG.entityKindAliases).find(([, alias]) => alias === value)?.[0];
+    return kind ? normalizedDeclarationKind(kind) : null;
+}
+function declarationAliasForKind(kind) {
+    const normalized = normalizedDeclarationKind(kind);
+    if (normalized === "class" || normalized === "interface" || normalized === "type" || normalized === "function" || normalized === "variable" || normalized === "enum") {
+        return defaults_1.DEFAULT_EFFECTIVE_CONFIG.entityKindAliases[normalized];
+    }
+    return null;
+}
+function normalizedDeclarationKind(kind) {
+    return kind === "variable-group" ? "variable" : kind;
+}
+function compactFiles(files, limit) {
+    return files.length <= limit ? files : [...files.slice(0, limit), `+ ${files.length - limit} more`];
+}
+function readStringArray(value) {
+    return Array.isArray(value) ? [...new Set(value.filter((item) => typeof item === "string" && item.trim() !== "").map((item) => item.trim()))] : [];
+}
+function readString(value) {
+    return typeof value === "string" && value.trim() !== "" ? value.trim() : null;
+}
+function numberField(value, field) {
+    const raw = value[field];
+    return typeof raw === "number" && Number.isFinite(raw) ? raw : 0;
+}
+function compactObject(input) {
+    const output = {};
+    for (const [key, value] of Object.entries(input)) {
+        if (value !== undefined && value !== null) {
+            output[key] = value;
+        }
+    }
+    return output;
+}
+function isObject(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function formatRelativePath(cwd, file) {
+    const relative = path.relative(cwd, file);
+    return relative && !relative.startsWith("..") && !path.isAbsolute(relative)
+        ? toSlash(relative)
+        : toSlash(file);
+}
+function toSlash(value) {
+    return value.replace(/\\/g, "/");
+}
+function plural(count, singular) {
+    return count === 1 ? singular : `${singular}s`;
+}