@nachoggodino/cello 0.1.0

package/docs/ARCHITECTURE.md

@@ -0,0 +1,43 @@
+# Architecture
+
+## Pipeline
+
+1. `parse(text)` -> AST
+2. `evaluate(ast)` -> AST with computed formula values when possible
+3. `render(text|ast)` -> self-contained HTML
+4. `serialize(ast)` -> `.cel` text
+
+## Main modules
+
+- `src/parser/parse.ts`
+  - Parses workbook/sheets/rows/cells
+  - Handles `@sheet`, `@header`, `@defaults`, rows, row modifiers, merges, external sheet source (`-> path`), formats (`csv/tsv/excel/markdown/json`)
+  - Emits parser diagnostics
+
+- `src/evaluator/evaluate.ts`
+  - Deep-clones AST
+  - Skips HyperFormula loading when the workbook contains no formulas
+  - Builds per-sheet matrix for HyperFormula
+  - Translates supported named references to A1 ranges before engine evaluation
+  - Evaluates formula cells and writes `computed`
+  - Emits diagnostics on evaluation failures
+
+- `src/renderer/render.ts`
+  - Parses text input, including external sheet sources through `baseDir`
+  - Evaluates by default, with `evaluate: false` available for raw formula previews
+  - Generates HTML tabs + tables
+  - Applies inline formatting and style modifiers (`bold`, `italic`, `bg`, color)
+
+- `src/serializer/serialize.ts`
+  - Converts AST back to `.cel` text for roundtrip workflows
+
+- `src/cli/serve.ts`
+  - Serves a rendered workbook over local HTTP
+  - Caches rendered HTML and refreshes it when the source file changes
+  - Injects a small live-reload script for browser previews
+
+## Design notes
+
+- BYLAWS-first behavior is normative for syntax decisions.
+- Named-reference translation is intentionally narrow: named columns and `!!` alias supported.
+- Parsing is permissive by design; unknown constructs tend to degrade to text/diagnostics.

package/docs/CLI.md

@@ -0,0 +1,58 @@
+# CLI Reference
+
+The package exposes a `cello` CLI binary from `dist/cli/cli.js`.
+
+## Commands
+
+- `cello parse <file.cel>`
+  - Prints parsed AST as JSON.
+
+- `cello --version`
+  - Prints the package version.
+
+- `cello evaluate <file.cel>`
+  - Parses and evaluates formulas, prints resulting AST as JSON.
+
+- `cello format <file.cel> [--check] [-o out.cel]`
+  - Pretty-prints native Cello pipe tables with padded cells.
+  - Rewrites the input file in place by default.
+  - `-o` / `--out` writes formatted output to another path instead.
+  - `--check` exits `0` when the file is already formatted and `1` when formatting would change it.
+
+- `cello validate <file.cel>`
+  - Parses and evaluates workbook diagnostics.
+  - Prints `{ "valid": boolean, "diagnostics": [...] }` as JSON.
+  - Exits `0` when there are no diagnostics, otherwise exits `1`.
+
+- `cello render <file.cel> [-o out.html] [--no-eval] [--format document|fragment]`
+  - Renders workbook to self-contained HTML.
+  - `--format document` is the default full HTML document.
+  - `--format fragment` emits an embeddable chunk without `html`, `head`, or `body` wrappers.
+  - Use `--no-eval` to render formula text without evaluating formulas.
+  - If `-o/--out` is provided, writes to file and prints `Wrote <absolute-path>`.
+  - Otherwise prints HTML to stdout.
+
+- `cello serialize <file.cel> [-o out.cel]`
+  - Parses and serializes AST back to `.cel`.
+  - If `-o/--out` is provided, writes to file and prints `Wrote <absolute-path>`.
+  - Otherwise prints to stdout.
+
+- `cello serve <file.cel> [--port 4321] [--host 127.0.0.1] [--open] [--no-eval]`
+  - Serves a live HTML preview for a workbook.
+  - Prints a local URL containing the served file name.
+  - Auto-reloads the browser view when the source file changes.
+  - Keeps the process warm so repeated renders reuse loaded dependencies.
+  - Does not open a browser unless `--open` is provided.
+
+- `cello help [command]`
+  - Prints basic CLI help, or command-specific help for `parse`, `evaluate`, `format`, `validate`, `render`, `serialize`, or `serve`.
+
+## Exit codes
+
+- `0`: success
+- `1`: invalid arguments, validation diagnostics, or runtime failure
+
+## Build/run notes
+
+- Build first: `npm run build`
+- Direct run example: `node dist/cli/cli.js render examples/basic.cel -o out.html`

