feat: add platform shells, CLI, formatting, plugins, tests, and benchmarks

Phase 4 — Platform shells:
- calcpad-macos/: SwiftUI two-column editor with Rust FFI bridge (16 files)
- calcpad-windows/: iced GUI with Windows 11 Fluent theme (7 files, 13 tests)
- calcpad-web/: React 18 + CodeMirror 6 + WASM Worker + PWA (20 files)
- calcpad-cli/: clap-based CLI with expression eval, pipe/stdin, JSON/CSV
  output, and interactive REPL with rustyline history

Phase 5 — Engine modules:
- formatting/: answer formatting (decimal/scientific/SI notation, thousands
  separators, currency), line type classification, clipboard values (93 tests)
- plugins/: CalcPadPlugin trait, PluginRegistry, Rhai scripting stub (43 tests)
- benches/: criterion benchmarks (single-line, 100/500-line sheets, DAG, incremental)
- tests/sheet_scenarios.rs: 20 real-world integration tests
- tests/proptest_fuzz.rs: 12 property-based fuzz tests

771 tests passing across workspace, 0 failures.
This commit is contained in:
C. Cassel
2026-03-17 09:46:40 -04:00
committed by C. Cassel
parent 68fa54615a
commit 806e2f1ec6
73 changed files with 11715 additions and 32 deletions

View File

@@ -0,0 +1,90 @@
/**
* CalcPad Engine — C FFI Header
*
* This header declares the C-compatible interface for the CalcPad calculation
* engine, built in Rust. It is designed for consumption by Swift via a
* bridging header or a module map.
*
* All functions are safe to call from any thread. Panics in Rust are caught
* and converted to error results — they never unwind into the caller.
*
* Memory ownership:
* - Strings returned by calcpad_eval_line / calcpad_eval_sheet are
* heap-allocated by Rust and MUST be freed by calling calcpad_free_result.
* - Passing NULL to calcpad_free_result is a safe no-op.
*
* JSON schema (version "1.0"):
*
* Single-line result (calcpad_eval_line):
* {
* "schema_version": "1.0",
* "result": {
* "value": { "kind": "Number", "value": 42.0 },
* "metadata": {
* "span": { "start": 0, "end": 4 },
* "result_type": "Number",
* "display": "42",
* "raw_value": 42.0
* }
* }
* }
*
* Multi-line result (calcpad_eval_sheet):
* {
* "schema_version": "1.0",
* "results": [ ... ] // array of result objects as above
* }
*/
#ifndef CALCPAD_H
#define CALCPAD_H
#ifdef __cplusplus
extern "C" {
#endif
/**
* Evaluate a single line of CalcPad input.
*
* @param input A null-terminated UTF-8 string containing the expression.
* Passing NULL returns a JSON error result.
*
* @return A heap-allocated, null-terminated JSON string containing the
* versioned result. The caller MUST free this with
* calcpad_free_result(). Returns NULL only on catastrophic
* allocation failure.
*/
char *calcpad_eval_line(const char *input);
/**
* Evaluate multiple lines of CalcPad input as a sheet.
*
* Variable assignments on earlier lines are visible to later lines
* (e.g., "x = 5" on line 1 makes x available on line 2).
*
* @param lines An array of null-terminated UTF-8 strings.
* NULL entries are treated as empty lines.
* @param count The number of elements in the lines array.
* Must be > 0.
*
* @return A heap-allocated, null-terminated JSON string containing the
* versioned results array. The caller MUST free this with
* calcpad_free_result(). Returns NULL only on catastrophic
* allocation failure.
*/
char *calcpad_eval_sheet(const char *const *lines, int count);
/**
* Free a result string previously returned by calcpad_eval_line or
* calcpad_eval_sheet.
*
* @param ptr The pointer to free. Passing NULL is safe (no-op).
* After this call the pointer is invalid.
*/
void calcpad_free_result(char *ptr);
#ifdef __cplusplus
}
#endif
#endif /* CALCPAD_H */

