Skip to content

[app][plugins][feature] Native document annotation providers for coverage, debugging, and profiling #263

Open

Description

@sgammon

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.docs provides 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:profile already 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

  1. Run tests with coverage from the project action panel.
  2. Select a measured file in the test results.
  3. Open it in the native editor with quiet line/branch coverage marks and details on hover.
  4. Edit the source: the previous measurement immediately becomes stale.
  5. 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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions