@rcrsr/rill-cli 0.6.0

package/dist/cli-exec.js

@@ -0,0 +1,326 @@
+#!/usr/bin/env node
+/**
+ * CLI Execution Entry Point
+ *
+ * Implements main(), parseArgs(), and executeScript() for rill-exec and rill-eval binaries.
+ * Handles file execution, stdin input, and module loading.
+ */
+import * as fs from 'fs/promises';
+import * as fsSync from 'fs';
+import * as path from 'path';
+import * as yaml from 'yaml';
+import { parse, execute, createRuntimeContext } from '@rcrsr/rill';
+import { formatOutput, formatError, determineExitCode, VERSION, detectHelpVersionFlag, } from './cli-shared.js';
+import { loadModule } from './cli-module-loader.js';
+import { explainError } from './cli-explain.js';
+/**
+ * Parse command-line arguments into structured command
+ *
+ * @param argv - Raw command-line arguments (typically process.argv.slice(2))
+ * @returns Parsed command object
+ */
+export function parseArgs(argv) {
+    // Check for --help or --version flags in any position
+    const helpVersionFlag = detectHelpVersionFlag(argv);
+    if (helpVersionFlag !== null) {
+        return helpVersionFlag;
+    }
+    // Check for --explain flag (IC-11)
+    const explainIndex = argv.findIndex((arg) => arg === '--explain');
+    if (explainIndex !== -1) {
+        const errorId = argv[explainIndex + 1];
+        if (!errorId) {
+            throw new Error('Missing error ID after --explain');
+        }
+        return { mode: 'explain', errorId };
+    }
+    // Parse format, verbose, and max-stack-depth flags (IC-11)
+    let format = 'human';
+    let verbose = false;
+    let maxStackDepth = 10;
+    const formatIndex = argv.findIndex((arg) => arg === '--format');
+    if (formatIndex !== -1) {
+        const formatValue = argv[formatIndex + 1];
+        // AC-15: Unknown --format value
+        if (formatValue !== 'human' &&
+            formatValue !== 'json' &&
+            formatValue !== 'compact') {
+            throw new Error(`Invalid --format value: ${formatValue}. Must be one of: human, json, compact`);
+        }
+        format = formatValue;
+    }
+    if (argv.includes('--verbose')) {
+        verbose = true;
+    }
+    const maxStackDepthIndex = argv.findIndex((arg) => arg === '--max-stack-depth');
+    if (maxStackDepthIndex !== -1) {
+        const depthValue = argv[maxStackDepthIndex + 1];
+        if (!depthValue) {
+            throw new Error('Missing value after --max-stack-depth');
+        }
+        const depth = parseInt(depthValue, 10);
+        if (isNaN(depth) || depth < 1 || depth > 100) {
+            throw new Error('--max-stack-depth must be a number between 1 and 100');
+        }
+        maxStackDepth = depth;
+    }
+    // Check for unknown flags
+    const knownFlags = [
+        '--help',
+        '-h',
+        '--version',
+        '-v',
+        '--explain',
+        '--format',
+        '--verbose',
+        '--max-stack-depth',
+    ];
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg && arg.startsWith('--')) {
+            if (!knownFlags.includes(arg)) {
+                throw new Error(`Unknown option: ${arg}`);
+            }
+            // Skip next argument if this is a flag that takes a value
+            if (arg === '--format' ||
+                arg === '--max-stack-depth' ||
+                arg === '--explain') {
+                i++;
+            }
+        }
+        else if (arg && arg.startsWith('-') && arg !== '-') {
+            if (!knownFlags.includes(arg)) {
+                throw new Error(`Unknown option: ${arg}`);
+            }
+        }
+    }
+    // Determine mode from first positional argument (skip flags and their values)
+    let firstArg;
+    const positionalArgs = [];
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (!arg)
+            continue;
+        // Skip flags
+        if (knownFlags.includes(arg)) {
+            // Skip the flag's value if it takes one
+            if (arg === '--format' ||
+                arg === '--max-stack-depth' ||
+                arg === '--explain') {
+                i++;
+            }
+            continue;
+        }
+        // This is a positional argument
+        if (!firstArg) {
+            firstArg = arg;
+        }
+        positionalArgs.push(arg);
+    }
+    if (!firstArg) {
+        throw new Error('Missing file argument');
+    }
+    // Eval mode is not supported in rill-exec (only rill-eval)
+    // This function is shared but context determines valid modes
+    if (firstArg === '-e') {
+        if (positionalArgs.length < 2) {
+            throw new Error('Missing expression after -e');
+        }
+        return { mode: 'eval', expression: positionalArgs[1] };
+    }
+    // Exec mode (file or stdin)
+    const file = firstArg;
+    const args = positionalArgs.slice(1);
+    return { mode: 'exec', file, args, format, verbose, maxStackDepth };
+}
+/**
+ * Execute a Rill script file with arguments and module support
+ *
+ * @param file - File path or '-' for stdin
+ * @param args - Command-line arguments to pass as $ pipe value
+ * @param options - Execution options
+ * @returns Execution result with value, variables, and source text
+ * @throws Error if file not found or execution fails
+ */
+export async function executeScript(file, args, options) {
+    // Use pre-read source if provided, otherwise read from file or stdin
+    let source;
+    let scriptPath;
+    if (options?.source !== undefined) {
+        source = options.source;
+        scriptPath =
+            file === '-'
+                ? path.resolve(process.cwd(), '<stdin>')
+                : path.resolve(file);
+    }
+    else if (file === '-' || options?.stdin) {
+        // Read from stdin (must use sync API for stdin)
+        source = fsSync.readFileSync(0, 'utf-8');
+        scriptPath = path.resolve(process.cwd(), '<stdin>');
+    }
+    else {
+        // Check if file exists
+        try {
+            await fs.access(file);
+        }
+        catch {
+            throw new Error(`File not found: ${file}`);
+        }
+        // Read from file
+        source = await fs.readFile(file, 'utf-8');
+        scriptPath = path.resolve(file);
+    }
+    // Parse the script
+    const ast = parse(source);
+    // Extract frontmatter for use: declarations
+    const frontmatter = ast.frontmatter
+        ? (yaml.parse(ast.frontmatter.content) ?? {})
+        : {};
+    // Load modules if use: declarations exist
+    const variables = {};
+    if (frontmatter['use'] && Array.isArray(frontmatter['use'])) {
+        const cache = new Map();
+        for (const entry of frontmatter['use']) {
+            if (typeof entry === 'object' && entry !== null) {
+                const [name, modulePath] = Object.entries(entry)[0];
+                variables[name] = await loadModule(modulePath, scriptPath, cache);
+            }
+        }
+    }
+    // Create runtime context with modules
+    const ctx = createRuntimeContext({
+        variables,
+        callbacks: {
+            onLog: (value) => console.log(formatOutput(value)),
+        },
+    });
+    // Set pipe value to arguments (string array)
+    ctx.pipeValue = args;
+    // Execute the script and return with source
+    const result = await execute(ast, ctx);
+    return { ...result, source };
+}
+/**
+ * Entry point for rill-exec and rill-eval binaries
+ *
+ * Parses command-line arguments, executes scripts, and handles errors.
+ * Writes results to stdout and errors to stderr.
+ * Sets process.exit(1) on any error.
+ */
+export async function main() {
+    let source;
+    let formatOptions;
+    try {
+        const parsed = parseArgs(process.argv.slice(2));
+        switch (parsed.mode) {
+            case 'help':
+                console.log(`Usage:
+  rill-exec <script.rill> [args...]  Execute a Rill script file
+  rill-exec -                        Read script from stdin
+  rill-exec --help                   Show this help message
+  rill-exec --version                Show version information
+  rill-exec --explain RILL-XXXX      Show error documentation
+
+Options:
+  --format <format>         Output format: human, json, compact (default: human)
+  --verbose                 Include additional error details
+  --max-stack-depth <n>     Maximum call stack depth to display (default: 10, range: 1-100)
+
+Arguments:
+  args are passed to the script as a list of strings in $ (pipe value)
+
+Examples:
+  rill-exec script.rill
+  rill-exec script.rill arg1 arg2
+  rill-exec --format json script.rill
+  rill-exec --verbose --max-stack-depth 20 script.rill
+  rill-exec --explain RILL-R009
+  echo "log(\\"hello\\")" | rill-exec -`);
+                return;
+            case 'version': {
+                console.log(VERSION);
+                return;
+            }
+            case 'explain': {
+                // AC-16: Handle --explain command
+                const documentation = explainError(parsed.errorId);
+                if (documentation === null) {
+                    // AC-16: Malformed errorId shows usage help
+                    console.error(`Invalid error ID: ${parsed.errorId}`);
+                    console.error('Error ID must be in format RILL-{L|P|R|C}{3-digit}, e.g., RILL-R009');
+                    process.exit(1);
+                    return;
+                }
+                console.log(documentation);
+                return;
+            }
+            case 'eval':
+                // This shouldn't happen in rill-exec, but handle it anyway
+                console.error('Eval mode not supported in rill-exec. Use rill-eval instead.');
+                process.exit(1);
+                return;
+            case 'exec': {
+                // Store format options for error handling
+                formatOptions = {
+                    format: parsed.format,
+                    verbose: parsed.verbose,
+                    maxStackDepth: parsed.maxStackDepth,
+                };
+                // Read source early so it's available for error enrichment even if parsing fails
+                if (parsed.file === '-') {
+                    source = fsSync.readFileSync(0, 'utf-8');
+                }
+                else {
+                    try {
+                        source = await fs.readFile(parsed.file, 'utf-8');
+                    }
+                    catch {
+                        throw new Error(`File not found: ${parsed.file}`);
+                    }
+                }
+                // Execute mode
+                const result = await executeScript(parsed.file, parsed.args, {
+                    source,
+                });
+                const { code, message } = determineExitCode(result.value);
+                // Output message if present, otherwise output the result value
+                if (message !== undefined) {
+                    console.log(message);
+                }
+                else {
+                    console.log(formatOutput(result.value));
+                }
+                // Exit with computed code
+                process.exit(code);
+            }
+        }
+    }
+    catch (err) {
+        if (err instanceof Error) {
+            // IC-11: Pass source text and format options to formatError
+            console.error(formatError(err, source, {
+                format: formatOptions?.format ?? 'human',
+                verbose: formatOptions?.verbose ?? false,
+                includeCallStack: true,
+                maxCallStackDepth: formatOptions?.maxStackDepth ?? 10,
+            }));
+        }
+        else {
+            console.error(formatError(new Error(String(err)), source, {
+                format: formatOptions?.format ?? 'human',
+                verbose: formatOptions?.verbose ?? false,
+                includeCallStack: true,
+                maxCallStackDepth: formatOptions?.maxStackDepth ?? 10,
+            }));
+        }
+        process.exit(1);
+    }
+}
+// Only run main if not in test environment
+const shouldRunMain = process.env['NODE_ENV'] !== 'test' &&
+    !process.env['VITEST'] &&
+    !process.env['VITEST_WORKER_ID'];
+if (shouldRunMain) {
+    main();
+}
+//# sourceMappingURL=cli-exec.js.map

package/dist/cli-exec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-exec.js","sourceRoot":"","sources":["../src/cli-exec.ts"],"names":[],"mappings":"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"}

package/dist/cli-explain.d.ts

@@ -0,0 +1,24 @@
+/**
+ * CLI Error Explanation
+ * Function for rendering full error documentation
+ */
+/**
+ * Render full error documentation for --explain command.
+ *
+ * Constraints:
+ * - Lookup from ERROR_REGISTRY
+ * - Renders cause, resolution, examples sections
+ *
+ * @param errorId - Error identifier (format: RILL-{category}{3-digit})
+ * @returns Formatted documentation string, or null if errorId is invalid/unknown
+ *
+ * @example
+ * explainError("RILL-R009")
+ * // Returns: formatted documentation with cause, resolution, examples
+ *
+ * @example
+ * explainError("invalid")
+ * // Returns: null
+ */
+export declare function explainError(errorId: string): string | null;
+//# sourceMappingURL=cli-explain.d.ts.map

package/dist/cli-explain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-explain.d.ts","sourceRoot":"","sources":["../src/cli-explain.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAkD3D"}

package/dist/cli-explain.js

@@ -0,0 +1,68 @@
+/**
+ * CLI Error Explanation
+ * Function for rendering full error documentation
+ */
+import { ERROR_REGISTRY } from '@rcrsr/rill';
+/**
+ * Render full error documentation for --explain command.
+ *
+ * Constraints:
+ * - Lookup from ERROR_REGISTRY
+ * - Renders cause, resolution, examples sections
+ *
+ * @param errorId - Error identifier (format: RILL-{category}{3-digit})
+ * @returns Formatted documentation string, or null if errorId is invalid/unknown
+ *
+ * @example
+ * explainError("RILL-R009")
+ * // Returns: formatted documentation with cause, resolution, examples
+ *
+ * @example
+ * explainError("invalid")
+ * // Returns: null
+ */
+export function explainError(errorId) {
+    // EC-12: Invalid errorId format returns null
+    const errorIdPattern = /^RILL-[LPRC]\d{3}$/;
+    if (!errorIdPattern.test(errorId)) {
+        return null;
+    }
+    // EC-13: Unknown errorId returns null
+    const definition = ERROR_REGISTRY.get(errorId);
+    if (!definition) {
+        return null;
+    }
+    // Build documentation sections
+    const sections = [];
+    // Header: errorId and description
+    sections.push(`${definition.errorId}: ${definition.description}`);
+    sections.push('');
+    // Cause section (if present)
+    if (definition.cause) {
+        sections.push('Cause:');
+        sections.push(`  ${definition.cause}`);
+        sections.push('');
+    }
+    // Resolution section (if present)
+    if (definition.resolution) {
+        sections.push('Resolution:');
+        sections.push(`  ${definition.resolution}`);
+        sections.push('');
+    }
+    // Examples section (if present)
+    if (definition.examples && definition.examples.length > 0) {
+        sections.push('Examples:');
+        for (const example of definition.examples) {
+            sections.push(`  ${example.description}`);
+            sections.push('');
+            // Indent code block
+            const codeLines = example.code.split('\n');
+            for (const line of codeLines) {
+                sections.push(`    ${line}`);
+            }
+            sections.push('');
+        }
+    }
+    return sections.join('\n').trimEnd();
+}
+//# sourceMappingURL=cli-explain.js.map

