ibex 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1cf3b4cceb041622899923a174e36d413adb399c22cdb44f8023f1f199acea73
-  data.tar.gz: 62ac1c3098103ac5270a8c684065424fcfc8bb2759332b3414672454ecbb25ca
+  metadata.gz: 305b0c04e2cc0e6340b5584b9c2f159c48c7525d34d5212eb7969393e1205244
+  data.tar.gz: 2a2993d999dedb2decf5bcda1356a4b36aba03edc30225c9d7548ace0587c925
 SHA512:
-  metadata.gz: ec45347b6c9ec5f427261ade9ea4102a2b7b6583bcec47ee024d920fc624018bae9315a7129657977de47241e867ef23809ccef372169cb8e1d6a9ad858e31b3
-  data.tar.gz: a163ab0fb84918570c2f62a9299d395653a0896c510e43a7672677803fe73f6010d74305868e1f6e5018b13b30d053c1a4d0852e16a0941f56a123bb883e7422
+  metadata.gz: 7ed7961859d052b5b205d0a3114c22e527fa627d2ec5c0dcd936e3480f0ba3dc453fccb5306b91bea0caece79f72f71e2670258a481a5a31dd4bdb9c981613fa
+  data.tar.gz: 420b15173d5da4ea674df973b48c7aaadb0d3f6f9c010654556e6ca4138aed08efd54e55198009e86413a76639d59401b7252725c371881db5289c11d1025137

data/README.md

@@ -1,26 +1,53 @@
 # Ibex
 
