@mycodemap/mycodemap 1.9.0 → 2.0.0

package/dist/cli/interface-contract/commands/query.js

@@ -0,0 +1,185 @@
+// [META] since:2026-04-30 | owner:cli-team | stable:false
+// [WHY] Interface contract for the `query` command family
+export const queryContract = {
+    name: 'query',
+    description: '查询代码地图中的符号、模块、依赖信息',
+    args: [],
+    flags: [
+        {
+            name: 'symbol',
+            short: 's',
+            long: 'symbol',
+            description: '精确查询符号',
+            type: 'string',
+        },
+        {
+            name: 'module',
+            short: 'm',
+            long: 'module',
+            description: '查询模块',
+            type: 'string',
+        },
+        {
+            name: 'deps',
+            short: 'd',
+            long: 'deps',
+            description: '查询依赖',
+            type: 'string',
+        },
+        {
+            name: 'search',
+            short: 'S',
+            long: 'search',
+            description: '模糊搜索',
+            type: 'string',
+        },
+        {
+            name: 'limit',
+            short: 'l',
+            long: 'limit',
+            description: '限制结果数量',
+            type: 'number',
+            defaultValue: 50,
+        },
+        {
+            name: 'json',
+            short: 'j',
+            long: 'json',
+            description: 'JSON 格式输出',
+            type: 'boolean',
+            defaultValue: false,
+        },
+        {
+            name: 'structured',
+            long: 'structured',
+            description: '输出完全结构化的 JSON（不包含自然语言字符串，需要配合 --json 使用）',
+            type: 'boolean',
+            defaultValue: false,
+        },
+        {
+            name: 'verbose',
+            short: 'v',
+            long: 'verbose',
+            description: '显示性能指标',
+            type: 'boolean',
+            defaultValue: false,
+        },
+        {
+            name: 'regex',
+            short: 'r',
+            long: 'regex',
+            description: '使用正则表达式搜索（仅适用于 -S/--search）',
+            type: 'boolean',
+            defaultValue: false,
+        },
+        {
+            name: 'context',
+            short: 'c',
+            long: 'context',
+            description: '显示代码上下文行数',
+            type: 'number',
+            defaultValue: 0,
+        },
+        {
+            name: 'case-sensitive',
+            long: 'case-sensitive',
+            description: '大小写敏感搜索（精确搜索默认开启）',
+            type: 'boolean',
+            defaultValue: false,
+        },
+        {
+            name: 'include-references',
+            long: 'include-references',
+            description: '包含符号引用位置信息',
+            type: 'boolean',
+            defaultValue: false,
+        },
+        {
+            name: 'deps-format',
+            long: 'deps-format',
+            description: '依赖查询输出格式 (default|detailed)',
+            type: 'string',
+            defaultValue: 'default',
+        },
+        {
+            name: 'no-cache',
+            long: 'no-cache',
+            description: '禁用缓存，强制重新加载索引',
+            type: 'boolean',
+            defaultValue: false,
+        },
+    ],
+    outputShape: {
+        description: '查询结果',
+        type: 'object',
+        properties: [
+            {
+                name: 'type',
+                type: 'string',
+                description: '查询类型: symbol | module | deps | search',
+            },
+            {
+                name: 'query',
+                type: 'string',
+                description: '实际执行的查询字符串',
+            },
+            {
+                name: 'count',
+                type: 'number',
+                description: '结果数量',
+            },
+            {
+                name: 'results',
+                type: 'array',
+                description: '结果条目列表',
+                items: {
+                    name: 'resultItem',
+                    type: 'object',
+                    properties: [
+                        { name: 'name', type: 'string' },
+                        { name: 'path', type: 'string', nullable: true },
+                        { name: 'kind', type: 'string', nullable: true },
+                        { name: 'details', type: 'string', nullable: true },
+                        {
+                            name: 'location',
+                            type: 'object',
+                            nullable: true,
+                            properties: [
+                                { name: 'file', type: 'string' },
+                                { name: 'line', type: 'number', nullable: true },
+                                { name: 'column', type: 'number', nullable: true },
+                            ],
+                        },
+                        { name: 'isExported', type: 'boolean', nullable: true },
+                    ],
+                },
+            },
+            {
+                name: 'metrics',
+                type: 'object',
+                description: '性能指标（verbose 模式输出）',
+                nullable: true,
+                properties: [
+                    { name: 'indexLoadTime', type: 'number' },
+                    { name: 'queryTime', type: 'number' },
+                    { name: 'totalTime', type: 'number' },
+                    { name: 'cacheHit', type: 'boolean' },
+                    { name: 'indexSize', type: 'number' },
+                ],
+            },
+        ],
+    },
+    errorCodes: [
+        { code: 'INDEX_NOT_FOUND', description: '代码地图索引不存在，需先运行 generate' },
+        { code: 'INVALID_QUERY', description: '查询参数无效或冲突' },
+        { code: 'NO_RESULTS', description: '未找到匹配结果' },
+        { code: 'CACHE_ERROR', description: '缓存读写失败' },
+    ],
+    examples: [
+        'codemap query -s MyClass --json',
+        'codemap query -m src/index.ts -l 10',
+        'codemap query -S "router" --regex -j',
+        'codemap query -d lodash --deps-format detailed --json',
+    ],
+};
+//# sourceMappingURL=query.js.map

