@rcrsr/rill-cli 0.6.0

package/src/cli-lsp-diagnostic.ts

@@ -0,0 +1,132 @@
+/**
+ * CLI LSP Diagnostic Conversion
+ * Convert RillError to LSP Diagnostic format
+ */
+
+import type { RillError, SourceLocation, ErrorSeverity } from '@rcrsr/rill';
+import { ERROR_REGISTRY } from '@rcrsr/rill';
+
+// ============================================================
+// PUBLIC TYPES
+// ============================================================
+
+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;
+}
+
+// ============================================================
+// 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: RillError): LspDiagnostic {
+  // Get error definition for severity mapping
+  const definition = ERROR_REGISTRY.get(error.errorId);
+  const errorSeverity: 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: string[] | undefined;
+
+  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: SourceLocation): LspPosition {
+  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: ErrorSeverity): 1 | 2 | 3 {
+  switch (severity) {
+    case 'error':
+      return 1;
+    case 'warning':
+      return 2;
+    default:
+      // Future-proof: if other severities are added, default to error
+      return 1;
+  }
+}

package/src/cli-module-loader.ts

@@ -0,0 +1,101 @@
+/**
+ * CLI Module Loader
+ *
+ * Implements module loading for the Rill CLI with circular dependency detection.
+ * See docs/integration-modules.md for module convention specification.
+ */
+
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import * as yaml from 'yaml';
+import { parse } from '@rcrsr/rill';
+import { execute, createRuntimeContext } from '@rcrsr/rill';
+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 async function loadModule(
+  specifier: string,
+  fromPath: string,
+  cache: Map<string, Record<string, RillValue>>,
+  chain: Set<string> = new Set()
+): Promise<Record<string, RillValue>> {
+  // Resolve to absolute canonical path
+  const absolutePath = path.resolve(path.dirname(fromPath), specifier);
+
+  // Check for circular dependency
+  if (chain.has(absolutePath)) {
+    const cycle = [...chain, absolutePath].join(' -> ');
+    throw new Error(`Circular dependency detected: ${cycle}`);
+  }
+
+  // Return cached module if already loaded
+  if (cache.has(absolutePath)) {
+    return cache.get(absolutePath)!;
+  }
+
+  // Check if module file exists
+  try {
+    await fs.access(absolutePath);
+  } catch {
+    throw new Error(`Module not found: ${specifier}`);
+  }
+
+  // Add to chain to detect cycles in dependencies
+  chain.add(absolutePath);
+
+  try {
+    // Load and parse module source
+    const source = await fs.readFile(absolutePath, 'utf-8');
+    const ast = parse(source);
+
+    // Extract frontmatter (yaml.parse returns null for empty content)
+    const frontmatter: Record<string, unknown> = ast.frontmatter
+      ? ((yaml.parse(ast.frontmatter.content) as Record<
+          string,
+          unknown
+        > | null) ?? {})
+      : {};
+
+    // Resolve dependencies first
+    const imports: Record<string, RillValue> = {};
+    if (frontmatter['use'] && Array.isArray(frontmatter['use'])) {
+      for (const entry of frontmatter['use']) {
+        if (typeof entry === 'object' && entry !== null) {
+          const [name, depPath] = Object.entries(entry)[0] as [string, string];
+          imports[name] = await loadModule(depPath, absolutePath, cache, chain);
+        }
+      }
+    }
+
+    // Execute module with dependencies
+    const ctx = createRuntimeContext({ variables: imports });
+    const result = await execute(ast, ctx);
+
+    // Extract exports
+    const exports: Record<string, RillValue> = {};
+    const exportList: unknown = frontmatter['export'];
+    if (Array.isArray(exportList)) {
+      for (const name of exportList) {
+        if (typeof name === 'string' && result.variables[name] !== undefined) {
+          exports[name] = result.variables[name];
+        }
+      }
+    }
+
+    // Cache and return
+    cache.set(absolutePath, exports);
+    return exports;
+  } finally {
+    // Remove from chain after processing
+    chain.delete(absolutePath);
+  }
+}

package/src/cli-shared.ts

