Skip to content

feat(api-model[erlang]) Link native type signatures - #279

Closed
tony wants to merge 3 commits into
erlang-api-modelfrom
erlang-signature-links
Closed

tony wants to merge 3 commits into
erlang-api-modelfrom
erlang-signature-links

Conversation

@tony

@tony tony commented Nov 8, 2026 •

Copy link
Copy Markdown
Contributor

Summary

  • Add compiler-derived links for Erlang types and native records.
  • Preserve native signatures in API pages and copied Markdown.
  • Validate reference ranges, OTP destinations, opaque boundaries and source identities.
  • Preserve the workspace application's product boundary.
  • Cache and verify the pinned Rebar3 release from GitHub's asset API.

This draft is stacked on #278, which adds the Erlang API-model adapter. It does not register Erlang site routes or request deployment.

Merge blocker

Draft remains unready for merge while whole-site validation and exact-head hosted CI remain open. The official medium and outer loops exceed their existing deadlines; #271 tracks that investigation. Erlang route registration and full rendered-site qualification remain separate delivery work. No timeout was increased.

Design

Reference ranges come from the parsed compiler declarations and retain Erlang namespaces, type arities, quoted atoms and UTF-16 offsets. Literal text stays unlinked. OTP destinations require a compiler-known builtin or a documented type entry. A syntax-tree round trip checks formatting, and rendered signatures retain the site's display-width check.

A temporary Rebar VM observes actual compiler file entries and recovers preprocessing context through an identity transform. Both preprocessing passes run inside that VM, preserving library paths, environment and working directory. Every documented declaration must match the compiled forms and resolve to a regular tracked source file. Explicit source remapping and tracked source symlinks are rejected. Temporary build output and context are removed on normal completion or export errors.

CI verifies the published Rebar3 digest on downloads and cache hits. It copies the verified payload into a fresh directory, validates the copy and version, then adds only that directory to PATH. Failed downloads and unpublished installations are removed.

Test plan

  • Native renderer tests preserve links, declarations and Markdown text.
  • API-model and site lint and type checks pass for the unchanged TypeScript implementation.
  • Complete API-model suite passes in 13.073 seconds, including native compiler integration cases.
  • Compiler regressions reject external headers, identical-header macro substitutions, remaps, symlink citations and swapped primary sources.
  • Compiler-VM library resolution rejects the independently reproduced include_lib citation error.
  • Core and workspace exports have no unresolved type references or display-width failures.
  • Generated OTP destinations reach their canonical pages and exact type anchors.
  • Recorded official inner loop passes in 1.915 seconds.
  • Installer cases pass in 1.738 seconds, including cache neighbors, corrupt payloads and failure cleanup.
  • Unfiltered workflow lint passes; the unchanged SC2129 shell-style finding remains. Other workflow checks pass with that diagnostic excluded.
  • Official medium loop passes; the last attempt fails at its deadline in 10.622 seconds.
  • Official outer loop passes; the last attempt, before the final compiler-VM correction, fails at its deadline in 60.950 seconds.
  • Exact-head hosted CI and a full rendered Erlang site are qualified.

The native compiler fixtures belong to the outer tier. These scoped passes do not waive either whole-loop failure or establish complete site delivery. Independent review evidence retains the original failures and verifies the source-provenance corrections.

why: Erlang reference pages need arity-aware type links without changing
native declarations or exposing opaque representations.

what:
- Export and validate compiler-derived UTF-16 reference ranges
- Preserve native signatures in HTML and copied Markdown
- Link documented OTP types and retain unresolved names
- Exercise quoted names, records, literal collisions and column limits
- Expose the deterministic header provenance defect with a regression
tony added 2 commits November 8, 2026 03:56
why: Deterministic builds omit paths and preprocessing context, so
basename matches can cite a tracked file the compiler did not read.

what:
- Observe compiler entries and preprocess inside an isolated Rebar VM
- Match native forms and exact regular tracked source paths
- Reject source remaps, external headers and tracked symlink citations
- Exercise compiler macros, library roots and swapped source inputs
why: Native compiler checks cannot start when the release download URL
returns gateway errors. The asset API serves the same pinned payload.

what:
- Fetch the official Rebar3 asset and validate its published digest
- Cache only the payload and install it into a clean directory
- Check copied bytes and version before exposing the executable on PATH
- Remove failed downloads and unpublished installations
tony added a commit that referenced this pull request Nov 9, 2026
…ts (#291)

why: Six ports had docs branches ready but no published site, and
three shared fixes were waiting behind them. Releasing them together
gives one docs commit to trust for deployment and one set of caller
pins to move, instead of six separate waves.

what:
- Add OCaml (#264), Haskell (#265), Erlang (#266, #278, #279, #280,
  #284, #292), Common Lisp (#268), Perl (#274) and Clojure (#276):
  native API pages, tested guides, navigation, landing and switcher
  entries, and cross-reference data for each
- Keep browser checks from loading third-party resources, and pass
  the check origin to the three scripts that named an undefined base
  (#287)
- Render guide badges at build time instead of hotlinking shields
  (#288)
- Size the reference sidebar and member bars from the viewport, so
  the Chrome iOS keyboard no longer shrinks them (#290)
- Make the OCaml model producer verify its native build inputs in
  their checkout and reject stale ones, with controls run in CI
- Offer one switcher page per port, and title Perl's workspace guide
  "Workspace guide"
- Regenerate the registry, mention index and cross-reference counts
  for the combined port set

Base main 2593131, head dabe59b. Port heads: #264 7d4f88f
and 73fb1ad, #265 dc024e3, #268 947da1f, #274 818fa2e,
#276 a134503, #287 a437e97, #292 e7740d9.
@tony

tony commented Nov 12, 2026

Copy link
Copy Markdown
Contributor Author

Shipped in #291 (8245169, 2026-11-09 07:38 CST), the combined release: this PR's head 323421620 is listed there and is an ancestor of main (cfa8a14), so the compiler-derived type links, the preserved native signatures and the verified Rebar3 installer are on main. The unfiltered workflow lint and the medium and outer loop deadlines noted in the description stay tracked in #271. Closing, since nothing in this branch is missing from main.

@tony tony closed this Nov 12, 2026
@tony
tony temporarily deployed to docs-preview-cleanup November 12, 2026 01:53 — with GitHub Actions Inactive

This branch was previously deployed

2 inactive deployments
docs-preview-cleanup — 32342162 Deployed Nov 12, 2026 by tony via cleanup #239
docs-preview — 32342162 Deployed Nov 8, 2026 by tony via publish-preview / publish #1276
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