بِسْمِ اللَّهِ الرَّحْمَٰنِ الرَّحِيمِ

In the name of Allah, the Compassionate, the Merciful

@modelscript/csv

RFC 4180 Comma-Separated Values (.csv) WebAssembly GLR parser, semantic table validator, delimiter auto-detector, Modelica parameter package & CombiTimeTable generator, and polyglot virtual component indexer for ModelScript.

---

Core Capabilities

• WASM GLR Incremental Parser: Generated by @modelscript/dsl (buildParser) into native WebAssembly (parser.wasm), parsing quoted and unquoted cells, embedded delimiters, escaped quotes (""), and multi-platform line endings (\r\n, \n, \r).
• Delimiter Auto-Detection & Measurement Parsing (parseCsvMeasurements): Automatically detects comma (,), semicolon (;), and tab (\t) delimiters outside quoted strings, resolves configurable or auto-detected time columns (time, t), maps column headers to Modelica variables, and extracts typed numerical time-series vectors for model calibration and telemetry plotting.
• Modelica Package & CombiTimeTable Codegen (parseCsvToModelica): Transpiles tabular CSV files into strongly-typed Modelica package definitions containing numRows, numCols, full 2D constant matrices (constant Real values[numRows, numCols]), and per-column 1D constant vectors compatible with Modelica.Blocks.Sources.CombiTimeTable and polyglot workspace imports.
• 6 CSV_* Semantic Lint Rules (lintCsv): Tokenizes CSV files with exact byte and 1-indexed line/column spans to diagnose structural, quoting, numeric, and time-monotonicity errors, wired directly into Salsa via lint__csvTableValidity.
• CSVVirtualComponent Salsa Queries: Exposes virtual component symbols for each CSV column and matrix to the polyglot WorkspaceIndex, providing demand-driven Salsa query hooks (resolvedType, classInstance, variability, causality, resolvedArrayDimensions, arrayDimensions, effectiveModification).
• Bidirectional Cell Writeback: Implements csvLanguage.writeback to propagate parameter modifications from simulation explorers, table editors, or coupled Modelica models directly back to the exact byte range of the target CSV cell.
• Polyglot TGG Rules: Bidirectional Triple Graph Grammar rules mapping CSV documents and virtual column components to Modelica packages and constant declarations.

---

Package Structure

Path	Description
language.ts	csvLanguage grammar definition, CSVVirtualComponent Salsa query hooks, cell writeback handler, LSP actions, and TGG rules
src/csv-parser.ts	parseCsvMeasurements, delimiter auto-detection, parseCsvToModelica generator, and lintCsv semantic linter (CSV_* rules)
build.js	Compiles language.ts into the native WebAssembly GLR parser (dist/parser.wasm) and generated TypeScript bindings
src-gen/	Auto-generated WASM parser bindings (createWasmParser)

---

Semantic Lint Rules (CSV_*)

Code	Severity	Description
CSV_UNCLOSED_QUOTE	error	Quoted cell string is missing a closing double-quote (") before end of row or file
CSV_EMPTY_HEADER	error	Header column cell in the first row is empty
CSV_DUPLICATE_HEADER	error	Duplicate column header name already declared in an earlier column
CSV_COLUMN_COUNT_MISMATCH	error	Data row column count does not match the header row column count (underlines excess cells)
CSV_INVALID_NUMERIC_CELL	error / warning	Missing (warning) or non-numeric (error) cell value in a numeric or time column
CSV_NON_MONOTONIC_TIME	warning	Time column value decreases relative to the preceding row ($t_k < t_{k-1}$)

---

Polyglot Triple Graph Grammar (TGG) Rules

Rule Name	Source (csv)	Target (modelica)
CsvDocumentToModelicaPackage	SourceFile(rows: docName)	ClassDefinition(name: docName, classKind: "package")
CsvVirtualComponentToModelicaComponent	CSVVirtualComponent(name: varName, typeSpecifier: typeName)	ComponentClause(name: varName, typeSpecifier: typeName)

---

Scripts

Command	Description
npm run build	Build WASM parser (node build.js) and compile TypeScript
npm run build:parser	Force-rebuild parser.wasm and generated bindings
npm test	Run unit and linter test suites via test-runner.js
npm run lint	Run ESLint across language.ts, src/, and tests/
npm run typecheck	Run tsc --noEmit type verification
npm run clean	Remove dist/, src-gen/, and .wasm build artifacts

---

Programmatic Usage

import { csvLanguage, lintCsv } from "@modelscript/csv";
import { parseCsvMeasurements, parseCsvToModelica } from "@modelscript/csv/csv-parser";
import { createWasmParser } from "@modelscript/csv/parser";

// 1. Parse time-series measurement data with automatic delimiter detection
const csvText = `time;voltage;current\n0.0;230.0;12.5\n0.1;229.4;12.8\n0.2;230.1;12.6\n`;
const measurements = parseCsvMeasurements(csvText);
console.log(measurements.time, measurements.data.get("voltage"));

// 2. Run semantic CSV lint rules
const diagnostics = lintCsv(csvText);

// 3. Transpile CSV table into a Modelica constant parameter package
const modelicaPkg = parseCsvToModelica(csvText, "GridTelemetry");

// 4. Initialize native WASM GLR parser
const wasmPath = require.resolve("@modelscript/csv/parser.wasm");
const { parser } = await createWasmParser(wasmPath);
const tree = parser.parse(csvText);