package/dist/cli-explain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-explain.js","sourceRoot":"","sources":["../src/cli-explain.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE7C;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,YAAY,CAAC,OAAe;IAC1C,6CAA6C;IAC7C,MAAM,cAAc,GAAG,oBAAoB,CAAC;IAC5C,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QAClC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,sCAAsC;IACtC,MAAM,UAAU,GAAG,cAAc,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAC/C,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,+BAA+B;IAC/B,MAAM,QAAQ,GAAa,EAAE,CAAC;IAE9B,kCAAkC;IAClC,QAAQ,CAAC,IAAI,CAAC,GAAG,UAAU,CAAC,OAAO,KAAK,UAAU,CAAC,WAAW,EAAE,CAAC,CAAC;IAClE,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAElB,6BAA6B;IAC7B,IAAI,UAAU,CAAC,KAAK,EAAE,CAAC;QACrB,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACxB,QAAQ,CAAC,IAAI,CAAC,KAAK,UAAU,CAAC,KAAK,EAAE,CAAC,CAAC;QACvC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACpB,CAAC;IAED,kCAAkC;IAClC,IAAI,UAAU,CAAC,UAAU,EAAE,CAAC;QAC1B,QAAQ,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;QAC7B,QAAQ,CAAC,IAAI,CAAC,KAAK,UAAU,CAAC,UAAU,EAAE,CAAC,CAAC;QAC5C,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACpB,CAAC;IAED,gCAAgC;IAChC,IAAI,UAAU,CAAC,QAAQ,IAAI,UAAU,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1D,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QAC3B,KAAK,MAAM,OAAO,IAAI,UAAU,CAAC,QAAQ,EAAE,CAAC;YAC1C,QAAQ,CAAC,IAAI,CAAC,KAAK,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;YAC1C,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YAClB,oBAAoB;YACpB,MAAM,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YAC3C,KAAK,MAAM,IAAI,IAAI,SAAS,EAAE,CAAC;gBAC7B,QAAQ,CAAC,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC;YAC/B,CAAC;YACD,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACpB,CAAC;IACH,CAAC;IAED,OAAO,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,CAAC;AACvC,CAAC"}

