@syrin/cli 1.3.0

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

@@ -0,0 +1,76 @@
+/**
+ * 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';
+/**
+ * Check if an input field appears to be user-provided.
+ * Indicators are treated as plain text (not regex patterns).
+ */
+function isUserFacingInput(inputName, description) {
+    const name = inputName.toLowerCase();
+    const desc = (description || '').toLowerCase();
+    // Keywords that suggest user input (treated as plain text, not regex)
+    const userInputIndicators = [
+        'user',
+        'person',
+        'name',
+        'email',
+        'location',
+        'address',
+        'preference',
+        'query',
+        'question',
+        'input',
+        'text',
+        'message',
+    ];
+    // Split into tokens for whole-word matching
+    const nameTokens = name
+        .split(/[^\w]+|(?<=[a-z])(?=[A-Z])/)
+        .filter(t => t.length > 0);
+    const descTokens = desc
+        .split(/[^\w]+|(?<=[a-z])(?=[A-Z])/)
+        .filter(t => t.length > 0);
+    const allTokens = new Set([...nameTokens, ...descTokens]);
+    // Check for whole-word matches using set membership
+    // Tokenization already enforces word boundaries, so regex is redundant
+    return userInputIndicators.some(indicator => allTokens.has(indicator));
+}
+class W102MissingExamplesRule extends BaseRule {
+    id = 'W102';
+    severity = 'warning';
+    ruleName = 'Missing Examples for User-Facing Inputs';
+    description = 'Tool accepts user-provided input but has no examples. LLM accuracy may be reduced.';
+    check(ctx) {
+        const diagnostics = [];
+        for (const tool of ctx.tools) {
+            for (const input of tool.inputs) {
+                // Only check user-facing inputs
+                if (!isUserFacingInput(input.name, input.description)) {
+                    continue;
+                }
+                // Check if it has an example (treat undefined, empty strings, whitespace-only, and empty arrays/objects as missing)
+                const example = input.example;
+                const isMissing = example === undefined ||
+                    (typeof example === 'string' && example.trim().length === 0) ||
+                    (Array.isArray(example) && example.length === 0) ||
+                    (typeof example === 'object' &&
+                        example !== null &&
+                        Object.keys(example).length === 0);
+                if (isMissing) {
+                    diagnostics.push(this.createDiagnostic(`Tool "${tool.name}" parameter "${input.name}" has no examples. LLM accuracy may be reduced.`, tool.name, input.name, `Add example values to "${input.name}" to help the LLM understand the expected format.`));
+                }
+            }
+        }
+        return diagnostics;
+    }
+}
+export const W102MissingExamples = new W102MissingExamplesRule();
+//# sourceMappingURL=w102-missing-examples.js.map

package/dist/runtime/analysis/rules/warnings/w103-overloaded-responsibility.d.ts

@@ -0,0 +1,23 @@
+/**
+ * W103: Overloaded Tool Responsibility
+ *
+ * Condition:
+ * - Tool does multiple conceptual things
+ * - Description contains multiple verbs or intents
+ *
+ * Why:
+ * - Tool selection becomes unstable
+ * - Hard to compose
+ */
+import { BaseRule } from '../base.js';
+import type { AnalysisContext, Diagnostic } from '../../types.js';
+declare class W103OverloadedResponsibilityRule extends BaseRule {
+    readonly id = "W103";
+    readonly severity: "warning";
+    readonly ruleName = "Overloaded Tool Responsibility";
+    readonly description = "Tool appears to handle multiple responsibilities. Tool selection becomes unstable.";
+    check(ctx: AnalysisContext): Diagnostic[];
+}
+export declare const W103OverloadedResponsibility: W103OverloadedResponsibilityRule;
+export {};
+//# sourceMappingURL=w103-overloaded-responsibility.d.ts.map

package/dist/runtime/analysis/rules/warnings/w103-overloaded-responsibility.js