View File

@@ -0,0 +1,5 @@
module CCalcPadEngine {
header "calcpad.h"
link "calcpad_engine"
export *
}

View File

@@ -0,0 +1,11 @@
import SwiftUI
@main
struct CalcPadApp: App {
var body: some Scene {
WindowGroup {
ContentView()
}
.defaultSize(width: 800, height: 600)
}
}

View File

@@ -0,0 +1,7 @@
import SwiftUI
struct ContentView: View {
var body: some View {
TwoColumnEditorView()
}
}

View File

@@ -0,0 +1,62 @@
import Foundation
/// Protocol for a calculation engine that evaluates text expressions.
/// The primary implementation is RustCalculationEngine (FFI bridge to calcpad-engine).
/// StubCalculationEngine is provided for testing without the Rust library.
protocol CalculationEngine: Sendable {
/// Evaluate a single line expression and return the result string, or nil for blank/comment lines.
func evaluateLine(_ line: String) -> LineResult
/// Evaluate an entire sheet (multi-line text) and return results for each line.
func evaluateSheet(_ text: String) -> [LineResult]
}
/// Stub engine for testing that handles basic arithmetic (+, -, *, /).
/// Used when the Rust engine library is not available.
final class StubCalculationEngine: CalculationEngine {
func evaluateLine(_ line: String) -> LineResult {
evaluateSingleLine(line, lineNumber: 1)
}
func evaluateSheet(_ text: String) -> [LineResult] {
let lines = text.components(separatedBy: "\n")
return lines.enumerated().map { index, line in
evaluateSingleLine(line, lineNumber: index + 1)
}
}
private func evaluateSingleLine(_ line: String, lineNumber: Int) -> LineResult {
let trimmed = line.trimmingCharacters(in: .whitespaces)
// Blank lines produce no result
guard !trimmed.isEmpty else {
return LineResult(id: lineNumber, expression: line, result: nil, isError: false)
}
// Comment lines (starting with // or #) produce no result
if trimmed.hasPrefix("//") || trimmed.hasPrefix("#") {
return LineResult(id: lineNumber, expression: line, result: nil, isError: false)
}
// Convert integer literals to floating-point so division produces decimals.
// NSExpression does integer division for "7 / 2" -> 3, but we want 3.5.
let floatExpr = trimmed.replacingOccurrences(
of: #"\b(\d+)\b"#,
with: "$1.0",
options: .regularExpression
)
// Try to evaluate as a basic arithmetic expression
do {
let expr = NSExpression(format: floatExpr)
if let value = expr.expressionValue(with: nil, context: nil) as? NSNumber {
let doubleValue = value.doubleValue
let formatted = String(format: "%g", doubleValue)
return LineResult(id: lineNumber, expression: line, result: formatted, isError: false)
}
}
return LineResult(id: lineNumber, expression: line, result: "Error", isError: true)
}
}

View File