package/dist/cli-lsp-diagnostic.d.ts

@@ -0,0 +1,35 @@
+/**
+ * CLI LSP Diagnostic Conversion
+ * Convert RillError to LSP Diagnostic format
+ */
+import type { RillError } from '@rcrsr/rill';
+export interface LspDiagnostic {
+    readonly range: LspRange | null;
+    readonly severity: 1 | 2 | 3;
+    readonly code: string;
+    readonly source: 'rill';
+    readonly message: string;
+    readonly suggestions?: string[] | undefined;
+}
+export interface LspRange {
+    readonly start: LspPosition;
+    readonly end: LspPosition;
+}
+export interface LspPosition {
+    readonly line: number;
+    readonly character: number;
+}
+/**
+ * Convert RillError to LSP Diagnostic format.
+ *
+ * Constraints:
+ * - LSP uses zero-based line/character positions
+ * - Severity mapping: Error=1, Warning=2, Info=3
+ * - Source is always 'rill'
+ * - Returns diagnostic with null range when error has no span
+ *
+ * @param error - RillError to convert
+ * @returns LSP Diagnostic
+ */
+export declare function toLspDiagnostic(error: RillError): LspDiagnostic;
+//# sourceMappingURL=cli-lsp-diagnostic.d.ts.map

package/dist/cli-lsp-diagnostic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-lsp-diagnostic.d.ts","sourceRoot":"","sources":["../src/cli-lsp-diagnostic.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAiC,MAAM,aAAa,CAAC;AAO5E,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;CAC7C;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAC;CAC3B;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,GAAG,aAAa,CA8C/D"}

