@syrin/cli 1.3.1 → 1.4.0

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

@@ -1,96 +0,0 @@
-/**
- * W004: 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: count "and" and "or" which often separate intents
-    const connectors = [' and ', ' or ', ', and ', ', or '];
-    let intentCount = 1; // Start with 1
-    const descLower = description.toLowerCase();
-    for (const connector of connectors) {
-        const matches = descLower.split(connector);
-        if (matches.length > 1) {
-            intentCount = Math.max(intentCount, matches.length);
-        }
-    }
-    return intentCount;
-}
-class W004OverloadedResponsibilityRule extends BaseRule {
-    id = 'W004';
-    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 W004OverloadedResponsibility = new W004OverloadedResponsibilityRule();
-//# sourceMappingURL=w004-overloaded-responsibility.js.map

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

@@ -1,53 +0,0 @@
-/**
- * W005: 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 { createW005Rule, DEFAULT_CONCRETE_NOUNS } from './w005-generic-description.js';
- * const customNouns = [...DEFAULT_CONCRETE_NOUNS, 'invoice', 'report'];
- * const customRule = createW005Rule(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 W005GenericDescriptionRule extends BaseRule {
-    private readonly concreteNouns;
-    readonly id = "W005";
-    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 W005 rule instance with custom concrete nouns.
- *
- * @param concreteNouns - Optional list of concrete nouns (defaults to DEFAULT_CONCRETE_NOUNS)
- * @returns A new W005GenericDescriptionRule instance
- *
- * @example
- * ```ts
- * import { createW005Rule, DEFAULT_CONCRETE_NOUNS } from './w005-generic-description.js';
- * const customNouns = [...DEFAULT_CONCRETE_NOUNS, 'invoice', 'report'];
- * const customRule = createW005Rule(customNouns);
- * ```
- */
-export declare function createW005Rule(concreteNouns?: readonly string[]): W005GenericDescriptionRule;
-export declare const W005GenericDescription: W005GenericDescriptionRule;
-export {};
-//# sourceMappingURL=w005-generic-description.d.ts.map

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

@@ -1,108 +0,0 @@
-/**
- * W005: 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 { createW005Rule, DEFAULT_CONCRETE_NOUNS } from './w005-generic-description.js';
- * const customNouns = [...DEFAULT_CONCRETE_NOUNS, 'invoice', 'report'];
- * const customRule = createW005Rule(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
-    const hasConcreteNoun = concreteNouns.some(noun => descLower.includes(noun));
-    // If has vague verb but no concrete noun, it's generic
-    return !hasConcreteNoun;
-}
-class W005GenericDescriptionRule extends BaseRule {
-    concreteNouns;
-    id = 'W005';
-    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 W005 rule instance with custom concrete nouns.
- *
- * @param concreteNouns - Optional list of concrete nouns (defaults to DEFAULT_CONCRETE_NOUNS)
- * @returns A new W005GenericDescriptionRule instance
- *
- * @example
- * ```ts
- * import { createW005Rule, DEFAULT_CONCRETE_NOUNS } from './w005-generic-description.js';
- * const customNouns = [...DEFAULT_CONCRETE_NOUNS, 'invoice', 'report'];
- * const customRule = createW005Rule(customNouns);
- * ```
- */
-export function createW005Rule(concreteNouns) {
-    return new W005GenericDescriptionRule(concreteNouns);
-}
-export const W005GenericDescription = new W005GenericDescriptionRule();
-//# sourceMappingURL=w005-generic-description.js.map

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

@@ -1,22 +0,0 @@
-/**
- * W006: 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 W006OptionalAsRequiredRule extends BaseRule {
-    readonly id = "W006";
-    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 W006OptionalAsRequired: W006OptionalAsRequiredRule;
-export {};
-//# sourceMappingURL=w006-optional-as-required.d.ts.map

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

@@ -1,44 +0,0 @@
-/**
- * W006: 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 W006OptionalAsRequiredRule extends BaseRule {
-    id = 'W006';
-    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
-            const isSourceOptional = fromField.nullable === true;
-            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 W006OptionalAsRequired = new W006OptionalAsRequiredRule();
-//# sourceMappingURL=w006-optional-as-required.js.map

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

@@ -1,23 +0,0 @@
-/**
- * W007: 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 W007BroadOutputSchemaRule extends BaseRule {
-    readonly id = "W007";
-    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 W007BroadOutputSchema: W007BroadOutputSchemaRule;
-export {};
-//# sourceMappingURL=w007-broad-output-schema.d.ts.map

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

@@ -1,37 +0,0 @@
-/**
- * W007: 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 W007BroadOutputSchemaRule extends BaseRule {
-    id = 'W007';
-    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 W007BroadOutputSchema = new W007BroadOutputSchemaRule();
-//# sourceMappingURL=w007-broad-output-schema.js.map

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

@@ -1,22 +0,0 @@
-/**
- * W008: 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 W008MultipleEntryPointsRule extends BaseRule {
-    readonly id = "W008";
-    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 W008MultipleEntryPoints: W008MultipleEntryPointsRule;
-export {};
-//# sourceMappingURL=w008-multiple-entry-points.d.ts.map

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

@@ -1,97 +0,0 @@
-/**
- * W008: 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 W008MultipleEntryPointsRule extends BaseRule {
-    id = 'W008';
-    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 W008MultipleEntryPoints = new W008MultipleEntryPointsRule();
-//# sourceMappingURL=w008-multiple-entry-points.js.map

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

@@ -1,23 +0,0 @@
-/**
- * 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';
-import type { AnalysisContext, Diagnostic } from '../../types.js';
-declare class W009HiddenSideEffectsRule extends BaseRule {
-    readonly id = "W009";
-    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 W009HiddenSideEffects: W009HiddenSideEffectsRule;
-export {};
-//# sourceMappingURL=w009-hidden-side-effects.d.ts.map

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

@@ -1,88 +0,0 @@
-/**
- * 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

@@ -1,22 +0,0 @@
-/**
- * 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