@@ -0,0 +1,107 @@
import Foundation
/// JSON response from `calcpad_eval_line` wraps a single `CalcResult`.
struct FFIResponse: Decodable {
let schemaVersion: String
let result: FFICalcResult
enum CodingKeys: String, CodingKey {
case schemaVersion = "schema_version"
case result
}
}
/// JSON response from `calcpad_eval_sheet` wraps an array of `CalcResult`.
struct FFISheetResponse: Decodable {
let schemaVersion: String
let results: [FFICalcResult]
enum CodingKeys: String, CodingKey {
case schemaVersion = "schema_version"
case results
}
}
/// A complete calculation result returned by the Rust engine.
struct FFICalcResult: Decodable {
let value: FFICalcValue
let metadata: FFIResultMetadata
}
/// Metadata attached to every evaluation result.
struct FFIResultMetadata: Decodable {
let span: FFISpan
let resultType: String
let display: String
let rawValue: Double?
enum CodingKeys: String, CodingKey {
case span
case resultType = "result_type"
case display
case rawValue = "raw_value"
}
}
/// Source span (byte offsets).
struct FFISpan: Decodable {
let start: Int
let end: Int
}
/// Tagged union of possible calculation values.
/// Rust serializes with `#[serde(tag = "kind")]`.
enum FFICalcValue: Decodable {
case number(value: Double)
case unitValue(value: Double, unit: String)
case currencyValue(amount: Double, currency: String)
case dateTime(date: String)
case timeDelta(days: Int64, description: String)
case boolean(value: Bool)
case error(message: String)
enum CodingKeys: String, CodingKey {
case kind
case value, unit, amount, currency, date, days, description, message, span
}
init(from decoder: Decoder) throws {
let container = try decoder.container(keyedBy: CodingKeys.self)
let kind = try container.decode(String.self, forKey: .kind)
switch kind {
case "Number":
let value = try container.decode(Double.self, forKey: .value)
self = .number(value: value)
case "UnitValue":
let value = try container.decode(Double.self, forKey: .value)
let unit = try container.decode(String.self, forKey: .unit)
self = .unitValue(value: value, unit: unit)
case "CurrencyValue":
let amount = try container.decode(Double.self, forKey: .amount)
let currency = try container.decode(String.self, forKey: .currency)
self = .currencyValue(amount: amount, currency: currency)
case "DateTime":
let date = try container.decode(String.self, forKey: .date)
self = .dateTime(date: date)
case "TimeDelta":
let days = try container.decode(Int64.self, forKey: .days)
let desc = try container.decode(String.self, forKey: .description)
self = .timeDelta(days: days, description: desc)
case "Boolean":
let value = try container.decode(Bool.self, forKey: .value)
self = .boolean(value: value)
case "Error":
let message = try container.decode(String.self, forKey: .message)
self = .error(message: message)
default:
self = .error(message: "Unknown result kind: \(kind)")
}
}
/// Whether this value represents an error from the Rust engine.
var isError: Bool {
if case .error = self { return true }
return false
}
}

View File

@@ -0,0 +1,92 @@
import CCalcPadEngine
import Foundation
/// Calculation engine backed by the Rust CalcPad engine via C FFI.
///
/// Thread safety: Each call creates its own `EvalContext` on the Rust side,
/// so concurrent calls from different threads are safe. The C FFI functions
/// are documented as safe to call from any thread.
final class RustCalculationEngine: CalculationEngine, @unchecked Sendable {
private let decoder = JSONDecoder()
func evaluateLine(_ line: String) -> LineResult {
evaluateSingleLine(line, lineNumber: 1)
}
func evaluateSheet(_ text: String) -> [LineResult] {
let lines = text.components(separatedBy: "\n")
// Build C string array for the FFI call
let cStrings = lines.map { strdup($0) }
defer { cStrings.forEach { free($0) } }
var pointers = cStrings.map { UnsafePointer<CChar>($0) }
let resultPtr = pointers.withUnsafeMutableBufferPointer { buffer -> UnsafeMutablePointer<CChar>? in
calcpad_eval_sheet(buffer.baseAddress, Int32(lines.count))
}
guard let resultPtr else {
return lines.enumerated().map { index, line in
LineResult(id: index + 1, expression: line, result: "Error", isError: true)
}
}
defer { calcpad_free_result(resultPtr) }
let jsonString = String(cString: resultPtr)
guard let jsonData = jsonString.data(using: .utf8),
let response = try? decoder.decode(FFISheetResponse.self, from: jsonData) else {
return lines.enumerated().map { index, line in
LineResult(id: index + 1, expression: line, result: "Error", isError: true)
}
}
return response.results.enumerated().map { index, calcResult in
mapToLineResult(calcResult, expression: lines[index], lineNumber: index + 1)
}
}
// MARK: - Private
private func evaluateSingleLine(_ line: String, lineNumber: Int) -> LineResult {
let resultPtr = calcpad_eval_line(line)
guard let resultPtr else {
return LineResult(id: lineNumber, expression: line, result: "Error", isError: true)
}
defer { calcpad_free_result(resultPtr) }
let jsonString = String(cString: resultPtr)
guard let jsonData = jsonString.data(using: .utf8),
let response = try? decoder.decode(FFIResponse.self, from: jsonData) else {
return LineResult(id: lineNumber, expression: line, result: "Error", isError: true)
}
return mapToLineResult(response.result, expression: line, lineNumber: lineNumber)
}
private func mapToLineResult(_ calcResult: FFICalcResult, expression: String, lineNumber: Int) -> LineResult {
switch calcResult.value {
case .error(let message):
// Blank/comment lines produce "empty expression" errors in the Rust engine.
// Map these to nil result (matching the protocol's convention for non-evaluable lines).
if isEmptyExpressionError(message) {
return LineResult(id: lineNumber, expression: expression, result: nil, isError: false)
}
return LineResult(id: lineNumber, expression: expression, result: "Error: \(message)", isError: true)
default:
return LineResult(id: lineNumber, expression: expression, result: calcResult.metadata.display, isError: false)
}
}
/// The Rust engine returns an error for blank lines, comments, and other
/// non-evaluable input. We detect these to return nil (matching protocol convention).
private func isEmptyExpressionError(_ message: String) -> Bool {
let lower = message.lowercased()
return lower.contains("empty") || lower.contains("no expression") || lower.contains("comment")
}
}