package/dist/cli-lsp-diagnostic.js

@@ -0,0 +1,98 @@
+/**
+ * CLI LSP Diagnostic Conversion
+ * Convert RillError to LSP Diagnostic format
+ */
+import { ERROR_REGISTRY } from '@rcrsr/rill';
+// ============================================================
+// LSP DIAGNOSTIC CONVERSION
+// ============================================================
+/**
+ * Convert RillError to LSP Diagnostic format.
+ *
+ * Constraints:
+ * - LSP uses zero-based line/character positions
+ * - Severity mapping: Error=1, Warning=2, Info=3
+ * - Source is always 'rill'
+ * - Returns diagnostic with null range when error has no span
+ *
+ * @param error - RillError to convert
+ * @returns LSP Diagnostic
+ */
+export function toLspDiagnostic(error) {
+    // Get error definition for severity mapping
+    const definition = ERROR_REGISTRY.get(error.errorId);
+    const errorSeverity = definition?.severity ?? 'error';
+    // Map ErrorSeverity to LSP severity (Error=1, Warning=2, Info=3)
+    const severity = mapSeverityToLsp(errorSeverity);
+    // Extract message without location suffix
+    const message = error.message.replace(/ at \d+:\d+$/, '');
+    // Convert span to LSP range (zero-based positions)
+    // EC-11: Missing span returns diagnostic with null range
+    const range = error.location
+        ? {
+            start: sourceLocationToLspPosition(error.location),
+            end: sourceLocationToLspPosition(error.location),
+        }
+        : null;
+    // Extract suggestions if present (max 3)
+    const errorData = error.toData();
+    const contextSuggestions = errorData.context?.['suggestions'];
+    let suggestions;
+    if (contextSuggestions) {
+        if (Array.isArray(contextSuggestions) && contextSuggestions.length > 0) {
+            const filtered = contextSuggestions
+                .slice(0, 3)
+                .map((s) => String(s))
+                .filter((s) => s.length > 0);
+            if (filtered.length > 0) {
+                suggestions = filtered;
+            }
+        }
+    }
+    // Build diagnostic
+    return {
+        range,
+        severity,
+        code: error.errorId,
+        source: 'rill',
+        message,
+        ...(suggestions ? { suggestions } : {}),
+    };
+}
+/**
+ * Convert SourceLocation to zero-based LspPosition.
+ *
+ * Rill uses 1-based line and column numbers; LSP uses 0-based.
+ *
+ * @param location - Source location (1-based line, 1-based column)
+ * @returns LSP position (0-based line, 0-based character)
+ */
+function sourceLocationToLspPosition(location) {
+    return {
+        line: location.line - 1, // Convert 1-based to 0-based
+        character: location.column - 1, // Convert 1-based to 0-based
+    };
+}
+/**
+ * Map ErrorSeverity to LSP severity code.
+ *
+ * Mapping:
+ * - 'error' -> 1 (Error)
+ * - 'warning' -> 2 (Warning)
+ * - (future) 'info' -> 3 (Information)
+ *
+ * @param severity - Error severity level
+ * @returns LSP severity code (1, 2, or 3)
+ */
+function mapSeverityToLsp(severity) {
+    switch (severity) {
+        case 'error':
+            return 1;
+        case 'warning':
+            return 2;
+        default:
+            // Future-proof: if other severities are added, default to error
+            return 1;
+    }
+}
+//# sourceMappingURL=cli-lsp-diagnostic.js.map

