@syrin/cli 1.3.0

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

@@ -0,0 +1,88 @@
+/**
+ * W009: 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';
+/**
+ * Check if a tool name/description suggests mutation.
+ */
+function suggestsMutation(toolName, description) {
+    const combined = `${toolName} ${description}`.toLowerCase();
+    // Mutation verbs
+    const mutationVerbs = [
+        'create',
+        'delete',
+        'remove',
+        'update',
+        'modify',
+        'change',
+        'set',
+        'save',
+        'write',
+        'add',
+        'insert',
+        'destroy',
+        'drop',
+        'clear',
+        'reset',
+    ];
+    return mutationVerbs.some(verb => {
+        const regex = new RegExp(`\\b${verb}\\b`, 'i');
+        return regex.test(combined);
+    });
+}
+/**
+ * Check if schema reflects mutation (has outputs that suggest state change).
+ */
+function schemaReflectsMutation(tool) {
+    // If no outputs, it might be a mutation (void operation)
+    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 W009HiddenSideEffectsRule extends BaseRule {
+    id = 'W009';
+    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 W009HiddenSideEffects = new W009HiddenSideEffectsRule();
+//# sourceMappingURL=w009-hidden-side-effects.js.map

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

@@ -0,0 +1,22 @@
+/**
+ * W010: 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 W010OutputNotReusableRule extends BaseRule {
+    readonly id = "W010";
+    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 W010OutputNotReusable: W010OutputNotReusableRule;
+export {};
+//# sourceMappingURL=w010-output-not-reusable.d.ts.map

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

@@ -0,0 +1,81 @@
+/**
+ * W010: 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;
+}
+/**
+ * Check if output is structured (object or array).
+ */
+function isStructured(output) {
+    if (output.type === 'object' || output.type === 'array') {
+        return true;
+    }
+    if (output.properties && typeof output.properties === 'object') {
+        if (Array.isArray(output.properties) && output.properties.length > 0) {
+            return true;
+        }
+        // Also check if it's a Record with keys
+        if (!Array.isArray(output.properties) &&
+            Object.keys(output.properties).length > 0) {
+            return true;
+        }
+    }
+    return false;
+}
+class W010OutputNotReusableRule extends BaseRule {
+    id = 'W010';
+    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
+            const allNaturalLanguage = tool.outputs.every(output => isNaturalLanguageOnly(output));
+            const hasStructured = tool.outputs.some(output => isStructured(output));
+            // If all outputs are natural language and none are structured
+            if (allNaturalLanguage && !hasStructured) {
+                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 W010OutputNotReusable = new W010OutputNotReusableRule();
+//# sourceMappingURL=w010-output-not-reusable.js.map

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

@@ -0,0 +1,40 @@
+/**
+ * W021: 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 W021WeakSchemaRule extends BaseRule {
+    readonly id = "W021";
+    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 W021WeakSchema: W021WeakSchemaRule;
+export {};
+//# sourceMappingURL=w021-weak-schema.d.ts.map

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

@@ -0,0 +1,32 @@
+/**
+ * W021: 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 W021WeakSchemaRule extends BaseRule {
+    id = 'W021';
+    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 W021WeakSchema = new W021WeakSchemaRule();
+//# sourceMappingURL=w021-weak-schema.js.map

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

@@ -0,0 +1,39 @@
+/**
+ * W022: 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 W022HighEntropyOutputRule extends BaseRule {
+    readonly id = "W022";
+    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 W022HighEntropyOutput: W022HighEntropyOutputRule;
+export {};
+//# sourceMappingURL=w022-high-entropy-output.d.ts.map

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

@@ -0,0 +1,36 @@
+/**
+ * W022: 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 W022HighEntropyOutputRule extends BaseRule {
+    id = 'W022';
+    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 = [];
+        // Use configured threshold or fall back to default 0.7
+        const threshold = behavioralCtx.entropyThreshold ?? 0.7;
+        // Threshold: entropy above configured value is considered high
+        if (behavioralCtx.entropyScore > threshold) {
+            diagnostics.push(this.createDiagnostic(`Tool "${behavioralCtx.toolName}" produces high entropy output (score: ${behavioralCtx.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 W022HighEntropyOutput = new W022HighEntropyOutputRule();
+//# sourceMappingURL=w022-high-entropy-output.js.map

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

@@ -0,0 +1,38 @@
+/**
+ * W023: 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 W023UnstableDefaultsRule extends BaseRule {
+    readonly id = "W023";
+    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 W023UnstableDefaults: W023UnstableDefaultsRule;
+export {};
+//# sourceMappingURL=w023-unstable-defaults.d.ts.map

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

@@ -0,0 +1,36 @@
+/**
+ * W023: 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 W023UnstableDefaultsRule extends BaseRule {
+    id = 'W023';
+    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 W023UnstableDefaults = new W023UnstableDefaultsRule();
+//# sourceMappingURL=w023-unstable-defaults.js.map

package/dist/runtime/analysis/rules/warnings/w100-implicit-dependency.d.ts

@@ -0,0 +1,22 @@
+/**
+ * W100: Implicit Tool Dependency
+ *
+ * Condition:
+ * - Medium confidence dependency inferred (0.6–0.8)
+ * - Not stated explicitly in description
+ *
+ * Why:
+ * - LLM may not chain tools reliably
+ */
+import { BaseRule } from '../base.js';
+import type { AnalysisContext, Diagnostic } from '../../types.js';
+declare class W100ImplicitDependencyRule extends BaseRule {
+    readonly id = "W100";
+    readonly severity: "warning";
+    readonly ruleName = "Implicit Tool Dependency";
+    readonly description = "Tool appears to depend on another tool, but the dependency is implicit.";
+    check(ctx: AnalysisContext): Diagnostic[];
+}
+export declare const W100ImplicitDependency: W100ImplicitDependencyRule;
+export {};
+//# sourceMappingURL=w100-implicit-dependency.d.ts.map

package/dist/runtime/analysis/rules/warnings/w100-implicit-dependency.js

@@ -0,0 +1,89 @@
+/**
+ * W100: Implicit Tool Dependency
+ *
+ * Condition:
+ * - Medium confidence dependency inferred (0.6–0.8)
+ * - Not stated explicitly in description
+ *
+ * Why:
+ * - LLM may not chain tools reliably
+ */
+import { BaseRule } from '../base.js';
+/**
+ * Normalize and tokenize a tool name or description for comparison.
+ * - Expand camelCase to space-separated words
+ * - Replace underscores/dashes with spaces
+ * - Lowercase
+ * - Remove non-alphanumeric chars
+ * - Split into tokens
+ */
+function tokenize(text) {
+    // Expand camelCase to space-separated words (must do before lowercasing)
+    let normalized = text.replace(/([a-z])([A-Z])/g, '$1 $2');
+    // Replace underscores and dashes with spaces
+    normalized = normalized.replace(/[_\-\s]+/g, ' ');
+    // Lowercase
+    normalized = normalized.toLowerCase();
+    // Remove non-alphanumeric chars (keep only alphanumeric and spaces)
+    normalized = normalized.replace(/[^\w\s]/g, '');
+    // Split into tokens and filter empty strings
+    return normalized.split(/\s+/).filter(t => t.length > 0);
+}
+/**
+ * Check if tool name tokens match description tokens.
+ * Returns true if there's a complete multi-token subsequence match (all tokens in order)
+ * or if all tool name tokens appear in description (allowing for order).
+ * This reduces false positives from common words like "get" or "user".
+ */
+function hasTokenMatch(toolNameTokens, descTokens) {
+    // Early return for empty tokens
+    if (toolNameTokens.length === 0) {
+        return false;
+    }
+    // Check for complete multi-token subsequence match (all tokens in order)
+    for (let i = 0; i <= descTokens.length - toolNameTokens.length; i++) {
+        const subsequence = descTokens.slice(i, i + toolNameTokens.length);
+        if (subsequence.join(' ') === toolNameTokens.join(' ')) {
+            return true;
+        }
+    }
+    // Check if all tool name tokens appear in description (allowing for order)
+    // This catches cases like "get_user_id" matching "uses get_user_id internally"
+    if (toolNameTokens.length >= 2) {
+        const descTokensSet = new Set(descTokens);
+        const allTokensPresent = toolNameTokens.every(token => descTokensSet.has(token));
+        if (allTokensPresent) {
+            return true;
+        }
+    }
+    return false;
+}
+class W100ImplicitDependencyRule extends BaseRule {
+    id = 'W100';
+    severity = 'warning';
+    ruleName = 'Implicit Tool Dependency';
+    description = 'Tool appears to depend on another tool, but the dependency is implicit.';
+    check(ctx) {
+        const diagnostics = [];
+        // Check medium to high confidence dependencies (0.6-0.8)
+        const implicitDeps = ctx.dependencies.filter(d => d.confidence >= 0.6 && d.confidence < 0.8);
+        for (const dep of implicitDeps) {
+            // Find the toTool to check its description
+            const toTool = ctx.indexes.toolIndex.get(dep.toTool.toLowerCase());
+            if (!toTool) {
+                continue;
+            }
+            const description = toTool.description || '';
+            // Tokenize both tool name and description for accurate comparison
+            const fromToolTokens = tokenize(dep.fromTool);
+            const descTokens = tokenize(description);
+            // Check if fromTool tokens match description tokens
+            if (!hasTokenMatch(fromToolTokens, descTokens)) {
+                diagnostics.push(this.createDiagnostic(`Tool "${dep.toTool}" appears to depend on "${dep.fromTool}", but the dependency is implicit.`, dep.toTool, dep.toField, `Mention "${dep.fromTool}" in the description of "${dep.toTool}" to make the dependency explicit.`));
+            }
+        }
+        return diagnostics;
+    }
+}
+export const W100ImplicitDependency = new W100ImplicitDependencyRule();
+//# sourceMappingURL=w100-implicit-dependency.js.map

package/dist/runtime/analysis/rules/warnings/w101-free-text-without-normalization.d.ts

@@ -0,0 +1,24 @@
+/**
+ * W101: Free-Text Output Without Normalization
+ *
+ * Condition:
+ * - Output is string
+ * - Not constrained or normalized
+ * - Even if not chained
+ *
+ * Why:
+ * - Hard to reuse
+ * - Hard to evolve
+ */
+import { BaseRule } from '../base.js';
+import type { AnalysisContext, Diagnostic } from '../../types.js';
+declare class W101FreeTextWithoutNormalizationRule extends BaseRule {
+    readonly id = "W101";
+    readonly severity: "warning";
+    readonly ruleName = "Free-Text Output Without Normalization";
+    readonly description = "Tool returns unconstrained free text. Consider normalizing output.";
+    check(ctx: AnalysisContext): Diagnostic[];
+}
+export declare const W101FreeTextWithoutNormalization: W101FreeTextWithoutNormalizationRule;
+export {};
+//# sourceMappingURL=w101-free-text-without-normalization.d.ts.map

package/dist/runtime/analysis/rules/warnings/w101-free-text-without-normalization.js

@@ -0,0 +1,40 @@
+/**
+ * W101: Free-Text Output Without Normalization
+ *
+ * Condition:
+ * - Output is string
+ * - Not constrained or normalized
+ * - Even if not chained
+ *
+ * Why:
+ * - Hard to reuse
+ * - Hard to evolve
+ */
+import { BaseRule } from '../base.js';
+class W101FreeTextWithoutNormalizationRule extends BaseRule {
+    id = 'W101';
+    severity = 'warning';
+    ruleName = 'Free-Text Output Without Normalization';
+    description = 'Tool returns unconstrained free text. Consider normalizing output.';
+    check(ctx) {
+        const diagnostics = [];
+        for (const tool of ctx.tools) {
+            for (const output of tool.outputs) {
+                // Check if output is unconstrained string
+                if (output.type !== 'string') {
+                    continue;
+                }
+                const hasEnum = Boolean(output.enum && output.enum.length > 0);
+                const hasPattern = Boolean(output.pattern);
+                const hasDescription = Boolean(output.description && output.description.trim());
+                // If it's a string with no constraints, it's unconstrained free text
+                if (!hasEnum && !hasPattern && !hasDescription) {
+                    diagnostics.push(this.createDiagnostic(`Tool "${tool.name}" returns unconstrained free text (field: "${output.name}"). Consider normalizing output.`, tool.name, output.name, `Add constraints to the output: enum values, regex pattern, or a clear description of the expected format.`));
+                }
+            }
+        }
+        return diagnostics;
+    }
+}
+export const W101FreeTextWithoutNormalization = new W101FreeTextWithoutNormalizationRule();
+//# sourceMappingURL=w101-free-text-without-normalization.js.map

package/dist/runtime/analysis/rules/warnings/w102-missing-examples.d.ts

@@ -0,0 +1,22 @@
+/**
+ * W102: Missing Examples for User-Facing Inputs
+ *
+ * Condition:
+ * - Tool takes user-provided input
+ * - No examples provided
+ *
+ * Why:
+ * - LLM guessing increases error rate
+ */
+import { BaseRule } from '../base.js';
+import type { AnalysisContext, Diagnostic } from '../../types.js';
+declare class W102MissingExamplesRule extends BaseRule {
+    readonly id = "W102";
+    readonly severity: "warning";
+    readonly ruleName = "Missing Examples for User-Facing Inputs";
+    readonly description = "Tool accepts user-provided input but has no examples. LLM accuracy may be reduced.";
+    check(ctx: AnalysisContext): Diagnostic[];
+}
+export declare const W102MissingExamples: W102MissingExamplesRule;
+export {};
+//# sourceMappingURL=w102-missing-examples.d.ts.map