package/docs/COMPLIANCE.md

@@ -0,0 +1,82 @@
+# Compliance Matrix (BYLAWS vs Current Code)
+
+This file maps `BYLAWS.md` expectations to current implementation in `src/` and tests in `tests/`.
+
+Status legend:
+- `implemented`: behavior present and tested
+- `partial`: behavior exists but scope/guarantees limited
+- `missing`: documented behavior not in code yet
+
+## Matrix
+
+1. Core file structure (`@sheet`, anonymous fallback)
+- Status: `implemented`
+- Code: `src/parser/parse.ts` (`ensureSheet`, sheet declaration parsing)
+- Tests: `tests/unit/parser/parse.unit.test.ts`, `tests/e2e/fixtures/anonymous-sheet.*`
+
+2. Sheet formats (`csv/tsv/excel`, custom delimiter, markdown, json)
+- Status: `implemented`
+- Code: `src/shared/utils.ts` (`parseSheetFormat`), `src/parser/parse.ts` format handlers
+- Tests: `tests/unit/parser/parse.unit.test.ts`, `tests/e2e/fixtures/format-matrix.*`
+
+3. External sheet source (`-> path`)
+- Status: `implemented`
+- Code: `src/parser/parse.ts` (`tryHandleExternalSource`)
+- Tests: `tests/unit/parser/parse.unit.test.ts`, `tests/e2e/fixtures/external-source.*`
+
+4. Rows, blank-line handling, row-level modifiers
+- Status: `implemented`
+- Code: `src/parser/parse.ts` (`splitNativeRow`, blank line handling)
+- Tests: `tests/unit/parser/parse.unit.test.ts`, `tests/e2e/fixtures/comments-blanklines.*`
+
+5. Header rows and column metadata/modifiers
+- Status: `implemented`
+- Code: `src/parser/parse.ts` (`parseHeadersFromLine`, `applyHeadersToColumns`)
+- Tests: `tests/unit/parser/parse.unit.test.ts`, `tests/e2e/fixtures/header-rebinding.*`
+
+5a. Column default formulas (`@defaults | ... |`)
+- Status: `implemented`
+- Code: `src/parser/parse.ts` (`tryHandleDefaultsDirective`, `getColumnDefaultFormula`)
+- Tests: `tests/unit/parser/parse.unit.test.ts`, `tests/it/evaluator/evaluate.test.ts`, `tests/it/renderer/render.test.ts`
+
+6. Formula parsing + evaluation engine integration
+- Status: `implemented`
+- Code: `src/evaluator/evaluate.ts`
+- Tests: `tests/unit/evaluator/evaluate.unit.test.ts`, `tests/it/evaluator/evaluate.test.ts`
+
+7. Named column refs (`SUM(Price)`, `SUM(Sheet!Price)`, slices, `!!`)
+- Status: `implemented`
+- Code: `src/evaluator/formula.ts`
+- Tests: `tests/unit/evaluator/formula.unit.test.ts`
+
+8. Row-name dot refs (`Sheet!row_name.Column`)
+- Status: `out of scope`
+- Code: row-name prefixes are not part of the AST or formula translation layer
+- Tests: parser regression covers unsupported row prefixes
+
+9. Merges (`<`, `^`)
+- Status: `partial`
+- Code: `src/parser/parse.ts` merge token handling
+- Tests: `tests/unit/parser/parse.unit.test.ts`, `tests/it/renderer/render.test.ts`
+- Note: orphan merge tokens degrade silently (no diagnostic)
+
+10. Modifiers precedence (column + row + cell)
+- Status: `implemented`
+- Code: `src/renderer/render.ts` (`collectModifiers` order: column -> row -> cell)
+- Tests: `tests/e2e/fixtures/types-precedence.*`, `tests/e2e/fixtures/row-name-modifiers.*`
+
+11. Modifier coverage in renderer
+- Status: `partial`
+- Code: `src/renderer/render.ts` (`bold`, `italic`, `bg`, color, tone presets, numeric display)
+- Missing: `[hidden]` rendering behavior
+
+12. Inline formatting (`*`, `_`, `~~`, `#`, `##`)
+- Status: `implemented`
+- Code: `src/renderer/render.ts` (`formatInline`)
+- Tests: `tests/it/renderer/render.test.ts`, `tests/e2e/fixtures/native-bylaws.*`
+
+13. Diagnostics and strict mode
+- Status: `implemented`
+- Code: `src/parser/parse.ts`, `src/evaluator/evaluate.ts`, `src/renderer/render.ts`
+- Tests: parser/evaluator unit + integration tests
+- Note: parser strict mode throws on `error` diagnostics only; warnings do not throw