package/dist/cli-lsp-diagnostic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-lsp-diagnostic.js","sourceRoot":"","sources":["../src/cli-lsp-diagnostic.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAyB7C,+DAA+D;AAC/D,4BAA4B;AAC5B,+DAA+D;AAE/D;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,eAAe,CAAC,KAAgB;IAC9C,4CAA4C;IAC5C,MAAM,UAAU,GAAG,cAAc,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACrD,MAAM,aAAa,GAAkB,UAAU,EAAE,QAAQ,IAAI,OAAO,CAAC;IAErE,iEAAiE;IACjE,MAAM,QAAQ,GAAG,gBAAgB,CAAC,aAAa,CAAC,CAAC;IAEjD,0CAA0C;IAC1C,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,cAAc,EAAE,EAAE,CAAC,CAAC;IAE1D,mDAAmD;IACnD,yDAAyD;IACzD,MAAM,KAAK,GAAG,KAAK,CAAC,QAAQ;QAC1B,CAAC,CAAC;YACE,KAAK,EAAE,2BAA2B,CAAC,KAAK,CAAC,QAAQ,CAAC;YAClD,GAAG,EAAE,2BAA2B,CAAC,KAAK,CAAC,QAAQ,CAAC;SACjD;QACH,CAAC,CAAC,IAAI,CAAC;IAET,yCAAyC;IACzC,MAAM,SAAS,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;IACjC,MAAM,kBAAkB,GAAG,SAAS,CAAC,OAAO,EAAE,CAAC,aAAa,CAAC,CAAC;IAC9D,IAAI,WAAiC,CAAC;IAEtC,IAAI,kBAAkB,EAAE,CAAC;QACvB,IAAI,KAAK,CAAC,OAAO,CAAC,kBAAkB,CAAC,IAAI,kBAAkB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACvE,MAAM,QAAQ,GAAG,kBAAkB;iBAChC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC;iBACX,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;iBACrB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;YAC/B,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACxB,WAAW,GAAG,QAAQ,CAAC;YACzB,CAAC;QACH,CAAC;IACH,CAAC;IAED,mBAAmB;IACnB,OAAO;QACL,KAAK;QACL,QAAQ;QACR,IAAI,EAAE,KAAK,CAAC,OAAO;QACnB,MAAM,EAAE,MAAM;QACd,OAAO;QACP,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACxC,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,2BAA2B,CAAC,QAAwB;IAC3D,OAAO;QACL,IAAI,EAAE,QAAQ,CAAC,IAAI,GAAG,CAAC,EAAE,6BAA6B;QACtD,SAAS,EAAE,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,6BAA6B;KAC9D,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAS,gBAAgB,CAAC,QAAuB;IAC/C,QAAQ,QAAQ,EAAE,CAAC;QACjB,KAAK,OAAO;YACV,OAAO,CAAC,CAAC;QACX,KAAK,SAAS;YACZ,OAAO,CAAC,CAAC;QACX;YACE,gEAAgE;YAChE,OAAO,CAAC,CAAC;IACb,CAAC;AACH,CAAC"}

package/dist/cli-module-loader.d.ts

@@ -0,0 +1,19 @@
+/**
+ * CLI Module Loader
+ *
+ * Implements module loading for the Rill CLI with circular dependency detection.
+ * See docs/integration-modules.md for module convention specification.
+ */
+import type { RillValue } from '@rcrsr/rill';
+/**
+ * Load a module and its dependencies recursively.
+ *
+ * @param specifier - Module path (relative or absolute)
+ * @param fromPath - Path of the importing file
+ * @param cache - Module cache keyed by canonical path
+ * @param chain - Set of paths in current import chain for circular detection
+ * @returns Dict of exported values
+ * @throws Error if module not found or circular dependency detected
+ */
+export declare function loadModule(specifier: string, fromPath: string, cache: Map<string, Record<string, RillValue>>, chain?: Set<string>): Promise<Record<string, RillValue>>;
+//# sourceMappingURL=cli-module-loader.d.ts.map

package/dist/cli-module-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-module-loader.d.ts","sourceRoot":"","sources":["../src/cli-module-loader.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C;;;;;;;;;GASG;AACH,wBAAsB,UAAU,CAC9B,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,EAC7C,KAAK,GAAE,GAAG,CAAC,MAAM,CAAa,GAC7B,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAuEpC"}