@mog-sdk/spreadsheet-contracts 0.1.12

package/dist/core/testing.d.ts

@@ -0,0 +1,309 @@
+/**
+ * Testing Framework Contracts
+ *
+ * Type definitions for the spreadsheet testing framework.
+ * Enables "unit tests for spreadsheets" - users define assertions on cells,
+ * run test suites, and catch errors before they reach stakeholders.
+ *
+ * @see spreadsheet/plans/TESTING-FOUNDATION.md
+ */
+/**
+ * Types of assertions that can be made about cell values
+ */
+export type AssertionType = 'equals' | 'notEquals' | 'greaterThan' | 'lessThan' | 'greaterOrEqual' | 'lessOrEqual' | 'between' | 'notEmpty' | 'isEmpty' | 'isType' | 'isUnique' | 'matchesPattern' | 'noError' | 'formula';
+/**
+ * Severity level of an assertion failure
+ */
+export type AssertionSeverity = 'error' | 'warning' | 'info';
+/**
+ * Target for an assertion - either a single cell or a range
+ */
+export type AssertionTarget = {
+    type: 'cell';
+    sheetId: string;
+    row: number;
+    col: number;
+} | {
+    type: 'range';
+    sheetId: string;
+    startRow: number;
+    startCol: number;
+    endRow: number;
+    endCol: number;
+};
+/**
+ * Parameters for different assertion types
+ */
+export interface AssertionParams {
+    expected?: unknown;
+    threshold?: number;
+    min?: number;
+    max?: number;
+    expectedType?: 'string' | 'number' | 'boolean' | 'date' | 'error';
+    pattern?: string;
+    formula?: string;
+    uniqueScope?: 'column' | 'row' | 'range';
+}
+/**
+ * A single cell assertion definition
+ */
+export interface CellAssertion {
+    /** Unique identifier for this assertion */
+    id: string;
+    /** Human-readable name for the assertion */
+    name?: string;
+    /** Target cell or range */
+    target: AssertionTarget;
+    /** Type of assertion to perform */
+    type: AssertionType;
+    /** Parameters specific to the assertion type */
+    params: AssertionParams;
+    /** Custom error message to display on failure */
+    message?: string;
+    /** Severity level of failure */
+    severity: AssertionSeverity;
+    /** Whether this assertion is enabled */
+    enabled: boolean;
+    /** Timestamp when assertion was created */
+    createdAt?: number;
+    /** Timestamp when assertion was last modified */
+    updatedAt?: number;
+}
+/**
+ * Result of evaluating a single assertion
+ */
+export interface TestResult {
+    /** ID of the assertion that was evaluated */
+    assertionId: string;
+    /** Name of the assertion (if provided) */
+    assertionName?: string;
+    /** Address where the assertion was evaluated */
+    address: {
+        sheetId: string;
+        row: number;
+        col: number;
+    };
+    /** Whether the assertion passed */
+    passed: boolean;
+    /** Actual value found in the cell */
+    actual?: unknown;
+    /** Expected value (if applicable) */
+    expected?: unknown;
+    /** Error message if failed */
+    message?: string;
+    /** Severity of the failure (if failed) */
+    severity: AssertionSeverity;
+    /** Timestamp when test was run */
+    timestamp: number;
+    /** How long the evaluation took (ms) */
+    durationMs?: number;
+}
+/**
+ * Summary of a test run
+ */
+export interface TestRunSummary {
+    /** Total number of assertions evaluated */
+    total: number;
+    /** Number of passed assertions */
+    passed: number;
+    /** Number of failed assertions */
+    failed: number;
+    /** Number of skipped assertions (disabled) */
+    skipped: number;
+    /** Number of errors (failures by severity) */
+    errors: number;
+    /** Number of warnings (failures by severity) */
+    warnings: number;
+    /** Total duration of test run (ms) */
+    durationMs: number;
+}
+/**
+ * A named collection of assertions
+ */
+export interface TestSuite {
+    /** Unique identifier for this suite */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Description of what this suite tests */
+    description?: string;
+    /** IDs of assertions in this suite */
+    assertionIds: string[];
+    /** Whether to automatically run tests after recalculation */
+    autoRun: boolean;
+    /** Whether to block export if this suite fails */
+    blockOnFailure: boolean;
+    /** Timestamp of last test run */
+    lastRun?: number;
+    /** Results from last test run */
+    lastResults?: TestResult[];
+    /** Summary from last test run */
+    lastSummary?: TestRunSummary;
+    /** Timestamp when suite was created */
+    createdAt?: number;
+    /** Timestamp when suite was last modified */
+    updatedAt?: number;
+}
+/**
+ * Main interface for the testing framework
+ */
+export interface ITestingFramework {
+    /**
+     * Add a new assertion
+     * @param assertion Assertion definition without ID
+     * @returns Created assertion with generated ID
+     */
+    addAssertion(assertion: Omit<CellAssertion, 'id'>): CellAssertion;
+    /**
+     * Update an existing assertion
+     * @param id Assertion ID to update
+     * @param updates Partial assertion updates
+     */
+    updateAssertion(id: string, updates: Partial<CellAssertion>): void;
+    /**
+     * Remove an assertion
+     * @param id Assertion ID to remove
+     */
+    removeAssertion(id: string): void;
+    /**
+     * Get an assertion by ID
+     * @param id Assertion ID
+     * @returns Assertion or undefined if not found
+     */
+    getAssertion(id: string): CellAssertion | undefined;
+    /**
+     * Get all assertions targeting a specific cell
+     * @param sheetId Sheet ID
+     * @param row Row index
+     * @param col Column index
+     * @returns Array of assertions targeting this cell
+     */
+    getAssertionsForCell(sheetId: string, row: number, col: number): CellAssertion[];
+    /**
+     * Get all assertions
+     * @returns Array of all assertions
+     */
+    getAllAssertions(): CellAssertion[];
+    /**
+     * Create a new test suite
+     * @param name Suite name
+     * @param options Optional suite configuration
+     * @returns Created suite
+     */
+    createSuite(name: string, options?: Partial<Omit<TestSuite, 'id' | 'name'>>): TestSuite;
+    /**
+     * Update an existing suite
+     * @param id Suite ID
+     * @param updates Partial suite updates
+     */
+    updateSuite(id: string, updates: Partial<TestSuite>): void;
+    /**
+     * Delete a suite
+     * @param id Suite ID to delete
+     */
+    deleteSuite(id: string): void;
+    /**
+     * Get a suite by ID
+     * @param id Suite ID
+     * @returns Suite or undefined if not found
+     */
+    getSuite(id: string): TestSuite | undefined;
+    /**
+     * Get all suites
+     * @returns Array of all suites
+     */
+    listSuites(): TestSuite[];
+    /**
+     * Add assertions to a suite
+     * @param suiteId Suite ID
+     * @param assertionIds Assertion IDs to add
+     */
+    addAssertionsToSuite(suiteId: string, assertionIds: string[]): void;
+    /**
+     * Remove assertions from a suite
+     * @param suiteId Suite ID
+     * @param assertionIds Assertion IDs to remove
+     */
+    removeAssertionsFromSuite(suiteId: string, assertionIds: string[]): void;
+    /**
+     * Run all enabled assertions
+     * @returns Array of test results
+     */
+    runAll(): Promise<TestResult[]>;
+    /**
+     * Run a specific test suite
+     * @param suiteId Suite ID to run
+     * @returns Array of test results
+     */
+    runSuite(suiteId: string): Promise<TestResult[]>;
+    /**
+     * Run assertions for a specific cell
+     * @param sheetId Sheet ID
+     * @param row Row index
+     * @param col Column index
+     * @returns Array of test results
+     */
+    runCell(sheetId: string, row: number, col: number): Promise<TestResult[]>;
+    /**
+     * Run a single assertion
+     * @param assertionId Assertion ID to run
+     * @returns Test result
+     */
+    runAssertion(assertionId: string): Promise<TestResult | undefined>;
+    /**
+     * Enable or disable auto-run mode
+     * When enabled, tests run automatically after recalculation
+     * @param enabled Whether auto-run is enabled
+     */
+    setAutoRun(enabled: boolean): void;
+    /**
+     * Check if auto-run is enabled
+     * @returns Whether auto-run is enabled
+     */
+    isAutoRunEnabled(): boolean;
+    /**
+     * Subscribe to test completion events
+     * @param handler Called when tests complete
+     * @returns Unsubscribe function
+     */
+    onTestsCompleted(handler: (results: TestResult[], summary: TestRunSummary) => void): () => void;
+    /**
+     * Subscribe to assertion failure events
+     * @param handler Called when an assertion fails
+     * @returns Unsubscribe function
+     */
+    onAssertionFailed(handler: (result: TestResult) => void): () => void;
+}
+/**
+ * Event emitted when tests complete
+ */
+export interface TestsCompletedEvent {
+    type: 'tests:completed';
+    timestamp: number;
+    suiteId?: string;
+    results: TestResult[];
+    summary: TestRunSummary;
+}
+/**
+ * Event emitted when an assertion fails
+ */
+export interface AssertionFailedEvent {
+    type: 'assertion:failed';
+    timestamp: number;
+    result: TestResult;
+}
+/**
+ * Event emitted when an assertion is created/updated/deleted
+ */
+export interface AssertionChangedEvent {
+    type: 'assertion:changed';
+    timestamp: number;
+    action: 'add' | 'update' | 'delete';
+    assertionId: string;
+    assertion?: CellAssertion;
+}
+/**
+ * All testing-related events
+ */
+export type TestingEvent = TestsCompletedEvent | AssertionFailedEvent | AssertionChangedEvent;
+//# sourceMappingURL=testing.d.ts.map

package/dist/core/testing.d.ts.map

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

package/dist/culture/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Culture types and utilities for contracts
+ *
+ * Stream G: Culture & Localization
+ *
+ * NOTE: Culture data (getCulture, getDefaultCulture) lives in @mog/culture.
+ * This module provides only types and cultureToLocaleOptions.
+ */
+export type { LocaleOptions } from './types';
+export type { CultureInfo, CurrencyNegativePattern, CurrencyPositivePattern, DayNamesTuple, DayOfWeek, MonthNamesTuple, NegativeNumberPattern, PercentNegativePattern, PercentPositivePattern, SupportedCultureName, } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/culture/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/culture/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C,YAAY,EACV,WAAW,EACX,uBAAuB,EACvB,uBAAuB,EACvB,aAAa,EACb,SAAS,EACT,eAAe,EACf,qBAAqB,EACrB,sBAAsB,EACtB,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,SAAS,CAAC"}

package/dist/culture/types.d.ts

@@ -0,0 +1,320 @@
+/**
+ * Culture/Locale types for internationalized number, date, and currency formatting.
+ *
+ * Stream G: Culture & Localization
+ *
+ * Design principles:
+ * 1. CultureInfo is immutable and complete - no partial definitions
+ * 2. Culture is workbook-level state (persisted in WorkbookSettings.culture)
+ * 3. Format codes are culture-agnostic; culture applies at render time
+ * 4. Uses IETF language tags (en-US, de-DE) not Windows locale IDs
+ */
+/**
+ * Day of week for firstDayOfWeek setting.
+ * 0 = Sunday (US, Japan), 1 = Monday (most of Europe)
+ */
+export type DayOfWeek = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+/**
+ * Currency positive pattern (matches .NET NumberFormatInfo).
+ * Determines where the currency symbol appears relative to the number.
+ *
+ * 0 = $n    (symbol before, no space) - en-US
+ * 1 = n$    (symbol after, no space)
+ * 2 = $ n   (symbol before, space)
+ * 3 = n $   (symbol after, space) - de-DE, fr-FR
+ */
+export type CurrencyPositivePattern = 0 | 1 | 2 | 3;
+/**
+ * Currency negative pattern (matches .NET NumberFormatInfo).
+ * Determines how negative currency values are displayed.
+ *
+ * 0  = ($n)     - en-US accounting
+ * 1  = -$n      - en-US standard
+ * 2  = $-n
+ * 3  = $n-
+ * 4  = (n$)
+ * 5  = -n$
+ * 6  = n-$
+ * 7  = n$-
+ * 8  = -n $     - de-DE
+ * 9  = -$ n
+ * 10 = n $-
+ * 11 = $ n-
+ * 12 = $ -n
+ * 13 = n- $
+ * 14 = ($ n)
+ * 15 = (n $)
+ */
+export type CurrencyNegativePattern = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15;
+/**
+ * Negative number pattern.
+ * Determines how negative numbers are displayed (outside of currency context).
+ *
+ * 0 = (n)      - parentheses
+ * 1 = -n       - leading minus (most common)
+ * 2 = - n      - leading minus with space
+ * 3 = n-       - trailing minus
+ * 4 = n -      - trailing minus with space
+ */
+export type NegativeNumberPattern = 0 | 1 | 2 | 3 | 4;
+/**
+ * Percent positive pattern.
+ *
+ * 0 = n %      - number, space, percent
+ * 1 = n%       - number, percent (most common)
+ * 2 = %n       - percent, number
+ * 3 = % n      - percent, space, number
+ */
+export type PercentPositivePattern = 0 | 1 | 2 | 3;
+/**
+ * Percent negative pattern.
+ *
+ * 0 = -n %
+ * 1 = -n%
+ * 2 = -%n
+ * 3 = %-n
+ * 4 = %n-
+ * 5 = n-%
+ * 6 = n%-
+ * 7 = -% n
+ * 8 = n %-
+ * 9 = % n-
+ * 10 = % -n
+ * 11 = n- %
+ */
+export type PercentNegativePattern = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11;
+/**
+ * Complete culture information for formatting numbers, dates, and currencies.
+ *
+ * All properties are required - no partial cultures allowed.
+ * Use the culture registry to get complete CultureInfo objects.
+ *
+ * @example
+ * ```typescript
+ * const culture = getCulture('de-DE');
+ * // culture.decimalSeparator === ','
+ * // culture.thousandsSeparator === '.'
+ * // culture.monthNames[0] === 'Januar'
+ * ```
+ */
+export interface CultureInfo {
+    /**
+     * IETF language tag (e.g., 'en-US', 'de-DE', 'ja-JP').
+     * This is the key used to look up the culture in the registry.
+     */
+    name: string;
+    /**
+     * Human-readable display name (e.g., 'English (United States)').
+     * Used in UI dropdowns.
+     */
+    displayName: string;
+    /**
+     * Native name in the culture's own language (e.g., 'Deutsch (Deutschland)').
+     */
+    nativeName: string;
+    /**
+     * ISO 639-1 two-letter language code (e.g., 'en', 'de', 'ja').
+     */
+    twoLetterLanguageCode: string;
+    /**
+     * Decimal separator character (e.g., '.' for en-US, ',' for de-DE).
+     */
+    decimalSeparator: string;
+    /**
+     * Thousands/grouping separator (e.g., ',' for en-US, '.' for de-DE, ' ' for fr-FR).
+     */
+    thousandsSeparator: string;
+    /**
+     * Negative sign (usually '-').
+     */
+    negativeSign: string;
+    /**
+     * Positive sign (usually '+' or '').
+     */
+    positiveSign: string;
+    /**
+     * Pattern for negative numbers.
+     */
+    negativeNumberPattern: NegativeNumberPattern;
+    /**
+     * Number of digits per group (usually 3).
+     * Some cultures use variable grouping (e.g., Indian: 3, then 2, 2, 2...).
+     * For simplicity, we use a single value in v1.
+     */
+    numberGroupSize: number;
+    /**
+     * Percent symbol (usually '%').
+     */
+    percentSymbol: string;
+    /**
+     * Per mille symbol (‰).
+     */
+    perMilleSymbol: string;
+    /**
+     * Pattern for positive percentages.
+     */
+    percentPositivePattern: PercentPositivePattern;
+    /**
+     * Pattern for negative percentages.
+     */
+    percentNegativePattern: PercentNegativePattern;
+    /**
+     * Default currency symbol for this culture (e.g., '$', '€', '¥').
+     */
+    currencySymbol: string;
+    /**
+     * ISO 4217 currency code (e.g., 'USD', 'EUR', 'JPY').
+     */
+    currencyCode: string;
+    /**
+     * Pattern for positive currency values.
+     */
+    currencyPositivePattern: CurrencyPositivePattern;
+    /**
+     * Pattern for negative currency values.
+     */
+    currencyNegativePattern: CurrencyNegativePattern;
+    /**
+     * Number of decimal digits for currency (e.g., 2 for USD, 0 for JPY).
+     */
+    currencyDecimalDigits: number;
+    /**
+     * Date separator (e.g., '/' for en-US, '.' for de-DE).
+     */
+    dateSeparator: string;
+    /**
+     * Time separator (e.g., ':').
+     */
+    timeSeparator: string;
+    /**
+     * Short date pattern (e.g., 'M/d/yyyy' for en-US, 'dd.MM.yyyy' for de-DE).
+     * Used for format code interpretation.
+     */
+    shortDatePattern: string;
+    /**
+     * Long date pattern (e.g., 'dddd, MMMM d, yyyy').
+     */
+    longDatePattern: string;
+    /**
+     * Short time pattern (e.g., 'h:mm tt' for en-US, 'HH:mm' for de-DE).
+     */
+    shortTimePattern: string;
+    /**
+     * Long time pattern (e.g., 'h:mm:ss tt' for en-US, 'HH:mm:ss' for de-DE).
+     */
+    longTimePattern: string;
+    /**
+     * AM designator (e.g., 'AM' for en-US, '' for 24-hour cultures).
+     */
+    amDesignator: string;
+    /**
+     * PM designator (e.g., 'PM' for en-US, '' for 24-hour cultures).
+     */
+    pmDesignator: string;
+    /**
+     * First day of the week (0 = Sunday, 1 = Monday).
+     */
+    firstDayOfWeek: DayOfWeek;
+    /**
+     * Full month names (12 entries, January = index 0).
+     */
+    monthNames: readonly [
+        string,
+        string,
+        string,
+        string,
+        string,
+        string,
+        string,
+        string,
+        string,
+        string,
+        string,
+        string
+    ];
+    /**
+     * Abbreviated month names (12 entries, Jan = index 0).
+     */
+    abbreviatedMonthNames: readonly [
+        string,
+        string,
+        string,
+        string,
+        string,
+        string,
+        string,
+        string,
+        string,
+        string,
+        string,
+        string
+    ];
+    /**
+     * Full day names (7 entries, Sunday = index 0).
+     */
+    dayNames: readonly [string, string, string, string, string, string, string];
+    /**
+     * Abbreviated day names (7 entries, Sun = index 0).
+     */
+    abbreviatedDayNames: readonly [string, string, string, string, string, string, string];
+    /**
+     * Shortest day names (7 entries, typically 1-2 letters).
+     * Used in narrow calendar UIs.
+     */
+    shortestDayNames: readonly [string, string, string, string, string, string, string];
+    /**
+     * String for TRUE value (e.g., 'TRUE', 'WAHR', 'VRAI').
+     */
+    trueString: string;
+    /**
+     * String for FALSE value (e.g., 'FALSE', 'FALSCH', 'FAUX').
+     */
+    falseString: string;
+    /**
+     * List separator (e.g., ',' for en-US, ';' for de-DE).
+     * This affects function argument separators in formulas.
+     */
+    listSeparator: string;
+}
+/**
+ * Type for the 12-element tuple of month names.
+ */
+export type MonthNamesTuple = readonly [
+    string,
+    string,
+    string,
+    string,
+    string,
+    string,
+    string,
+    string,
+    string,
+    string,
+    string,
+    string
+];
+/**
+ * Type for the 7-element tuple of day names.
+ */
+export type DayNamesTuple = readonly [string, string, string, string, string, string, string];
+/**
+ * Supported culture name literals (for strict typing in some contexts).
+ */
+export type SupportedCultureName = 'en-US' | 'en-GB' | 'de-DE' | 'fr-FR' | 'es-ES' | 'it-IT' | 'pt-BR' | 'ja-JP' | 'zh-CN' | 'ko-KR';
+/**
+ * Locale-specific formatting options.
+ *
+ * A lightweight subset of CultureInfo properties needed by the format engine.
+ * Use cultureToLocaleOptions() to derive from a full CultureInfo.
+ */
+export interface LocaleOptions {
+    decimalSeparator?: string;
+    thousandsSeparator?: string;
+    currencySymbol?: string;
+    dateOrder?: 'MDY' | 'DMY' | 'YMD';
+    use24Hour?: boolean;
+    currencyPositivePattern?: 0 | 1 | 2 | 3;
+    currencyNegativePattern?: number;
+    culture?: CultureInfo;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/culture/types.d.ts.map

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