@@ -0,0 +1,91 @@
+/**
+ * W103: Overloaded Tool Responsibility
+ *
+ * Condition:
+ * - Tool does multiple conceptual things
+ * - Description contains multiple verbs or intents
+ *
+ * Why:
+ * - Tool selection becomes unstable
+ * - Hard to compose
+ */
+import { BaseRule } from '../base.js';
+/**
+ * Count verbs in a description.
+ */
+function countVerbs(description) {
+    const commonVerbs = [
+        'get',
+        'set',
+        'create',
+        'delete',
+        'update',
+        'find',
+        'search',
+        'fetch',
+        'send',
+        'receive',
+        'process',
+        'handle',
+        'execute',
+        'run',
+        'call',
+        'invoke',
+        'parse',
+        'format',
+        'validate',
+        'transform',
+        'convert',
+        'merge',
+        'split',
+        'filter',
+        'sort',
+        'save',
+        'load',
+        'read',
+        'write',
+    ];
+    const descLower = description.toLowerCase();
+    let verbCount = 0;
+    for (const verb of commonVerbs) {
+        // Check if verb appears as a word (not just as part of another word)
+        const regex = new RegExp(`\\b${verb}\\b`, 'i');
+        if (regex.test(descLower)) {
+            verbCount++;
+        }
+    }
+    return verbCount;
+}
+/**
+ * Count distinct intents (action + object pairs).
+ */
+function countIntents(description) {
+    // Simple heuristic: split on connectors ("and", "or", commas) to count intents
+    // Use combined regex to handle multiple different connectors in one pass
+    const descLower = description.toLowerCase();
+    const combinedRegex = /(?:\s+and\s+|\s+or\s+|,\s*)/i;
+    const parts = descLower.split(combinedRegex).filter(Boolean);
+    return parts.length;
+}
+class W103OverloadedResponsibilityRule extends BaseRule {
+    id = 'W103';
+    severity = 'warning';
+    ruleName = 'Overloaded Tool Responsibility';
+    description = 'Tool appears to handle multiple responsibilities. Tool selection becomes unstable.';
+    check(ctx) {
+        const diagnostics = [];
+        for (const tool of ctx.tools) {
+            const description = tool.description || '';
+            // Count verbs and intents
+            const verbCount = countVerbs(description);
+            const intentCount = countIntents(description);
+            // If too many verbs (>3) or multiple intents (>2), it's overloaded
+            if (verbCount > 3 || intentCount > 2) {
+                diagnostics.push(this.createDiagnostic(`Tool "${tool.name}" appears to handle multiple responsibilities.`, tool.name, undefined, `Split "${tool.name}" into multiple focused tools, each handling a single responsibility.`));
+            }
+        }
+        return diagnostics;
+    }
+}
+export const W103OverloadedResponsibility = new W103OverloadedResponsibilityRule();
+//# sourceMappingURL=w103-overloaded-responsibility.js.map

package/dist/runtime/analysis/rules/warnings/w104-generic-description.d.ts

@@ -0,0 +1,53 @@
+/**
+ * W104: Tool Description Too Generic
+ *
+ * Condition:
+ * - Description uses vague verbs:
+ *   - "get"
+ *   - "handle"
+ *   - "process"
+ * - No concrete nouns
+ *
+ * Why:
+ * - LLM cannot discriminate tools
+ */
+import { BaseRule } from '../base.js';
+import type { AnalysisContext, Diagnostic } from '../../types.js';
+/**
+ * Default list of concrete nouns that make a description specific.
+ * This list can be extended or overridden when creating a custom rule instance.
+ *
+ * @example
+ * ```ts
+ * import { createW104Rule, DEFAULT_CONCRETE_NOUNS } from './w104-generic-description.js';
+ * const customNouns = [...DEFAULT_CONCRETE_NOUNS, 'invoice', 'report'];
+ * const customRule = createW104Rule(customNouns);
+ * ```
+ */
+export declare const DEFAULT_CONCRETE_NOUNS: readonly ["weather", "location", "user", "file", "data", "email", "message", "order", "payment", "product", "customer", "account", "transaction", "request", "response"];
+declare class W104GenericDescriptionRule extends BaseRule {
+    private readonly concreteNouns;
+    readonly id = "W104";
+    readonly severity: "warning";
+    readonly ruleName = "Tool Description Too Generic";
+    readonly description = "Description of tool is too generic. LLM cannot discriminate tools.";
+    constructor(concreteNouns?: readonly string[]);
+    check(ctx: AnalysisContext): Diagnostic[];
+}
+/**
+ * Create a W104 rule instance with custom concrete nouns.
+ *
+ * @param concreteNouns - Optional list of concrete nouns (defaults to DEFAULT_CONCRETE_NOUNS)
+ * @returns A new W104GenericDescriptionRule instance
+ *
+ * @example
+ * ```ts
+ * import { createW104Rule, DEFAULT_CONCRETE_NOUNS } from './w005-generic-description.js';
+ * const customNouns = [...DEFAULT_CONCRETE_NOUNS, 'invoice', 'report'];
+ * const customRule = createW104Rule(customNouns);
+ * ```
+ */
+export declare function createW104Rule(concreteNouns?: readonly string[]): W104GenericDescriptionRule;
+export declare const W104GenericDescription: W104GenericDescriptionRule;
+export {};
+//# sourceMappingURL=w104-generic-description.d.ts.map

package/dist/runtime/analysis/rules/warnings/w104-generic-description.js

@@ -0,0 +1,108 @@
+/**
+ * W104: Tool Description Too Generic
+ *
+ * Condition:
+ * - Description uses vague verbs:
+ *   - "get"
+ *   - "handle"
+ *   - "process"
+ * - No concrete nouns
+ *
+ * Why:
+ * - LLM cannot discriminate tools
+ */
+import { BaseRule } from '../base.js';
+/**
+ * Default list of concrete nouns that make a description specific.
+ * This list can be extended or overridden when creating a custom rule instance.
+ *
+ * @example
+ * ```ts
+ * import { createW104Rule, DEFAULT_CONCRETE_NOUNS } from './w104-generic-description.js';
+ * const customNouns = [...DEFAULT_CONCRETE_NOUNS, 'invoice', 'report'];
+ * const customRule = createW104Rule(customNouns);
+ * ```
+ */
+export const DEFAULT_CONCRETE_NOUNS = [
+    'weather',
+    'location',
+    'user',
+    'file',
+    'data',
+    'email',
+    'message',
+    'order',
+    'payment',
+    'product',
+    'customer',
+    'account',
+    'transaction',
+    'request',
+    'response',
+];
+/**
+ * Check if description is too generic.
+ *
+ * @param description - Tool description to check
+ * @param concreteNouns - Optional list of concrete nouns (defaults to DEFAULT_CONCRETE_NOUNS)
+ */
+function isGenericDescription(description, concreteNouns = DEFAULT_CONCRETE_NOUNS) {
+    const descLower = description.toLowerCase();
+    // Vague verbs
+    const vagueVerbs = ['get', 'handle', 'process', 'do', 'make', 'use', 'call'];
+    // Check for vague verbs without concrete nouns
+    let hasVagueVerb = false;
+    for (const verb of vagueVerbs) {
+        const regex = new RegExp(`\\b${verb}\\b`, 'i');
+        if (regex.test(descLower)) {
+            hasVagueVerb = true;
+            break;
+        }
+    }
+    if (!hasVagueVerb) {
+        return false;
+    }
+    // Check if description has concrete nouns (case-insensitive)
+    const hasConcreteNoun = concreteNouns.some(noun => descLower.includes(noun.toLowerCase()));
+    // If has vague verb but no concrete noun, it's generic
+    return !hasConcreteNoun;
+}
+class W104GenericDescriptionRule extends BaseRule {
+    concreteNouns;
+    id = 'W104';
+    severity = 'warning';
+    ruleName = 'Tool Description Too Generic';
+    description = 'Description of tool is too generic. LLM cannot discriminate tools.';
+    constructor(concreteNouns = DEFAULT_CONCRETE_NOUNS) {
+        super();
+        this.concreteNouns = concreteNouns;
+    }
+    check(ctx) {
+        const diagnostics = [];
+        for (const tool of ctx.tools) {
+            const description = tool.description || '';
+            if (isGenericDescription(description, this.concreteNouns)) {
+                diagnostics.push(this.createDiagnostic(`Description of "${tool.name}" is too generic.`, tool.name, undefined, `Make the description more specific by including concrete nouns and specific actions (e.g., "Get weather data for a location" instead of "Get data").`));
+            }
+        }
+        return diagnostics;
+    }
+}
+/**
+ * Create a W104 rule instance with custom concrete nouns.
+ *
+ * @param concreteNouns - Optional list of concrete nouns (defaults to DEFAULT_CONCRETE_NOUNS)
+ * @returns A new W104GenericDescriptionRule instance
+ *
+ * @example
+ * ```ts
+ * import { createW104Rule, DEFAULT_CONCRETE_NOUNS } from './w005-generic-description.js';
+ * const customNouns = [...DEFAULT_CONCRETE_NOUNS, 'invoice', 'report'];
+ * const customRule = createW104Rule(customNouns);
+ * ```
+ */
+export function createW104Rule(concreteNouns) {
+    return new W104GenericDescriptionRule(concreteNouns);
+}
+export const W104GenericDescription = new W104GenericDescriptionRule();
+//# sourceMappingURL=w104-generic-description.js.map