package/dist/cli/interface-contract/commands/query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.js","sourceRoot":"","sources":["../../../../src/cli/interface-contract/commands/query.ts"],"names":[],"mappings":"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"}

package/dist/cli/interface-contract/index.d.ts

@@ -0,0 +1,22 @@
+import type { InterfaceContract } from './types.js';
+export type { ArgDef, CommandContract, ErrorCode, FlagDef, FlagType, InterfaceContract, OutputProperty, OutputShape, } from './types.js';
+export { interfaceContractSchema, safeValidateInterfaceContract, validateInterfaceContract, } from './schema.js';
+export { commandContracts, analyzeContract, queryContract, depsContract, doctorContract, benchmarkContract, initContract, } from './commands/index.js';
+/**
+ * Build the full interface contract from the registered command contracts.
+ */
+export declare function getFullContract(): InterfaceContract;
+/**
+ * Validate a candidate contract object against the meta-schema.
+ * @throws {z.ZodError} if validation fails
+ */
+export declare function validateContract(data: unknown): InterfaceContract;
+/**
+ * Validate the current full contract against the meta-schema.
+ * Useful as a self-test during CI or startup.
+ */
+export declare function validateCurrentContract(): {
+    valid: boolean;
+    errors?: string[];
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/interface-contract/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/cli/interface-contract/index.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAQpD,YAAY,EACV,MAAM,EACN,eAAe,EACf,SAAS,EACT,OAAO,EACP,QAAQ,EACR,iBAAiB,EACjB,cAAc,EACd,WAAW,GACZ,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,uBAAuB,EACvB,6BAA6B,EAC7B,yBAAyB,GAC1B,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,aAAa,EACb,YAAY,EACZ,cAAc,EACd,iBAAiB,EACjB,YAAY,GACb,MAAM,qBAAqB,CAAC;AAE7B;;GAEG;AACH,wBAAgB,eAAe,IAAI,iBAAiB,CASnD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,iBAAiB,CAEjE;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,IAAI;IACzC,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB,CAYA"}

package/dist/cli/interface-contract/index.js

@@ -0,0 +1,41 @@
+// [META] since:2026-04-30 | owner:cli-team | stable:false
+// [WHY] Public API for the CLI interface contract — schema access, validation, and programmatic introspection
+import { commandContracts } from './commands/index.js';
+import { safeValidateInterfaceContract, validateInterfaceContract, } from './schema.js';
+export { interfaceContractSchema, safeValidateInterfaceContract, validateInterfaceContract, } from './schema.js';
+export { commandContracts, analyzeContract, queryContract, depsContract, doctorContract, benchmarkContract, initContract, } from './commands/index.js';
+/**
+ * Build the full interface contract from the registered command contracts.
+ */
+export function getFullContract() {
+    return {
+        version: '0.1.0',
+        programName: 'mycodemap',
+        aliases: ['codemap'],
+        description: 'TypeScript 代码地图工具 - 为 AI 辅助开发提供结构化上下文',
+        commands: [...commandContracts],
+    };
+}
+/**
+ * Validate a candidate contract object against the meta-schema.
+ * @throws {z.ZodError} if validation fails
+ */
+export function validateContract(data) {
+    return validateInterfaceContract(data);
+}
+/**
+ * Validate the current full contract against the meta-schema.
+ * Useful as a self-test during CI or startup.
+ */
+export function validateCurrentContract() {
+    const contract = getFullContract();
+    const result = safeValidateInterfaceContract(contract);
+    if (result.success) {
+        return { valid: true };
+    }
+    return {
+        valid: false,
+        errors: result.error.issues.map((e) => `${String(e.path)}: ${e.message}`),
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/cli/interface-contract/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/cli/interface-contract/index.ts"],"names":[],"mappings":"AAAA,0DAA0D;AAC1D,8GAA8G;AAG9G,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAEL,6BAA6B,EAC7B,yBAAyB,GAC1B,MAAM,aAAa,CAAC;AAarB,OAAO,EACL,uBAAuB,EACvB,6BAA6B,EAC7B,yBAAyB,GAC1B,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,aAAa,EACb,YAAY,EACZ,cAAc,EACd,iBAAiB,EACjB,YAAY,GACb,MAAM,qBAAqB,CAAC;AAE7B;;GAEG;AACH,MAAM,UAAU,eAAe;IAC7B,OAAO;QACL,OAAO,EAAE,OAAO;QAChB,WAAW,EAAE,WAAW;QACxB,OAAO,EAAE,CAAC,SAAS,CAAC;QACpB,WAAW,EACT,uCAAuC;QACzC,QAAQ,EAAE,CAAC,GAAG,gBAAgB,CAAC;KAChC,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAa;IAC5C,OAAO,yBAAyB,CAAC,IAAI,CAAC,CAAC;AACzC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,uBAAuB;IAIrC,MAAM,QAAQ,GAAG,eAAe,EAAE,CAAC;IACnC,MAAM,MAAM,GAAG,6BAA6B,CAAC,QAAQ,CAAC,CAAC;IACvD,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;QACnB,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IACzB,CAAC;IACD,OAAO;QACL,KAAK,EAAE,KAAK;QACZ,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAC7B,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,CACzC;KACF,CAAC;AACJ,CAAC"}

package/dist/cli/interface-contract/schema.d.ts

@@ -0,0 +1,30 @@
+import { z } from 'zod';
+import type { ArgDef, CommandContract, ErrorCode, FlagDef, InterfaceContract, OutputProperty, OutputShape } from './types.js';
+export declare const flagTypeSchema: z.ZodEnum<{
+    string: "string";
+    number: "number";
+    boolean: "boolean";
+}>;
+export declare const argDefSchema: z.ZodType<ArgDef>;
+export declare const flagDefSchema: z.ZodType<FlagDef>;
+export declare const outputPropertySchema: z.ZodType<OutputProperty>;
+export declare const outputShapeSchema: z.ZodType<OutputShape>;
+export declare const errorCodeSchema: z.ZodType<ErrorCode>;
+export declare const commandContractSchema: z.ZodType<CommandContract>;
+export declare const interfaceContractSchema: z.ZodType<InterfaceContract>;
+/**
+ * Validate an unknown value as an InterfaceContract.
+ * @returns parsed contract on success, throws ZodError on failure
+ */
+export declare function validateInterfaceContract(data: unknown): InterfaceContract;
+/**
+ * Safe validation — returns a result object instead of throwing.
+ */
+export declare function safeValidateInterfaceContract(data: unknown): {
+    success: true;
+    data: InterfaceContract;
+} | {
+    success: false;
+    error: z.ZodError;
+};
+//# sourceMappingURL=schema.d.ts.map

package/dist/cli/interface-contract/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/cli/interface-contract/schema.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EACV,MAAM,EACN,eAAe,EACf,SAAS,EACT,OAAO,EACP,iBAAiB,EACjB,cAAc,EACd,WAAW,EACZ,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,cAAc;;;;EAA0C,CAAC;AAEtE,eAAO,MAAM,YAAY,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAKzC,CAAC;AAEH,eAAO,MAAM,aAAa,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAS3C,CAAC;AAEH,eAAO,MAAM,oBAAoB,EAAE,CAAC,CAAC,OAAO,CAAC,cAAc,CAS1D,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,CAAC,CAAC,OAAO,CAAC,WAAW,CAInD,CAAC;AAEH,eAAO,MAAM,eAAe,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,CAG/C,CAAC;AAEH,eAAO,MAAM,qBAAqB,EAAE,CAAC,CAAC,OAAO,CAAC,eAAe,CAS3D,CAAC;AAEH,eAAO,MAAM,uBAAuB,EAAE,CAAC,CAAC,OAAO,CAAC,iBAAiB,CAM/D,CAAC;AAEH;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,OAAO,GAAG,iBAAiB,CAE1E;AAED;;GAEG;AACH,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,OAAO,GACZ;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,iBAAiB,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,CAAC,CAAC,QAAQ,CAAA;CAAE,CAMpF"}

package/dist/cli/interface-contract/schema.js

@@ -0,0 +1,72 @@
+// [META] since:2026-04-30 | owner:cli-team | stable:false
+// [WHY] Zod meta-schema for runtime validation of interface contracts
+import { z } from 'zod';
+export const flagTypeSchema = z.enum(['string', 'boolean', 'number']);
+export const argDefSchema = z.object({
+    name: z.string(),
+    description: z.string(),
+    required: z.boolean().optional(),
+    variadic: z.boolean().optional(),
+});
+export const flagDefSchema = z.object({
+    name: z.string(),
+    short: z.string().optional(),
+    long: z.string(),
+    description: z.string(),
+    type: flagTypeSchema,
+    defaultValue: z.unknown().optional(),
+    multiple: z.boolean().optional(),
+    required: z.boolean().optional(),
+});
+export const outputPropertySchema = z.lazy(() => z.object({
+    name: z.string(),
+    type: z.enum(['string', 'number', 'boolean', 'object', 'array', 'null']),
+    description: z.string().optional(),
+    nullable: z.boolean().optional(),
+    items: outputPropertySchema.optional(),
+    properties: z.array(outputPropertySchema).optional(),
+}));
+export const outputShapeSchema = z.object({
+    description: z.string().optional(),
+    type: z.enum(['object', 'array']),
+    properties: z.array(outputPropertySchema),
+});
+export const errorCodeSchema = z.object({
+    code: z.string(),
+    description: z.string(),
+});
+export const commandContractSchema = z.object({
+    name: z.string(),
+    description: z.string(),
+    aliases: z.array(z.string()).optional(),
+    args: z.array(argDefSchema),
+    flags: z.array(flagDefSchema),
+    outputShape: outputShapeSchema,
+    errorCodes: z.array(errorCodeSchema),
+    examples: z.array(z.string()),
+});
+export const interfaceContractSchema = z.object({
+    version: z.string(),
+    programName: z.string(),
+    aliases: z.array(z.string()),
+    description: z.string(),
+    commands: z.array(commandContractSchema),
+});
+/**
+ * Validate an unknown value as an InterfaceContract.
+ * @returns parsed contract on success, throws ZodError on failure
+ */
+export function validateInterfaceContract(data) {
+    return interfaceContractSchema.parse(data);
+}
+/**
+ * Safe validation — returns a result object instead of throwing.
+ */
+export function safeValidateInterfaceContract(data) {
+    const result = interfaceContractSchema.safeParse(data);
+    if (result.success) {
+        return { success: true, data: result.data };
+    }
+    return { success: false, error: result.error };
+}
+//# sourceMappingURL=schema.js.map

package/dist/cli/interface-contract/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../src/cli/interface-contract/schema.ts"],"names":[],"mappings":"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"}

package/dist/cli/interface-contract/types.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Supported flag value types
+ */
+export type FlagType = 'string' | 'boolean' | 'number';
+/**
+ * Positional argument definition
+ */
+export interface ArgDef {
+    name: string;
+    description: string;
+    required?: boolean;
+    variadic?: boolean;
+}
+/**
+ * Flag / option definition
+ */
+export interface FlagDef {
+    name: string;
+    short?: string;
+    long: string;
+    description: string;
+    type: FlagType;
+    defaultValue?: unknown;
+    multiple?: boolean;
+    required?: boolean;
+}
+/**
+ * Output property descriptor (JSON Schema-ish, serializable)
+ */
+export interface OutputProperty {
+    name: string;
+    type: 'string' | 'number' | 'boolean' | 'object' | 'array' | 'null';
+    description?: string;
+    nullable?: boolean;
+    items?: OutputProperty;
+    properties?: OutputProperty[];
+}
+/**
+ * Output shape descriptor for a command
+ */
+export interface OutputShape {
+    description?: string;
+    type: 'object' | 'array';
+    properties: OutputProperty[];
+}
+/**
+ * Known error code for a command
+ */
+export interface ErrorCode {
+    code: string;
+    description: string;
+}
+/**
+ * Contract for a single CLI command
+ */
+export interface CommandContract {
+    name: string;
+    description: string;
+    aliases?: string[];
+    args: ArgDef[];
+    flags: FlagDef[];
+    outputShape: OutputShape;
+    errorCodes: ErrorCode[];
+    examples: string[];
+}
+/**
+ * Full CLI interface contract
+ */
+export interface InterfaceContract {
+    version: string;
+    programName: string;
+    aliases: string[];
+    description: string;
+    commands: CommandContract[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/cli/interface-contract/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/cli/interface-contract/types.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAC;AAEvD;;GAEG;AACH,MAAM,WAAW,MAAM;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,QAAQ,CAAC;IACf,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,CAAC;IACpE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,UAAU,CAAC,EAAE,cAAc,EAAE,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC;IACzB,UAAU,EAAE,cAAc,EAAE,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,KAAK,EAAE,OAAO,EAAE,CAAC;IACjB,WAAW,EAAE,WAAW,CAAC;IACzB,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,eAAe,EAAE,CAAC;CAC7B"}

package/dist/cli/interface-contract/types.js

@@ -0,0 +1,4 @@
+// [META] since:2026-04-30 | owner:cli-team | stable:false
+// [WHY] TypeScript types for the CLI interface contract schema — single source of truth for command shapes
+export {};
+//# sourceMappingURL=types.js.map

package/dist/cli/interface-contract/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/cli/interface-contract/types.ts"],"names":[],"mappings":"AAAA,0DAA0D;AAC1D,2GAA2G"}

package/dist/cli/output/apply-suggestion.d.ts

@@ -0,0 +1,12 @@
+import type { OutputMode, ActionableError } from './types.js';
+export interface SuggestionResult {
+    type: 'result';
+    success: boolean;
+    data?: unknown;
+    attemptedCommand?: string;
+}
+export declare function tryApplySuggestion(error: ActionableError, options: {
+    applySuggestion?: boolean;
+    wasmFallback?: boolean;
+}, _mode: OutputMode): Promise<SuggestionResult>;
+//# sourceMappingURL=apply-suggestion.d.ts.map

package/dist/cli/output/apply-suggestion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply-suggestion.d.ts","sourceRoot":"","sources":["../../../src/cli/output/apply-suggestion.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAK9D,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,QAAQ,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,eAAe,EACtB,OAAO,EAAE;IAAE,eAAe,CAAC,EAAE,OAAO,CAAC;IAAC,YAAY,CAAC,EAAE,OAAO,CAAA;CAAE,EAC9D,KAAK,EAAE,UAAU,GAChB,OAAO,CAAC,gBAAgB,CAAC,CAwB3B"}

package/dist/cli/output/apply-suggestion.js

@@ -0,0 +1,29 @@
+// [META] since:2026-05-01 | owner:cli-team | stable:false
+// [WHY] Safety-gated auto-remediation engine — executes nextCommand only when confidence >= threshold and --apply-suggestion flag set
+import { exec } from 'node:child_process';
+import { promisify } from 'node:util';
+import { APPLY_SUGGESTION_CONFIDENCE_THRESHOLD } from './types.js';
+const execAsync = promisify(exec);
+export async function tryApplySuggestion(error, options, _mode) {
+    if (!options.applySuggestion) {
+        return { type: 'result', success: false, data: { reason: 'apply-suggestion flag not set' } };
+    }
+    if (error.confidence < APPLY_SUGGESTION_CONFIDENCE_THRESHOLD) {
+        return { type: 'result', success: false, data: { reason: `confidence ${error.confidence} below threshold ${APPLY_SUGGESTION_CONFIDENCE_THRESHOLD}` } };
+    }
+    if (!error.nextCommand) {
+        return { type: 'result', success: false, data: { reason: 'no nextCommand available' } };
+    }
+    process.stderr.write(JSON.stringify({ type: 'apply-suggestion', action: 'attempt', command: error.nextCommand, confidence: error.confidence }) + '\n');
+    try {
+        const { stdout } = await execAsync(error.nextCommand, { timeout: 30000 });
+        process.stderr.write(JSON.stringify({ type: 'apply-suggestion', action: 'success', command: error.nextCommand }) + '\n');
+        return { type: 'result', success: true, data: { stdout: stdout.trim() }, attemptedCommand: error.nextCommand };
+    }
+    catch (execError) {
+        const msg = execError instanceof Error ? execError.message : String(execError);
+        process.stderr.write(JSON.stringify({ type: 'apply-suggestion', action: 'failed', command: error.nextCommand, error: msg }) + '\n');
+        return { type: 'result', success: false, data: { error: msg }, attemptedCommand: error.nextCommand };
+    }
+}
+//# sourceMappingURL=apply-suggestion.js.map

package/dist/cli/output/apply-suggestion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply-suggestion.js","sourceRoot":"","sources":["../../../src/cli/output/apply-suggestion.ts"],"names":[],"mappings":"AAAA,0DAA0D;AAC1D,sIAAsI;AAEtI,OAAO,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,OAAO,EAAE,qCAAqC,EAAE,MAAM,YAAY,CAAC;AAEnE,MAAM,SAAS,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;AASlC,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,KAAsB,EACtB,OAA8D,EAC9D,KAAiB;IAEjB,IAAI,CAAC,OAAO,CAAC,eAAe,EAAE,CAAC;QAC7B,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,MAAM,EAAE,+BAA+B,EAAE,EAAE,CAAC;IAC/F,CAAC;IAED,IAAI,KAAK,CAAC,UAAU,GAAG,qCAAqC,EAAE,CAAC;QAC7D,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,MAAM,EAAE,cAAc,KAAK,CAAC,UAAU,oBAAoB,qCAAqC,EAAE,EAAE,EAAE,CAAC;IACzJ,CAAC;IAED,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC;QACvB,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,MAAM,EAAE,0BAA0B,EAAE,EAAE,CAAC;IAC1F,CAAC;IAED,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,kBAAkB,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,CAAC,WAAW,EAAE,UAAU,EAAE,KAAK,CAAC,UAAU,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;IAEvJ,IAAI,CAAC;QACH,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,SAAS,CAAC,KAAK,CAAC,WAAW,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;QAC1E,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,kBAAkB,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,CAAC,WAAW,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;QACzH,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE,EAAE,EAAE,gBAAgB,EAAE,KAAK,CAAC,WAAW,EAAE,CAAC;IACjH,CAAC;IAAC,OAAO,SAAS,EAAE,CAAC;QACnB,MAAM,GAAG,GAAG,SAAS,YAAY,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAC/E,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,kBAAkB,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,CAAC,WAAW,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;QACpI,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,gBAAgB,EAAE,KAAK,CAAC,WAAW,EAAE,CAAC;IACvG,CAAC;AACH,CAAC"}

package/dist/cli/output/error-codes.d.ts

@@ -0,0 +1,22 @@
+export declare const ErrorCodes: {
+    readonly DEP_NATIVE_MISSING: "DEP_NATIVE_MISSING";
+    readonly DEP_WASM_FALLBACK_AVAILABLE: "DEP_WASM_FALLBACK_AVAILABLE";
+    readonly DEP_MODULE_NOT_FOUND: "DEP_MODULE_NOT_FOUND";
+    readonly DEP_REBUILD_REQUIRED: "DEP_REBUILD_REQUIRED";
+    readonly CFG_INVALID_CONFIG: "CFG_INVALID_CONFIG";
+    readonly CFG_WORKSPACE_NOT_INITIALIZED: "CFG_WORKSPACE_NOT_INITIALIZED";
+    readonly CFG_WORKSPACE_DRIFT: "CFG_WORKSPACE_DRIFT";
+    readonly RUN_COMMAND_FAILED: "RUN_COMMAND_FAILED";
+    readonly RUN_PARSE_ERROR: "RUN_PARSE_ERROR";
+    readonly RUN_TIMEOUT: "RUN_TIMEOUT";
+    readonly FS_FILE_NOT_FOUND: "FS_FILE_NOT_FOUND";
+    readonly FS_PERMISSION_DENIED: "FS_PERMISSION_DENIED";
+    readonly FS_WORKING_DIR_INVALID: "FS_WORKING_DIR_INVALID";
+};
+export type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
+export declare const ErrorRemediation: Record<ErrorCode, {
+    message: string;
+    nextCommand?: string;
+    confidence: number;
+}>;
+//# sourceMappingURL=error-codes.d.ts.map

package/dist/cli/output/error-codes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-codes.d.ts","sourceRoot":"","sources":["../../../src/cli/output/error-codes.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,UAAU;;;;;;;;;;;;;;CAqBb,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,OAAO,UAAU,CAAC,CAAC;AAErE,eAAO,MAAM,gBAAgB,EAAE,MAAM,CACnC,SAAS,EACT;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAiE9D,CAAC"}

package/dist/cli/output/error-codes.js

@@ -0,0 +1,82 @@
+// [META] since:2026-05-01 | owner:cli-team | stable:false
+// [WHY] Canonical error code registry with prefix classification and remediation map
+export const ErrorCodes = {
+    // Dependency errors
+    DEP_NATIVE_MISSING: 'DEP_NATIVE_MISSING',
+    DEP_WASM_FALLBACK_AVAILABLE: 'DEP_WASM_FALLBACK_AVAILABLE',
+    DEP_MODULE_NOT_FOUND: 'DEP_MODULE_NOT_FOUND',
+    DEP_REBUILD_REQUIRED: 'DEP_REBUILD_REQUIRED',
+    // Configuration errors
+    CFG_INVALID_CONFIG: 'CFG_INVALID_CONFIG',
+    CFG_WORKSPACE_NOT_INITIALIZED: 'CFG_WORKSPACE_NOT_INITIALIZED',
+    CFG_WORKSPACE_DRIFT: 'CFG_WORKSPACE_DRIFT',
+    // Runtime errors
+    RUN_COMMAND_FAILED: 'RUN_COMMAND_FAILED',
+    RUN_PARSE_ERROR: 'RUN_PARSE_ERROR',
+    RUN_TIMEOUT: 'RUN_TIMEOUT',
+    // Filesystem errors
+    FS_FILE_NOT_FOUND: 'FS_FILE_NOT_FOUND',
+    FS_PERMISSION_DENIED: 'FS_PERMISSION_DENIED',
+    FS_WORKING_DIR_INVALID: 'FS_WORKING_DIR_INVALID',
+};
+export const ErrorRemediation = {
+    DEP_NATIVE_MISSING: {
+        message: 'Native dependency cannot be loaded. Try: --wasm-fallback, npm rebuild, or install prebuilt binaries',
+        nextCommand: 'codemap --wasm-fallback',
+        confidence: 0.9,
+    },
+    DEP_WASM_FALLBACK_AVAILABLE: {
+        message: 'Native dependency unavailable but WASM fallback is available',
+        nextCommand: 'codemap --wasm-fallback',
+        confidence: 0.95,
+    },
+    DEP_MODULE_NOT_FOUND: {
+        message: 'Required module not found. Run npm install to install dependencies',
+        nextCommand: 'npm install',
+        confidence: 0.85,
+    },
+    DEP_REBUILD_REQUIRED: {
+        message: 'Native modules need rebuilding. Run npm rebuild',
+        nextCommand: 'npm rebuild',
+        confidence: 0.85,
+    },
+    CFG_INVALID_CONFIG: {
+        message: 'Configuration file is invalid. Check .mycodemap/config.json syntax',
+        confidence: 0.7,
+    },
+    CFG_WORKSPACE_NOT_INITIALIZED: {
+        message: 'Workspace not initialized. Run codemap init first',
+        nextCommand: 'codemap init',
+        confidence: 0.9,
+    },
+    CFG_WORKSPACE_DRIFT: {
+        message: 'Workspace has drifted from receipt state. Run codemap doctor for details',
+        nextCommand: 'codemap doctor',
+        confidence: 0.8,
+    },
+    RUN_COMMAND_FAILED: {
+        message: 'Command execution failed. Check the error details above',
+        confidence: 0.3,
+    },
+    RUN_PARSE_ERROR: {
+        message: 'Parse error in source file. Verify the file syntax',
+        confidence: 0.5,
+    },
+    RUN_TIMEOUT: {
+        message: 'Operation timed out. Try with a smaller scope or increase timeout',
+        confidence: 0.6,
+    },
+    FS_FILE_NOT_FOUND: {
+        message: 'Required file not found. Verify the path is correct',
+        confidence: 0.7,
+    },
+    FS_PERMISSION_DENIED: {
+        message: 'Permission denied. Check file/directory permissions',
+        confidence: 0.6,
+    },
+    FS_WORKING_DIR_INVALID: {
+        message: 'Working directory is invalid or does not exist',
+        confidence: 0.8,
+    },
+};
+//# sourceMappingURL=error-codes.js.map

package/dist/cli/output/error-codes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-codes.js","sourceRoot":"","sources":["../../../src/cli/output/error-codes.ts"],"names":[],"mappings":"AAAA,0DAA0D;AAC1D,qFAAqF;AAErF,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,oBAAoB;IACpB,kBAAkB,EAAE,oBAAoB;IACxC,2BAA2B,EAAE,6BAA6B;IAC1D,oBAAoB,EAAE,sBAAsB;IAC5C,oBAAoB,EAAE,sBAAsB;IAE5C,uBAAuB;IACvB,kBAAkB,EAAE,oBAAoB;IACxC,6BAA6B,EAAE,+BAA+B;IAC9D,mBAAmB,EAAE,qBAAqB;IAE1C,iBAAiB;IACjB,kBAAkB,EAAE,oBAAoB;IACxC,eAAe,EAAE,iBAAiB;IAClC,WAAW,EAAE,aAAa;IAE1B,oBAAoB;IACpB,iBAAiB,EAAE,mBAAmB;IACtC,oBAAoB,EAAE,sBAAsB;IAC5C,sBAAsB,EAAE,wBAAwB;CACxC,CAAC;AAIX,MAAM,CAAC,MAAM,gBAAgB,GAGzB;IACF,kBAAkB,EAAE;QAClB,OAAO,EACL,qGAAqG;QACvG,WAAW,EAAE,yBAAyB;QACtC,UAAU,EAAE,GAAG;KAChB;IACD,2BAA2B,EAAE;QAC3B,OAAO,EAAE,8DAA8D;QACvE,WAAW,EAAE,yBAAyB;QACtC,UAAU,EAAE,IAAI;KACjB;IACD,oBAAoB,EAAE;QACpB,OAAO,EACL,oEAAoE;QACtE,WAAW,EAAE,aAAa;QAC1B,UAAU,EAAE,IAAI;KACjB;IACD,oBAAoB,EAAE;QACpB,OAAO,EAAE,iDAAiD;QAC1D,WAAW,EAAE,aAAa;QAC1B,UAAU,EAAE,IAAI;KACjB;IACD,kBAAkB,EAAE;QAClB,OAAO,EACL,oEAAoE;QACtE,UAAU,EAAE,GAAG;KAChB;IACD,6BAA6B,EAAE;QAC7B,OAAO,EAAE,mDAAmD;QAC5D,WAAW,EAAE,cAAc;QAC3B,UAAU,EAAE,GAAG;KAChB;IACD,mBAAmB,EAAE;QACnB,OAAO,EACL,0EAA0E;QAC5E,WAAW,EAAE,gBAAgB;QAC7B,UAAU,EAAE,GAAG;KAChB;IACD,kBAAkB,EAAE;QAClB,OAAO,EAAE,yDAAyD;QAClE,UAAU,EAAE,GAAG;KAChB;IACD,eAAe,EAAE;QACf,OAAO,EAAE,oDAAoD;QAC7D,UAAU,EAAE,GAAG;KAChB;IACD,WAAW,EAAE;QACX,OAAO,EACL,mEAAmE;QACrE,UAAU,EAAE,GAAG;KAChB;IACD,iBAAiB,EAAE;QACjB,OAAO,EAAE,qDAAqD;QAC9D,UAAU,EAAE,GAAG;KAChB;IACD,oBAAoB,EAAE;QACpB,OAAO,EAAE,qDAAqD;QAC9D,UAAU,EAAE,GAAG;KAChB;IACD,sBAAsB,EAAE;QACtB,OAAO,EAAE,gDAAgD;QACzD,UAAU,EAAE,GAAG;KAChB;CACF,CAAC"}