@syrin/cli 1.3.0

package/dist/runtime/analysis/rules/warnings/w108-hidden-side-effects.js

@@ -0,0 +1,94 @@
+/**
+ * W108: Hidden Side Effects
+ *
+ * Condition:
+ * - Tool name/description suggests mutation
+ * - But schema does not reflect it
+ *
+ * Why:
+ * - Execution surprises
+ * - Hard to reason
+ */
+import { BaseRule } from '../base.js';
+/**
+ * Mutation verbs used to detect side effects.
+ */
+const mutationVerbs = [
+    'create',
+    'delete',
+    'remove',
+    'update',
+    'modify',
+    'change',
+    'set',
+    'save',
+    'write',
+    'add',
+    'insert',
+    'destroy',
+    'drop',
+    'clear',
+    'reset',
+];
+/**
+ * Compiled regex for mutation verb detection (compiled once at module load).
+ */
+const MUTATION_REGEX = new RegExp(mutationVerbs.map(verb => `\\b${verb}\\b`).join('|'), 'i');
+/**
+ * Check if a tool name/description suggests mutation.
+ */
+function suggestsMutation(toolName, description) {
+    const combined = `${toolName} ${description}`.toLowerCase();
+    return MUTATION_REGEX.test(combined);
+}
+/**
+ * Check if schema reflects mutation (has outputs that suggest state change).
+ */
+function schemaReflectsMutation(tool) {
+    // If no outputs, treat as void mutation (e.g., DELETE operations, ack-only operations).
+    // This intentionally returns true to avoid false positives for tools that perform
+    // side effects without returning data (such operations may mutate state but only
+    // return success/acknowledgment implicitly).
+    if (tool.outputs.length === 0) {
+        return true;
+    }
+    // Check if outputs suggest mutation confirmation
+    const mutationOutputs = [
+        'success',
+        'id',
+        'result',
+        'status',
+        'created',
+        'updated',
+        'deleted',
+    ];
+    for (const output of tool.outputs) {
+        const name = output.name.toLowerCase();
+        const desc = (output.description || '').toLowerCase();
+        if (mutationOutputs.some(mo => name.includes(mo) || desc.includes(mo))) {
+            return true;
+        }
+    }
+    return false;
+}
+class W108HiddenSideEffectsRule extends BaseRule {
+    id = 'W108';
+    severity = 'warning';
+    ruleName = 'Hidden Side Effects';
+    description = 'Tool appears to have side effects not reflected in schema. Execution surprises.';
+    check(ctx) {
+        const diagnostics = [];
+        for (const tool of ctx.tools) {
+            const description = tool.description || '';
+            const suggestsMut = suggestsMutation(tool.name, description);
+            const reflectsMut = schemaReflectsMutation(tool);
+            // If it suggests mutation but schema doesn't reflect it
+            if (suggestsMut && !reflectsMut) {
+                diagnostics.push(this.createDiagnostic(`Tool "${tool.name}" appears to have side effects not reflected in schema.`, tool.name, undefined, `Update the output schema of "${tool.name}" to reflect state changes (e.g., add success status, created ID, etc.).`));
+            }
+        }
+        return diagnostics;
+    }
+}
+export const W108HiddenSideEffects = new W108HiddenSideEffectsRule();
+//# sourceMappingURL=w108-hidden-side-effects.js.map

package/dist/runtime/analysis/rules/warnings/w109-output-not-reusable.d.ts

@@ -0,0 +1,22 @@
+/**
+ * W109: Tool Output Not Reusable
+ *
+ * Condition:
+ * - Output tailored only for natural language
+ * - Not structured for reuse
+ *
+ * Why:
+ * - Limits composability
+ */
+import { BaseRule } from '../base.js';
+import type { AnalysisContext, Diagnostic } from '../../types.js';
+declare class W109OutputNotReusableRule extends BaseRule {
+    readonly id = "W109";
+    readonly severity: "warning";
+    readonly ruleName = "Tool Output Not Reusable";
+    readonly description = "Output of tool is not designed for reuse. Limits composability.";
+    check(ctx: AnalysisContext): Diagnostic[];
+}
+export declare const W109OutputNotReusable: W109OutputNotReusableRule;
+export {};
+//# sourceMappingURL=w109-output-not-reusable.d.ts.map