package/docs/ERROR_MODEL.md

@@ -0,0 +1,25 @@
+# Error Model
+
+## Parse stage
+
+- Non-row lines in native Cello sheets are skipped with `warning` diagnostics.
+- Invalid JSON sheets degrade to a single text data row plus warning.
+- Parser strict mode (`parse(..., { strict: true })`) throws only on parser `error` diagnostics (warnings do not throw).
+
+## Evaluate stage
+
+- If HyperFormula is missing, evaluation is skipped and a warning diagnostic is added.
+- If HyperFormula throws on workbook evaluation, evaluator adds an `error` diagnostic.
+- `evaluate(..., { strict: true })` rethrows evaluation errors.
+
+## Render stage
+
+- `render(text, { strict })` delegates to parser/evaluator strictness.
+- `render(text, { evaluate: false })` skips evaluation and renders formula text.
+- Non-strict render still returns HTML even when diagnostics exist.
+- Strict render throws only when parse/evaluate throw; non-fatal diagnostics alone do not throw.
+
+## Practical contract
+
+- `diagnostics` are the canonical error/warning channel in non-strict mode.
+- Strict mode is for CI/validation workflows where failure must be explicit.

package/docs/FORMULA_SUPPORT.md

@@ -0,0 +1,33 @@
+# Formula Support (Current State)
+
+## What works now
+
+- Formula cells detected when value starts with `=`.
+- Evaluation uses HyperFormula when dependency available.
+- A1 references pass through unchanged.
+- Named column translation supported before engine eval:
+  - `SUM(Name)`
+  - `SUM(Name[n:m])`
+  - `SUM(Sheet!Name)`
+  - `SUM(Sheet!Name[n:m])`
+- `!!` alias supported for first workbook sheet:
+  - `SUM(!!Amount)` -> `SUM(<first-sheet>!Amount)`
+
+## What does not work yet
+
+- Row-name dot refs are not supported:
+  - `Sheet!row_name.Column`
+- Translation intentionally regex-based/narrow; complex token patterns can require explicit A1 refs.
+- Direct file-style formula addressing is not supported.
+
+## Translation model
+
+- Formulas are preprocessed in `src/evaluator/formula.ts`.
+- Unresolvable tokens are kept unchanged.
+- Named refs with missing data rows emit warning diagnostics and remain unchanged.
+- Formula parse errors from engine degrade to original formula text in output (`computed`).
+
+## Suggested next steps
+
+1. Add strict translation option for unresolved refs.
+2. Expand tests for mixed expressions and nested formula patterns.