Skip to content

feat: plan 13 source formatter and API documentation - #34

Merged
MicroProofs merged 19 commits into
mainfrom
plan-13
Sep 27, 2026
Merged

MicroProofs merged 19 commits into
mainfrom
plan-13

Conversation

@MicroProofs

@MicroProofs MicroProofs commented Sep 26, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Implements plan 13 (plans/13-fmt-docs.md): all seven chunks complete. Two new crates, nash-fmt (AST-based source formatter) and nash-docs (API documentation extraction and rendering), plus nash format and nash docs in the CLI. The parser now keeps comments and documentation in the surface AST. The branch also removes the completed benchmark experiments, tightens one case-lowering path in codegen, and updates the plan documents for the optimizer, macros and Big constructor tags. Sixteen commits, nine changesets.

Versioning: minor bumps for nash-source, nash-parse, nash-report, nash-fmt, nash-docs, nash-cli; patch for nash-plutus, nash-codegen, nash-driver. See .sampo/changesets/.

Comments in the surface AST (feat(parse): preserve comments and documentation)

  • The parser keeps comment regions and text through backtracking and attaches module and declaration documentation. The formatter and documentation extraction read them from the AST.

Formatter (feat(fmt): add source formatter and check diffs, fix(fmt): keep short expressions compact, fix(fmt): refine signatures and exposing layout, fix(cli): format files concurrently with Tokio)

  • nash-fmt: 80-column layout, comment preservation, source snapshot tests.
  • nash format (alias fmt) formats in place or from stdin. --check reports contextual diffs through the existing report style.
  • Short definitions and arithmetic stay compact. do blocks follow assignment and bind operators without extra indentation. Aligned explicit continuations inside do do not merge statements.
  • Constrained type signatures wrap before the fat arrow and keep the function type together when it fits. Multiline exposing lists start on the next line.
  • Whitespace after message keywords and before constructor docs is corrected.
  • The CLI processes format inputs concurrently with asynchronous filesystem and stream I/O and keeps formatting work off Tokio executor threads.

Documentation (feat(docs): extract public API documentation, feat(docs): render searchable API documentation)

  • nash-docs extracts public documentation from source comments and solved interfaces, including the compiler-bundled Base API.
  • nash docs renders searchable HTML and Markdown.
  • docs/formatter.md, docs/documentation.md and docs/cli.md specify the two tools.

Codegen and cleanup (fix(codegen): tighten case lowering and coverage, test: remove completed performance experiments, test(driver): remove integer-width benchmark)

  • Unused native-unit bindings lower to a single-branch UPLC case, preserving strict sequencing without a lambda/application pair.
  • Completed performance experiments, benchmark fixtures and unused benchmark dependencies are removed; functional coverage remains. docs/research/list-extraction-costs.md records the findings.

Plan documents (docs: …)

  • Plan 08: start the optimizer with ANF normalization; optimize before the recursion rewrite.
  • Plan 11: structured macro invocation forms; the macro plan is reconciled with the pattern proposals.
  • Plan 12: single-field pair projections.
  • New plans/14-explicit-big-constructor-tags.md: explicit dispatch and Big tags. docs/codegen.md, docs/representation.md, docs/macros.md and docs/overview.md are updated to match.

Test plan

  • cargo fmt --all -- --check
  • cargo clippy --all-targets --all-features -- -D warnings
  • cargo test

Signed-off-by: microproofs <kwhitemsg@gmail.com>
Signed-off-by: microproofs <kwhitemsg@gmail.com>
Signed-off-by: microproofs <kwhitemsg@gmail.com>
Signed-off-by: microproofs <kwhitemsg@gmail.com>
Signed-off-by: microproofs <kwhitemsg@gmail.com>
Signed-off-by: microproofs <kwhitemsg@gmail.com>
Signed-off-by: microproofs <kwhitemsg@gmail.com>
Signed-off-by: microproofs <kwhitemsg@gmail.com>
Signed-off-by: microproofs <kwhitemsg@gmail.com>
Signed-off-by: microproofs <kwhitemsg@gmail.com>
Signed-off-by: microproofs <kwhitemsg@gmail.com>
Signed-off-by: microproofs <kwhitemsg@gmail.com>
Signed-off-by: microproofs <kwhitemsg@gmail.com>
Signed-off-by: microproofs <kwhitemsg@gmail.com>
Signed-off-by: microproofs <kwhitemsg@gmail.com>
Signed-off-by: microproofs <kwhitemsg@gmail.com>
Signed-off-by: microproofs <kwhitemsg@gmail.com>
Keep map keys and values Storable, with equality constraints on library
implementations. Use structural Data equality for Big-element lists and
Big/Big maps; preserve selected element Eq for Little and mixed maps.

Map builtins and helpers retain alias identity. Generic callers must ask
for container Eq, and Lift to Big maps now uses the native map alias.

Signed-off-by: microproofs <kwhitemsg@gmail.com>
Place boolean helpers and operators below Eq and Ord, preserving existing
short-circuit rules. Simplify equality and boolean ordering using Logic.

Qualified helpers move from Bool to Logic; explicit boolean operator
imports move from Prelude to Logic. Default application scope is retained.

Signed-off-by: microproofs <kwhitemsg@gmail.com>
@MicroProofs
MicroProofs merged commit 7714903 into main Sep 27, 2026
11 checks passed
@MicroProofs
MicroProofs deleted the plan-13 branch September 27, 2026 16:38

This branch had an error being deployed

1 failed deployment
github-pages — 77149037 Deployed Sep 27, 2026 by MicroProofs via deploy #3
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant