@aiquants/spreadsheet 0.8.0

package/src/commands/selfCalc.ts

@@ -0,0 +1,279 @@
+/**
+ * @fileoverview Self-calculation over the selected cells' texts (v0.8 §4.1.12 — the
+ * `multiplyBy100` / `multiplyBy1000` / `divideBy100` / `divideBy1000` / `signReversal` commands,
+ * ported from the sheets-enhancer extension's `calculateClipboardData`). Pure, React / DOM-free.
+ *
+ * Contract (each clause is pinned by selfCalc.spec.ts):
+ * - Text side (`scaleDecimalText` / `reverseSignText`): "is it a number" is decided by
+ *   `parseNumber` from cellFormat.ts (the single source of the decimal grammar); the arithmetic is
+ *   EXACT string digit shifting / sign flipping — no double is ever constructed, so integers beyond
+ *   2^53 keep every digit and "0.07" × 100 is "7" (not 7.000000000000001). The output is the
+ *   canonical decimal (no "+", no "-0", no redundant leading / trailing zeros); an exponent-form
+ *   input keeps its exponent form with the exponent shifted ("1e3" × 100 = "1e5"). Non-numeric
+ *   text (for the sign: anything but TRUE / FALSE, case-insensitive) ⇒ null = "leave the cell";
+ *   so is a RESULT that leaves the parseNumber grammar / finite envelope ("9e307" × 100,
+ *   "1e-9999" ÷ 100, a 308-digit plain integer × 100) — the operation must never write text the
+ *   package itself no longer recognises as a number (one-way domain escape; Excel refuses too).
+ * - Formula side (`scaleFormula` / `reverseSignFormula`): reversible wrap / peel. Wrap =
+ *   `=(body)*100` / `=(body)/100` / `=-(body)`; peel removes exactly our own INVERSE wrapper
+ *   (`=(inner)/100` under ×100, `=(inner)*100` under ÷100, `=-(inner)` under sign) and ONLY when
+ *   the leading "(" pairs with the ")" before the suffix — "…" string literals and '…' quoted
+ *   sheet names are opaque (a doubled quote toggles the literal state twice, so no escape rule).
+ *   The extension's greedy `^\((.+)\)/100$` mis-peels `=(A1)/100+(B1)/100` into the broken
+ *   `=A1)/100+(B1`; here that formula wraps.
+ * - A formula is "=" + a non-empty body; anything else is a caller bug ⇒ RangeError (fail-fast,
+ *   the same rule getCellFormula's "=" contract enforces). An exponent outside ±2 / ±3 is a
+ *   RangeError too (JS callers).
+ * - Whether a cell IS a formula is the CALLER's decision (the `getCellFormula` capability branch
+ *   in useCommands): no function here sniffs a leading "=" on the text side, so a v0.7 adapter
+ *   without `getCellFormula` sees "=A1" as plain text (untouched) — never as a formula.
+ *
+ * 選択セルの text に対する自己計算 (v0.8 §4.1.12 — multiplyBy100 / multiplyBy1000 / divideBy100 /
+ * divideBy1000 / signReversal、sheets-enhancer 拡張 `calculateClipboardData` の移植)。純関数・
+ * React / DOM 非依存。契約: text 側は「数値か」を cellFormat.ts の parseNumber で決め (十進文法の
+ * 単一真実源)、演算は文字列の桁シフト / 符号反転で**正確** (double を作らない — 2^53 超は全桁保持、
+ * "0.07"×100 = "7")。出力は正準十進 ("+" / "-0" / 余分な前後 0 なし)、指数形入力は指数形のまま指数を
+ * シフト。非数値 (符号は大文字小文字を問わない TRUE / FALSE 以外) は null = セルを触らない。**結果**が
+ * parseNumber の文法 / 有限域を出る演算 ("9e307"×100 / "1e-9999"÷100 / 308 桁整数の ×100) も同じ
+ * null (数値領域からの片道脱出を書かない — Excel も拒否)。数式側は
+ * 可逆ラップ / 剥離 — 剥離は自前の**逆**ラッパだけ、かつ先頭 "(" が接尾辞直前の ")" と対になるとき
+ * だけ (文字列リテラル / クオート済みシート名は不透過。拡張の貪欲 regex は `=(A1)/100+(B1)/100` を
+ * `=A1)/100+(B1` に壊すが、ここではラップする)。数式は "=" + 非空本体、それ以外と ±2 / ±3 以外の
+ * 指数は呼び手バグとして RangeError。「数式か」は呼び手 (useCommands の getCellFormula 能力分岐) が
+ * 決め、text 側で "=" を嗅がない (getCellFormula 未宣言の v0.7 アダプタでは "=A1" は素の text)。
+ */
+
+import { parseNumber } from "../model/cellFormat.ts"
+
+/** Power-of-ten exponent of a self-calc scale: +2 / +3 multiply by 100 / 1000, -2 / -3 divide. / 自己計算の 10 の冪指数: +2 / +3 は ×100 / ×1000、-2 / -3 は ÷100 / ÷1000。 */
+export type ScaleExponent = 2 | 3 | -2 | -3
+
+/** Decomposed decimal literal: sign, all digits without the point, point position (digits before the point) and the literal exponent (null when the input had none). / 分解した十進リテラル: 符号、小数点抜きの全桁、小数点位置 (点より前の桁数)、リテラル指数 (無ければ null)。 */
+type DecimalParts = { negative: boolean; digits: string; point: number; exponent: number | null }
+
+/** Rejects an exponent outside the ±2 / ±3 vocabulary (JS callers) with RangeError. / ±2 / ±3 以外の指数 (JS 呼び手) を RangeError で拒否。 */
+const assertScaleExponent = (exponent: number): void => {
+    if (exponent !== 2 && exponent !== 3 && exponent !== -2 && exponent !== -3) {
+        throw new RangeError(`[spreadsheet] self-calc exponent must be 2, 3, -2 or -3; got ${String(exponent)}`)
+    }
+}
+
+/**
+ * Splits a parseNumber-validated literal into its parts. The grammar guarantees a sign of at most
+ * one character, at least one digit, at most one point and an exponent of 1-4 digits, so every
+ * slice below is total.
+ * parseNumber 検証済みリテラルを部品へ分解。文法が符号 1 文字以下・桁 1 以上・点 1 以下・指数 1-4 桁を
+ * 保証するため、以下のスライスは全域で安全。
+ */
+const splitDecimal = (literal: Intl.StringNumericLiteral): DecimalParts => {
+    let rest: string = literal
+    let negative = false
+    // 符号 (+ は落とす、- は保持)
+    if (rest.startsWith("-")) {
+        negative = true
+        rest = rest.slice(1)
+    } else if (rest.startsWith("+")) {
+        rest = rest.slice(1)
+    }
+    // 指数部 (1-4 桁の整数 — Number は正確)
+    const at = rest.search(/[eE]/)
+    let exponent: number | null = null
+    if (at >= 0) {
+        exponent = Number(rest.slice(at + 1))
+        rest = rest.slice(0, at)
+    }
+    // 小数点で整数部 / 小数部へ
+    const dot = rest.indexOf(".")
+    const intPart = dot < 0 ? rest : rest.slice(0, dot)
+    const fracPart = dot < 0 ? "" : rest.slice(dot + 1)
+    return { negative, digits: intPart + fracPart, point: intPart.length, exponent }
+}
+
+/**
+ * Canonical decimal text for a digit run with the point after `point` digits (`point` may fall
+ * left of the first digit or right of the last): leading / trailing zeros dropped, zero unsigned.
+ * 桁列と小数点位置 (先頭より左 / 末尾より右も可) から正準十進文字列を作る: 前後の余分な 0 を落とし、
+ * ゼロは符号を持たない。
+ */
+const renderDecimal = (negative: boolean, digits: string, point: number): string => {
+    let int: string
+    let frac: string
+    // 小数点位置を桁列の範囲へ収める (左へ出れば 0 詰め、右へ出れば 0 付加)
+    if (point <= 0) {
+        int = "0"
+        frac = "0".repeat(-point) + digits
+    } else if (point >= digits.length) {
+        int = digits + "0".repeat(point - digits.length)
+        frac = ""
+    } else {
+        int = digits.slice(0, point)
+        frac = digits.slice(point)
+    }
+    // 正準化: 整数部の先頭 0 (1 桁は残す) と小数部の末尾 0 を落とす
+    int = int.replace(/^0+(?=\d)/, "")
+    frac = frac.replace(/0+$/, "")
+    // ゼロは符号を持たない
+    if (int === "0" && frac === "") {
+        return "0"
+    }
+    return `${negative ? "-" : ""}${int}${frac === "" ? "" : `.${frac}`}`
+}
+
+/**
+ * Canonical text of decimal parts after shifting the power of ten by `shift`: a plain literal
+ * moves its point, an exponent-form literal keeps its (normalised) mantissa and shifts the
+ * exponent; a zero mantissa is "0" whatever the exponent. A result that leaves the parseNumber
+ * grammar / finite envelope (an exponent grown past 4 digits, or a value overflowing double to
+ * Infinity — plain OR exponent form) is null = the cell is left alone, the same rule as
+ * non-numeric input.
+ * 10 の冪を `shift` だけずらした正準文字列: 通常形は小数点を移動、指数形は (正準化した) 仮数を保って
+ * 指数をずらす。仮数ゼロは指数に依らず "0"。結果が parseNumber の文法 / 有限域を出る場合 (指数の
+ * 5 桁化、通常形 / 指数形を問わない double の Infinity 溢れ) は非数値入力と同じ null = セルを
+ * 触らない。
+ */
+const renderShifted = (parts: DecimalParts, shift: number): string | null => {
+    let candidate: string
+    if (parts.exponent === null) {
+        candidate = renderDecimal(parts.negative, parts.digits, parts.point + shift)
+    } else {
+        const mantissa = renderDecimal(parts.negative, parts.digits, parts.point)
+        candidate = mantissa === "0" ? "0" : `${mantissa}e${parts.exponent + shift}`
+    }
+    // 結果が自前の数値文法 / 有限域を出ると (例: "9e307"×100 = Infinity 溢れ、"1e-9999"÷100 = 指数
+    // 5 桁化) セルが数値領域から片道脱出する — 逆演算も null 化して自己計算では戻せなくなるため、
+    // Excel が拒否するのと同様に「触らない」へ倒す
+    return parseNumber(candidate) === null ? null : candidate
+}
+
+/**
+ * Decimal string × 10^exponent EXACTLY (string digit shift — no double). Non-numeric text (by
+ * parseNumber) ⇒ null (the cell is left alone); a result outside the parseNumber grammar / finite
+ * envelope ⇒ null too (no one-way escape from the numeric domain). Output is canonical (see
+ * fileoverview).
+ * 十進文字列の正確な 10^exponent 倍 (文字列の桁シフト — double 不使用)。非数値 (parseNumber 判定) は
+ * null (セルを触らない)。結果が parseNumber の文法 / 有限域を出る場合も null (数値領域からの片道
+ * 脱出を書かない)。出力は正準形 (fileoverview 参照)。
+ */
+export const scaleDecimalText = (text: string, exponent: ScaleExponent): string | null => {
+    assertScaleExponent(exponent)
+    const literal = parseNumber(text)
+    // 数値でなければ触らない
+    if (literal === null) {
+        return null
+    }
+    return renderShifted(splitDecimal(literal), exponent)
+}
+
+/**
+ * Sign reversal of a cell text: a number (by parseNumber) negates exactly (zero stays "0"),
+ * TRUE / FALSE (case-insensitive, trimmed) flip to the canonical upper-case opposite, anything
+ * else ⇒ null (the cell is left alone).
+ * セル text の符号反転: 数値 (parseNumber 判定) は正確に反転 (ゼロは "0" のまま)、TRUE / FALSE
+ * (大文字小文字を問わず、trim 後) は正準大文字の逆へ、それ以外は null (セルを触らない)。
+ */
+export const reverseSignText = (text: string): string | null => {
+    const literal = parseNumber(text)
+    if (literal !== null) {
+        const parts = splitDecimal(literal)
+        return renderShifted({ ...parts, negative: !parts.negative }, 0)
+    }
+    // 真偽値 (Excel / Sheets の大文字小文字を問わない TRUE / FALSE) は反転して正準大文字へ
+    const upper = text.trim().toUpperCase()
+    if (upper === "TRUE") {
+        return "FALSE"
+    }
+    if (upper === "FALSE") {
+        return "TRUE"
+    }
+    return null
+}
+
+/** Body of a formula ("=" + non-empty body); anything else is a caller bug ⇒ RangeError. / 数式の本体 ("=" + 非空本体)。それ以外は呼び手バグとして RangeError。 */
+const formulaBody = (formula: string): string => {
+    if (!formula.startsWith("=") || formula.length === 1) {
+        throw new RangeError(`[spreadsheet] self-calc expects a formula ("=" followed by a body); got ${JSON.stringify(formula)}`)
+    }
+    return formula.slice(1)
+}
+
+/**
+ * True when `text` has balanced parentheses — depth never negative and zero at the end — with
+ * "…" string literals and '…' quoted sheet names opaque (a doubled quote closes and reopens, which
+ * is the same state as an escape — no escape rule needed); an unterminated quote is unbalanced.
+ * `text` の括弧が釣り合う (深さが負にならず末尾で 0) とき true。"…" 文字列リテラルと '…' クオート済み
+ * シート名は不透過 (二重化クオートは閉じ + 再開で脱出と同じ状態 — 脱出規則は不要)、未終端クオートは
+ * 不釣合い扱い。
+ */
+const isParenBalanced = (text: string): boolean => {
+    let depth = 0
+    let quote: '"' | "'" | null = null
+    for (let i = 0; i < text.length; i++) {
+        const ch = text[i]
+        if (quote !== null) {
+            // クオート内: 同種のクオートで閉じる (二重化 "" / '' は閉じ + 再開と同じ状態遷移なので脱出規則は不要)
+            if (ch === quote) {
+                quote = null
+            }
+            continue
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch
+        } else if (ch === "(") {
+            depth++
+        } else if (ch === ")") {
+            depth--
+            // 閉じ過多は先頭 "(" が接尾辞直前の ")" と対でない証拠
+            if (depth < 0) {
+                return false
+            }
+        }
+    }
+    return quote === null && depth === 0
+}
+
+/**
+ * Inner text when `body` is exactly `open + inner + close` with a non-empty, balanced inner (so
+ * the "(" ending `open` pairs with the ")" starting `close`); null otherwise.
+ * `body` が `open + inner + close` そのもので inner が非空かつ釣り合う (open 末尾の "(" が close 先頭の
+ * ")" と対になる) とき inner、それ以外は null。
+ */
+const peelWrapper = (body: string, open: string, close: string): string | null => {
+    // 形が合わなければ自前ラッパではない
+    if (body.length <= open.length + close.length || !body.startsWith(open) || !body.endsWith(close)) {
+        return null
+    }
+    const inner = body.slice(open.length, body.length - close.length)
+    return isParenBalanced(inner) ? inner : null
+}
+
+/**
+ * Wraps a formula as `=(body)*100` / `*1000` / `/100` / `/1000`, or peels our own INVERSE wrapper
+ * (`=(inner)/100` under ×100 etc.) back to `=inner` — reversible: ×100 then ÷100 returns the
+ * original. Same-direction wrappers nest (`=((A1)*100)*100`). RangeError for a non-formula or an
+ * exponent outside ±2 / ±3.
+ * 数式を `=(body)*100` / `*1000` / `/100` / `/1000` へラップ、または自前の**逆**ラッパ (×100 なら
+ * `=(inner)/100` 等) を `=inner` へ剥離 — 可逆 (×100 の後の ÷100 は元へ)。同方向は入れ子
+ * (`=((A1)*100)*100`)。非数式と ±2 / ±3 以外の指数は RangeError。
+ */
+export const scaleFormula = (formula: string, exponent: ScaleExponent): string => {
+    assertScaleExponent(exponent)
+    const body = formulaBody(formula)
+    const power = Math.abs(exponent) === 2 ? "100" : "1000"
+    // ラップ演算子と、剥離対象 (逆演算) の演算子
+    const wrapOp = exponent > 0 ? "*" : "/"
+    const peelOp = exponent > 0 ? "/" : "*"
+    const inner = peelWrapper(body, "(", `)${peelOp}${power}`)
+    return inner === null ? `=(${body})${wrapOp}${power}` : `=${inner}`
+}
+
+/**
+ * Wraps a formula as `=-(body)`, or peels our own wrapper `=-(inner)` back to `=inner` —
+ * reversible (two reversals return the original). RangeError for a non-formula.
+ * 数式を `=-(body)` へラップ、または自前ラッパ `=-(inner)` を `=inner` へ剥離 — 可逆 (2 回で元へ)。
+ * 非数式は RangeError。
+ */
+export const reverseSignFormula = (formula: string): string => {
+    const body = formulaBody(formula)
+    const inner = peelWrapper(body, "-(", ")")
+    return inner === null ? `=-(${body})` : `=${inner}`
+}