@j0hanz/code-assistant 0.9.0

package/dist/schemas/outputs.d.ts

@@ -0,0 +1,121 @@
+import { z } from 'zod';
+export declare const DefaultOutputSchema: z.ZodObject<{
+    ok: z.ZodBoolean;
+    result: z.ZodOptional<z.ZodUnknown>;
+    error: z.ZodOptional<z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+        retryable: z.ZodOptional<z.ZodBoolean>;
+        kind: z.ZodOptional<z.ZodEnum<{
+            validation: "validation";
+            budget: "budget";
+            upstream: "upstream";
+            timeout: "timeout";
+            cancelled: "cancelled";
+            busy: "busy";
+            internal: "internal";
+        }>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const PrImpactResultSchema: z.ZodObject<{
+    severity: z.ZodEnum<{
+        low: "low";
+        medium: "medium";
+        high: "high";
+        critical: "critical";
+    }>;
+    categories: z.ZodArray<z.ZodEnum<{
+        breaking_change: "breaking_change";
+        api_change: "api_change";
+        schema_change: "schema_change";
+        config_change: "config_change";
+        dependency_update: "dependency_update";
+        security_fix: "security_fix";
+        deprecation: "deprecation";
+        performance_change: "performance_change";
+        bug_fix: "bug_fix";
+        feature_addition: "feature_addition";
+    }>>;
+    summary: z.ZodString;
+    breakingChanges: z.ZodArray<z.ZodString>;
+    affectedAreas: z.ZodArray<z.ZodString>;
+    rollbackComplexity: z.ZodEnum<{
+        trivial: "trivial";
+        moderate: "moderate";
+        complex: "complex";
+        irreversible: "irreversible";
+    }>;
+}, z.core.$strict>;
+export declare const ReviewSummaryResultSchema: z.ZodObject<{
+    summary: z.ZodString;
+    overallRisk: z.ZodEnum<{
+        low: "low";
+        medium: "medium";
+        high: "high";
+    }>;
+    keyChanges: z.ZodArray<z.ZodString>;
+    recommendation: z.ZodString;
+    stats: z.ZodObject<{
+        filesChanged: z.ZodNumber;
+        linesAdded: z.ZodNumber;
+        linesRemoved: z.ZodNumber;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare const TestCaseSchema: z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodEnum<{
+        unit: "unit";
+        integration: "integration";
+        e2e: "e2e";
+        regression: "regression";
+        security: "security";
+        performance: "performance";
+    }>;
+    file: z.ZodString;
+    description: z.ZodString;
+    pseudoCode: z.ZodString;
+    priority: z.ZodEnum<{
+        must_have: "must_have";
+        should_have: "should_have";
+        nice_to_have: "nice_to_have";
+    }>;
+}, z.core.$strict>;
+export declare const TestPlanResultSchema: z.ZodObject<{
+    summary: z.ZodString;
+    testCases: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        type: z.ZodEnum<{
+            unit: "unit";
+            integration: "integration";
+            e2e: "e2e";
+            regression: "regression";
+            security: "security";
+            performance: "performance";
+        }>;
+        file: z.ZodString;
+        description: z.ZodString;
+        pseudoCode: z.ZodString;
+        priority: z.ZodEnum<{
+            must_have: "must_have";
+            should_have: "should_have";
+            nice_to_have: "nice_to_have";
+        }>;
+    }, z.core.$strict>>;
+    coverageSummary: z.ZodString;
+}, z.core.$strict>;
+export declare const AnalyzeComplexityResultSchema: z.ZodObject<{
+    timeComplexity: z.ZodString;
+    spaceComplexity: z.ZodString;
+    explanation: z.ZodString;
+    potentialBottlenecks: z.ZodArray<z.ZodString>;
+    isDegradation: z.ZodBoolean;
+}, z.core.$strict>;
+export declare const DetectApiBreakingResultSchema: z.ZodObject<{
+    hasBreakingChanges: z.ZodBoolean;
+    breakingChanges: z.ZodArray<z.ZodObject<{
+        element: z.ZodString;
+        natureOfChange: z.ZodString;
+        consumerImpact: z.ZodString;
+        suggestedMitigation: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;

package/dist/schemas/outputs.js

@@ -0,0 +1,162 @@
+import { z } from 'zod';
+const OUTPUT_LIMITS = {
+    reviewDiffResult: {
+        summary: { min: 1, max: 2_000 },
+        findingsMax: 50,
+        testsNeeded: { minItems: 0, maxItems: 20, itemMin: 1, itemMax: 300 },
+    },
+    complexity: {
+        timeComplexity: { min: 1, max: 200 },
+        spaceComplexity: { min: 1, max: 200 },
+        explanation: { min: 1, max: 2_000 },
+        bottleneck: { min: 1, max: 500, maxItems: 10 },
+    },
+    apiBreaking: {
+        element: { min: 1, max: 300 },
+        natureOfChange: { min: 1, max: 500 },
+        consumerImpact: { min: 1, max: 500 },
+        suggestedMitigation: { min: 1, max: 500 },
+        maxItems: 20,
+    },
+};
+const QUALITY_RISK_LEVELS = ['low', 'medium', 'high', 'critical'];
+const MERGE_RISK_LEVELS = ['low', 'medium', 'high'];
+const REVIEW_SUMMARY_LIMITS = OUTPUT_LIMITS.reviewDiffResult.summary;
+const ERROR_KINDS = [
+    'validation',
+    'budget',
+    'upstream',
+    'timeout',
+    'cancelled',
+    'busy',
+    'internal',
+];
+function createBoundedString(min, max, description) {
+    return z.string().min(min).max(max).describe(description);
+}
+function createBoundedStringArray(itemMin, itemMax, minItems, maxItems, description) {
+    return z
+        .array(z.string().min(itemMin).max(itemMax))
+        .min(minItems)
+        .max(maxItems)
+        .describe(description);
+}
+function createReviewSummarySchema(description) {
+    return z
+        .string()
+        .min(REVIEW_SUMMARY_LIMITS.min)
+        .max(REVIEW_SUMMARY_LIMITS.max)
+        .describe(description);
+}
+const mergeRiskSchema = z
+    .enum(MERGE_RISK_LEVELS)
+    .describe('High-level merge risk.');
+export const DefaultOutputSchema = z.strictObject({
+    ok: z.boolean().describe('Whether the tool completed successfully.'),
+    result: z.unknown().optional().describe('Successful result payload.'),
+    error: z
+        .strictObject({
+        code: z.string().describe('Stable error code for callers.'),
+        message: z.string().describe('Human readable error details.'),
+        retryable: z
+            .boolean()
+            .optional()
+            .describe('Whether the client should retry this request.'),
+        kind: z
+            .enum(ERROR_KINDS)
+            .optional()
+            .describe('Machine-readable error category.'),
+    })
+        .optional()
+        .describe('Error payload when ok is false.'),
+});
+export const PrImpactResultSchema = z.strictObject({
+    severity: z.enum(QUALITY_RISK_LEVELS).describe('Overall severity.'),
+    categories: z
+        .array(z.enum([
+        'breaking_change',
+        'api_change',
+        'schema_change',
+        'config_change',
+        'dependency_update',
+        'security_fix',
+        'deprecation',
+        'performance_change',
+        'bug_fix',
+        'feature_addition',
+    ]))
+        .min(0)
+        .max(10)
+        .describe('Impact categories.'),
+    summary: z.string().min(1).max(1000).describe('Concise summary.'),
+    breakingChanges: createBoundedStringArray(1, 500, 0, 10, 'Specific breaking changes.'),
+    affectedAreas: createBoundedStringArray(1, 200, 0, 20, 'Impacted subsystems/files.'),
+    rollbackComplexity: z
+        .enum(['trivial', 'moderate', 'complex', 'irreversible'])
+        .describe('Revert difficulty.'),
+});
+export const ReviewSummaryResultSchema = z.strictObject({
+    summary: createReviewSummarySchema('PR summary.'),
+    overallRisk: mergeRiskSchema,
+    keyChanges: createBoundedStringArray(1, 300, 1, 15, 'Key changes (significance desc).'),
+    recommendation: z.string().min(1).max(500).describe('Merge recommendation.'),
+    stats: z
+        .strictObject({
+        filesChanged: z.number().int().min(0).describe('Files changed.'),
+        linesAdded: z.number().int().min(0).describe('Lines added.'),
+        linesRemoved: z.number().int().min(0).describe('Lines removed.'),
+    })
+        .describe('Change statistics (computed from diff before Gemini call).'),
+});
+export const TestCaseSchema = z.strictObject({
+    name: z.string().min(1).max(200).describe('Test case name.'),
+    type: z
+        .enum([
+        'unit',
+        'integration',
+        'e2e',
+        'regression',
+        'security',
+        'performance',
+    ])
+        .describe('Test category.'),
+    file: z.string().min(1).max(500).describe('Test file path.'),
+    description: z.string().min(1).max(1000).describe('Verification goal.'),
+    pseudoCode: z.string().min(1).max(2000).describe('Pseudocode/starter.'),
+    priority: z
+        .enum(['must_have', 'should_have', 'nice_to_have'])
+        .describe('Priority.'),
+});
+export const TestPlanResultSchema = z.strictObject({
+    summary: z.string().min(1).max(1000).describe('Plan overview.'),
+    testCases: z
+        .array(TestCaseSchema)
+        .min(1)
+        .max(30)
+        .describe('Test cases (must_have first).'),
+    coverageSummary: z
+        .string()
+        .min(1)
+        .max(500)
+        .describe('Coverage gaps addressed.'),
+});
+export const AnalyzeComplexityResultSchema = z.strictObject({
+    timeComplexity: createBoundedString(OUTPUT_LIMITS.complexity.timeComplexity.min, OUTPUT_LIMITS.complexity.timeComplexity.max, 'Big-O time complexity (e.g. O(n log n)).'),
+    spaceComplexity: createBoundedString(OUTPUT_LIMITS.complexity.spaceComplexity.min, OUTPUT_LIMITS.complexity.spaceComplexity.max, 'Big-O space complexity (e.g. O(n)).'),
+    explanation: createBoundedString(OUTPUT_LIMITS.complexity.explanation.min, OUTPUT_LIMITS.complexity.explanation.max, 'Analysis explanation (loops, recursion).'),
+    potentialBottlenecks: createBoundedStringArray(OUTPUT_LIMITS.complexity.bottleneck.min, OUTPUT_LIMITS.complexity.bottleneck.max, 0, OUTPUT_LIMITS.complexity.bottleneck.maxItems, 'Potential bottlenecks.'),
+    isDegradation: z.boolean().describe('True if degradation vs original.'),
+});
+export const DetectApiBreakingResultSchema = z.strictObject({
+    hasBreakingChanges: z.boolean().describe('True if breaking.'),
+    breakingChanges: z
+        .array(z.strictObject({
+        element: createBoundedString(OUTPUT_LIMITS.apiBreaking.element.min, OUTPUT_LIMITS.apiBreaking.element.max, 'Changed element (signature/field/export).'),
+        natureOfChange: createBoundedString(OUTPUT_LIMITS.apiBreaking.natureOfChange.min, OUTPUT_LIMITS.apiBreaking.natureOfChange.max, 'Change details & breaking reason.'),
+        consumerImpact: createBoundedString(OUTPUT_LIMITS.apiBreaking.consumerImpact.min, OUTPUT_LIMITS.apiBreaking.consumerImpact.max, 'Consumer impact.'),
+        suggestedMitigation: createBoundedString(OUTPUT_LIMITS.apiBreaking.suggestedMitigation.min, OUTPUT_LIMITS.apiBreaking.suggestedMitigation.max, 'Mitigation strategy.'),
+    }))
+        .min(0)
+        .max(OUTPUT_LIMITS.apiBreaking.maxItems)
+        .describe('Breaking changes list.'),
+});

package/dist/server.d.ts

@@ -0,0 +1,6 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export interface ServerHandle {
+    server: McpServer;
+    shutdown: () => Promise<void>;
+}
+export declare function createServer(): ServerHandle;

package/dist/server.js

@@ -0,0 +1,88 @@
+import { readFileSync } from 'node:fs';
+import { findPackageJSON } from 'node:module';
+import { InMemoryTaskStore } from '@modelcontextprotocol/sdk/experimental/tasks/stores/in-memory.js';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { initDiffStore } from './lib/diff.js';
+import { getErrorMessage } from './lib/errors.js';
+import { registerAllPrompts } from './prompts/index.js';
+import { registerAllResources } from './resources/index.js';
+import { buildServerInstructions } from './resources/instructions.js';
+import { registerAllTools } from './tools/index.js';
+const SERVER_NAME = 'code-assistant';
+const UTF8_ENCODING = 'utf8';
+const PackageJsonSchema = z.object({
+    version: z.string().min(1),
+});
+const TASK_TOOL_CALL_CAPABILITY = {
+    tools: {
+        call: {},
+    },
+};
+const SERVER_CAPABILITIES = {
+    logging: {},
+    completions: {},
+    prompts: {},
+    resources: { subscribe: true },
+    tools: {},
+    tasks: {
+        list: {},
+        cancel: {},
+        requests: TASK_TOOL_CALL_CAPABILITY,
+    },
+};
+function readUtf8File(path) {
+    try {
+        return readFileSync(path, UTF8_ENCODING);
+    }
+    catch (error) {
+        throw new Error(`Unable to read ${path}: ${getErrorMessage(error)}`, {
+            cause: error,
+        });
+    }
+}
+function parsePackageVersion(packageJsonText, packageJsonPath) {
+    try {
+        const json = JSON.parse(packageJsonText);
+        return PackageJsonSchema.parse(json).version;
+    }
+    catch (error) {
+        throw new Error(`Invalid package.json at ${packageJsonPath}: ${getErrorMessage(error)}`, { cause: error });
+    }
+}
+function loadVersion() {
+    const packageJsonPath = findPackageJSON(import.meta.url);
+    if (!packageJsonPath) {
+        throw new Error(`Unable to locate package.json for ${SERVER_NAME}.`);
+    }
+    const packageJsonText = readUtf8File(packageJsonPath);
+    return parsePackageVersion(packageJsonText, packageJsonPath);
+}
+const SERVER_VERSION = loadVersion();
+const SERVER_INSTRUCTIONS = buildServerInstructions();
+function createMcpServer(taskStore) {
+    return new McpServer({
+        name: SERVER_NAME,
+        version: SERVER_VERSION,
+    }, {
+        instructions: SERVER_INSTRUCTIONS,
+        taskStore,
+        capabilities: SERVER_CAPABILITIES,
+    });
+}
+function registerServerCapabilities(server) {
+    initDiffStore(server);
+    registerAllTools(server);
+    registerAllResources(server, SERVER_INSTRUCTIONS);
+    registerAllPrompts(server, SERVER_INSTRUCTIONS);
+}
+export function createServer() {
+    const taskStore = new InMemoryTaskStore();
+    const server = createMcpServer(taskStore);
+    registerServerCapabilities(server);
+    const shutdown = async () => {
+        await server.close();
+        taskStore.cleanup();
+    };
+    return { server, shutdown };
+}

package/dist/tools/analyze-complexity.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerAnalyzeComplexityTool(server: McpServer): void;

package/dist/tools/analyze-complexity.js

@@ -0,0 +1,50 @@
+import { buildLanguageDiffPrompt } from '../lib/format.js';
+import { getDiffContextSnapshot } from '../lib/tools.js';
+import { buildStructuredToolExecutionOptions, registerStructuredToolTask, requireToolContract, } from '../lib/tools.js';
+import { AnalyzeComplexityInputSchema } from '../schemas/inputs.js';
+import { AnalyzeComplexityResultSchema } from '../schemas/outputs.js';
+const SYSTEM_INSTRUCTION = `
+<role>
+Algorithm Complexity Analyst.
+You are an expert in Big-O analysis and performance optimization.
+</role>
+
+<task>
+Analyze the time and space complexity of the code changes:
+- Compare new complexity vs. original implementation.
+- Detect performance degradation (regression).
+- Identify bottlenecks (nested loops, recursion, allocations).
+</task>
+
+<constraints>
+- Focus on the changed code paths.
+- Flag degradation only if complexity class worsens (e.g., O(n) -> O(n^2)).
+- Return valid JSON matching the schema.
+</constraints>
+`;
+const TOOL_CONTRACT = requireToolContract('analyze_time_space_complexity');
+export function registerAnalyzeComplexityTool(server) {
+    registerStructuredToolTask(server, {
+        name: 'analyze_time_space_complexity',
+        title: 'Analyze Time & Space Complexity',
+        description: 'Analyze Big-O complexity. Prerequisite: generate_diff. Auto-infer language.',
+        inputSchema: AnalyzeComplexityInputSchema,
+        fullInputSchema: AnalyzeComplexityInputSchema,
+        resultSchema: AnalyzeComplexityResultSchema,
+        errorCode: 'E_ANALYZE_COMPLEXITY',
+        ...buildStructuredToolExecutionOptions(TOOL_CONTRACT),
+        requiresDiff: true,
+        progressContext: (input) => input.language ?? 'auto-detect',
+        formatOutcome: (result) => result.isDegradation
+            ? 'Performance degradation detected'
+            : 'No degradation',
+        formatOutput: (result) => `Time=${result.timeComplexity}, Space=${result.spaceComplexity}. ${result.explanation}`,
+        buildPrompt: (input, ctx) => {
+            const { diff } = getDiffContextSnapshot(ctx);
+            return {
+                systemInstruction: SYSTEM_INSTRUCTION,
+                prompt: buildLanguageDiffPrompt(input.language, diff, 'Based on the diff above, analyze the Big-O time and space complexity.'),
+            };
+        },
+    });
+}

package/dist/tools/analyze-pr-impact.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerAnalyzePrImpactTool(server: McpServer): void;

package/dist/tools/analyze-pr-impact.js

@@ -0,0 +1,62 @@
+import { computeDiffStatsAndSummaryFromFiles } from '../lib/diff.js';
+import { formatLanguageSegment } from '../lib/format.js';
+import { getDiffContextSnapshot } from '../lib/tools.js';
+import { buildStructuredToolExecutionOptions, registerStructuredToolTask, requireToolContract, } from '../lib/tools.js';
+import { AnalyzePrImpactInputSchema } from '../schemas/inputs.js';
+import { PrImpactResultSchema } from '../schemas/outputs.js';
+const SYSTEM_INSTRUCTION = `
+<role>
+Technical Change Analyst.
+You are a strict, objective auditor of code changes.
+</role>
+
+<task>
+Analyze the unified diff to assess:
+- Severity (low/medium/high/critical)
+- Risk categories (security, stability, etc.)
+- Breaking changes (API, contract, schema)
+- Rollback complexity
+</task>
+
+<constraints>
+- Base analysis ONLY on the provided diff. No external inference.
+- Ignore formatting/style changes unless they affect logic.
+- Return valid JSON matching the schema.
+</constraints>
+`;
+const TOOL_CONTRACT = requireToolContract('analyze_pr_impact');
+export function registerAnalyzePrImpactTool(server) {
+    registerStructuredToolTask(server, {
+        name: 'analyze_pr_impact',
+        title: 'Analyze PR Impact',
+        description: 'Assess impact and risk from cached diff. Prerequisite: generate_diff. Auto-infer repo/language.',
+        inputSchema: AnalyzePrImpactInputSchema,
+        fullInputSchema: AnalyzePrImpactInputSchema,
+        resultSchema: PrImpactResultSchema,
+        errorCode: 'E_ANALYZE_IMPACT',
+        ...buildStructuredToolExecutionOptions(TOOL_CONTRACT),
+        requiresDiff: true,
+        progressContext: (input) => input.repository,
+        formatOutcome: (result) => `severity: ${result.severity}`,
+        formatOutput: (result) => `[${result.severity}] ${result.summary}`,
+        buildPrompt: (input, ctx) => {
+            const { diff, parsedFiles } = getDiffContextSnapshot(ctx);
+            const { stats, summary: fileSummary } = computeDiffStatsAndSummaryFromFiles(parsedFiles);
+            const languageSegment = formatLanguageSegment(input.language);
+            return {
+                systemInstruction: SYSTEM_INSTRUCTION,
+                prompt: `
+Repository: ${input.repository}${languageSegment}
+Change Stats: ${stats.files} files, +${stats.added} lines, -${stats.deleted} lines.
+Changed Files:
+${fileSummary}
+
+Diff:
+${diff}
+
+Based on the diff and change stats above, analyze the PR impact.
+`,
+            };
+        },
+    });
+}

package/dist/tools/detect-api-breaking.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerDetectApiBreakingTool(server: McpServer): void;

package/dist/tools/detect-api-breaking.js

@@ -0,0 +1,49 @@
+import { buildLanguageDiffPrompt } from '../lib/format.js';
+import { getDiffContextSnapshot } from '../lib/tools.js';
+import { buildStructuredToolExecutionOptions, registerStructuredToolTask, requireToolContract, } from '../lib/tools.js';
+import { DetectApiBreakingInputSchema } from '../schemas/inputs.js';
+import { DetectApiBreakingResultSchema } from '../schemas/outputs.js';
+const SYSTEM_INSTRUCTION = `
+<role>
+API Compatibility Analyst.
+You are a strict guardian of public interfaces and contracts.
+</role>
+
+<task>
+Detect breaking changes in public APIs, interfaces, or schemas:
+- Identify changes that require consumer code modification.
+- classify the nature, impact, and mitigation for each break.
+</task>
+
+<constraints>
+- Definition: Breaking change = backwards-incompatible modification.
+- Ignore internal/private APIs unless exported.
+- Return valid JSON matching the schema.
+</constraints>
+`;
+const TOOL_CONTRACT = requireToolContract('detect_api_breaking_changes');
+export function registerDetectApiBreakingTool(server) {
+    registerStructuredToolTask(server, {
+        name: 'detect_api_breaking_changes',
+        title: 'Detect API Breaking Changes',
+        description: 'Detect breaking API changes. Prerequisite: generate_diff. Auto-infer language.',
+        inputSchema: DetectApiBreakingInputSchema,
+        fullInputSchema: DetectApiBreakingInputSchema,
+        resultSchema: DetectApiBreakingResultSchema,
+        errorCode: 'E_DETECT_API_BREAKING',
+        ...buildStructuredToolExecutionOptions(TOOL_CONTRACT),
+        requiresDiff: true,
+        progressContext: (input) => input.language ?? 'auto-detect',
+        formatOutcome: (result) => `${result.breakingChanges.length} breaking change(s) found`,
+        formatOutput: (result) => result.hasBreakingChanges
+            ? `${result.breakingChanges.length} breaking changes found.`
+            : 'No breaking changes.',
+        buildPrompt: (input, ctx) => {
+            const { diff } = getDiffContextSnapshot(ctx);
+            return {
+                systemInstruction: SYSTEM_INSTRUCTION,
+                prompt: buildLanguageDiffPrompt(input.language, diff, 'Based on the diff above, detect any breaking API changes.'),
+            };
+        },
+    });
+}

package/dist/tools/generate-diff.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerGenerateDiffTool(server: McpServer): void;