@@ -0,0 +1,187 @@
+/**
+ * CLI Shared Utilities
+ * Common formatting functions for CLI tools
+ */
+
+import { isCallable, VERSION } from '@rcrsr/rill';
+import type { RillValue } from '@rcrsr/rill';
+import { ParseError, RuntimeError } from '@rcrsr/rill';
+import { LexerError } from '@rcrsr/rill';
+import { enrichError, type ScopeInfo } from './cli-error-enrichment.js';
+import {
+  formatError as formatEnrichedError,
+  type FormatOptions,
+} from './cli-error-formatter.js';
+
+/**
+ * Convert execution result to human-readable string
+ *
+ * @param value - The value to format
+ * @returns Formatted string representation
+ */
+export function formatOutput(value: RillValue): string {
+  if (value === null) return 'null';
+  if (typeof value === 'string') return value;
+  if (typeof value === 'number' || typeof value === 'boolean') {
+    return String(value);
+  }
+  if (isCallable(value)) return '[closure]';
+  return JSON.stringify(value, null, 2);
+}
+
+/**
+ * Format error for stderr output
+ *
+ * When source is available, uses enrichment pipeline to add source snippets and suggestions.
+ * Otherwise, falls back to simple formatting for backward compatibility.
+ *
+ * @param err - The error to format
+ * @param source - Optional source code for enrichment
+ * @param options - Optional format options (defaults to human format)
+ * @param scope - Optional scope information for suggestions
+ * @returns Formatted error message
+ */
+export function formatError(
+  err: Error,
+  source?: string,
+  options?: Partial<FormatOptions>,
+  scope?: ScopeInfo
+): string {
+  // IC-12: Use enrichment pipeline when source is available and error is RillError
+  if (
+    source !== undefined &&
+    (err instanceof LexerError ||
+      err instanceof ParseError ||
+      err instanceof RuntimeError)
+  ) {
+    try {
+      const enriched = enrichError(err, source, scope);
+      const formatOpts: FormatOptions = {
+        format: options?.format ?? 'human',
+        verbose: options?.verbose ?? false,
+        includeCallStack: options?.includeCallStack ?? false,
+        maxCallStackDepth: options?.maxCallStackDepth ?? 10,
+      };
+      return formatEnrichedError(enriched, formatOpts);
+    } catch {
+      // If enrichment fails, fall back to simple formatting
+    }
+  }
+
+  // IC-12: Fallback to existing behavior for backward compatibility
+  if (err instanceof LexerError) {
+    const location = err.location;
+    return `Lexer error at line ${location.line}: ${err.message.replace(/ at \d+:\d+$/, '')}`;
+  }
+
+  if (err instanceof ParseError) {
+    const location = err.location;
+    if (location) {
+      return `Parse error at line ${location.line}: ${err.message.replace(/ at \d+:\d+$/, '')}`;
+    }
+    return `Parse error: ${err.message}`;
+  }
+
+  if (err instanceof RuntimeError) {
+    const location = err.location;
+    const baseMessage = err.message.replace(/ at \d+:\d+$/, '');
+    if (location) {
+      return `Runtime error at line ${location.line}: ${baseMessage}`;
+    }
+    return `Runtime error: ${baseMessage}`;
+  }
+
+  // Handle file not found errors (ENOENT)
+  if (
+    err instanceof Error &&
+    'code' in err &&
+    err.code === 'ENOENT' &&
+    'path' in err
+  ) {
+    return `File not found: ${err.path}`;
+  }
+
+  // Handle module errors
+  if (err.message.includes('Cannot find module')) {
+    return `Module error: ${err.message}`;
+  }
+
+  return err.message;
+}
+
+/**
+ * Determine exit code from script result
+ *
+ * Implements exit code semantics per language spec:
+ * - true / non-empty string: exit 0
+ * - false / empty string: exit 1
+ * - [0, "message"]: exit 0 with message
+ * - [1, "message"]: exit 1 with message
+ *
+ * @param value - The script return value
+ * @returns Exit code and optional message
+ */
+export function determineExitCode(value: RillValue): {
+  code: number;
+  message?: string;
+} {
+  // Handle tuple format: [code, message]
+  if (Array.isArray(value)) {
+    if (value.length >= 2) {
+      const code = value[0];
+      const message = value[1];
+
+      // Validate code is 0 or 1
+      if (typeof code === 'number' && (code === 0 || code === 1)) {
+        // Return with message if provided as string
+        if (typeof message === 'string' && message !== '') {
+          return { code, message };
+        }
+        return { code };
+      }
+    }
+    // Non-conforming array: treat as truthy (exit 0)
+    return { code: 0 };
+  }
+
+  // Boolean values
+  if (typeof value === 'boolean') {
+    return { code: value ? 0 : 1 };
+  }
+
+  // String values
+  if (typeof value === 'string') {
+    return { code: value === '' ? 1 : 0 };
+  }
+
+  // All other values (number, dict, closure, etc.) are truthy: exit 0
+  return { code: 0 };
+}
+
+/**
+ * Detect help or version flags in CLI argument array.
+ * Checks for --help, -h, --version, -v in any position.
+ *
+ * @param argv - Command-line arguments (process.argv.slice(2))
+ * @returns Object with mode if flag found, null otherwise
+ */
+export function detectHelpVersionFlag(
+  argv: string[]
+): { mode: 'help' | 'version' } | null {
+  // Help takes precedence over version
+  if (argv.includes('--help') || argv.includes('-h')) {
+    return { mode: 'help' };
+  }
+  if (argv.includes('--version') || argv.includes('-v')) {
+    return { mode: 'version' };
+  }
+  return null;
+}
+
+/**
+ * Package version string (re-exported from version-data.ts)
+ *
+ * This replaces the previous async readVersion() function with a synchronous constant.
+ * The version is now generated at build time by packages/core/scripts/generate-version.ts.
+ */
+export { VERSION };