package/dist/runtime/analysis/rules/warnings/w105-optional-as-required.d.ts

@@ -0,0 +1,22 @@
+/**
+ * W105: Optional Input Used as Required Downstream
+ *
+ * Condition:
+ * - Input marked optional
+ * - Treated as required in chaining
+ *
+ * Why:
+ * - Hidden contract violation
+ */
+import { BaseRule } from '../base.js';
+import type { AnalysisContext, Diagnostic } from '../../types.js';
+declare class W105OptionalAsRequiredRule extends BaseRule {
+    readonly id = "W105";
+    readonly severity: "warning";
+    readonly ruleName = "Optional Input Used as Required Downstream";
+    readonly description = "Optional input is treated as required downstream. Hidden contract violation.";
+    check(ctx: AnalysisContext): Diagnostic[];
+}
+export declare const W105OptionalAsRequired: W105OptionalAsRequiredRule;
+export {};
+//# sourceMappingURL=w105-optional-as-required.d.ts.map

package/dist/runtime/analysis/rules/warnings/w105-optional-as-required.js

@@ -0,0 +1,45 @@
+/**
+ * W105: Optional Input Used as Required Downstream
+ *
+ * Condition:
+ * - Input marked optional
+ * - Treated as required in chaining
+ *
+ * Why:
+ * - Hidden contract violation
+ */
+import { BaseRule } from '../base.js';
+class W105OptionalAsRequiredRule extends BaseRule {
+    id = 'W105';
+    severity = 'warning';
+    ruleName = 'Optional Input Used as Required Downstream';
+    description = 'Optional input is treated as required downstream. Hidden contract violation.';
+    check(ctx) {
+        const diagnostics = [];
+        // Check high-confidence dependencies (>= 0.8)
+        const highConfidenceDeps = ctx.dependencies.filter(d => d.confidence >= 0.8);
+        for (const dep of highConfidenceDeps) {
+            // Find the source output
+            const fromTool = ctx.indexes.toolIndex.get(dep.fromTool.toLowerCase());
+            const toTool = ctx.indexes.toolIndex.get(dep.toTool.toLowerCase());
+            if (!fromTool || !toTool) {
+                continue;
+            }
+            const fromField = fromTool.outputs.find(f => f.name === dep.fromField);
+            const toField = toTool.inputs.find(f => f.name === dep.toField);
+            if (!fromField || !toField) {
+                continue;
+            }
+            // Check if source is optional/nullable but target is required
+            // Source is optional if: nullable === true OR required === false
+            const isSourceOptional = fromField.nullable === true || fromField.required === false;
+            const isTargetRequired = toField.required === true;
+            if (isSourceOptional && isTargetRequired) {
+                diagnostics.push(this.createDiagnostic(`Source field "${dep.fromTool}.${dep.fromField}" is nullable/optional but is being wired into required input "${dep.toTool}.${dep.toField}".`, dep.toTool, dep.toField, `Make "${dep.fromTool}.${dep.fromField}" non-nullable, or make "${dep.toTool}.${dep.toField}" optional.`));
+            }
+        }
+        return diagnostics;
+    }
+}
+export const W105OptionalAsRequired = new W105OptionalAsRequiredRule();
+//# sourceMappingURL=w105-optional-as-required.js.map

