fmstyle 0.2.0__tar.gz

fmstyle-0.2.0/PKG-INFO

@@ -0,0 +1,283 @@
+Metadata-Version: 2.4
+Name: fmstyle
+Version: 0.2.0
+Summary: Deterministic formatter and shareable style engine for FileMaker calculations
+Author: OOGI BV
+License: MIT
+Project-URL: Homepage, https://github.com/oogi-io/fm-code-formatter
+Keywords: filemaker,formatter,calculation,style,lint
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# fm-style
+
+**A deterministic formatter and shareable style engine for FileMaker code.**
+Think *prettier / gofmt for FileMaker calculations*: any company or solo developer
+defines their house style once, and every calculation — written by a human or by an
+LLM — comes out formatted exactly the same way, every time.
+
+Sibling of [fm-ddr-analyzer](../fm-ddr-analyzer) (same philosophy: pure-stdlib
+Python core, zero dependencies, client data never leaves the machine).
+
+## Why
+
+1. **Consistency is a style pack, not a habit.** Today FileMaker style lives in
+   people's heads or in prose guidelines. fm-style splits a guideline into its two
+   natural halves:
+   - the **mechanical half** (`fmstyle.json`) — indentation, Let/While shape, line
+     width, naming patterns — enforced *deterministically* by this tool;
+   - the **advisory half** (`guidelines.md`) — philosophy, intent, naming semantics —
+     written for humans **and for LLMs** to read.
+2. **The LLM era is coming to FileMaker.** Claris is planning LLM/agent integration
+   (Claude Code extensions and other models coding inside FileMaker). Prompting a
+   model to "always format Let like this" works 95% of the time; a deterministic
+   post-pass works 100% of the time. fm-style is the harness: the model writes the
+   logic, `fmstyle format` guarantees the shape, `fmstyle lint` guarantees the rules.
+   Useful today (paste / pipe / pre-commit), ready for tomorrow (skill / MCP tool
+   inside the Claris integration).
+3. **Safety you can trust.** A formatter that can silently change semantics is
+   worthless. fm-style **verifies that the output re-tokenizes to the exact same
+   code tokens and comments as the input** and refuses to emit anything otherwise
+   (`FormatSafetyError`). If it can't parse an expression, it changes nothing.
+
+## What works today (v0.1)
+
+- **Works on any calculation** — Let, While, Case, If, Substitute, ExecuteSQL,
+  JSON functions, custom functions, plain operator expressions… (Let/While simply
+  have the strictest mandatory shapes). Script *steps* are not parsed yet — see
+  roadmap.
+- Full tokenizer + parser + printer for FileMaker calculation expressions:
+  operators (incl. `≤ ≥ ≠ ¶`), strings with escapes, field names **with spaces**
+  (`Invoice Lines::Amount 2`), `${quoted names}`, `$var` / `$$var`, `//` and
+  nestable `/* */` comments, `Substitute`-style `[...]` argument lists.
+- **Style-guide-exact Let and While layout** (mandatory shapes from the
+  [FileMaker Development Style Guide](../../filemaker/source_of_truth/style/filemaker_development_style_guide.md)),
+  Case pair layout, width-aware inline-vs-exploded decisions, comment preservation.
+- Deterministic + **idempotent** (`format(format(x)) == format(x)`, tested).
+- Token-preservation safety check on every format.
+- Configurable via `fmstyle.json` (indent, width, blank lines, keyword casing,
+  result-variable name, naming pattern) — including **per-function layout rules**:
+  any function name can be given its own shape (`layout`) and explode behaviour
+  (`multiline`) under `"functions"`.
+- Lint rules: `let-explicit-result`, `variable-naming` (more to come).
+- CLI: `fmstyle format` (stdin/files, `--write`, `--check`) and `fmstyle lint` —
+  CI- and pre-commit-ready, exit codes included.
+
+## Web app (no install)
+
+Open `fmstyle/web/index.html` in any browser (or host it as a static page). Paste a
+calculation, it formats live, copy the result. Load your organisation's
+`fmstyle.json` to format in your house style; quick controls for indent and width.
+Everything runs **entirely client-side — nothing is uploaded** (same privacy story
+as the DDR analyzer's web app).
+
+The page embeds a JS port of the Python engine. Parity is enforced by fixtures:
+`tests/gen_parity_fixtures.py` renders every case through the Python reference,
+`node tests/test_parity.mjs` replays them through the JS engine extracted from the
+HTML and requires **byte-identical** output (formatting + lint findings).
+
+## Use it from your AI assistant (Claude Code skill)
+
+Same three-way engine as [fmsonar](../fm-ddr-analyzer): one deterministic core,
+reachable from the browser, the shell, **and an AI assistant**. The package ships
+a Claude Code skill so the assistant supplies the logic and `fmstyle` supplies the
+guaranteed shape:
+
+```bash
+pipx install fmstyle        # (PyPI) or: pip install fmstyle
+fmstyle install-skill       # copies the skill to ~/.claude/skills/fmstyle
+fmstyle install-skill --check   # freshness check after an upgrade
+```
+
+Once installed, when the assistant writes or edits a FileMaker calculation it
+runs it through `fmstyle format` before presenting it, so the output matches the
+house style exactly rather than approximately — and the token-safe guarantee
+means it can trust the result without re-reading it for correctness. This is the
+piece that anticipates Claris's LLM/agent integration: the model writes the calc,
+`fmstyle` makes it house-style, deterministically.
+
+## Usage
+
+```bash
+cd projects/fm-style
+
+# format from clipboard / stdin
+pbpaste | python3 -m fmstyle.cli format | pbcopy
+
+# format files, fail CI when not formatted
+python3 -m fmstyle.cli format --check calcs/*.fmcalc
+
+# guideline checks
+python3 -m fmstyle.cli lint mycalc.txt
+
+# as a library (this is what an LLM harness calls)
+python3 -c "from fmstyle import format_calc; print(format_calc('Let([x=1;result=x];result)'))"
+```
+
+## Configuration (`fmstyle.json`)
+
+```json
+{
+  "indent": "tab",
+  "width": 96,
+  "let_blank_lines": true,
+  "lowercase_keywords": true,
+  "space_before_semicolon": true,
+  "result_name": "result",
+  "local_variable_pattern": "^[_a-z][A-Za-z0-9]*$",
+  "functions": {
+    "let":   { "layout": "let",   "multiline": "always" },
+    "while": { "layout": "while", "multiline": "always" },
+    "case":  { "layout": "pairs" },
+    "if":    { "multiline": "always" }
+  }
+}
+```
+
+Defaults implement the Thomas DS style guide with 4-space indent. An organisation's
+pack is just this file plus their `guidelines.md`, versioned in their repo.
+
+### Presets
+
+Named, ready-made style packs — pick one in the web app's toolbar or via
+`fmstyle --preset <name>` (a `--config` file overrides preset keys;
+`fmstyle presets` lists them):
+
+| Preset | Source | Highlights |
+|---|---|---|
+| `oogi` | OOGI BV FileMaker Development Style Guide | 4-space indent, blank-line Let blocks, explicit `result`, leading-semicolon JSONSetElement (§8.1) |
+| `soliant` | *draft* — derived from observed AMPS conventions | tab indent, compact Let blocks, `_camelCase` locals |
+
+Presets must be **derived from a firm's real conventions, not invented** — the
+Soliant preset is marked draft until someone at Soliant blesses it. Adding a
+consultancy's preset is a PR with one dict in `fmstyle/presets.py` (+ the same
+entry in the web app).
+
+**Community edition (vision).** The end game is a `community` preset governed in
+the open: proposals per rule ("blank lines in Let: yes/no"), public voting, a
+versioned result (`community-2027.1`). If enough firms adopt it, FileMaker gets
+what gofmt gave Go — one format, zero debates. The deterministic engine is the
+prerequisite; the governance can start as GitHub issues + reactions before it
+needs anything fancier.
+
+**Per-function rules** — every FileMaker (or custom) function name can get its own
+entry under `"functions"`, so how *each* call formats is a config edit, not a code
+change:
+
+| Option | Values | Meaning |
+|---|---|---|
+| `layout` | `args` (default) | one argument per line when exploded |
+| | `pairs` | condition ; result pairs per line (Case-style) |
+| | `let` / `while` | the mandatory Let / While block shapes |
+| `multiline` | `auto` (default) | explode only when the call exceeds `width` |
+| | `always` | always explode, even when it would fit |
+
+(`force_multiline: [...]` is still accepted as a legacy shorthand for
+`multiline: "always"`.)
+
+## Validated against real solutions
+
+`tools/corpus_audit.py` replays **every calculation** from an
+[fm-ddr-analyzer](../fm-ddr-analyzer) SQLite database through the formatter:
+
+| Solution | Calculations | Format cleanly |
+|---|---|---|
+| tjouly (4-file DDR, 2026-05) | 47,665 | **94.8%** |
+| AMPS / Sunsolar (9-file DDR, 2026-06) | 88,401 | **94.2%** |
+
+The remainder is almost entirely DDR-export artifacts (several calcs
+concatenated into one layout-object entry, `<Field Missing>` placeholders) which
+the formatter correctly *refuses* rather than mangles. The audit drove real
+grammar fixes: `~`/`#`/dotted/unicode names (`$$~DISABLETRIGGERS`,
+`#ScriptResultJSON`, `Session.GetValue`, `Rep 5¢ Commission`), repetition
+references (`field[11]`), `x = not y` assignments, trailing semicolons
+(`Case ( a ; b ; )`), and commented-out calcs. It also inventories which
+built-in and custom functions a solution actually uses (`--functions`) — input
+for choosing per-function rules.
+
+## One tool, three fronts (convergence plan)
+
+Three FileMaker tools now share one DNA (stream Claris XML, pure stdlib, private
+by design):
+
+| Tool | Input | Output |
+|---|---|---|
+| [fm-ddr-analyzer](../fm-ddr-analyzer) | DDR XML | queryable SQLite + explorer |
+| [accessibility-label-patcher](../soliant/spikes/accessibility-label-patcher) | SaXML | FMUpgradeTool patch |
+| **fm-style** (this) | calculation text (later: SaXML/snippets) | formatted code + lint report |
+
+Convergence happens in two layers, without merging repos prematurely:
+
+1. **Shared cores.** The calculation tokenizer built here is directly reusable by
+   the DDR analyzer (pretty-printing calcs in the explorer, structural search) and
+   by any SaXML-processing step. Extract to a shared package only when a second
+   consumer actually lands.
+2. **One web umbrella.** Like the DDR analyzer's zero-upload web app, fm-style gets
+   a client-side page (paste calc → formatted, org pack loadable from a JSON file).
+   The umbrella site (oogi.io) presents them as one FileMaker toolbelt; each tool
+   stays independently shippable underneath.
+
+## Roadmap
+
+- [x] **v0.1 — calculation formatter + first lint rules + CLI** (this).
+- [x] **Web app** — single client-side HTML page (`fmstyle/web/index.html`), JS
+      port parity-tested byte-for-byte against Python. Paste → format → copy;
+      load your `fmstyle.json`; live lint findings; light/dark.
+- [ ] **Copy as FM object** — where applicable, wrap output as `fmxmlsnippet`
+      (custom functions, Set Variable steps) so paste lands as a real object.
+- [x] **LLM harness packaging** — a Claude Code skill (`fmstyle install-skill`)
+      that makes the assistant auto-run `fmstyle format` on FileMaker calcs it
+      writes, plus PyPI-ready packaging (wheel bundles the web app + skill).
+      Next: publish to PyPI; optionally inject the org's `guidelines.md`.
+- [ ] **Script-step formatting & linting** — via SaXML (the accessibility patcher
+      already proves parse→patch round-trips): script naming, error-handling
+      blocks, comment headers from the style guide.
+- [ ] **More lint rules** — custom function headers, `While` counter conventions,
+      magic-number detection, configurable per org.
+- [ ] **Community preset + voting** — public per-rule proposals and voting
+      (GitHub issues/reactions to start), producing a versioned `community`
+      preset that firms can adopt — one unified FileMaker format, eventually.
+- [ ] **DDR synergy** — lint a whole solution by piping every calculation from an
+      fm-ddr-analyzer SQLite DB through `fmstyle lint` (style report for an entire
+      file, like a health report).
+
+## Known limitations (v0.1)
+
+- Calculation expressions only — no script steps yet (see roadmap).
+- Reserved/ambiguous names: a bare multi-word field reference is accepted
+  verbatim; a field literally named like a keyword (`and`) needs `${and}`.
+- Comments in unusual positions (e.g. between an operator and its operand) are
+  preserved but may be moved to the nearest line boundary; if preservation is
+  ever impossible the tool refuses rather than guesses.
+- Function names are kept in the author's casing (no canonical-case rewrite yet).
+
+## Tech stack
+
+| Concern | Choice | Why |
+|---|---|---|
+| Language | Python 3.10+, stdlib only | Zero install friction, matches fm-ddr-analyzer |
+| Parsing | hand-written lexer + recursive descent | FM calc grammar is small; full control over verbatim tokens |
+| Safety | token-stream equality check | formatter can provably never change semantics |
+| Config | JSON dataclass | trivially shareable as an "org style pack" |
+
+## Project structure
+
+```
+fm-style/
+├── README.md
+├── pyproject.toml
+├── fmstyle/
+│   ├── web/index.html  # zero-install client-side web app (JS engine + UI)
+│   ├── __init__.py     # format_calc / lint_calc API + safety check
+│   ├── lexer.py        # verbatim tokenizer (comments, spaced names, ${...})
+│   ├── parser.py       # recursive descent -> small AST
+│   ├── printer.py      # deterministic layout engine (Let/While/Case shapes)
+│   ├── config.py       # Style dataclass <- fmstyle.json
+│   ├── rules.py        # lint rules
+│   └── cli.py          # fmstyle format / lint
+└── tests/
+    ├── test_fmstyle.py          # exact-output, idempotence, safety, lint tests
+    ├── gen_parity_fixtures.py   # Python reference -> parity_fixtures.json
+    ├── parity_fixtures.json     # generated JS<->Python parity cases
+    └── test_parity.mjs          # node: JS engine must match Python byte-for-byte
+```