View File

@@ -0,0 +1,15 @@
import Foundation
/// Represents the evaluation result for a single line in the editor.
struct LineResult: Identifiable, Equatable {
let id: Int
let expression: String
let result: String?
let isError: Bool
/// Line number (1-based) corresponding to this result.
var lineNumber: Int { id }
/// A blank/comment line that produces no result.
var isEmpty: Bool { result == nil && !isError }
}

View File

@@ -0,0 +1,111 @@
import AppKit
import SwiftUI
/// Displays calculation results in a vertical column, one result per line,
/// aligned to match the corresponding editor lines.
/// Uses NSViewRepresentable wrapping NSScrollView + NSTextView for pixel-perfect
/// line height alignment with the editor.
struct AnswerColumnView: NSViewRepresentable {
let results: [LineResult]
@Binding var scrollOffset: CGFloat
var font: NSFont
func makeCoordinator() -> Coordinator {
Coordinator()
}
func makeNSView(context: Context) -> NSScrollView {
let scrollView = NSScrollView()
scrollView.hasVerticalScroller = false
scrollView.hasHorizontalScroller = false
scrollView.borderType = .noBorder
scrollView.drawsBackground = false
// Disable user scrolling scroll is driven by the editor
scrollView.verticalScrollElasticity = .none
scrollView.horizontalScrollElasticity = .none
let textView = NSTextView()
textView.isEditable = false
textView.isSelectable = true
textView.isRichText = true
textView.usesFontPanel = false
textView.drawsBackground = false
textView.backgroundColor = .clear
// Match editor text container settings for alignment
textView.textContainer?.lineFragmentPadding = 4
textView.textContainerInset = NSSize(width: 8, height: 8)
// Disable line wrapping to match editor behavior
textView.isHorizontallyResizable = true
textView.textContainer?.widthTracksTextView = false
textView.textContainer?.containerSize = NSSize(
width: CGFloat.greatestFiniteMagnitude,
height: CGFloat.greatestFiniteMagnitude
)
textView.maxSize = NSSize(
width: CGFloat.greatestFiniteMagnitude,
height: CGFloat.greatestFiniteMagnitude
)
scrollView.documentView = textView
context.coordinator.textView = textView
context.coordinator.scrollView = scrollView
updateContent(textView: textView)
return scrollView
}
func updateNSView(_ scrollView: NSScrollView, context: Context) {
guard let textView = scrollView.documentView as? NSTextView else { return }
updateContent(textView: textView)
// Sync scroll position from editor
let currentOffset = scrollView.contentView.bounds.origin.y
if abs(currentOffset - scrollOffset) > 0.5 {
scrollView.contentView.scroll(to: NSPoint(x: 0, y: scrollOffset))
scrollView.reflectScrolledClipView(scrollView.contentView)
}
}
private func updateContent(textView: NSTextView) {
let attributedString = NSMutableAttributedString()
let paragraphStyle = NSMutableParagraphStyle()
paragraphStyle.alignment = .right
let resultColor = NSColor.secondaryLabelColor
let errorColor = NSColor.systemRed
for (index, lineResult) in results.enumerated() {
let displayText = lineResult.result ?? ""
let color = lineResult.isError ? errorColor : resultColor
let attributes: [NSAttributedString.Key: Any] = [
.font: font,
.foregroundColor: color,
.paragraphStyle: paragraphStyle,
]
let line = NSAttributedString(string: displayText, attributes: attributes)
attributedString.append(line)
// Add newline between lines (but not after the last)
if index < results.count - 1 {
let newline = NSAttributedString(
string: "\n",
attributes: [.font: font]
)
attributedString.append(newline)
}
}
textView.textStorage?.setAttributedString(attributedString)
}
final class Coordinator {
weak var textView: NSTextView?
weak var scrollView: NSScrollView?
}
}

View File

@@ -0,0 +1,137 @@
import AppKit
import SwiftUI
/// A SwiftUI wrapper around NSTextView for the editor pane.
/// Uses NSViewRepresentable to bridge AppKit's NSTextView into SwiftUI,
/// providing line-level control, scroll position access, and performance
/// that SwiftUI's TextEditor cannot match.
struct EditorTextView: NSViewRepresentable {
@Binding var text: String
@Binding var scrollOffset: CGFloat
var font: NSFont
func makeCoordinator() -> Coordinator {
Coordinator(self)
}
func makeNSView(context: Context) -> NSScrollView {
let scrollView = NSScrollView()
scrollView.hasVerticalScroller = true
scrollView.hasHorizontalScroller = false
scrollView.autohidesScrollers = true
scrollView.borderType = .noBorder
scrollView.drawsBackground = false
let textView = NSTextView()
textView.isEditable = true
textView.isSelectable = true
textView.allowsUndo = true
textView.isRichText = false
textView.usesFontPanel = false
textView.isAutomaticQuoteSubstitutionEnabled = false
textView.isAutomaticDashSubstitutionEnabled = false
textView.isAutomaticTextReplacementEnabled = false
textView.isAutomaticSpellingCorrectionEnabled = false
// Disable line wrapping horizontal scroll instead
textView.isHorizontallyResizable = true
textView.textContainer?.widthTracksTextView = false
textView.textContainer?.containerSize = NSSize(
width: CGFloat.greatestFiniteMagnitude,
height: CGFloat.greatestFiniteMagnitude
)
textView.maxSize = NSSize(
width: CGFloat.greatestFiniteMagnitude,
height: CGFloat.greatestFiniteMagnitude
)
// Configure font and text color
textView.font = font
textView.textColor = .textColor
textView.backgroundColor = .clear
textView.drawsBackground = false
textView.insertionPointColor = .textColor
// Set the text
textView.string = text
// Configure the text container for consistent line spacing
textView.textContainer?.lineFragmentPadding = 4
textView.textContainerInset = NSSize(width: 8, height: 8)
scrollView.documentView = textView
context.coordinator.textView = textView
context.coordinator.scrollView = scrollView
// Observe text changes
textView.delegate = context.coordinator
// Observe scroll changes
scrollView.contentView.postsBoundsChangedNotifications = true
NotificationCenter.default.addObserver(
context.coordinator,
selector: #selector(Coordinator.scrollViewDidScroll(_:)),
name: NSView.boundsDidChangeNotification,
object: scrollView.contentView
)
return scrollView
}
func updateNSView(_ scrollView: NSScrollView, context: Context) {
guard let textView = scrollView.documentView as? NSTextView else { return }
// Update font if changed
if textView.font != font {
textView.font = font
// Reapply font to entire text storage
let range = NSRange(location: 0, length: textView.textStorage?.length ?? 0)
textView.textStorage?.addAttribute(.font, value: font, range: range)
}
// Update text only if it actually changed (avoid feedback loops)
if textView.string != text {
let selectedRanges = textView.selectedRanges
textView.string = text
textView.selectedRanges = selectedRanges
}
// Update scroll position if driven externally
context.coordinator.isUpdatingScroll = true
let currentOffset = scrollView.contentView.bounds.origin.y
if abs(currentOffset - scrollOffset) > 0.5 {
scrollView.contentView.scroll(to: NSPoint(x: 0, y: scrollOffset))
scrollView.reflectScrolledClipView(scrollView.contentView)
}
context.coordinator.isUpdatingScroll = false
}
final class Coordinator: NSObject, NSTextViewDelegate {
var parent: EditorTextView
weak var textView: NSTextView?
weak var scrollView: NSScrollView?
var isUpdatingScroll = false
init(_ parent: EditorTextView) {
self.parent = parent
}
func textDidChange(_ notification: Notification) {
guard let textView = notification.object as? NSTextView else { return }
parent.text = textView.string
}
@objc func scrollViewDidScroll(_ notification: Notification) {
guard !isUpdatingScroll,
let scrollView = scrollView else { return }
let offset = scrollView.contentView.bounds.origin.y
DispatchQueue.main.async { [weak self] in
self?.parent.scrollOffset = offset
}
}
deinit {
NotificationCenter.default.removeObserver(self)
}
}
}