package/dist/runtime/analysis/rules/warnings/w109-output-not-reusable.js

@@ -0,0 +1,63 @@
+/**
+ * W109: Tool Output Not Reusable
+ *
+ * Condition:
+ * - Output tailored only for natural language
+ * - Not structured for reuse
+ *
+ * Why:
+ * - Limits composability
+ */
+import { BaseRule } from '../base.js';
+/**
+ * Check if output appears to be only for natural language display.
+ */
+function isNaturalLanguageOnly(output) {
+    const name = output.name.toLowerCase();
+    const desc = (output.description || '').toLowerCase();
+    const combined = `${name} ${desc}`;
+    // Indicators that output is only for display
+    const displayOnlyIndicators = [
+        'message',
+        'response',
+        'reply',
+        'answer',
+        'text',
+        'description',
+        'summary',
+        'note',
+        'comment',
+        'info',
+    ];
+    // If it's a string type and name suggests display-only
+    if (output.type === 'string') {
+        return displayOnlyIndicators.some(indicator => combined.includes(indicator));
+    }
+    return false;
+}
+class W109OutputNotReusableRule extends BaseRule {
+    id = 'W109';
+    severity = 'warning';
+    ruleName = 'Tool Output Not Reusable';
+    description = 'Output of tool is not designed for reuse. Limits composability.';
+    check(ctx) {
+        const diagnostics = [];
+        for (const tool of ctx.tools) {
+            // Only check tools that have outputs
+            if (tool.outputs.length === 0) {
+                continue;
+            }
+            // Check if all outputs are natural language only
+            // Note: isNaturalLanguageOnly and isStructured are mutually exclusive,
+            // so if allNaturalLanguage is true, hasStructured must be false
+            const allNaturalLanguage = tool.outputs.every(output => isNaturalLanguageOnly(output));
+            // If all outputs are natural language only (implies none are structured)
+            if (allNaturalLanguage) {
+                diagnostics.push(this.createDiagnostic(`Output of "${tool.name}" is not designed for reuse (only natural language output).`, tool.name, undefined, `Add structured output fields (objects/arrays) to "${tool.name}" to improve composability with other tools.`));
+            }
+        }
+        return diagnostics;
+    }
+}
+export const W109OutputNotReusable = new W109OutputNotReusableRule();
+//# sourceMappingURL=w109-output-not-reusable.js.map

package/dist/runtime/analysis/rules/warnings/w110-weak-schema.d.ts

@@ -0,0 +1,40 @@
+/**
+ * W110: Weak Schema
+ *
+ * Condition: Contract schema is too loose or doesn't match MCP tool schema structure
+ *
+ * Why this is a warning:
+ * - Loose schemas make validation less effective
+ * - Mismatch between contract and actual tool schema indicates contract needs update
+ */
+import { BaseRule } from '../base.js';
+import type { AnalysisContext, Diagnostic } from '../../types.js';
+/**
+ * Context for weak schema detection.
+ */
+export interface WeakSchemaContext {
+    /** Tool name */
+    toolName: string;
+    /** Contract input schema name */
+    contractInputSchema: string;
+    /** Contract output schema name */
+    contractOutputSchema: string;
+    /** Whether schemas match actual MCP tool schemas */
+    schemasMatch: boolean;
+    /** Details about mismatch (if any) */
+    mismatchDetails?: string;
+}
+declare class W110WeakSchemaRule extends BaseRule {
+    readonly id = "W110";
+    readonly severity: "warning";
+    readonly ruleName = "Weak Schema";
+    readonly description = "Contract schema is too loose or does not match MCP tool schema structure.";
+    check(_ctx: AnalysisContext): Diagnostic[];
+    /**
+     * Check with behavioral context (called from test orchestrator).
+     */
+    checkWithBehavioralContext(behavioralCtx: WeakSchemaContext): Diagnostic[];
+}
+export declare const W110WeakSchema: W110WeakSchemaRule;
+export {};
+//# sourceMappingURL=w110-weak-schema.d.ts.map

package/dist/runtime/analysis/rules/warnings/w110-weak-schema.js