fmstyle-0.2.0/README.md

@@ -0,0 +1,272 @@
+# fm-style
+
+**A deterministic formatter and shareable style engine for FileMaker code.**
+Think *prettier / gofmt for FileMaker calculations*: any company or solo developer
+defines their house style once, and every calculation — written by a human or by an
+LLM — comes out formatted exactly the same way, every time.
+
+Sibling of [fm-ddr-analyzer](../fm-ddr-analyzer) (same philosophy: pure-stdlib
+Python core, zero dependencies, client data never leaves the machine).
+
+## Why
+
+1. **Consistency is a style pack, not a habit.** Today FileMaker style lives in
+   people's heads or in prose guidelines. fm-style splits a guideline into its two
+   natural halves:
+   - the **mechanical half** (`fmstyle.json`) — indentation, Let/While shape, line
+     width, naming patterns — enforced *deterministically* by this tool;
+   - the **advisory half** (`guidelines.md`) — philosophy, intent, naming semantics —
+     written for humans **and for LLMs** to read.
+2. **The LLM era is coming to FileMaker.** Claris is planning LLM/agent integration
+   (Claude Code extensions and other models coding inside FileMaker). Prompting a
+   model to "always format Let like this" works 95% of the time; a deterministic
+   post-pass works 100% of the time. fm-style is the harness: the model writes the
+   logic, `fmstyle format` guarantees the shape, `fmstyle lint` guarantees the rules.
+   Useful today (paste / pipe / pre-commit), ready for tomorrow (skill / MCP tool
+   inside the Claris integration).
+3. **Safety you can trust.** A formatter that can silently change semantics is
+   worthless. fm-style **verifies that the output re-tokenizes to the exact same
+   code tokens and comments as the input** and refuses to emit anything otherwise
+   (`FormatSafetyError`). If it can't parse an expression, it changes nothing.
+
+## What works today (v0.1)
+
+- **Works on any calculation** — Let, While, Case, If, Substitute, ExecuteSQL,
+  JSON functions, custom functions, plain operator expressions… (Let/While simply
+  have the strictest mandatory shapes). Script *steps* are not parsed yet — see
+  roadmap.
+- Full tokenizer + parser + printer for FileMaker calculation expressions:
+  operators (incl. `≤ ≥ ≠ ¶`), strings with escapes, field names **with spaces**
+  (`Invoice Lines::Amount 2`), `${quoted names}`, `$var` / `$$var`, `//` and
+  nestable `/* */` comments, `Substitute`-style `[...]` argument lists.
+- **Style-guide-exact Let and While layout** (mandatory shapes from the
+  [FileMaker Development Style Guide](../../filemaker/source_of_truth/style/filemaker_development_style_guide.md)),
+  Case pair layout, width-aware inline-vs-exploded decisions, comment preservation.
+- Deterministic + **idempotent** (`format(format(x)) == format(x)`, tested).
+- Token-preservation safety check on every format.
+- Configurable via `fmstyle.json` (indent, width, blank lines, keyword casing,
+  result-variable name, naming pattern) — including **per-function layout rules**:
+  any function name can be given its own shape (`layout`) and explode behaviour
+  (`multiline`) under `"functions"`.
+- Lint rules: `let-explicit-result`, `variable-naming` (more to come).
+- CLI: `fmstyle format` (stdin/files, `--write`, `--check`) and `fmstyle lint` —
+  CI- and pre-commit-ready, exit codes included.
+
+## Web app (no install)
+
+Open `fmstyle/web/index.html` in any browser (or host it as a static page). Paste a
+calculation, it formats live, copy the result. Load your organisation's
+`fmstyle.json` to format in your house style; quick controls for indent and width.
+Everything runs **entirely client-side — nothing is uploaded** (same privacy story
+as the DDR analyzer's web app).
+
+The page embeds a JS port of the Python engine. Parity is enforced by fixtures:
+`tests/gen_parity_fixtures.py` renders every case through the Python reference,
+`node tests/test_parity.mjs` replays them through the JS engine extracted from the
+HTML and requires **byte-identical** output (formatting + lint findings).
+
+## Use it from your AI assistant (Claude Code skill)
+
+Same three-way engine as [fmsonar](../fm-ddr-analyzer): one deterministic core,
+reachable from the browser, the shell, **and an AI assistant**. The package ships
+a Claude Code skill so the assistant supplies the logic and `fmstyle` supplies the
+guaranteed shape:
+
+```bash
+pipx install fmstyle        # (PyPI) or: pip install fmstyle
+fmstyle install-skill       # copies the skill to ~/.claude/skills/fmstyle
+fmstyle install-skill --check   # freshness check after an upgrade
+```
+
+Once installed, when the assistant writes or edits a FileMaker calculation it
+runs it through `fmstyle format` before presenting it, so the output matches the
+house style exactly rather than approximately — and the token-safe guarantee
+means it can trust the result without re-reading it for correctness. This is the
+piece that anticipates Claris's LLM/agent integration: the model writes the calc,
+`fmstyle` makes it house-style, deterministically.
+
+## Usage
+
+```bash
+cd projects/fm-style
+
+# format from clipboard / stdin
+pbpaste | python3 -m fmstyle.cli format | pbcopy
+
+# format files, fail CI when not formatted
+python3 -m fmstyle.cli format --check calcs/*.fmcalc
+
+# guideline checks
+python3 -m fmstyle.cli lint mycalc.txt
+
+# as a library (this is what an LLM harness calls)
+python3 -c "from fmstyle import format_calc; print(format_calc('Let([x=1;result=x];result)'))"
+```
+
+## Configuration (`fmstyle.json`)
+
+```json
+{
+  "indent": "tab",
+  "width": 96,
+  "let_blank_lines": true,
+  "lowercase_keywords": true,
+  "space_before_semicolon": true,
+  "result_name": "result",
+  "local_variable_pattern": "^[_a-z][A-Za-z0-9]*$",
+  "functions": {
+    "let":   { "layout": "let",   "multiline": "always" },
+    "while": { "layout": "while", "multiline": "always" },
+    "case":  { "layout": "pairs" },
+    "if":    { "multiline": "always" }
+  }
+}
+```
+
+Defaults implement the Thomas DS style guide with 4-space indent. An organisation's
+pack is just this file plus their `guidelines.md`, versioned in their repo.
+
+### Presets
+
+Named, ready-made style packs — pick one in the web app's toolbar or via
+`fmstyle --preset <name>` (a `--config` file overrides preset keys;
+`fmstyle presets` lists them):
+
+| Preset | Source | Highlights |
+|---|---|---|
+| `oogi` | OOGI BV FileMaker Development Style Guide | 4-space indent, blank-line Let blocks, explicit `result`, leading-semicolon JSONSetElement (§8.1) |
+| `soliant` | *draft* — derived from observed AMPS conventions | tab indent, compact Let blocks, `_camelCase` locals |
+
+Presets must be **derived from a firm's real conventions, not invented** — the
+Soliant preset is marked draft until someone at Soliant blesses it. Adding a
+consultancy's preset is a PR with one dict in `fmstyle/presets.py` (+ the same
+entry in the web app).
+
+**Community edition (vision).** The end game is a `community` preset governed in
+the open: proposals per rule ("blank lines in Let: yes/no"), public voting, a
+versioned result (`community-2027.1`). If enough firms adopt it, FileMaker gets
+what gofmt gave Go — one format, zero debates. The deterministic engine is the
+prerequisite; the governance can start as GitHub issues + reactions before it
+needs anything fancier.
+
+**Per-function rules** — every FileMaker (or custom) function name can get its own
+entry under `"functions"`, so how *each* call formats is a config edit, not a code
+change:
+
+| Option | Values | Meaning |
+|---|---|---|
+| `layout` | `args` (default) | one argument per line when exploded |
+| | `pairs` | condition ; result pairs per line (Case-style) |
+| | `let` / `while` | the mandatory Let / While block shapes |
+| `multiline` | `auto` (default) | explode only when the call exceeds `width` |
+| | `always` | always explode, even when it would fit |
+
+(`force_multiline: [...]` is still accepted as a legacy shorthand for
+`multiline: "always"`.)
+
+## Validated against real solutions
+
+`tools/corpus_audit.py` replays **every calculation** from an
+[fm-ddr-analyzer](../fm-ddr-analyzer) SQLite database through the formatter:
+
+| Solution | Calculations | Format cleanly |
+|---|---|---|
+| tjouly (4-file DDR, 2026-05) | 47,665 | **94.8%** |
+| AMPS / Sunsolar (9-file DDR, 2026-06) | 88,401 | **94.2%** |
+
+The remainder is almost entirely DDR-export artifacts (several calcs
+concatenated into one layout-object entry, `<Field Missing>` placeholders) which
+the formatter correctly *refuses* rather than mangles. The audit drove real
+grammar fixes: `~`/`#`/dotted/unicode names (`$$~DISABLETRIGGERS`,
+`#ScriptResultJSON`, `Session.GetValue`, `Rep 5¢ Commission`), repetition
+references (`field[11]`), `x = not y` assignments, trailing semicolons
+(`Case ( a ; b ; )`), and commented-out calcs. It also inventories which
+built-in and custom functions a solution actually uses (`--functions`) — input
+for choosing per-function rules.
+
+## One tool, three fronts (convergence plan)
+
+Three FileMaker tools now share one DNA (stream Claris XML, pure stdlib, private
+by design):
+
+| Tool | Input | Output |
+|---|---|---|
+| [fm-ddr-analyzer](../fm-ddr-analyzer) | DDR XML | queryable SQLite + explorer |
+| [accessibility-label-patcher](../soliant/spikes/accessibility-label-patcher) | SaXML | FMUpgradeTool patch |
+| **fm-style** (this) | calculation text (later: SaXML/snippets) | formatted code + lint report |
+
+Convergence happens in two layers, without merging repos prematurely:
+
+1. **Shared cores.** The calculation tokenizer built here is directly reusable by
+   the DDR analyzer (pretty-printing calcs in the explorer, structural search) and
+   by any SaXML-processing step. Extract to a shared package only when a second
+   consumer actually lands.
+2. **One web umbrella.** Like the DDR analyzer's zero-upload web app, fm-style gets
+   a client-side page (paste calc → formatted, org pack loadable from a JSON file).
+   The umbrella site (oogi.io) presents them as one FileMaker toolbelt; each tool
+   stays independently shippable underneath.
+
+## Roadmap
+
+- [x] **v0.1 — calculation formatter + first lint rules + CLI** (this).
+- [x] **Web app** — single client-side HTML page (`fmstyle/web/index.html`), JS
+      port parity-tested byte-for-byte against Python. Paste → format → copy;
+      load your `fmstyle.json`; live lint findings; light/dark.
+- [ ] **Copy as FM object** — where applicable, wrap output as `fmxmlsnippet`
+      (custom functions, Set Variable steps) so paste lands as a real object.
+- [x] **LLM harness packaging** — a Claude Code skill (`fmstyle install-skill`)
+      that makes the assistant auto-run `fmstyle format` on FileMaker calcs it
+      writes, plus PyPI-ready packaging (wheel bundles the web app + skill).
+      Next: publish to PyPI; optionally inject the org's `guidelines.md`.
+- [ ] **Script-step formatting & linting** — via SaXML (the accessibility patcher
+      already proves parse→patch round-trips): script naming, error-handling
+      blocks, comment headers from the style guide.
+- [ ] **More lint rules** — custom function headers, `While` counter conventions,
+      magic-number detection, configurable per org.
+- [ ] **Community preset + voting** — public per-rule proposals and voting
+      (GitHub issues/reactions to start), producing a versioned `community`
+      preset that firms can adopt — one unified FileMaker format, eventually.
+- [ ] **DDR synergy** — lint a whole solution by piping every calculation from an
+      fm-ddr-analyzer SQLite DB through `fmstyle lint` (style report for an entire
+      file, like a health report).
+
+## Known limitations (v0.1)
+
+- Calculation expressions only — no script steps yet (see roadmap).
+- Reserved/ambiguous names: a bare multi-word field reference is accepted
+  verbatim; a field literally named like a keyword (`and`) needs `${and}`.
+- Comments in unusual positions (e.g. between an operator and its operand) are
+  preserved but may be moved to the nearest line boundary; if preservation is
+  ever impossible the tool refuses rather than guesses.
+- Function names are kept in the author's casing (no canonical-case rewrite yet).
+
+## Tech stack
+
+| Concern | Choice | Why |
+|---|---|---|
+| Language | Python 3.10+, stdlib only | Zero install friction, matches fm-ddr-analyzer |
+| Parsing | hand-written lexer + recursive descent | FM calc grammar is small; full control over verbatim tokens |
+| Safety | token-stream equality check | formatter can provably never change semantics |
+| Config | JSON dataclass | trivially shareable as an "org style pack" |
+
+## Project structure
+
+```
+fm-style/
+├── README.md
+├── pyproject.toml
+├── fmstyle/
+│   ├── web/index.html  # zero-install client-side web app (JS engine + UI)
+│   ├── __init__.py     # format_calc / lint_calc API + safety check
+│   ├── lexer.py        # verbatim tokenizer (comments, spaced names, ${...})
+│   ├── parser.py       # recursive descent -> small AST
+│   ├── printer.py      # deterministic layout engine (Let/While/Case shapes)
+│   ├── config.py       # Style dataclass <- fmstyle.json
+│   ├── rules.py        # lint rules
+│   └── cli.py          # fmstyle format / lint
+└── tests/
+    ├── test_fmstyle.py          # exact-output, idempotence, safety, lint tests
+    ├── gen_parity_fixtures.py   # Python reference -> parity_fixtures.json
+    ├── parity_fixtures.json     # generated JS<->Python parity cases
+    └── test_parity.mjs          # node: JS engine must match Python byte-for-byte
+```

