Refactor and enhance OSF parser and documentation

## Summary
- Improved string parsing in the OSF parser to handle escape sequences, including backslashes, quotes, and control characters.
- Added a new function `escapeString` to ensure proper serialization of strings with escape sequences.
- Updated tests to cover various scenarios for escape sequences in strings, bullet points, arrays, and objects.
- Enhanced documentation to clarify the handling of escape sequences and updated the roadmap in the specification.

## Testing
- Run `pnpm test` to verify all new and existing tests pass successfully.

Author: alpha912

README.md

@@ -191,7 +191,6 @@ Join us on
 [GitHub Discussions](https://github.com/OmniScriptOSF/omniscript-core/discussions)
 to propose ideas, ask questions, or share feedback.
 
-
 ## 💡 Vision
 
 OmniScript Format (OSF) aims to be the universal document source language — a
@@ -200,6 +199,9 @@ world of AI collaboration and versioned knowledge.
 
 ## ❗ Known Limitations (v0.5)
 
-- The initial CLI only covers parsing, linting and basic rendering; advanced conversion targets are under development.
-- Diagram blocks, citation syntax and macro support are planned for future revisions.
-- Formal grammar and normative references are scheduled for a later appendix release.
+- The initial CLI only covers parsing, linting and basic rendering; advanced
+  conversion targets are under development.
+- Diagram blocks, citation syntax and macro support are planned for future
+  revisions.
+- Formal grammar and normative references are scheduled for a later appendix
+  release.

cli/src/osf.ts

@@ -32,8 +32,7 @@ const commands: CliCommand[] = [
   {
     name: 'render',
     description: 'Render OSF to various output formats',
-    usage:
-      'osf render <file> [--format <html|pdf|docx|pptx|xlsx>] [--output <file>]',
+    usage: 'osf render <file> [--format <html|pdf|docx|pptx|xlsx>] [--output <file>]',
     args: ['file'],
   },
   {
@@ -149,10 +148,10 @@ class FormulaEvaluator {
 
     // Replace cell references with actual values
     const cellRefRegex = /\b([A-Z]+\d+)\b/g;
-    const processedExpr = expr.replace(cellRefRegex, (match) => {
+    const processedExpr = expr.replace(cellRefRegex, match => {
       const [row, col] = this.cellRefToCoords(match);
       const value = this.getCellValue(row, col);
-      
+
       // Convert to number if possible, otherwise use as string
       if (typeof value === 'number') {
         return value.toString();
@@ -181,14 +180,14 @@ class FormulaEvaluator {
     while (expr.includes('(')) {
       const innerMatch = expr.match(/\(([^()]+)\)/);
       if (!innerMatch) break;
-      
+
       const innerResult = this.evaluateExpression(innerMatch[1]!);
       expr = expr.replace(innerMatch[0]!, innerResult.toString());
     }
 
     // Handle multiplication and division (left to right, same precedence)
     expr = this.evaluateOperatorsLeftToRight(expr, ['*', '/']);
-    
+
     // Handle addition and subtraction (left to right, same precedence)
     expr = this.evaluateOperatorsLeftToRight(expr, ['+', '-']);
 
@@ -197,7 +196,7 @@ class FormulaEvaluator {
     if (isNaN(result)) {
       throw new Error(`Invalid expression: ${expr}`);
     }
-    
+
     return result;
   }
 
@@ -206,37 +205,44 @@ class FormulaEvaluator {
     // Create a regex that matches any of the operators
     const opPattern = operators.map(op => `\\${op}`).join('|');
     const regex = new RegExp(`(-?\\d+(?:\\.\\d+)?)(${opPattern})(-?\\d+(?:\\.\\d+)?)`, 'g');
-    
+
     // Keep evaluating until no more matches
     while (regex.test(expr)) {
       regex.lastIndex = 0; // Reset regex
       expr = expr.replace(regex, (_, left, op, right) => {
         const leftNum = parseFloat(left);
         const rightNum = parseFloat(right);
         let result: number;
-        
+
         switch (op) {
-          case '+': result = leftNum + rightNum; break;
-          case '-': result = leftNum - rightNum; break;
-          case '*': result = leftNum * rightNum; break;
-          case '/': 
+          case '+':
+            result = leftNum + rightNum;
+            break;
+          case '-':
+            result = leftNum - rightNum;
+            break;
+          case '*':
+            result = leftNum * rightNum;
+            break;
+          case '/':
             if (rightNum === 0) throw new Error('Division by zero');
-            result = leftNum / rightNum; 
+            result = leftNum / rightNum;
             break;
-          default: throw new Error(`Unknown operator: ${op}`);
+          default:
+            throw new Error(`Unknown operator: ${op}`);
         }
-        
+
         return result.toString();
       });
     }
-    
+
     return expr;
   }
 
   // Get all computed values for a sheet
   getAllComputedValues(maxRow: number, maxCol: number): Record<string, any> {
     const result: Record<string, any> = {};
-    
+
     for (let r = 1; r <= maxRow; r++) {
       for (let c = 1; c <= maxCol; c++) {
         const key = `${r},${c}`;
@@ -251,7 +257,7 @@ class FormulaEvaluator {
         }
       }
     }
-    
+
     return result;
   }
 }
@@ -402,15 +408,15 @@ function renderHtml(doc: OSFDocument): string {
         if (sheet.data) {
           // Evaluate formulas
           const evaluator = new FormulaEvaluator(sheet.data, sheet.formulas || []);
-          
+
           // Calculate dimensions including formula cells
           const dataCoords = Object.keys(sheet.data).map(k => k.split(',').map(Number));
           const formulaCoords = (sheet.formulas || []).map((f: any) => f.cell);
           const allCoords = [...dataCoords, ...formulaCoords];
-          
+
           const maxRow = Math.max(...allCoords.map(c => c[0]!));
           const maxCol = Math.max(...allCoords.map(c => c[1]!));
-          
+
           // Get all computed values including formulas
           const allValues = evaluator.getAllComputedValues(maxRow, maxCol);
 
@@ -420,12 +426,14 @@ function renderHtml(doc: OSFDocument): string {
             for (let c = 1; c <= maxCol; c++) {
               const key = `${r},${c}`;
               const val = allValues[key] ?? '';
-              const hasFormula = sheet.formulas?.some((f: any) => f.cell[0] === r && f.cell[1] === c);
+              const hasFormula = sheet.formulas?.some(
+                (f: any) => f.cell[0] === r && f.cell[1] === c
+              );
               const isError = typeof val === 'string' && val.startsWith('#ERROR:');
-              
-              const cssClass = isError ? 'error' : (hasFormula ? 'computed' : '');
+
+              const cssClass = isError ? 'error' : hasFormula ? 'computed' : '';
               const cellContent = isError ? val.replace('#ERROR: ', '') : val;
-              
+
               parts.push(`        <td class="${cssClass}">${cellContent}</td>`);
             }
             parts.push('      </tr>');
@@ -525,15 +533,15 @@ function exportMarkdown(doc: OSFDocument): string {
         if (sheet.data) {
           // Evaluate formulas
           const evaluator = new FormulaEvaluator(sheet.data, sheet.formulas || []);
-          
+
           // Calculate dimensions including formula cells
           const dataCoords = Object.keys(sheet.data).map(k => k.split(',').map(Number));
           const formulaCoords = (sheet.formulas || []).map((f: any) => f.cell);
           const allCoords = [...dataCoords, ...formulaCoords];
-          
+
           const maxRow = Math.max(...allCoords.map(c => c[0]!));
           const maxCol = Math.max(...allCoords.map(c => c[1]!));
-          
+
           // Get all computed values including formulas
           const allValues = evaluator.getAllComputedValues(maxRow, maxCol);
 
@@ -542,8 +550,10 @@ function exportMarkdown(doc: OSFDocument): string {
             for (let c = 1; c <= maxCol; c++) {
               const key = `${r},${c}`;
               const val = allValues[key] ?? '';
-              const hasFormula = sheet.formulas?.some((f: any) => f.cell[0] === r && f.cell[1] === c);
-              
+              const hasFormula = sheet.formulas?.some(
+                (f: any) => f.cell[0] === r && f.cell[1] === c
+              );
+
               if (hasFormula && typeof val === 'number') {
                 // Show computed value with indication it's calculated
                 cells.push(`${val} *(calc)*`);
@@ -583,35 +593,35 @@ function exportJson(doc: OSFDocument): string {
       case 'sheet': {
         const sheet: any = { ...block };
         delete sheet.type;
-        
+
         if (sheet.data) {
           // Evaluate formulas and include computed values
           const evaluator = new FormulaEvaluator(sheet.data, sheet.formulas || []);
-          
+
           // Calculate dimensions including formula cells
           const dataCoords = Object.keys(sheet.data).map((k: string) => k.split(',').map(Number));
           const formulaCoords = (sheet.formulas || []).map((f: any) => f.cell);
           const allCoords = [...dataCoords, ...formulaCoords];
-          
+
           const maxRow = Math.max(...allCoords.map(c => c[0]!));
           const maxCol = Math.max(...allCoords.map(c => c[1]!));
-          
+
           // Get all computed values including formulas
           const allValues = evaluator.getAllComputedValues(maxRow, maxCol);
-          
+
           // Convert to array format with computed values
           sheet.data = Object.entries(allValues).map(([cell, value]) => {
             const [r, c] = cell.split(',').map(Number);
             const hasFormula = sheet.formulas?.some((f: any) => f.cell[0] === r && f.cell[1] === c);
-            return { 
-              row: r, 
-              col: c, 
+            return {
+              row: r,
+              col: c,
               value,
-              computed: hasFormula 
+              computed: hasFormula,
             };
           });
         }
-        
+
         if (sheet.formulas) {
           sheet.formulas = sheet.formulas.map((f: any) => ({
             row: f.cell[0],
@@ -763,9 +773,7 @@ function main(): void {
             output = renderXlsx(doc);
             break;
           default:
-            throw new Error(
-              `Unknown format: ${format}. Supported: html, pdf, docx, pptx, xlsx`
-            );
+            throw new Error(`Unknown format: ${format}. Supported: html, pdf, docx, pptx, xlsx`);
         }
 
         if (outputFile) {

cli/tests/cli.test.ts

@@ -308,16 +308,16 @@ describe('OSF CLI', () => {
       expect(exported.docs).toHaveLength(1);
       expect(exported.slides).toHaveLength(1);
       expect(exported.sheets).toHaveLength(1);
-      
+
       // Check that computed values are included
       const sheet = exported.sheets[0];
       expect(sheet.data).toBeDefined();
       expect(Array.isArray(sheet.data)).toBe(true);
-      
+
       // Find computed cells
       const computedCells = sheet.data.filter((cell: any) => cell.computed === true);
       expect(computedCells.length).toBeGreaterThan(0);
-      
+
       // Check specific computed values
       const growthCell1 = sheet.data.find((cell: any) => cell.row === 2 && cell.col === 3);
       const growthCell2 = sheet.data.find((cell: any) => cell.row === 3 && cell.col === 3);
@@ -336,18 +336,18 @@ describe('OSF CLI', () => {
 
         const exported = JSON.parse(result);
         const sheet = exported.sheets[0];
-        
+
         // Check computed values
         const cellC1 = sheet.data.find((cell: any) => cell.row === 1 && cell.col === 3);
         const cellD1 = sheet.data.find((cell: any) => cell.row === 1 && cell.col === 4);
         const cellC2 = sheet.data.find((cell: any) => cell.row === 2 && cell.col === 3);
         const cellD2 = sheet.data.find((cell: any) => cell.row === 2 && cell.col === 4);
-        
+
         expect(cellC1?.value).toBe(30); // A1+B1 = 10+20 = 30
         expect(cellD1?.value).toBe(200); // A1*B1 = 10*20 = 200
         expect(cellC2?.value).toBe(20); // A2+B2 = 5+15 = 20
         expect(cellD2?.value).toBe(50); // C1+C2 = 30+20 = 50
-        
+
         // Check computed flags
         expect(cellC1?.computed).toBe(true);
         expect(cellD1?.computed).toBe(true);

docs/architecture.md

@@ -4,7 +4,9 @@ This repository hosts the reference implementation of **OmniScript Format
 (OSF)**. The codebase is organised as a monorepo with separate packages for the
 parser and CLI.
 
-The `spec/` directory contains versioned specifications. The current release is [spec/v0.5](../spec/v0.5/) which defines the grammar and JSON schema used by the parser.
+The `spec/` directory contains versioned specifications. The current release is
+[spec/v0.5](../spec/v0.5/) which defines the grammar and JSON schema used by the
+parser.
 
 ```
 omniscript-core/

docs/contributing.md

@@ -2,7 +2,8 @@
 
 We welcome pull requests!
 
-1. Read the OSF v0.5 specification in [spec/v0.5](../spec/v0.5/) to understand the current language features.
+1. Read the OSF v0.5 specification in [spec/v0.5](../spec/v0.5/) to understand
+   the current language features.
 2. Follow the coding style used in the parser and CLI packages.
 3. Tests are located under `tests/` and `parser/tests`. Please add tests for new
    functionality.

docs/spec-v0.5-overview.md

@@ -1,7 +1,8 @@
 # OSF v0.5 Overview
 
-This document summarises the key elements of the OmniScript Format v0.5 specification.
-Refer to the files under `spec/v0.5/` for the authoritative specification.
+This document summarises the key elements of the OmniScript Format v0.5
+specification. Refer to the files under `spec/v0.5/` for the authoritative
+specification.
 
 ## Core Blocks