package/tests/check/cli-check.test.ts

@@ -0,0 +1,189 @@
+/**
+ * Tests for parseCheckArgs function
+ *
+ * Test Coverage Matrix (maps TCs to specification requirements):
+ * TC-1: --help flag returns help mode [AC-S6]
+ * TC-2: --version flag returns version mode [AC-S5]
+ * TC-3: Unknown flag throws error [EC-1]
+ * TC-4: Missing file throws error [EC-2]
+ * TC-5: --fix flag parsed correctly [IR-2]
+ * TC-6: --verbose flag parsed correctly [IR-2]
+ * TC-7: --format text parsed correctly [IR-2]
+ * TC-8: --format json parsed correctly [IR-2]
+ * TC-9: --format with invalid value throws error [EC-1]
+ */
+
+import { describe, it, expect } from 'vitest';
+import { parseCheckArgs } from '../../src/cli-check.js';
+
+describe('parseCheckArgs', () => {
+  describe('help and version modes', () => {
+    it('returns help mode when --help flag present [TC-1]', () => {
+      const result = parseCheckArgs(['--help']);
+      expect(result).toEqual({ mode: 'help' });
+    });
+
+    it('returns help mode when -h flag present [TC-1]', () => {
+      const result = parseCheckArgs(['-h']);
+      expect(result).toEqual({ mode: 'help' });
+    });
+
+    it('returns help mode when --help flag present with other args [TC-1]', () => {
+      const result = parseCheckArgs(['file.rill', '--help', '--fix']);
+      expect(result).toEqual({ mode: 'help' });
+    });
+
+    it('returns version mode when --version flag present [TC-2]', () => {
+      const result = parseCheckArgs(['--version']);
+      expect(result).toEqual({ mode: 'version' });
+    });
+
+    it('returns version mode when -v flag present [TC-2]', () => {
+      const result = parseCheckArgs(['-v']);
+      expect(result).toEqual({ mode: 'version' });
+    });
+
+    it('returns version mode when --version flag present with other args [TC-2]', () => {
+      const result = parseCheckArgs(['file.rill', '--version', '--fix']);
+      expect(result).toEqual({ mode: 'version' });
+    });
+  });
+
+  describe('error cases', () => {
+    it('throws error for unknown flag [TC-3]', () => {
+      expect(() => parseCheckArgs(['--unknown', 'file.rill'])).toThrow(
+        'Unknown option: --unknown'
+      );
+    });
+
+    it('throws error for unknown short flag [TC-3]', () => {
+      expect(() => parseCheckArgs(['-x', 'file.rill'])).toThrow(
+        'Unknown option: -x'
+      );
+    });
+
+    it('throws error when file argument missing [TC-4]', () => {
+      expect(() => parseCheckArgs(['--fix'])).toThrow('Missing file argument');
+    });
+
+    it('throws error when only flags provided [TC-4]', () => {
+      expect(() => parseCheckArgs(['--fix', '--verbose'])).toThrow(
+        'Missing file argument'
+      );
+    });
+
+    it('throws error when --format has no value [TC-9]', () => {
+      expect(() => parseCheckArgs(['file.rill', '--format'])).toThrow(
+        '--format requires argument: text or json'
+      );
+    });
+
+    it('throws error when --format value is another flag [TC-9]', () => {
+      expect(() => parseCheckArgs(['file.rill', '--format', '--fix'])).toThrow(
+        '--format requires argument: text or json'
+      );
+    });
+
+    it('throws error when --format value is invalid [TC-9]', () => {
+      expect(() => parseCheckArgs(['file.rill', '--format', 'xml'])).toThrow(
+        'Invalid format: xml. Expected text or json'
+      );
+    });
+  });
+
+  describe('check mode parsing', () => {
+    it('parses file path correctly [TC-4]', () => {
+      const result = parseCheckArgs(['test.rill']);
+      expect(result).toEqual({
+        mode: 'check',
+        file: 'test.rill',
+        fix: false,
+        verbose: false,
+        format: 'text',
+      });
+    });
+
+    it('parses --fix flag correctly [TC-5]', () => {
+      const result = parseCheckArgs(['test.rill', '--fix']);
+      expect(result).toEqual({
+        mode: 'check',
+        file: 'test.rill',
+        fix: true,
+        verbose: false,
+        format: 'text',
+      });
+    });
+
+    it('parses --verbose flag correctly [TC-6]', () => {
+      const result = parseCheckArgs(['test.rill', '--verbose']);
+      expect(result).toEqual({
+        mode: 'check',
+        file: 'test.rill',
+        fix: false,
+        verbose: true,
+        format: 'text',
+      });
+    });
+
+    it('parses --format text correctly [TC-7]', () => {
+      const result = parseCheckArgs(['test.rill', '--format', 'text']);
+      expect(result).toEqual({
+        mode: 'check',
+        file: 'test.rill',
+        fix: false,
+        verbose: false,
+        format: 'text',
+      });
+    });
+
+    it('parses --format json correctly [TC-8]', () => {
+      const result = parseCheckArgs(['test.rill', '--format', 'json']);
+      expect(result).toEqual({
+        mode: 'check',
+        file: 'test.rill',
+        fix: false,
+        verbose: false,
+        format: 'json',
+      });
+    });
+
+    it('parses multiple flags together [TC-5, TC-6, TC-7]', () => {
+      const result = parseCheckArgs([
+        'test.rill',
+        '--fix',
+        '--verbose',
+        '--format',
+        'json',
+      ]);
+      expect(result).toEqual({
+        mode: 'check',
+        file: 'test.rill',
+        fix: true,
+        verbose: true,
+        format: 'json',
+      });
+    });
+
+    it('extracts file path when mixed with flags', () => {
+      const result = parseCheckArgs(['--fix', 'test.rill', '--verbose']);
+      expect(result).toEqual({
+        mode: 'check',
+        file: 'test.rill',
+        fix: true,
+        verbose: true,
+        format: 'text',
+      });
+    });
+
+    it('uses default format when not specified', () => {
+      const result = parseCheckArgs(['test.rill']);
+      expect(result).toEqual({
+        mode: 'check',
+        file: 'test.rill',
+        fix: false,
+        verbose: false,
+        format: 'text',
+      });
+    });
+  });
+});