fmstyle-0.2.0/fmstyle/__init__.py

@@ -0,0 +1,68 @@
+"""fmstyle - deterministic formatter + style engine for FileMaker calculations.
+
+Public API:
+
+    format_calc(source, style)  -> formatted text (token-preservation verified)
+    lint_calc(source, style)    -> [(rule_id, message), ...]
+    Style                       -> configuration (an org's mechanical rules)
+"""
+
+from __future__ import annotations
+
+from .config import Style
+from .lexer import LexError, tokenize
+from .parser import ParseError, Parser
+from .printer import Printer
+from .rules import lint as _lint
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "format_calc",
+    "lint_calc",
+    "Style",
+    "LexError",
+    "ParseError",
+    "FormatSafetyError",
+]
+
+
+class FormatSafetyError(RuntimeError):
+    """Formatting would have changed the token stream - refused."""
+
+
+def _signature(source: str):
+    code = []
+    comments = []
+    for tok in tokenize(source):
+        comments.extend(c.text for c in tok.pre_comments)
+        if tok.kind != "EOF":
+            text = tok.text.lower() if tok.kind == "OP" else tok.text
+            code.append((tok.kind, text))
+    return code, comments
+
+
+def format_calc(source: str, style: Style | None = None) -> str:
+    """Format a FileMaker calculation. Guaranteed semantics-preserving: the
+    output must re-tokenize to the exact same code tokens and comments as the
+    input, otherwise FormatSafetyError is raised and nothing is changed."""
+    style = style or Style()
+    tokens = tokenize(source)
+    if len(tokens) == 1:  # comments only (e.g. a commented-out calc) - keep as is
+        return source
+    node = Parser(tokens).parse()
+    out = Printer(style).format(node)
+    if _signature(source) != _signature(out):
+        raise FormatSafetyError(
+            "formatting would alter the token stream; refusing (please report this input)"
+        )
+    return out
+
+
+def lint_calc(source: str, style: Style | None = None):
+    """Run guideline lint rules over a calculation."""
+    style = style or Style()
+    tokens = tokenize(source)
+    if len(tokens) == 1:  # comments only - nothing to lint
+        return []
+    return _lint(Parser(tokens).parse(), style)