windows-exe-decompiler-mcp-server 0.1.0

package/dist/tools/code-function-explain-apply.d.ts

@@ -0,0 +1,255 @@
+import { z } from 'zod';
+import type { ToolArgs, ToolDefinition, WorkerResult } from '../types.js';
+import type { WorkspaceManager } from '../workspace-manager.js';
+import type { DatabaseManager } from '../database.js';
+export declare const codeFunctionExplainApplyInputSchema: z.ZodObject<{
+    sample_id: z.ZodString;
+    explanations: z.ZodArray<z.ZodEffects<z.ZodObject<{
+        address_or_function: z.ZodOptional<z.ZodString>;
+        address: z.ZodOptional<z.ZodString>;
+        function: z.ZodOptional<z.ZodString>;
+        summary: z.ZodString;
+        behavior: z.ZodString;
+        confidence: z.ZodNumber;
+        assumptions: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
+        evidence_used: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
+        rewrite_guidance: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">]>>;
+    }, "strip", z.ZodTypeAny, {
+        summary: string;
+        confidence: number;
+        evidence_used: string[];
+        behavior: string;
+        assumptions: string[];
+        function?: string | undefined;
+        address?: string | undefined;
+        rewrite_guidance?: string | string[] | undefined;
+        address_or_function?: string | undefined;
+    }, {
+        summary: string;
+        confidence: number;
+        behavior: string;
+        function?: string | undefined;
+        address?: string | undefined;
+        evidence_used?: string[] | undefined;
+        assumptions?: string[] | undefined;
+        rewrite_guidance?: string | string[] | undefined;
+        address_or_function?: string | undefined;
+    }>, {
+        summary: string;
+        confidence: number;
+        evidence_used: string[];
+        behavior: string;
+        assumptions: string[];
+        function?: string | undefined;
+        address?: string | undefined;
+        rewrite_guidance?: string | string[] | undefined;
+        address_or_function?: string | undefined;
+    }, {
+        summary: string;
+        confidence: number;
+        behavior: string;
+        function?: string | undefined;
+        address?: string | undefined;
+        evidence_used?: string[] | undefined;
+        assumptions?: string[] | undefined;
+        rewrite_guidance?: string | string[] | undefined;
+        address_or_function?: string | undefined;
+    }>, "many">;
+    client_name: z.ZodOptional<z.ZodString>;
+    model_name: z.ZodOptional<z.ZodString>;
+    prepare_artifact_id: z.ZodOptional<z.ZodString>;
+    session_tag: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    sample_id: string;
+    explanations: {
+        summary: string;
+        confidence: number;
+        evidence_used: string[];
+        behavior: string;
+        assumptions: string[];
+        function?: string | undefined;
+        address?: string | undefined;
+        rewrite_guidance?: string | string[] | undefined;
+        address_or_function?: string | undefined;
+    }[];
+    session_tag?: string | undefined;
+    client_name?: string | undefined;
+    model_name?: string | undefined;
+    prepare_artifact_id?: string | undefined;
+}, {
+    sample_id: string;
+    explanations: {
+        summary: string;
+        confidence: number;
+        behavior: string;
+        function?: string | undefined;
+        address?: string | undefined;
+        evidence_used?: string[] | undefined;
+        assumptions?: string[] | undefined;
+        rewrite_guidance?: string | string[] | undefined;
+        address_or_function?: string | undefined;
+    }[];
+    session_tag?: string | undefined;
+    client_name?: string | undefined;
+    model_name?: string | undefined;
+    prepare_artifact_id?: string | undefined;
+}>;
+export declare const codeFunctionExplainApplyOutputSchema: z.ZodObject<{
+    ok: z.ZodBoolean;
+    data: z.ZodOptional<z.ZodObject<{
+        sample_id: z.ZodString;
+        accepted_count: z.ZodNumber;
+        rejected_count: z.ZodNumber;
+        accepted_explanations: z.ZodArray<z.ZodObject<{
+            address: z.ZodNullable<z.ZodString>;
+            function: z.ZodNullable<z.ZodString>;
+            behavior: z.ZodString;
+            confidence: z.ZodNumber;
+            rewrite_guidance_count: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            function: string | null;
+            address: string | null;
+            confidence: number;
+            behavior: string;
+            rewrite_guidance_count: number;
+        }, {
+            function: string | null;
+            address: string | null;
+            confidence: number;
+            behavior: string;
+            rewrite_guidance_count: number;
+        }>, "many">;
+        artifact: z.ZodObject<{
+            id: z.ZodString;
+            type: z.ZodLiteral<"semantic_function_explanations">;
+            path: z.ZodString;
+            sha256: z.ZodString;
+            mime: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            path: string;
+            type: "semantic_function_explanations";
+            id: string;
+            sha256: string;
+            mime?: string | undefined;
+        }, {
+            path: string;
+            type: "semantic_function_explanations";
+            id: string;
+            sha256: string;
+            mime?: string | undefined;
+        }>;
+        next_steps: z.ZodArray<z.ZodString, "many">;
+    }, "strip", z.ZodTypeAny, {
+        sample_id: string;
+        artifact: {
+            path: string;
+            type: "semantic_function_explanations";
+            id: string;
+            sha256: string;
+            mime?: string | undefined;
+        };
+        accepted_count: number;
+        rejected_count: number;
+        next_steps: string[];
+        accepted_explanations: {
+            function: string | null;
+            address: string | null;
+            confidence: number;
+            behavior: string;
+            rewrite_guidance_count: number;
+        }[];
+    }, {
+        sample_id: string;
+        artifact: {
+            path: string;
+            type: "semantic_function_explanations";
+            id: string;
+            sha256: string;
+            mime?: string | undefined;
+        };
+        accepted_count: number;
+        rejected_count: number;
+        next_steps: string[];
+        accepted_explanations: {
+            function: string | null;
+            address: string | null;
+            confidence: number;
+            behavior: string;
+            rewrite_guidance_count: number;
+        }[];
+    }>>;
+    warnings: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    errors: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    artifacts: z.ZodOptional<z.ZodArray<z.ZodAny, "many">>;
+    metrics: z.ZodOptional<z.ZodObject<{
+        elapsed_ms: z.ZodNumber;
+        tool: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        elapsed_ms: number;
+        tool: string;
+    }, {
+        elapsed_ms: number;
+        tool: string;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    ok: boolean;
+    metrics?: {
+        elapsed_ms: number;
+        tool: string;
+    } | undefined;
+    data?: {
+        sample_id: string;
+        artifact: {
+            path: string;
+            type: "semantic_function_explanations";
+            id: string;
+            sha256: string;
+            mime?: string | undefined;
+        };
+        accepted_count: number;
+        rejected_count: number;
+        next_steps: string[];
+        accepted_explanations: {
+            function: string | null;
+            address: string | null;
+            confidence: number;
+            behavior: string;
+            rewrite_guidance_count: number;
+        }[];
+    } | undefined;
+    warnings?: string[] | undefined;
+    errors?: string[] | undefined;
+    artifacts?: any[] | undefined;
+}, {
+    ok: boolean;
+    metrics?: {
+        elapsed_ms: number;
+        tool: string;
+    } | undefined;
+    data?: {
+        sample_id: string;
+        artifact: {
+            path: string;
+            type: "semantic_function_explanations";
+            id: string;
+            sha256: string;
+            mime?: string | undefined;
+        };
+        accepted_count: number;
+        rejected_count: number;
+        next_steps: string[];
+        accepted_explanations: {
+            function: string | null;
+            address: string | null;
+            confidence: number;
+            behavior: string;
+            rewrite_guidance_count: number;
+        }[];
+    } | undefined;
+    warnings?: string[] | undefined;
+    errors?: string[] | undefined;
+    artifacts?: any[] | undefined;
+}>;
+export declare const codeFunctionExplainApplyToolDefinition: ToolDefinition;
+export declare function createCodeFunctionExplainApplyHandler(workspaceManager: WorkspaceManager, database: DatabaseManager): (args: ToolArgs) => Promise<WorkerResult>;
+//# sourceMappingURL=code-function-explain-apply.d.ts.map

package/dist/tools/code-function-explain-apply.js

@@ -0,0 +1,225 @@
+import { z } from 'zod';
+import { persistSemanticFunctionExplanationsArtifact, SEMANTIC_FUNCTION_EXPLANATIONS_ARTIFACT_TYPE, } from '../semantic-name-suggestion-artifacts.js';
+const TOOL_NAME = 'code.function.explain.apply';
+const ExplanationSuggestionInputSchema = z
+    .object({
+    address_or_function: z
+        .string()
+        .optional()
+        .describe('Optional combined identifier when the reviewing client returns a single address_or_function field'),
+    address: z.string().optional().describe('Optional function address for precise matching'),
+    function: z.string().optional().describe('Optional function symbol/name for fallback matching'),
+    summary: z.string().min(1).max(1200).describe('Evidence-grounded plain-language explanation of the function'),
+    behavior: z.string().min(1).max(160).describe('Short behavior label, such as resolve_dynamic_imports or dispatch_exported_command'),
+    confidence: z.number().min(0).max(1).describe('Heuristic support score for the explanation'),
+    assumptions: z.array(z.string()).optional().default([]).describe('Assumptions that must hold for the explanation to remain valid'),
+    evidence_used: z.array(z.string()).optional().default([]).describe('Evidence sources used by the external LLM'),
+    rewrite_guidance: z
+        .union([z.string().min(1), z.array(z.string().min(1))])
+        .optional()
+        .describe('One or more rewrite-oriented guidance items derived from the evidence'),
+})
+    .refine((value) => Boolean(value.address_or_function?.trim()) ||
+    Boolean(value.address?.trim()) ||
+    Boolean(value.function?.trim()), {
+    message: 'Each explanation must provide at least one of `address_or_function`, `address`, or `function`.',
+});
+function normalizeExplanationIdentifier(explanation) {
+    const normalizedAddress = explanation.address?.trim() || null;
+    const normalizedFunction = explanation.function?.trim() || null;
+    if (normalizedAddress || normalizedFunction) {
+        return {
+            address: normalizedAddress,
+            function: normalizedFunction,
+        };
+    }
+    const identifier = explanation.address_or_function?.trim();
+    if (!identifier) {
+        return {
+            address: null,
+            function: null,
+        };
+    }
+    if (/^(0x)?[0-9a-f]+$/i.test(identifier)) {
+        return {
+            address: identifier,
+            function: null,
+        };
+    }
+    return {
+        address: null,
+        function: identifier,
+    };
+}
+function normalizeRewriteGuidance(input) {
+    if (!input) {
+        return [];
+    }
+    const values = Array.isArray(input) ? input : [input];
+    return values.map((item) => item.trim()).filter((item) => item.length > 0).slice(0, 8);
+}
+export const codeFunctionExplainApplyInputSchema = z.object({
+    sample_id: z.string().describe('Sample ID (format: sha256:<hex>)'),
+    explanations: z
+        .array(ExplanationSuggestionInputSchema)
+        .min(1)
+        .describe('Structured explanation outputs returned by an external MCP client / LLM'),
+    client_name: z
+        .string()
+        .optional()
+        .describe('Optional client identifier, such as claude-desktop or codex-cli'),
+    model_name: z
+        .string()
+        .optional()
+        .describe('Optional model identifier for provenance only'),
+    prepare_artifact_id: z
+        .string()
+        .optional()
+        .describe('Optional semantic_explanation_prepare_bundle artifact ID that produced this review task'),
+    session_tag: z
+        .string()
+        .optional()
+        .describe('Optional semantic explanation session tag used for artifact grouping'),
+});
+export const codeFunctionExplainApplyOutputSchema = z.object({
+    ok: z.boolean(),
+    data: z
+        .object({
+        sample_id: z.string(),
+        accepted_count: z.number().int().nonnegative(),
+        rejected_count: z.number().int().nonnegative(),
+        accepted_explanations: z.array(z.object({
+            address: z.string().nullable(),
+            function: z.string().nullable(),
+            behavior: z.string(),
+            confidence: z.number().min(0).max(1),
+            rewrite_guidance_count: z.number().int().nonnegative(),
+        })),
+        artifact: z.object({
+            id: z.string(),
+            type: z.literal(SEMANTIC_FUNCTION_EXPLANATIONS_ARTIFACT_TYPE),
+            path: z.string(),
+            sha256: z.string(),
+            mime: z.string().optional(),
+        }),
+        next_steps: z.array(z.string()),
+    })
+        .optional(),
+    warnings: z.array(z.string()).optional(),
+    errors: z.array(z.string()).optional(),
+    artifacts: z.array(z.any()).optional(),
+    metrics: z
+        .object({
+        elapsed_ms: z.number(),
+        tool: z.string(),
+    })
+        .optional(),
+});
+export const codeFunctionExplainApplyToolDefinition = {
+    name: TOOL_NAME,
+    description: 'Persist structured function explanations returned by any external MCP client / LLM so export and report layers can consume them.',
+    inputSchema: codeFunctionExplainApplyInputSchema,
+    outputSchema: codeFunctionExplainApplyOutputSchema,
+};
+export function createCodeFunctionExplainApplyHandler(workspaceManager, database) {
+    return async (args) => {
+        const startTime = Date.now();
+        try {
+            const input = codeFunctionExplainApplyInputSchema.parse(args);
+            const sample = database.findSample(input.sample_id);
+            if (!sample) {
+                return {
+                    ok: false,
+                    errors: [`Sample not found: ${input.sample_id}`],
+                    metrics: {
+                        elapsed_ms: Date.now() - startTime,
+                        tool: TOOL_NAME,
+                    },
+                };
+            }
+            const acceptedExplanations = [];
+            const acceptedSummary = [];
+            const warnings = [];
+            for (const explanation of input.explanations) {
+                const normalizedIdentifier = normalizeExplanationIdentifier(explanation);
+                const rewriteGuidance = normalizeRewriteGuidance(explanation.rewrite_guidance);
+                const summary = explanation.summary.trim();
+                const behavior = explanation.behavior.trim();
+                if (summary.length === 0 || behavior.length === 0) {
+                    warnings.push(`Rejected explanation for ${normalizedIdentifier.address || normalizedIdentifier.function || explanation.address_or_function || 'unknown'} because summary or behavior was empty after normalization.`);
+                    continue;
+                }
+                acceptedExplanations.push({
+                    address: normalizedIdentifier.address,
+                    function: normalizedIdentifier.function,
+                    summary,
+                    behavior,
+                    confidence: explanation.confidence,
+                    assumptions: explanation.assumptions || [],
+                    evidence_used: explanation.evidence_used || [],
+                    rewrite_guidance: rewriteGuidance,
+                });
+                acceptedSummary.push({
+                    address: normalizedIdentifier.address,
+                    function: normalizedIdentifier.function,
+                    behavior,
+                    confidence: explanation.confidence,
+                    rewrite_guidance_count: rewriteGuidance.length,
+                });
+            }
+            if (acceptedExplanations.length === 0) {
+                return {
+                    ok: false,
+                    errors: ['No explanations were accepted after normalization.'],
+                    warnings: warnings.length > 0 ? warnings : undefined,
+                    metrics: {
+                        elapsed_ms: Date.now() - startTime,
+                        tool: TOOL_NAME,
+                    },
+                };
+            }
+            const payload = {
+                schema_version: 1,
+                sample_id: input.sample_id,
+                created_at: new Date().toISOString(),
+                session_tag: input.session_tag || null,
+                client_name: input.client_name || null,
+                model_name: input.model_name || null,
+                prepare_artifact_id: input.prepare_artifact_id || null,
+                explanations: acceptedExplanations,
+            };
+            const artifact = await persistSemanticFunctionExplanationsArtifact(workspaceManager, database, payload);
+            return {
+                ok: true,
+                data: {
+                    sample_id: input.sample_id,
+                    accepted_count: acceptedExplanations.length,
+                    rejected_count: input.explanations.length - acceptedExplanations.length,
+                    accepted_explanations: acceptedSummary,
+                    artifact,
+                    next_steps: [
+                        'rerun code.reconstruct.export to propagate explanation summaries and rewrite guidance into rewrite output',
+                        'rerun report.generate or report.summarize if you want explanation artifacts reflected in higher-level analyst output',
+                    ],
+                },
+                warnings: warnings.length > 0 ? warnings : undefined,
+                artifacts: [artifact],
+                metrics: {
+                    elapsed_ms: Date.now() - startTime,
+                    tool: TOOL_NAME,
+                },
+            };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                errors: [error instanceof Error ? error.message : String(error)],
+                metrics: {
+                    elapsed_ms: Date.now() - startTime,
+                    tool: TOOL_NAME,
+                },
+            };
+        }
+    };
+}
+//# sourceMappingURL=code-function-explain-apply.js.map