@@ -0,0 +1,32 @@
+/**
+ * W110: Weak Schema
+ *
+ * Condition: Contract schema is too loose or doesn't match MCP tool schema structure
+ *
+ * Why this is a warning:
+ * - Loose schemas make validation less effective
+ * - Mismatch between contract and actual tool schema indicates contract needs update
+ */
+import { BaseRule } from '../base.js';
+class W110WeakSchemaRule extends BaseRule {
+    id = 'W110';
+    severity = 'warning';
+    ruleName = 'Weak Schema';
+    description = 'Contract schema is too loose or does not match MCP tool schema structure.';
+    check(_ctx) {
+        // This rule requires behavioral context (schema comparison)
+        return [];
+    }
+    /**
+     * Check with behavioral context (called from test orchestrator).
+     */
+    checkWithBehavioralContext(behavioralCtx) {
+        const diagnostics = [];
+        if (!behavioralCtx.schemasMatch) {
+            diagnostics.push(this.createDiagnostic(`Tool "${behavioralCtx.toolName}" contract schemas do not match actual MCP tool schemas.${behavioralCtx.mismatchDetails ? ` ${behavioralCtx.mismatchDetails}` : ''}`, behavioralCtx.toolName, undefined, 'Update contract to match actual tool schema structure. Ensure input_schema and output_schema names reference correct schemas.'));
+        }
+        return diagnostics;
+    }
+}
+export const W110WeakSchema = new W110WeakSchemaRule();
+//# sourceMappingURL=w110-weak-schema.js.map

package/dist/runtime/analysis/rules/warnings/w300-high-entropy-output.d.ts

@@ -0,0 +1,39 @@
+/**
+ * W300: High Entropy Output
+ *
+ * Condition: Tool output has high entropy (random, unpredictable structure)
+ *
+ * Why this is a warning:
+ * - High entropy makes it hard for LLM to reason about output
+ * - Indicates potential design issues
+ * - May indicate non-determinism
+ */
+import { BaseRule } from '../base.js';
+import type { AnalysisContext, Diagnostic } from '../../types.js';
+/**
+ * Context for high entropy detection.
+ */
+export interface HighEntropyContext {
+    /** Tool name */
+    toolName: string;
+    /** Entropy score (0-1, higher = more entropy) */
+    entropyScore: number;
+    /** Reason for high entropy */
+    reason?: string;
+    /** Optional custom entropy threshold (defaults to 0.7 if not provided) */
+    entropyThreshold?: number;
+}
+declare class W300HighEntropyOutputRule extends BaseRule {
+    readonly id = "W300";
+    readonly severity: "warning";
+    readonly ruleName = "High Entropy Output";
+    readonly description = "Tool output has high entropy, making it difficult for LLM to reason about.";
+    check(_ctx: AnalysisContext): Diagnostic[];
+    /**
+     * Check with behavioral context (called from test orchestrator).
+     */
+    checkWithBehavioralContext(behavioralCtx: HighEntropyContext): Diagnostic[];
+}
+export declare const W300HighEntropyOutput: W300HighEntropyOutputRule;
+export {};
+//# sourceMappingURL=w300-high-entropy-output.d.ts.map

package/dist/runtime/analysis/rules/warnings/w300-high-entropy-output.js

