Repository navigation
Description
I'd like plugins to publish versioned, owner-scoped annotations into Tern's native file editor: coverage marks, breakpoints, the current execution location, diagnostics, and source-level profiling heat. Tern should continue to own the document, editing, undo, layout, and rendering.
We have a working Elide plugin integration that composes native Files, document panes, an action canvas, terminals, and TSP REPL/test/server views. The next useful step is connecting runtime inspection to the source already open in Tern. Rebuilding the editor in a program-owned TSP surface would duplicate buffer ownership and lose the seamless native workflow we're aiming for.
Existing facilities and the gap
Audited against Tern 0.9.12 and the installed Luau declarations:
cx.docsprovides native open/read/edit/save operations. I couldn't find exposed buffer revisions, a document change subscription, or native annotation providers.- TSP editor nodes already have decoration, gutter, and virtual-line primitives. Those belong to program-owned editors; we need equivalent integration with an existing native file buffer.
cx.procs:profilealready opens a native profile view. Its returned function sample counts don't expose source URI/line information for editor overlays. Our runtime can supply source-attributed measurements independently; enriching native profile results could be a separate follow-up.
First complete workflow
- Run tests with coverage from the project action panel.
- Select a measured file in the test results.
- Open it in the native editor with quiet line/branch coverage marks and details on hover.
- Edit the source: the previous measurement immediately becomes stale.
- Rerun: replace the layer atomically with results for the new source version.
We would initially exercise this with JavaScript and Kotlin/JUnit. The same contract should then support debugger breakpoints/current-stop markers and optional sampled source heat.
Proposed SDK capabilities
These are requested semantics, not proposed final API names:
| Capability | Useful contract |
|---|---|
| Observe documents | Atomically return a buffer snapshot and an ordered event cursor/subscription, avoiding a read-then-subscribe race. Include document/overlay identity, URI, language, opaque revision, exact text or content digest, and dirty state. |
| Register a provider | Allocate an owner-scoped handle for annotation layers and their interaction callbacks. Expose capability discovery so plugins can support older Tern versions. |
| Replace a layer | Atomically replace a document's layer, checking the expected buffer revision, measured source identity, and provider generation. Reject stale publications without replacing a newer layer. |
| Interact | Deliver gutter toggles, hover requests, and registered annotation/context actions with document identity, revision, range, and stable item ID. |
| Reveal source | Open a URI/range with optional source identity and focus policy. Distinguish matching current source from historical or unavailable source. |
| Dispose | Remove only the owner's annotations and subscriptions on disposal/plugin reload. Make service disconnection and document detachment explicit lifecycle events. |
A later extension could expose revision-checked edits using the same document identity, preserving native undo and conflict handling.
Source correctness and native presentation
- A measurement must identify the source actually executed or compiled. A path alone, or hashing the file after execution, isn't sufficient. Use a declared digest/encoding convention and explicitly handle source maps.
- Split views of one buffer share its identity; divergent unsaved buffers must remain distinguishable even when their URI matches. Include save, rename, external modification, and close events; event overflow should require resnapshotting.
- Specify coordinate encoding. Zero-based lines/UTF-16 columns with exclusive ends would align well with common tooling, with adapters converting debugger and existing SDK coordinates.
- Editing must invalidate source-dependent measurements immediately. Breakpoint intent may follow native text anchors, but verified runtime bindings and execution markers must retain their loaded-source identity.
- Keep coverage, breakpoint, execution, and heat layers independently visible. Tern should control styling, accessibility, priorities, and keyboard interaction; providers send semantic data, not arbitrary HTML or executable content.
- Bound items and update rates, support visible-range requests for large files, and preserve caret, selection, scroll, and undo during annotation updates.
The runtime/plugin side would own measurement production, debugger control, source attribution, and historical artifacts. This request is for the reusable native document/provider boundary, so other language and tooling plugins can use it too.
Validation and related requests
The first slice should cover edit-during-run/stale publication, Unicode and CRLF ranges, divergent unsaved buffers, simultaneous providers, and plugin reload cleanup, alongside the normal coverage workflow. Debugger follow-ups should distinguish requested/verified breakpoints and never place a current-stop arrow against mismatched source. Heat should retain its measurement semantics: sample share is different from exact duration or execution count.
Related: #51 and #177 request anchored comments and selection interactions. They overlap with native document hooks, while this proposal focuses on runtime-owned, revision-checked inspection layers.
Would a native document/annotation provider API fit Tern's direction? We're building the runtime and plugin side and can exercise a coverage-first implementation as the SDK contract develops.
Activity