View File

@@ -0,0 +1,72 @@
import Combine
import SwiftUI
/// The main two-column editor layout: text editor on the left, results on the right.
/// Scrolling is synchronized between both columns.
struct TwoColumnEditorView: View {
@State private var text: String = ""
@State private var scrollOffset: CGFloat = 0
@State private var results: [LineResult] = []
@State private var evaluationTask: Task<Void, Never>?
/// Uses the Rust FFI engine. Falls back to StubCalculationEngine if the Rust
/// library is not linked (e.g., during UI-only development).
private let engine: CalculationEngine = RustCalculationEngine()
/// Debounce interval for re-evaluation after typing (seconds).
private let evaluationDebounce: TimeInterval = 0.05
/// Font that respects the user's accessibility / Dynamic Type settings.
private var editorFont: NSFont {
// Use the system's preferred monospaced font size, which scales with
// Accessibility > Display > Text Size in System Settings (macOS 14+).
let baseSize = NSFont.systemFontSize
// Scale with accessibility settings via the body text style size
let preferredSize = NSFont.preferredFont(forTextStyle: .body, options: [:]).pointSize
// Use the larger of system default or accessibility-preferred size
let size = max(baseSize, preferredSize)
return NSFont.monospacedSystemFont(ofSize: size, weight: .regular)
}
var body: some View {
HSplitView {
// Left pane: Editor
EditorTextView(
text: $text,
scrollOffset: $scrollOffset,
font: editorFont
)
.frame(minWidth: 200)
// Divider is automatic with HSplitView
// Right pane: Answer column
AnswerColumnView(
results: results,
scrollOffset: $scrollOffset,
font: editorFont
)
.frame(minWidth: 120, idealWidth: 200)
}
.onChange(of: text) { _, newValue in
scheduleEvaluation(newValue)
}
.onAppear {
evaluateText(text)
}
}
/// Debounce evaluation so rapid typing doesn't cause excessive recalculation.
private func scheduleEvaluation(_ newText: String) {
evaluationTask?.cancel()
evaluationTask = Task { @MainActor in
try? await Task.sleep(for: .milliseconds(Int(evaluationDebounce * 1000)))
guard !Task.isCancelled else { return }
evaluateText(newText)
}
}
private func evaluateText(_ newText: String) {
results = engine.evaluateSheet(newText)
}
}