-Ibex is a Pure Ruby LR parser generator. It accepts racc-compatible grammar files, generates parsers with the familiar
-`do_parse` / `yyparse` API, and requires no C or Java extension. Its staged Grammar IR and Automaton IR can also drive extended
-EBNF syntax, diagnostics, visualizations, and alternate LR construction algorithms.
+[![Gem](https://badge.fury.io/rb/ibex.svg)](https://rubygems.org/gems/ibex)
+[![CI](https://github.com/ydah/ibex/actions/workflows/main.yml/badge.svg)](https://github.com/ydah/ibex/actions/workflows/main.yml)
+[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-4ade80)](https://ydah.github.io/ibex/)
+[![License](https://img.shields.io/badge/license-MIT-4ade80.svg)](LICENSE.txt)
 
-## Requirements and installation
+Ibex is a Pure Ruby LR parser generator. It reads racc-compatible grammar
+files, generates parsers with the familiar `do_parse` / `yyparse` API, and
+requires no native extension.
 
-Ibex supports Ruby 3.0 or later and has no runtime gem dependencies. From a source checkout:
+The shortest path is the [Getting Started guide](https://ydah.github.io/ibex/getting-started/):
+install the gem, try the calculator grammar, and then choose the compatible or
+extended contract you need. You can also [inspect a grammar in the browser](https://ydah.github.io/ibex/playground/)
+without uploading its source.
+
+## Release status
+
+Ibex is pre-1.0. The v1.0 publication decision is on hold pending an
+independent review of the published error-experience evidence; feature
+development continues. The default compatible mode and its current IR
+contracts are the conservative adoption baseline. See the [release status](https://ydah.github.io/ibex/project/status/)
+and [stability policy](docs/stability.md) for the human-readable boundaries.
+
+<!-- r001-review-status:start -->
+R001: `HOLD` — [`awaiting_independent_review`](docs/error-ux-review-status-v1.json).
+<!-- r001-review-status:end -->
+
+<!-- type-stats:start -->
+The current whole-library `steep stats` result is 28,836 typed calls and 2,734 untyped calls out of 31,610 (91.2% typed).
+The generated signature tree contains 492 explicit `untyped` occurrences across 39 files.
+<!-- type-stats:end -->
+
+## Install
+
+Add the generator to an application or tool project:
 
 ```sh
-bundle install
-bundle exec rake
+gem install ibex
+# or, in a Gemfile:
+bundle add ibex
 ```
 
-Build and install the local gem when you want the `ibex` executable on your `PATH`:
+Applications that only run generated parsers can depend on the smaller runtime:
 
 ```sh
-gem build ibex.gemspec
-gem install ./ibex-0.1.0.gem
+bundle add ibex-runtime
 ```
 
-## Three-minute calculator
+## First parser
 
 Save this as `calculator.y`:
 
@@ -57,138 +84,77 @@ end
 Generate and run it:
 
 ```sh
-ibex calculator.y
+ibex -o calculator.rb calculator.y
 ruby calculator.rb
 # 14
 ```
 
-From a checkout without installing the gem, use `bundle exec ruby -Ilib exe/ibex calculator.y` and
-`bundle exec ruby -Ilib calculator.rb` instead.
+The generated parser uses compact immutable tables and depends on
+`ibex-runtime`. Use `-E` when a single self-contained generated file is more
+convenient. Use `--check` in CI to detect stale generated output.
 
-Ibex generates compact tables by default. Compatibility-safe default reductions shrink profitable states while retaining
-explicit error cells, including recovery and undeclared-token behavior. `--table=plain` produces inspectable Hash rows, while
-`-E` embeds the runtime into a single dependency-free output file.
+## Choose a contract
 
-## Lexer contract
+| Surface | Use it for | Maturity |
+| --- | --- | --- |
+| Compatible mode | Existing racc grammars and conservative migrations | Stable baseline |
+| Extended mode | EBNF, imports, generated lexers, trees, types, and tooling | Preview; explicit opt-in |
+| Browser playground and incremental CST sessions | Local analysis and evaluation | Preview/Experimental; bounded |
 
-Ibex does not generate a lexer. A pull parser implements `next_token` and returns `[token, value]`; `false` or `nil` marks EOF.
-Bare grammar tokens normally use Ruby symbols (`:NUM`), and quoted grammar tokens use strings (`'+'`). A push source can call
-`yyparse(receiver, method_name)` where the receiver method yields the same pairs.
+The default frontend remains unchanged unless a grammar opts into
+`pragma extended` or the command line uses `--mode=extended`. Read the
+[grammar reference](https://ydah.github.io/ibex/docs/grammar-reference/),
+[racc migration guide](https://ydah.github.io/ibex/docs/racc-migration/), and
+[maturity audit](https://ydah.github.io/ibex/docs/maturity/) before adopting a
+Preview or Experimental surface.
 
-The default `on_error(token_id, value, value_stack)` raises `Ibex::ParseError`. Override it to use yacc-style `error` recovery.
-Semantic actions can call `yyerror`, `yyerrok`, or `yyaccept`, and `expected_tokens` reports valid lookaheads in the current state.
-Parser subclasses can also override `on_shift(token_id, value, state)`,
-`on_reduce(production_id, values, result)`, and `on_error_recover(token_id, value, value_stack)` as no-op-by-default observers.
-Ordinary shifts and the synthetic recovery-token shift use separate hooks; observer return values never replace semantic values.
+IELR is also explicit: `--algorithm=ielr` uses the conservative partition
+strategy by default, while `--ielr-strategy=direct` enables the experimental
+LR(0)-based construction. Direct IELR is profiled and reviewable, but it is not
+the default release strategy; see the [IELR guide](docs/ielr.md).
 
-## Extended mode
+## Trust boundary
 
-`--mode=extended` enables optional, repeated, and separated values plus named references. A grammar can make the same choice
-locally with `pragma extended` immediately after its `class` header:
+Static frontend, formatting, documentation, LSP, IR, verification, and
+browser analysis treat grammar actions and user sections as opaque source.
+Generated parsers and semantic parses execute application Ruby and are not
+sandboxes. The playground runs in a local Web Worker, does not upload grammar
+source, and never executes parser actions or user-code sections. Its limits and
+non-goals are documented in the [playground guide](https://ydah.github.io/ibex/playground/).
 
-```text
-class ExtendedParser
-pragma extended
-rule
-  arguments : separated_list(NUM, ',') { result = val[0] }
-  sum       : NUM:left '+' NUM:right { result = left + right }
-  maybe     : NUM?
-  many      : NUM*
-  some      : NUM+
-  pairs     : (KEY VALUE)*
-end
-```
+## Where to go next
 
-The value conventions are `nil` or a value for `?`, and arrays for `*`, `+`, `separated_list`, and
-`separated_nonempty_list`. Parenthesized sequences and alternatives can be nested; multi-item groups produce an Array value.
-Text, DOT, and HTML automaton reports label lowered helper symbols with these source-level EBNF expressions.
-
-## Pipeline and diagnostics
-
-```sh
-ibex --emit=grammar-ir grammar.y > grammar.json
-ibex --from=grammar-ir --emit=automaton-ir grammar.json > automaton.json
-ibex --from=automaton-ir -o parser.rb automaton.json
-ibex -v --dot=states.dot --html=states.html grammar.y
-ibex --algorithm=lr1 grammar.y
-ibex --counterexamples --counterexample-max-tokens=64 --counterexample-max-configurations=100000 grammar.y
-ibex --rbs -o parser.rb grammar.y
-ibex --warnings=all,error -C grammar.y
-```
-
-Supported construction algorithms are `slr`, `lalr` (default), and canonical `lr1`. Reports retain precedence-resolved
-conflicts and distinguish unifying counterexamples from nonunifying reachability witnesses. Counterexample searches default to
-32 tokens and 50,000 explored configurations; `--counterexample-max-tokens=N` and
-`--counterexample-max-configurations=N` set positive per-run budgets and request a report. `--rbs` writes a signature beside the
-generated parser; `--rbs=FILE` selects another path. Application methods supplied as opaque `---- inner` code can be declared by
-reopening the generated class in an application RBS file.
-
-`--warnings=all` prints unused terminals, unreachable nonterminals, duplicate productions, undeclared terminals, and empty-language
-diagnostics. Add `error` (`--warnings=all,error`, or simply `--warnings=error`) to make any such diagnostic fail the command.
-Action exceptions and `inner` methods point back to their `.y` lines by default. `--line-convert-all` extends that mapping to
-`header` and `footer`; `-l` disables every source-line conversion. User-code chunk locations survive Grammar/Automaton IR JSON
-round trips, so resumed generation has the same backtraces as direct generation.
-
-## Documentation
-
-- [Grammar reference](docs/grammar-reference.md)
-- [racc migration guide](docs/racc-migration.md)
-- [Architecture and IR schemas](docs/architecture.md)
-- [Compatibility observations](docs/compat-notes.md)
-- [Phase 10 extensions](docs/phase10-extensions.md)
+- [Documentation hub](https://ydah.github.io/ibex/docs/) — task-oriented entry points.
+- [Grammar gallery](https://ydah.github.io/ibex/gallery/) — executable examples with declared tests.
+- [API reference](https://ydah.github.io/ibex/api/) — generated Ruby API documentation.
+- [Configuration model](https://ydah.github.io/ibex/docs/configuration-model/) — grammar-owned and invocation-owned settings.
+- [Project status and evidence](https://ydah.github.io/ibex/project/) — release, roadmap, and bounded claims.
+- [Contributing](CONTRIBUTING.md) and [security reporting](SECURITY.md) — community workflow.
 
 ## Development
 
-Run all unit, integration, documentation, and optional local racc black-box tests with `bundle exec rake test`; run style checks
-with `bundle exec rake lint`. The default `bundle exec rake` runs both. Compatibility tests skip automatically when the `racc`
-command is unavailable.
-
-Ibex's grammar frontend is self-hosted. Edit `lib/ibex/frontend/grammar.y`, then regenerate and verify the committed parser with:
+Clone the repository only when you need to contribute or run the complete
+quality suite:
 
 ```sh
-bundle exec rake frontend:generate
-git diff --exit-code -- lib/ibex/frontend/generated_parser.rb
-bundle exec ruby -Itest test/frontend/self_host_test.rb
-```
-
-Normal library and CLI execution use the generated parser. The handwritten `BootstrapParser` is loaded only by this regeneration
-workflow, whose direct dependency graph also works when the generated file is absent. Byte-comparison and AST/error parity tests
-prevent generated-source drift.
-
-Fixed-seed property tests exercise SLR, LALR, and LR(1) pipeline invariants, while versioned Grammar and Automaton IR fixtures
-guard byte-stable schema compatibility. Intentional fixture updates are documented in `test/fixtures/ir/README.md`. Run the
-reproducible whole-builder benchmark without a timing pass/fail threshold with:
-
-```sh
-benchmark/pipeline.rb --rules 200 --iterations 5 --seed 12345
+git clone https://github.com/ydah/ibex.git
+cd ibex
+bundle install
+bundle exec rake
+npm ci
+npm run test:site
 ```
 
-Signatures for every Ruby source under `lib/` are generated from rbs-inline annotations and checked with Steep, including the
-self-hosted generated parser. To regenerate the committed signature tree and reproduce its validation locally:
-
-```sh
-BUNDLE_GEMFILE=gemfiles/Gemfile bundle install
-BUNDLE_GEMFILE=gemfiles/Gemfile ruby -e '
-  sources = Dir.glob("lib/**/*.rb").sort
-  exec("bundle", "exec", "rbs-inline", "--opt-out", "--base=lib", "--output=sig", *sources)
-'
-BUNDLE_GEMFILE=gemfiles/Gemfile bundle exec rbs -r digest -r json -r optparse -I sig validate
-BUNDLE_GEMFILE=gemfiles/Gemfile bundle exec steep check
-BUNDLE_GEMFILE=gemfiles/Gemfile bundle exec steep stats
-BUNDLE_GEMFILE=gemfiles/Gemfile bundle exec ruby tool/type_stats.rb --write
-```
+The [development guide](https://ydah.github.io/ibex/docs/development/) lists
+the focused frontend, type, evidence, browser, and workflow checks.
 
-CI performs generation in a clean temporary directory and compares the complete trees, so missing source signatures and stale
-signature files both fail the build.
-<!-- type-stats:start -->
-The current whole-library `steep stats` result is 3,771 typed calls and 449 untyped calls out of 4,220 (89.4% typed).
-The generated signature tree contains 397 explicit `untyped` occurrences across 16 files.
-<!-- type-stats:end -->
+## Decisions and evidence
 
-Those boundaries are concentrated in generated-parser reduction values, heterogeneous JSON decoding/serialization, runtime
-semantic values and parser-table cells, and embedded user Ruby. Token/location records, the complete grammar AST, parser
-classifier state, IR, the public Ruby DSL, bootstrap parser state, analysis, automaton construction, code generators, table
-construction, and CLI options use concrete domain types. The committed self-hosted parser remains in the Steep target; no library
-directory or generated source is excluded.
+The public reference also indexes the [direct IELR decision](docs/direct-ielr-decision.md),
+[direct multi-entry decision](docs/direct-multi-entry-decision.md),
+[verifier trust boundary](docs/verifier-trust-boundary.md), and the
+[error-experience review status](docs/error-ux-review-status-v1.json). These
+records scope claims to their evidence and revision; they do not change the
+compatible installation path above.
 
 Ibex is available under the [MIT License](LICENSE.txt).