package/dist/runtime/analysis/rules/warnings/w106-broad-output-schema.d.ts

@@ -0,0 +1,23 @@
+/**
+ * W106: Output Schema Too Broad
+ *
+ * Condition:
+ * - Output type is object with no properties
+ * - Or any
+ *
+ * Why:
+ * - No contract enforcement
+ * - Breaks evolution
+ */
+import { BaseRule } from '../base.js';
+import type { AnalysisContext, Diagnostic } from '../../types.js';
+declare class W106BroadOutputSchemaRule extends BaseRule {
+    readonly id = "W106";
+    readonly severity: "warning";
+    readonly ruleName = "Output Schema Too Broad";
+    readonly description = "Output schema of tool is too broad. No contract enforcement.";
+    check(ctx: AnalysisContext): Diagnostic[];
+}
+export declare const W106BroadOutputSchema: W106BroadOutputSchemaRule;
+export {};
+//# sourceMappingURL=w106-broad-output-schema.d.ts.map

package/dist/runtime/analysis/rules/warnings/w106-broad-output-schema.js

@@ -0,0 +1,37 @@
+/**
+ * W106: Output Schema Too Broad
+ *
+ * Condition:
+ * - Output type is object with no properties
+ * - Or any
+ *
+ * Why:
+ * - No contract enforcement
+ * - Breaks evolution
+ */
+import { BaseRule } from '../base.js';
+class W106BroadOutputSchemaRule extends BaseRule {
+    id = 'W106';
+    severity = 'warning';
+    ruleName = 'Output Schema Too Broad';
+    description = 'Output schema of tool is too broad. No contract enforcement.';
+    check(ctx) {
+        const diagnostics = [];
+        for (const tool of ctx.tools) {
+            for (const output of tool.outputs) {
+                // Check if output is "any" type
+                if (output.type === 'any') {
+                    diagnostics.push(this.createDiagnostic(`Output schema of "${tool.name}" (field: "${output.name}") is too broad (type: "any").`, tool.name, output.name, `Specify a concrete type for "${output.name}" instead of "any".`));
+                }
+                // Check if output is object with no properties
+                if (output.type === 'object' &&
+                    (!output.properties || output.properties.length === 0)) {
+                    diagnostics.push(this.createDiagnostic(`Output schema of "${tool.name}" (field: "${output.name}") is an object with no properties defined.`, tool.name, output.name, `Define the properties of the object schema for "${output.name}".`));
+                }
+            }
+        }
+        return diagnostics;
+    }
+}
+export const W106BroadOutputSchema = new W106BroadOutputSchemaRule();
+//# sourceMappingURL=w106-broad-output-schema.js.map

package/dist/runtime/analysis/rules/warnings/w107-multiple-entry-points.d.ts

@@ -0,0 +1,22 @@
+/**
+ * W107: Multiple Entry Points for Same Concept
+ *
+ * Condition:
+ * - Multiple tools ask user for same conceptual data
+ *   (e.g. location, user_id)
+ *
+ * Why:
+ * - Conflicting sources of truth
+ */
+import { BaseRule } from '../base.js';
+import type { AnalysisContext, Diagnostic } from '../../types.js';
+declare class W107MultipleEntryPointsRule extends BaseRule {
+    readonly id = "W107";
+    readonly severity: "warning";
+    readonly ruleName = "Multiple Entry Points for Same Concept";
+    readonly description = "Multiple tools capture the same concept. Conflicting sources of truth.";
+    check(ctx: AnalysisContext): Diagnostic[];
+}
+export declare const W107MultipleEntryPoints: W107MultipleEntryPointsRule;
+export {};
+//# sourceMappingURL=w107-multiple-entry-points.d.ts.map

package/dist/runtime/analysis/rules/warnings/w107-multiple-entry-points.js

