Skip to content

fix(api-model) Keep Clojure signature bindings local - #299

Merged
tony merged 3 commits into
mainfrom
fix/clojure-signature-bindings
Nov 11, 2026
Merged

tony merged 3 commits into
mainfrom
fix/clojure-signature-bindings

Conversation

@tony

@tony tony commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

Summary

  • Fix unrelated Java links on Clojure argument names.
  • Preserve hyphenated var names and native declaration links.
  • Keep authored references and Java type hints resolvable.
  • Rebaseline only Clojure’s cross-reference minimum after removing false signature links.

In (send! connection argv timeout), timeout linked to Java's CommandRequest.timeout. The tokenizer also split join-pane! and one-or-none into fragments and linked those fragments to unrelated methods. Native Clojure call forms now identify the public var and its local bindings before generic symbol lookup.

The renderer regression exercises all 85 public functions and 98 arities with the actual Java parent inventory. Other language branches retain their existing behavior.

Test plan

  • Reproduce the accidental timeout link with the original renderer.
  • Pass 231 focused Clojure, JVM, scope, type-parameter and inline-link tests.
  • Pass the actual Astro signature renderer across every public Clojure arity.
  • Reject the original renderer, restore the fix, and pass the renderer regression.
  • Pass API-model lint, type checks and git diff --check.
  • Build the fix combined with PR Fix five ports' docs builds and tidy the port landing page #296 through the actual Clojure publisher inputs in 113.05 seconds.
  • Verify 3,382 provenance files, 14,175 internal links/anchors and 3,440 assets; reject Java type links inside native call forms.
  • Check four Clojure pages at 280, 390, 768 and 1440 pixels in Chromium; exercise JVM grouping, keyboard focus and two deliberate rejection controls.
  • Audit source-matched publisher output: 53 false signature links removed, one correct namespace link added, and all 311 references outside signatures unchanged. The checker passes at 643 and rejects 644; other ports’ minimums are unchanged.
  • Rebase both implementation/test patches unchanged onto docs main 856211d85; pass the focused model, renderer, type and ratchet checks.
  • Complete the broad outer gate. On the rebased branch, pnpm test failed after 40.96 seconds: 1,454 model tests passed and 14 skipped, but the full-corpus resolver test exceeded its unchanged five-second timeout (11.11 seconds under parallel load). Pending checks were stopped. Earlier isolated success is not a broad pass; no timeout or loop budget is increased.
  • Hosted CI.

This draft targets current docs main. Coordinate landing with the shared docs release; the no-preview label holds preview publication.

Local publisher qualification uses an unpublished integration commit, 7cf7d80f20cc8dea8437f51342b2c794fb91cde8, combining PR #296 at 0149aad1 with this fix at 2d326686e. It renders 124 Clojure pages, including 92 reference pages, from clean source records. The production type-link checker reports six linked types and five plain ns keyword tokens. All native call forms are free of unrelated Java links. This local result leaves full shared CI and publication of this renderer fix pending. The r19 baseline documentation is already publicly published; it does not contain this follow-up fix.

The browser check of that same build passes 16 page/width combinations in 6.52 seconds, including the real shared native-header geometry checks. The picker places Clojure with Java, Kotlin and Scala; filtering, Escape and focus return work. Covered controls and an injected false Java link are rejected, then restored. Chromium closes with no remaining owned process. Firefox failed at startup and supplies no rendering evidence. External requests are blocked or replaced by the shared checker; other ports and public deployment remain outside this check.

The original hosted run failed at the Clojure cross-reference minimum: 643
against 673. The before/after output measures 695 → 643 because 39 Java
links and 14 own-symbol/partial-prefix links inside signatures disappear,
while the corrected libtmux.core-async namespace contributes one valid
link. All 311 references outside signatures are identical. Set the Clojure
minimum to the measured 643; retain the shared checker and every other
port’s record. A deliberate one-count shortfall still fails.

The rebase preserves both original patches exactly. The linker is byte-for-byte
identical to the already-qualified local publisher input; the new commit only
updates the measured Clojure minimum. The outer failure above remains open,
and this PR remains a draft while its new hosted CI run is pending.

@tony tony added the no-preview Run CI without publishing a PR preview. label Nov 10, 2026
tony added 3 commits November 10, 2026 03:37
why: Native call forms linked local arguments and fragments of var names
to unrelated Java APIs.

what:
- Preserve complete Clojure var and argument tokens.
- Mark native call names and parameters as declarations.
- Retain authored references and Java type-hint links.
- Cover colliding names through the actual symbol resolver.
why: Native signature rendering must preserve callable names and keep
local arguments out of the Java parent inventory.

what:
- Render every public Clojure function arity through Astro.
- Check copied source text, declaration names and link destinations.
why: The corrected renderer removes 53 spurious signature links and adds
one valid namespace link, taking the measured count from 695 to 643.
All 311 references outside signatures remain unchanged. The old minimum
of 673 counted declaration and binding links that should never resolve.

what:
- Set only the Clojure cross-reference minimum to the measured 643
- Keep every other port minimum and the shared checker unchanged
@tony
tony force-pushed the fix/clojure-signature-bindings branch from 2d32668 to f58c5b5 Compare November 10, 2026 09:53
@tony
tony merged commit 08619fc into main Nov 11, 2026
3 checks passed
tony added a commit that referenced this pull request Nov 11, 2026
why: Four kinds of failure reached the ports only when a port built its
own docs, never in docs CI: an unmapped README badge, a checkout path a
wrapper library could not derive, a tmux-usage citation pinned to a line
the port had moved, and a Haskell exporter gap at the port head. The six
new ports' pages also lagged their repositories, and the Haskell front
page described entity IDs instead of the client.

what:
- Resolve every port checkout through one helper, so a wrapper such as
  Clojure derives its parent's checkout (scripts/lib/port-checkout.mjs)
- Fail on any README badge the badge renderer cannot map
  (scripts/check-port-badges.mjs)
- Build every port's head against docs main weekly and on dispatch,
  without publishing (.github/workflows/port-heads.yml); port-docs.yml
  gains an optional source-repository input, so callers are unchanged
- Locate tmux-usage citations by their text within their body instead of
  a stored line (scripts/lib/tmux-usage-locate.mjs, claims.json)
- Bring the Haskell (#293, #300), OCaml (#294, #295), Clojure (#299),
  Erlang, Common Lisp and Perl pages up to each port's source, with
  examples indexes of their tested programs
- Describe a staged guide without a catalog description by its first
  sentence, and title a link to a staged guide instead of naming its file
- List a port's API roots in llms.txt, and mention MCP only for ports
  that ship an MCP server
- Give every language's Core Library card on the front page the same
  one line, and drop the MCP aside from the new ports' landing pages
- Remove two 5-second test timeouts and record Common Lisp's type-link
  baseline at libtmux-lisp e6f319c42

Base main 856211d, head e36e62b. CI run 43009353757.
@tony
tony temporarily deployed to docs-preview-cleanup November 11, 2026 22:49 — with GitHub Actions Inactive

This branch was previously deployed

1 inactive deployment
docs-preview-cleanup — f58c5b58 Deployed Nov 11, 2026 by tony via cleanup #235
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

no-preview Run CI without publishing a PR preview.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant