mulmoclaude 0.1.0

package/src/plugins/spreadsheet/engine/cellBuilder.ts

@@ -0,0 +1,81 @@
+/**
+ * Build a SpreadsheetCell from the raw input captured by the mini
+ * editor (type + value / formula / format). Extracted from
+ * `saveMiniEditor` in `src/plugins/spreadsheet/View.vue` where it
+ * was inlined as ~30 lines of nested if/else that pushed the
+ * surrounding function over the cognitive-complexity threshold.
+ *
+ * Pure — no refs, no DOM, no side effects. Given the same inputs
+ * it always returns the same SpreadsheetCell. Tested in
+ * `test/plugins/spreadsheet/engine/test_cellBuilder.ts`.
+ */
+
+import type { SpreadsheetCell } from "./types.js";
+
+/** Inputs to the cell builder. Mirrors the mini editor refs in the
+ *  View but as plain values so unit tests don't need a Vue runtime. */
+export interface MiniEditorInput {
+  /** "string" → value is stored as-is as a string.
+   *  Anything else → the `formula` field is parsed (formula / number / raw string). */
+  type: string;
+  /** Used when type === "string". Coerced to string. */
+  value: unknown;
+  /** Used when type !== "string". Trimmed before classification. */
+  formula?: string;
+  /** Optional format code (e.g. "$#,##0.00"). */
+  format?: string;
+}
+
+// Anchored at the start of the input (after optional unary +/-) so we
+// only treat expressions that clearly begin with a function call as
+// formulas. Unanchored would match "abc FOO(" inside ordinary text.
+const FORMULA_FUNCTION_CALL = /^[-+]?\s*[A-Z]+\s*\(/i;
+
+// `A1 + B2` style — cell reference next to an arithmetic operator.
+const FORMULA_CELL_OP = /[A-Z]+\d+\s*[+\-*/^]/;
+
+// `6/100`, `5 * 2` — arithmetic between two literal numbers.
+const FORMULA_NUMERIC_OP = /\d+\s*[+\-*/^]\s*\d+/;
+
+// Strict numeric literal. `parseFloat` accepts trailing junk
+// ("42abc" → 42) which silently corrupts user input; this anchor
+// ensures the ENTIRE trimmed string is a number.
+const STRICT_NUMBER = /^[-+]?(?:\d+\.?\d*|\.\d+)(?:[eE][-+]?\d+)?$/;
+
+/**
+ * Best-effort formula detection. The rules are conservative enough
+ * that plain text like "hello world" stays as text, but any input
+ * with arithmetic operators or function calls is treated as a
+ * formula and gets the "=" prefix the engine expects.
+ */
+export function looksLikeFormula(input: string): boolean {
+  return FORMULA_FUNCTION_CALL.test(input) || FORMULA_CELL_OP.test(input) || FORMULA_NUMERIC_OP.test(input);
+}
+
+/**
+ * Parse the raw (non-string-type) editor input into a cell value.
+ * Priority: formula > number > raw string > empty string.
+ */
+export function parseNonStringInput(raw: string): number | string {
+  const input = raw.trim();
+  if (input === "") return "";
+  if (looksLikeFormula(input)) return `=${input}`;
+  return STRICT_NUMBER.test(input) ? Number(input) : input;
+}
+
+/**
+ * Build the full SpreadsheetCell from a mini editor input record.
+ * String type short-circuits to `{ v: String(value) }`.
+ * Everything else goes through parseNonStringInput for formula /
+ * number / text classification, then optionally attaches `f`.
+ */
+export function buildCellFromInput(input: MiniEditorInput): SpreadsheetCell {
+  if (input.type === "string") {
+    return { v: String(input.value) };
+  }
+  const cell: SpreadsheetCell = { v: parseNonStringInput(input.formula ?? "") };
+  if (input.format && input.format.length > 0) {
+    cell.f = input.format;
+  }
+  return cell;
+}

package/src/plugins/spreadsheet/engine/date-parser.ts

@@ -0,0 +1,220 @@
+/**
+ * Date Parsing Utilities
+ *
+ * Parse various date string formats into Excel serial numbers.
+ */
+
+import { dateToSerial, MONTH_NAMES_SHORT, MONTH_NAMES_FULL } from "./date-utils";
+
+/**
+ * Check if a string looks like a date
+ *
+ * @param str - String to check
+ * @returns true if string matches common date patterns
+ */
+export function isDateLike(str: string): boolean {
+  if (typeof str !== "string") return false;
+  if (str.length < 6 || str.length > 30) return false; // Reasonable length for dates
+
+  // Common date patterns:
+  // MM/DD/YYYY, DD/MM/YYYY, M/D/YYYY
+  // YYYY-MM-DD, YYYY/MM/DD
+  // DD-MMM-YYYY, D-MMM-YYYY
+  // MMM D, YYYY, MMMM D, YYYY
+
+  // Pattern 1: Contains digits and separators (/, -, space)
+  const hasDigits = /\d/.test(str);
+  const hasSeparator = /[/\-\s,]/.test(str);
+
+  if (!hasDigits || !hasSeparator) return false;
+
+  // Pattern 2: Matches common date formats
+  const datePatterns = [
+    /^\d{1,2}\/\d{1,2}\/\d{2,4}$/, // MM/DD/YYYY or DD/MM/YYYY
+    /^\d{4}-\d{1,2}-\d{1,2}$/, // YYYY-MM-DD
+    /^\d{4}\/\d{1,2}\/\d{1,2}$/, // YYYY/MM/DD
+    /^\d{1,2}-[A-Za-z]{3}-\d{2,4}$/, // DD-MMM-YYYY
+    /^[A-Za-z]{3,9}\s+\d{1,2},?\s+\d{4}$/, // MMM D, YYYY or MMMM D, YYYY
+    /^\d{1,2}\s+[A-Za-z]{3,9}\s+\d{4}$/, // D MMM YYYY
+  ];
+
+  return datePatterns.some((pattern) => pattern.test(str.trim()));
+}
+
+/**
+ * Parse a month name to month number (1-12)
+ */
+function parseMonthName(monthStr: string): number | null {
+  const month = monthStr.toLowerCase();
+
+  // Try short names
+  const shortIndex = MONTH_NAMES_SHORT.findIndex((m) => m.toLowerCase() === month);
+  if (shortIndex !== -1) return shortIndex + 1;
+
+  // Try full names
+  const fullIndex = MONTH_NAMES_FULL.findIndex((m) => m.toLowerCase() === month);
+  if (fullIndex !== -1) return fullIndex + 1;
+
+  return null;
+}
+
+/**
+ * Parse a date string into Excel serial number
+ *
+ * Supports formats:
+ * - MM/DD/YYYY, M/D/YYYY
+ * - DD/MM/YYYY (when day > 12)
+ * - YYYY-MM-DD, YYYY/MM/DD (ISO format)
+ * - DD-MMM-YYYY, D-MMM-YYYY
+ * - MMM D, YYYY, MMMM D, YYYY
+ *
+ * @param dateStr - String that might contain a date
+ * @param preferDDMMYYYY - Prefer DD/MM/YYYY over MM/DD/YYYY for ambiguous dates (default: false)
+ * @returns Serial number or null if not a valid date
+ */
+export function parseDate(dateStr: string, preferDDMMYYYY: boolean = false): number | null {
+  if (!isDateLike(dateStr)) return null;
+
+  const trimmed = dateStr.trim();
+
+  // Try YYYY-MM-DD or YYYY/MM/DD (ISO format)
+  const isoMatch = trimmed.match(/^(\d{4})[-/](\d{1,2})[-/](\d{1,2})$/);
+  if (isoMatch) {
+    const year = parseInt(isoMatch[1]);
+    const month = parseInt(isoMatch[2]);
+    const day = parseInt(isoMatch[3]);
+
+    if (isValidDate(year, month, day)) {
+      const date = new Date(Date.UTC(year, month - 1, day));
+      return dateToSerial(date);
+    }
+    return null;
+  }
+
+  // Try DD-MMM-YYYY or D-MMM-YYYY
+  const dmmyMatch = trimmed.match(/^(\d{1,2})-([A-Za-z]{3})-(\d{2,4})$/);
+  if (dmmyMatch) {
+    const day = parseInt(dmmyMatch[1]);
+    const monthName = dmmyMatch[2];
+    let year = parseInt(dmmyMatch[3]);
+
+    // Handle 2-digit years
+    if (year < 100) {
+      year = year < 30 ? 2000 + year : 1900 + year;
+    }
+
+    const month = parseMonthName(monthName);
+    if (month && isValidDate(year, month, day)) {
+      const date = new Date(Date.UTC(year, month - 1, day));
+      return dateToSerial(date);
+    }
+    return null;
+  }
+
+  // Try MMM D, YYYY or MMMM D, YYYY
+  const mmmMatch = trimmed.match(/^([A-Za-z]{3,9})\s+(\d{1,2}),?\s+(\d{4})$/);
+  if (mmmMatch) {
+    const monthName = mmmMatch[1];
+    const day = parseInt(mmmMatch[2]);
+    const year = parseInt(mmmMatch[3]);
+
+    const month = parseMonthName(monthName);
+    if (month && isValidDate(year, month, day)) {
+      const date = new Date(Date.UTC(year, month - 1, day));
+      return dateToSerial(date);
+    }
+    return null;
+  }
+
+  // Try D MMM YYYY
+  const dMmmMatch = trimmed.match(/^(\d{1,2})\s+([A-Za-z]{3,9})\s+(\d{4})$/);
+  if (dMmmMatch) {
+    const day = parseInt(dMmmMatch[1]);
+    const monthName = dMmmMatch[2];
+    const year = parseInt(dMmmMatch[3]);
+
+    const month = parseMonthName(monthName);
+    if (month && isValidDate(year, month, day)) {
+      const date = new Date(Date.UTC(year, month - 1, day));
+      return dateToSerial(date);
+    }
+    return null;
+  }
+
+  // Try MM/DD/YYYY or DD/MM/YYYY
+  const slashMatch = trimmed.match(/^(\d{1,2})\/(\d{1,2})\/(\d{2,4})$/);
+  if (slashMatch) {
+    const first = parseInt(slashMatch[1]);
+    const second = parseInt(slashMatch[2]);
+    let year = parseInt(slashMatch[3]);
+
+    // Handle 2-digit years
+    if (year < 100) {
+      year = year < 30 ? 2000 + year : 1900 + year;
+    }
+
+    // Determine if it's MM/DD/YYYY or DD/MM/YYYY
+    // If first > 12, it must be DD/MM; if second > 12, it must be MM/DD
+    // Otherwise use preference (default to MM/DD for US format)
+    const isDayFirst = first > 12 || (second <= 12 && first <= 12 && preferDDMMYYYY);
+    const month = isDayFirst ? second : first;
+    const day = isDayFirst ? first : second;
+
+    if (isValidDate(year, month, day)) {
+      const date = new Date(Date.UTC(year, month - 1, day));
+      return dateToSerial(date);
+    }
+    return null;
+  }
+
+  return null;
+}
+
+/**
+ * Validate that a date is valid
+ */
+function isValidDate(year: number, month: number, day: number): boolean {
+  // Check basic ranges
+  if (year < 1900 || year > 2100) return false;
+  if (month < 1 || month > 12) return false;
+  if (day < 1 || day > 31) return false;
+
+  // Check if day is valid for the given month
+  const date = new Date(Date.UTC(year, month - 1, day));
+
+  // If the date rolls over to the next month, it's invalid
+  return date.getUTCFullYear() === year && date.getUTCMonth() === month - 1 && date.getUTCDate() === day;
+}
+
+/**
+ * Get default date format based on parsed date
+ *
+ * @param originalStr - Original date string
+ * @returns Appropriate format code
+ */
+export function getDefaultDateFormat(originalStr: string): string {
+  const trimmed = originalStr.trim();
+
+  // YYYY-MM-DD → use same format
+  if (/^\d{4}-\d{1,2}-\d{1,2}$/.test(trimmed)) {
+    return "YYYY-MM-DD";
+  }
+
+  // DD-MMM-YYYY → use same format
+  if (/^\d{1,2}-[A-Za-z]{3}-\d{2,4}$/.test(trimmed)) {
+    return "DD-MMM-YYYY";
+  }
+
+  // MMM D, YYYY → use same format
+  if (/^[A-Za-z]{3}\s+\d{1,2},?\s+\d{4}$/.test(trimmed)) {
+    return "MMM D, YYYY";
+  }
+
+  // MMMM D, YYYY → use same format
+  if (/^[A-Za-z]{4,9}\s+\d{1,2},?\s+\d{4}$/.test(trimmed)) {
+    return "MMMM D, YYYY";
+  }
+
+  // Default to MM/DD/YYYY for slash-separated dates
+  return "MM/DD/YYYY";
+}

package/src/plugins/spreadsheet/engine/date-utils.ts

@@ -0,0 +1,56 @@
+/**
+ * Date Utility Functions
+ *
+ * Shared utilities for converting between JavaScript Date objects and Excel serial numbers.
+ * Excel stores dates as sequential serial numbers so they can be used in calculations.
+ * January 1, 1900 is serial number 1.
+ */
+
+// Constants
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+// Excel base date: Dec 30, 1899 (to handle the 1900 leap year bug correctly)
+const EXCEL_BASE_DATE = new Date(Date.UTC(1899, 11, 30));
+
+/**
+ * Convert JavaScript Date to Excel Serial Number
+ *
+ * @param date - JavaScript Date object
+ * @returns Excel serial number (days since Dec 30, 1899)
+ */
+export const dateToSerial = (date: Date): number => {
+  const diff = date.getTime() - EXCEL_BASE_DATE.getTime();
+  return diff / MS_PER_DAY;
+};
+
+/**
+ * Convert Excel Serial Number to JavaScript Date
+ *
+ * @param serial - Excel serial number
+ * @returns JavaScript Date object
+ */
+export const serialToDate = (serial: number): Date => {
+  const days = Math.floor(serial);
+  const timePart = serial - days;
+
+  const date = new Date(EXCEL_BASE_DATE.getTime() + days * MS_PER_DAY);
+
+  // Add time component
+  const totalSeconds = Math.round(timePart * 24 * 60 * 60);
+  date.setSeconds(date.getSeconds() + totalSeconds);
+
+  return date;
+};
+
+/**
+ * Month names for formatting
+ */
+export const MONTH_NAMES_SHORT = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+
+export const MONTH_NAMES_FULL = ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"];
+
+/**
+ * Day names for formatting
+ */
+export const DAY_NAMES_SHORT = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
+
+export const DAY_NAMES_FULL = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];

package/src/plugins/spreadsheet/engine/engine.ts

@@ -0,0 +1,176 @@
+/**
+ * SpreadsheetEngine - Main API
+ *
+ * High-level interface for spreadsheet calculations
+ */
+
+import { calculateSheet, calculateWorkbook } from "./calculator";
+import type { SheetData, CalculatedSheet, EngineOptions, SpreadsheetCell } from "./types";
+import { isObj } from "../../../utils/types";
+
+/**
+ * SpreadsheetEngine - Main calculation engine class
+ *
+ * Provides a clean API for calculating spreadsheet formulas with support for:
+ * - Formula evaluation (SUM, AVERAGE, IF, etc.)
+ * - Cell references (A1, $B$2, Sheet1!C3)
+ * - Cross-sheet references
+ * - Number formatting ($#,##0.00, 0.00%, etc.)
+ * - Circular reference detection
+ *
+ * @example
+ * ```typescript
+ * const engine = new SpreadsheetEngine();
+ * const sheet = {
+ *   name: 'Sales',
+ *   data: [
+ *     [{v: 'Product'}, {v: 'Price'}, {v: 'Qty'}, {v: 'Total'}],
+ *     [{v: 'Widget'}, {v: 10}, {v: 100}, {v: '=B2*C2'}],
+ *   ]
+ * };
+ * const result = engine.calculate(sheet);
+ * console.log(result.data); // [['Product', 'Price', 'Qty', 'Total'], ['Widget', 10, 100, 1000]]
+ * ```
+ */
+export class SpreadsheetEngine {
+  private options: Required<EngineOptions>;
+
+  /**
+   * Create a new SpreadsheetEngine
+   *
+   * @param options - Configuration options
+   */
+  constructor(options: EngineOptions = {}) {
+    this.options = {
+      maxIterations: options.maxIterations ?? 100,
+      enableCrossSheetRefs: options.enableCrossSheetRefs ?? true,
+      strictMode: options.strictMode ?? false,
+    };
+  }
+
+  /**
+   * Calculate a single sheet
+   *
+   * Evaluates all formulas in the sheet and applies number formatting.
+   * Returns calculated values with formula metadata and any errors.
+   *
+   * @param sheet - Sheet data with formulas
+   * @param allSheets - Optional array of all sheets for cross-sheet references
+   * @returns Calculated sheet with evaluated formulas
+   *
+   * @example
+   * ```typescript
+   * const result = engine.calculate({
+   *   name: 'Budget',
+   *   data: [
+   *     [{v: 'Item'}, {v: 'Amount'}],
+   *     [{v: 'Revenue'}, {v: 1000}],
+   *     [{v: 'Expenses'}, {v: 600}],
+   *     [{v: 'Profit'}, {v: '=B2-B3'}],
+   *   ]
+   * });
+   * console.log(result.data[3][1]); // 400
+   * ```
+   */
+  calculate(sheet: SheetData, allSheets?: SheetData[]): CalculatedSheet {
+    return calculateSheet(sheet, allSheets);
+  }
+
+  /**
+   * Calculate all sheets in a workbook
+   *
+   * Evaluates formulas across multiple sheets with support for
+   * cross-sheet references (e.g., Sheet1!A1).
+   *
+   * @param sheets - Array of sheets to calculate
+   * @returns Array of calculated sheets
+   *
+   * @example
+   * ```typescript
+   * const results = engine.calculateWorkbook([
+   *   { name: 'Data', data: [[{v: 100}]] },
+   *   { name: 'Summary', data: [[{v: '=Data!A1*2'}]] }
+   * ]);
+   * console.log(results[1].data[0][0]); // 200
+   * ```
+   */
+  calculateWorkbook(sheets: SheetData[]): CalculatedSheet[] {
+    return calculateWorkbook(sheets);
+  }
+
+  /**
+   * Get current engine options
+   *
+   * @returns Current configuration options
+   */
+  getOptions(): Required<EngineOptions> {
+    return { ...this.options };
+  }
+
+  /**
+   * Update engine options
+   *
+   * @param options - Options to update
+   *
+   * @example
+   * ```typescript
+   * engine.setOptions({ strictMode: true });
+   * ```
+   */
+  setOptions(options: Partial<EngineOptions>): void {
+    this.options = {
+      ...this.options,
+      ...options,
+    };
+  }
+
+  /**
+   * Create a simple sheet from array data
+   *
+   * Helper method to create a SheetData object from simple arrays.
+   * Automatically converts values to SpreadsheetCell format.
+   *
+   * @param name - Sheet name
+   * @param data - Array of arrays (rows and cells)
+   * @returns SheetData object
+   *
+   * @example
+   * ```typescript
+   * const sheet = engine.createSheet('Sales', [
+   *   ['Product', 'Price', 'Qty', 'Total'],
+   *   ['Widget', 10, 100, '=B2*C2'],
+   * ]);
+   * ```
+   */
+  createSheet(name: string, data: Array<Array<SpreadsheetCell | string | number>>): SheetData {
+    return {
+      name,
+      data: data.map((row) =>
+        row.map((cell) => {
+          if (isObj(cell) && "v" in cell) {
+            return cell as SpreadsheetCell;
+          }
+          return { v: cell };
+        }),
+      ),
+    };
+  }
+
+  /**
+   * Convert calculated sheet data to string array
+   *
+   * Helper method for testing and output formatting.
+   *
+   * @param calculated - Calculated sheet
+   * @returns 2D array of strings
+   *
+   * @example
+   * ```typescript
+   * const result = engine.calculate(sheet);
+   * const stringArray = engine.toStringArray(result);
+   * ```
+   */
+  toStringArray(calculated: CalculatedSheet): string[][] {
+    return calculated.data.map((row) => row.map((cell) => String(cell ?? "")));
+  }
+}