@@ -0,0 +1,47 @@
+/**
+ * W300: High Entropy Output
+ *
+ * Condition: Tool output has high entropy (random, unpredictable structure)
+ *
+ * Why this is a warning:
+ * - High entropy makes it hard for LLM to reason about output
+ * - Indicates potential design issues
+ * - May indicate non-determinism
+ */
+import { BaseRule } from '../base.js';
+class W300HighEntropyOutputRule extends BaseRule {
+    id = 'W300';
+    severity = 'warning';
+    ruleName = 'High Entropy Output';
+    description = 'Tool output has high entropy, making it difficult for LLM to reason about.';
+    check(_ctx) {
+        // This rule requires behavioral context
+        return [];
+    }
+    /**
+     * Check with behavioral context (called from test orchestrator).
+     */
+    checkWithBehavioralContext(behavioralCtx) {
+        const diagnostics = [];
+        // Validate and clamp entropyScore to [0, 1]
+        const entropyScore = Math.max(0, Math.min(1, behavioralCtx.entropyScore));
+        if (entropyScore !== behavioralCtx.entropyScore) {
+            // Out of range - could log warning or error in production
+            // For now, we silently clamp to valid range
+        }
+        // Validate and clamp entropyThreshold to [0, 1], default to 0.7
+        let threshold = behavioralCtx.entropyThreshold ?? 0.7;
+        if (threshold < 0 || threshold > 1 || !Number.isFinite(threshold)) {
+            // Invalid threshold - use default
+            threshold = 0.7;
+        }
+        threshold = Math.max(0, Math.min(1, threshold));
+        // Threshold: entropy above configured value is considered high
+        if (entropyScore > threshold) {
+            diagnostics.push(this.createDiagnostic(`Tool "${behavioralCtx.toolName}" produces high entropy output (score: ${entropyScore.toFixed(2)}, threshold: ${threshold.toFixed(2)}).${behavioralCtx.reason ? ` ${behavioralCtx.reason}` : ''}`, behavioralCtx.toolName, undefined, 'Consider normalizing output structure, reducing randomness, or providing more predictable output format.'));
+        }
+        return diagnostics;
+    }
+}
+export const W300HighEntropyOutput = new W300HighEntropyOutputRule();
+//# sourceMappingURL=w300-high-entropy-output.js.map

package/dist/runtime/analysis/rules/warnings/w301-unstable-defaults.d.ts

@@ -0,0 +1,38 @@
+/**
+ * W301: Unstable Defaults
+ *
+ * Condition: Tool behavior changes significantly with default values
+ *
+ * Why this is a warning:
+ * - Defaults should be stable and predictable
+ * - Changing defaults breaks agent expectations
+ * - Indicates design inconsistency
+ */
+import { BaseRule } from '../base.js';
+import type { AnalysisContext, Diagnostic } from '../../types.js';
+/**
+ * Context for unstable defaults detection.
+ */
+export interface UnstableDefaultsContext {
+    /** Tool name */
+    toolName: string;
+    /** Fields with unstable defaults */
+    unstableFields: Array<{
+        fieldName: string;
+        reason: string;
+    }>;
+}
+declare class W301UnstableDefaultsRule extends BaseRule {
+    readonly id = "W301";
+    readonly severity: "warning";
+    readonly ruleName = "Unstable Defaults";
+    readonly description = "Tool behavior changes significantly with default values, breaking agent expectations.";
+    check(_ctx: AnalysisContext): Diagnostic[];
+    /**
+     * Check with behavioral context (called from test orchestrator).
+     */
+    checkWithBehavioralContext(behavioralCtx: UnstableDefaultsContext): Diagnostic[];
+}
+export declare const W301UnstableDefaults: W301UnstableDefaultsRule;
+export {};
+//# sourceMappingURL=w301-unstable-defaults.d.ts.map

package/dist/runtime/analysis/rules/warnings/w301-unstable-defaults.js

@@ -0,0 +1,36 @@
+/**
+ * W301: Unstable Defaults
+ *
+ * Condition: Tool behavior changes significantly with default values
+ *
+ * Why this is a warning:
+ * - Defaults should be stable and predictable
+ * - Changing defaults breaks agent expectations
+ * - Indicates design inconsistency
+ */
+import { BaseRule } from '../base.js';
+class W301UnstableDefaultsRule extends BaseRule {
+    id = 'W301';
+    severity = 'warning';
+    ruleName = 'Unstable Defaults';
+    description = 'Tool behavior changes significantly with default values, breaking agent expectations.';
+    check(_ctx) {
+        // This rule requires behavioral context
+        return [];
+    }
+    /**
+     * Check with behavioral context (called from test orchestrator).
+     */
+    checkWithBehavioralContext(behavioralCtx) {
+        const diagnostics = [];
+        if (behavioralCtx.unstableFields.length > 0) {
+            const fieldList = behavioralCtx.unstableFields
+                .map(f => `  - ${f.fieldName}: ${f.reason}`)
+                .join('\n');
+            diagnostics.push(this.createDiagnostic(`Tool "${behavioralCtx.toolName}" has unstable default values:\n${fieldList}`, behavioralCtx.toolName, undefined, 'Ensure default values are stable and predictable. Avoid defaults that change behavior significantly.'));
+        }
+        return diagnostics;
+    }
+}
+export const W301UnstableDefaults = new W301UnstableDefaultsRule();
+//# sourceMappingURL=w301-unstable-defaults.js.map

package/dist/runtime/analysis/strict-mode.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Strict mode utilities.
+ * Converts warnings to errors when strict mode is enabled.
+ */
+import type { Diagnostic } from './types.js';
+/**
+ * Apply strict mode to diagnostics.
+ * In strict mode, warnings are treated as errors.
+ * @param diagnostics - Array of diagnostics
+ * @param strictMode - Whether strict mode is enabled
+ * @returns Diagnostics with warnings converted to errors (if strict mode)
+ */
+export declare function applyStrictMode(diagnostics: Diagnostic[], strictMode: boolean): Diagnostic[];
+/**
+ * Compute verdict from diagnostics (with strict mode support).
+ * @param diagnostics - Array of diagnostics
+ * @param strictMode - Whether strict mode is enabled
+ * @returns Verdict: 'pass', 'fail', or 'pass-with-warnings'
+ */
+export declare function computeVerdict(diagnostics: Diagnostic[], strictMode?: boolean): 'pass' | 'fail' | 'pass-with-warnings';
+//# sourceMappingURL=strict-mode.d.ts.map

package/dist/runtime/analysis/strict-mode.js

@@ -0,0 +1,44 @@
+/**
+ * Strict mode utilities.
+ * Converts warnings to errors when strict mode is enabled.
+ */
+/**
+ * Apply strict mode to diagnostics.
+ * In strict mode, warnings are treated as errors.
+ * @param diagnostics - Array of diagnostics
+ * @param strictMode - Whether strict mode is enabled
+ * @returns Diagnostics with warnings converted to errors (if strict mode)
+ */
+export function applyStrictMode(diagnostics, strictMode) {
+    if (!strictMode) {
+        return diagnostics;
+    }
+    return diagnostics.map(diagnostic => {
+        if (diagnostic.severity === 'warning') {
+            return {
+                ...diagnostic,
+                severity: 'error',
+            };
+        }
+        return diagnostic;
+    });
+}
+/**
+ * Compute verdict from diagnostics (with strict mode support).
+ * @param diagnostics - Array of diagnostics
+ * @param strictMode - Whether strict mode is enabled
+ * @returns Verdict: 'pass', 'fail', or 'pass-with-warnings'
+ */
+export function computeVerdict(diagnostics, strictMode = false) {
+    const processedDiagnostics = applyStrictMode(diagnostics, strictMode);
+    const errors = processedDiagnostics.filter(d => d.severity === 'error');
+    const warnings = processedDiagnostics.filter(d => d.severity === 'warning');
+    if (errors.length > 0) {
+        return 'fail';
+    }
+    if (warnings.length > 0) {
+        return 'pass-with-warnings';
+    }
+    return 'pass';
+}
+//# sourceMappingURL=strict-mode.js.map

package/dist/runtime/analysis/types.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Type definitions for the analysis engine.
+ * Core types for static analysis of MCP tool contracts.
+ */
+/**
+ * Raw tool data from MCP server (before normalization).
+ */
+export interface RawTool {
+    name: string;
+    description?: string;
+    inputSchema?: unknown;
+    outputSchema?: unknown;
+}
+/**
+ * Field specification extracted from JSON Schema.
+ */
+export interface FieldSpec {
+    /** Tool name this field belongs to */
+    tool: string;
+    /** Field name */
+    name: string;
+    /** JSON Schema type (string, number, object, array, etc.) */
+    type: string;
+    /** Whether this field is required */
+    required: boolean;
+    /** Field description */
+    description?: string;
+    /** Enum values if applicable */
+    enum?: string[];
+    /** Regex pattern if applicable */
+    pattern?: string;
+    /** Example value if provided */
+    example?: unknown;
+    /** Whether field is nullable */
+    nullable?: boolean;
+    /** Nested properties for object types */
+    properties?: FieldSpec[];
+}
+/**
+ * Normalized tool specification.
+ */
+export interface ToolSpec {
+    /** Tool name */
+    name: string;
+    /** Tool description */
+    description: string;
+    /** Input fields */
+    inputs: FieldSpec[];
+    /** Output fields */
+    outputs: FieldSpec[];
+    /** Extracted tokens from description (for similarity matching) */
+    descriptionTokens: Set<string>;
+}
+/**
+ * Inferred dependency between tools.
+ */
+export interface Dependency {
+    /** Source tool name */
+    fromTool: string;
+    /** Source field name */
+    fromField: string;
+    /** Target tool name */
+    toTool: string;
+    /** Target field name */
+    toField: string;
+    /** Confidence score (0.0-1.0) */
+    confidence: number;
+}
+/**
+ * Analysis diagnostic (error or warning).
+ */
+export interface Diagnostic {
+    /** Diagnostic code (E001-E010 for errors, W001-W010 for warnings) */
+    code: string;
+    /** Severity level */
+    severity: 'error' | 'warning';
+    /** Human-readable message */
+    message: string;
+    /** Tool name (if applicable) */
+    tool?: string;
+    /** Field name (if applicable) */
+    field?: string;
+    /** Suggestion for fixing the issue */
+    suggestion?: string;
+    /** Additional context */
+    context?: Record<string, unknown>;
+}
+/**
+ * Analysis verdict.
+ */
+export type Verdict = 'pass' | 'fail' | 'pass-with-warnings';
+/**
+ * Indexes for fast lookups.
+ */
+export interface Indexes {
+    /** Map of tool name to ToolSpec */
+    toolIndex: Map<string, ToolSpec>;
+    /** Map of field name to FieldSpec[] (for inputs) */
+    inputIndex: Map<string, FieldSpec[]>;
+    /** Map of field name to FieldSpec[] (for outputs) */
+    outputIndex: Map<string, FieldSpec[]>;
+    /** Map of keyword to Set<tool names> */
+    keywordIndex: Map<string, Set<string>>;
+}
+/**
+ * Analysis context passed to rules.
+ */
+export interface AnalysisContext {
+    /** All normalized tools */
+    tools: ToolSpec[];
+    /** Inferred dependencies */
+    dependencies: Dependency[];
+    /** Built indexes */
+    indexes: Indexes;
+}
+/**
+ * Analysis result.
+ */
+export interface AnalysisResult {
+    /** Final verdict */
+    verdict: Verdict;
+    /** All diagnostics */
+    diagnostics: Diagnostic[];
+    /** Error diagnostics only */
+    errors: Diagnostic[];
+    /** Warning diagnostics only */
+    warnings: Diagnostic[];
+    /** Inferred dependencies */
+    dependencies: Dependency[];
+    /** Number of tools analyzed */
+    toolCount: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/runtime/analysis/types.js

@@ -0,0 +1,6 @@
+/**
+ * Type definitions for the analysis engine.
+ * Core types for static analysis of MCP tool contracts.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/runtime/analysis/utils.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Shared utility functions for analysis rules.
+ */
+/**
+ * Escape regex metacharacters in a string to use it as a literal pattern.
+ * This prevents ReDoS attacks and regex injection vulnerabilities.
+ *
+ * @param str - The string to escape
+ * @returns The escaped string safe for use in RegExp constructor
+ *
+ * @example
+ * ```ts
+ * const keyword = "user.id";
+ * const escaped = escapeRegex(keyword); // "user\\.id"
+ * const regex = new RegExp(`\\b${escaped}\\b`, 'i');
+ * ```
+ */
+export declare function escapeRegex(str: string): string;
+//# sourceMappingURL=utils.d.ts.map

package/dist/runtime/analysis/utils.js

@@ -0,0 +1,21 @@
+/**
+ * Shared utility functions for analysis rules.
+ */
+/**
+ * Escape regex metacharacters in a string to use it as a literal pattern.
+ * This prevents ReDoS attacks and regex injection vulnerabilities.
+ *
+ * @param str - The string to escape
+ * @returns The escaped string safe for use in RegExp constructor
+ *
+ * @example
+ * ```ts
+ * const keyword = "user.id";
+ * const escaped = escapeRegex(keyword); // "user\\.id"
+ * const regex = new RegExp(`\\b${escaped}\\b`, 'i');
+ * ```
+ */
+export function escapeRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+//# sourceMappingURL=utils.js.map