@@ -0,0 +1,97 @@
+/**
+ * W107: Multiple Entry Points for Same Concept
+ *
+ * Condition:
+ * - Multiple tools ask user for same conceptual data
+ *   (e.g. location, user_id)
+ *
+ * Why:
+ * - Conflicting sources of truth
+ */
+import { BaseRule } from '../base.js';
+import { escapeRegex } from '../../utils.js';
+/**
+ * Extract the concept from an input field name.
+ */
+function extractConcept(fieldName) {
+    // Split field name into tokens (on non-word characters and camelCase boundaries)
+    // Preserve case for camelCase detection, then lowercase tokens individually
+    const tokens = fieldName
+        .split(/[^\w]+|(?<=[a-z])(?=[A-Z])/)
+        .filter(t => t.length > 0)
+        .map(t => t.toLowerCase());
+    const name = fieldName.toLowerCase();
+    // Common concepts
+    const concepts = [
+        [['location', 'loc', 'place', 'address', 'city', 'country'], 'location'],
+        [['user', 'user_id', 'userid', 'username', 'person'], 'user'],
+        [['email', 'e-mail', 'mail'], 'email'],
+        [['phone', 'telephone', 'mobile'], 'phone'],
+        [['name', 'fullname', 'full_name'], 'name'],
+        [['id', 'identifier'], 'id'],
+    ];
+    for (const [keywords, concept] of concepts) {
+        for (const keyword of keywords) {
+            // Check for exact token match or word-boundary match
+            // Escape keyword to prevent regex injection
+            const escapedKeyword = escapeRegex(keyword);
+            const keywordRegex = new RegExp(`\\b${escapedKeyword}\\b`, 'i');
+            if (tokens.includes(keyword) || keywordRegex.test(name)) {
+                return concept;
+            }
+        }
+    }
+    return null;
+}
+class W107MultipleEntryPointsRule extends BaseRule {
+    id = 'W107';
+    severity = 'warning';
+    ruleName = 'Multiple Entry Points for Same Concept';
+    description = 'Multiple tools capture the same concept. Conflicting sources of truth.';
+    check(ctx) {
+        const diagnostics = [];
+        // Map concept to tools that have it
+        const conceptToTools = new Map();
+        for (const tool of ctx.tools) {
+            for (const input of tool.inputs) {
+                // Only check user-facing inputs
+                if (!input.required) {
+                    continue;
+                }
+                const concept = extractConcept(input.name);
+                if (!concept) {
+                    continue;
+                }
+                if (!conceptToTools.has(concept)) {
+                    conceptToTools.set(concept, []);
+                }
+                conceptToTools.get(concept).push({
+                    tool: tool.name,
+                    field: input.name,
+                });
+            }
+        }
+        // Check for concepts that appear in multiple tools
+        for (const [concept, tools] of conceptToTools.entries()) {
+            if (tools.length > 1) {
+                const toolNames = tools.map(t => `"${t.tool}"`).join(', ');
+                // Group by tool name in case same tool appears multiple times
+                const toolFieldsMap = new Map();
+                for (const toolEntry of tools) {
+                    if (!toolFieldsMap.has(toolEntry.tool)) {
+                        toolFieldsMap.set(toolEntry.tool, []);
+                    }
+                    toolFieldsMap.get(toolEntry.tool).push(toolEntry.field);
+                }
+                const context = {};
+                for (const [tool, fields] of toolFieldsMap.entries()) {
+                    context[tool] = fields.join(', ');
+                }
+                diagnostics.push(this.createDiagnostic(`Multiple tools capture the same concept: "${concept}" (${toolNames}).`, undefined, undefined, `Consolidate "${concept}" collection into a single tool to avoid conflicting sources of truth.`, context));
+            }
+        }
+        return diagnostics;
+    }
+}
+export const W107MultipleEntryPoints = new W107MultipleEntryPointsRule();
+//# sourceMappingURL=w107-multiple-entry-points.js.map

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

@@ -0,0 +1,23 @@
+/**
+ * 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';
+import type { AnalysisContext, Diagnostic } from '../../types.js';
+declare class W108HiddenSideEffectsRule extends BaseRule {
+    readonly id = "W108";
+    readonly severity: "warning";
+    readonly ruleName = "Hidden Side Effects";
+    readonly description = "Tool appears to have side effects not reflected in schema. Execution surprises.";
+    check(ctx: AnalysisContext): Diagnostic[];
+}
+export declare const W108HiddenSideEffects: W108HiddenSideEffectsRule;
+export {};
+//# sourceMappingURL=w108-hidden-side-effects.d.ts.map