@termwright/probe-tview 0.2.0 → 0.3.1

package/assets/tview_probe_test.go.txt

@@ -0,0 +1,483 @@
+package tview
+
+import (
+	"errors"
+	"reflect"
+	"runtime/debug"
+	"sync/atomic"
+	"testing"
+
+	"github.com/gdamore/tcell/v2"
+
+	"github.com/gorce-ai/termwright/clients/go/protocol"
+)
+
+type termwrightControlledPublicationSink struct {
+	ready    chan struct{}
+	failures atomic.Int32
+}
+
+func (s *termwrightControlledPublicationSink) TryPublish(*protocol.Snapshot) (string, error) {
+	return "", protocol.ErrPublicationQueueFull
+}
+
+func (s *termwrightControlledPublicationSink) ReadyAfterDrop() <-chan struct{} { return s.ready }
+func (s *termwrightControlledPublicationSink) Fail(string, string)             { s.failures.Add(1) }
+
+type termwrightTestScreen struct {
+	tcell.Screen
+	onShow    func()
+	onFini    func()
+	finalized atomic.Bool
+}
+
+func (s *termwrightTestScreen) Show() {
+	if s.onShow != nil {
+		s.onShow()
+		return
+	}
+	s.Screen.Show()
+}
+
+func (s *termwrightTestScreen) Fini() {
+	if !s.finalized.CompareAndSwap(false, true) {
+		return
+	}
+	if s.onFini != nil {
+		s.onFini()
+	}
+	s.Screen.Fini()
+}
+
+func termwrightNewTestScreen(t *testing.T) *termwrightTestScreen {
+	t.Helper()
+	simulation := tcell.NewSimulationScreen("UTF-8")
+	if err := simulation.Init(); err != nil {
+		t.Fatal(err)
+	}
+	screen := &termwrightTestScreen{Screen: simulation}
+	t.Cleanup(screen.Fini)
+	return screen
+}
+
+func termwrightDecorator(application *Application, screen tcell.Screen, commit func(Primitive, tcell.Screen)) *termwrightScreen {
+	decorated := &termwrightScreen{
+		Screen: screen, application: application, commit: commit,
+	}
+	decorated.previousBefore = application.beforeDraw
+	decorated.previousAfter = application.afterDraw
+	decorated.beforeHook = decorated.beforeDraw
+	decorated.afterHook = decorated.afterDraw
+	application.beforeDraw = decorated.beforeHook
+	application.afterDraw = decorated.afterHook
+	application.screen = decorated
+	return decorated
+}
+
+type termwrightIntermediateShowPrimitive struct{ *Box }
+
+func (p *termwrightIntermediateShowPrimitive) Draw(screen tcell.Screen) {
+	x, y, _, _ := p.GetRect()
+	screen.SetContent(x, y, 'a', nil, tcell.StyleDefault)
+	screen.Show()
+	screen.SetContent(x+1, y, 'b', nil, tcell.StyleDefault)
+}
+
+func TestTermwrightScreenIgnoresIntermediateCustomPrimitiveShow(t *testing.T) {
+	application := NewApplication()
+	root := &termwrightIntermediateShowPrimitive{Box: NewBox()}
+	application.SetRoot(root, true)
+	underlying := termwrightNewTestScreen(t)
+	shows := 0
+	underlying.onShow = func() { shows++ }
+	commits := 0
+	termwrightDecorator(application, underlying, func(Primitive, tcell.Screen) { commits++ })
+
+	application.draw()
+	if shows != 2 || commits != 1 {
+		t.Fatalf("custom draw shows/commits = %d/%d, want 2/1", shows, commits)
+	}
+}
+
+func TestTermwrightScreenIgnoresShowsInsideLifecycleHooks(t *testing.T) {
+	for _, test := range []struct {
+		name string
+		set  func(*Application)
+	}{
+		{name: "before-short-circuit", set: func(application *Application) {
+			application.SetBeforeDrawFunc(func(screen tcell.Screen) bool { screen.Show(); return true })
+		}},
+		{name: "after", set: func(application *Application) {
+			application.SetAfterDrawFunc(func(screen tcell.Screen) { screen.Show() })
+		}},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			application := NewApplication()
+			application.SetRoot(NewBox(), true)
+			test.set(application)
+			underlying := termwrightNewTestScreen(t)
+			shows := 0
+			underlying.onShow = func() { shows++ }
+			commits := 0
+			termwrightDecorator(application, underlying, func(Primitive, tcell.Screen) { commits++ })
+			application.draw()
+			if shows != 2 || commits != 1 {
+				t.Fatalf("hook shows/commits = %d/%d, want 2/1", shows, commits)
+			}
+		})
+	}
+}
+
+func TestTermwrightScreenFailsClosedWhenLifecycleHookIsDisplaced(t *testing.T) {
+	application := NewApplication()
+	application.SetRoot(NewBox(), true)
+	underlying := termwrightNewTestScreen(t)
+	commits := 0
+	decorated := termwrightDecorator(application, underlying, func(Primitive, tcell.Screen) { commits++ })
+	failures := 0
+	decorated.fail = func(code, message string) {
+		if code != "adapter-guarantee-violation" || message == "" {
+			t.Fatalf("unexpected failure %q: %q", code, message)
+		}
+		failures++
+	}
+	application.SetAfterDrawFunc(func(tcell.Screen) {})
+
+	application.draw()
+	if failures != 1 || commits != 0 || !decorated.failed.Load() {
+		t.Fatalf("displaced hook failures/commits/failed = %d/%d/%v, want 1/0/true", failures, commits, decorated.failed.Load())
+	}
+}
+
+func TestTermwrightDependencyVersionAcceptsWorkspaceAndLocalReplacement(t *testing.T) {
+	for _, test := range []struct {
+		module *debug.Module
+		want   string
+	}{
+		{module: &debug.Module{Version: "v0.42.0", Replace: &debug.Module{Path: "/workspace/tview"}}, want: "v0.42.0"},
+		{module: &debug.Module{Version: "(devel)", Replace: &debug.Module{Path: "/workspace/tview"}}, want: "capability-local"},
+		{module: &debug.Module{Replace: &debug.Module{Path: "/workspace/tview"}}, want: "capability-local"},
+	} {
+		if got := termwrightDependencyVersion(test.module); got != test.want {
+			t.Fatalf("dependency version = %q, want %q", got, test.want)
+		}
+	}
+}
+
+func TestTermwrightScreenCommitsAfterTheOnlyUnderlyingShow(t *testing.T) {
+	application := NewApplication()
+	root := NewBox()
+	application.SetRoot(root, true)
+	events := make([]string, 0, 2)
+	underlying := termwrightNewTestScreen(t)
+	underlying.onShow = func() { events = append(events, "show") }
+	termwrightDecorator(application, underlying, func(got Primitive, screen tcell.Screen) {
+		if got != root || screen != underlying {
+			t.Fatalf("commit observed root/screen %T/%T", got, screen)
+		}
+		events = append(events, "commit-marker")
+	})
+
+	application.draw()
+	if want := []string{"show", "commit-marker"}; !reflect.DeepEqual(events, want) {
+		t.Fatalf("frame order = %v, want %v", events, want)
+	}
+}
+
+func TestTermwrightScreenObservesBeforeDrawShortCircuit(t *testing.T) {
+	application := NewApplication()
+	root := NewBox()
+	application.SetRoot(root, true)
+	events := make([]string, 0, 3)
+	application.SetBeforeDrawFunc(func(tcell.Screen) bool {
+		events = append(events, "before")
+		return true
+	})
+	underlying := termwrightNewTestScreen(t)
+	underlying.onShow = func() { events = append(events, "show") }
+	termwrightDecorator(application, underlying, func(got Primitive, _ tcell.Screen) {
+		if got != root {
+			t.Fatalf("commit root = %T, want initial root", got)
+		}
+		events = append(events, "commit-marker")
+	})
+
+	application.draw()
+	if want := []string{"before", "show", "commit-marker"}; !reflect.DeepEqual(events, want) {
+		t.Fatalf("short-circuit order = %v, want %v", events, want)
+	}
+}
+
+func TestTermwrightScreenReadsDynamicRootAfterEachShow(t *testing.T) {
+	application := NewApplication()
+	first := NewBox()
+	second := NewTextView().SetText("second")
+	application.SetRoot(first, true)
+	underlying := termwrightNewTestScreen(t)
+	roots := make([]Primitive, 0, 2)
+	termwrightDecorator(application, underlying, func(root Primitive, _ tcell.Screen) {
+		roots = append(roots, root)
+	})
+
+	application.draw()
+	application.SetRoot(second, true)
+	application.draw()
+	if want := []Primitive{first, second}; !reflect.DeepEqual(roots, want) {
+		t.Fatalf("committed roots = %v, want %v", roots, want)
+	}
+}
+
+func TestTermwrightScreensDoNotSerializeIndependentApplications(t *testing.T) {
+	firstApplication := NewApplication()
+	secondApplication := NewApplication()
+	firstApplication.root = NewBox()
+	secondApplication.root = NewBox()
+	firstUnderlying := termwrightNewTestScreen(t)
+	secondUnderlying := termwrightNewTestScreen(t)
+	entered := make(chan struct{})
+	release := make(chan struct{})
+	firstUnderlying.onShow = func() {
+		close(entered)
+		<-release
+	}
+	secondShown := false
+	secondUnderlying.onShow = func() { secondShown = true }
+	first := termwrightDecorator(firstApplication, firstUnderlying, nil)
+	second := termwrightDecorator(secondApplication, secondUnderlying, nil)
+	done := make(chan struct{})
+	go func() {
+		first.Show()
+		close(done)
+	}()
+	<-entered
+	second.Show()
+	if !secondShown {
+		t.Fatal("second application was serialized behind the first")
+	}
+	close(release)
+	<-done
+}
+
+func TestTermwrightIdleShowDoesNotReadHooksBeingConfigured(t *testing.T) {
+	application := NewApplication()
+	underlying := termwrightNewTestScreen(t)
+	underlying.onShow = func() {}
+	decorated := termwrightDecorator(application, underlying, nil)
+	done := make(chan struct{})
+	go func() {
+		defer close(done)
+		for index := 0; index < 1000; index++ {
+			application.SetAfterDrawFunc(func(tcell.Screen) {})
+		}
+	}()
+	for index := 0; index < 1000; index++ {
+		decorated.Show()
+	}
+	<-done
+}
+
+func TestTermwrightScreenFailsClosedOnReentrantShow(t *testing.T) {
+	application := NewApplication()
+	application.root = NewBox()
+	underlying := termwrightNewTestScreen(t)
+	var decorated *termwrightScreen
+	var failures atomic.Int32
+	commits := 0
+	decorated = termwrightDecorator(application, underlying, func(Primitive, tcell.Screen) {
+		commits++
+	})
+	decorated.fail = func(code, message string) {
+		if code != "adapter-guarantee-violation" || message == "" {
+			t.Fatalf("unexpected failure %q: %q", code, message)
+		}
+		failures.Add(1)
+	}
+	underlying.onShow = func() { decorated.Show() }
+
+	decorated.Show()
+	if failures.Load() != 1 || commits != 0 {
+		t.Fatalf("reentrant Show failures/commits = %d/%d, want 1/0", failures.Load(), commits)
+	}
+}
+
+func TestTermwrightScreenCleanupRestoresOnlyItsOwnInstallation(t *testing.T) {
+	t.Run("restores", func(t *testing.T) {
+		application := NewApplication()
+		underlying := termwrightNewTestScreen(t)
+		decorated := termwrightDecorator(application, underlying, nil)
+		decorated.detach()
+		if application.screen != underlying {
+			t.Fatalf("cleanup restored %T, want underlying screen", application.screen)
+		}
+	})
+	t.Run("later replacement wins", func(t *testing.T) {
+		application := NewApplication()
+		underlying := termwrightNewTestScreen(t)
+		replacement := termwrightNewTestScreen(t)
+		decorated := termwrightDecorator(application, underlying, nil)
+		application.screen = replacement
+		decorated.detach()
+		if application.screen != replacement {
+			t.Fatalf("cleanup clobbered later screen with %T", application.screen)
+		}
+	})
+}
+
+func TestTermwrightScreenFailsClosedBeforeRuntimeReplacement(t *testing.T) {
+	application := NewApplication()
+	underlying := termwrightNewTestScreen(t)
+	replacement := termwrightNewTestScreen(t)
+	finalized := 0
+	underlying.onFini = func() { finalized++ }
+	decorated := termwrightDecorator(application, underlying, nil)
+	failures := 0
+	decorated.fail = func(code, message string) {
+		if code != "adapter-guarantee-violation" || message == "" {
+			t.Fatalf("unexpected failure %q: %q", code, message)
+		}
+		failures++
+	}
+
+	application.SetScreen(replacement)
+	if failures != 1 || finalized != 1 || !decorated.failed.Load() || !decorated.detached.Load() {
+		t.Fatalf("replacement failures/finalized/failed/detached = %d/%d/%v/%v", failures, finalized, decorated.failed.Load(), decorated.detached.Load())
+	}
+	decorated.Fini()
+	if finalized != 1 {
+		t.Fatalf("underlying screen finalized %d times, want once", finalized)
+	}
+}
+
+func TestTermwrightScreenStopDoesNotReenterApplicationLock(t *testing.T) {
+	application := NewApplication()
+	underlying := termwrightNewTestScreen(t)
+	finalized := 0
+	underlying.onFini = func() { finalized++ }
+	decorated := termwrightDecorator(application, underlying, nil)
+	failures := 0
+	decorated.fail = func(string, string) { failures++ }
+
+	// This is the real upstream lifecycle: Stop holds Application.Lock while it
+	// invokes the decorated screen's Fini method.
+	application.Stop()
+	if finalized != 1 || failures != 0 || !decorated.failed.Load() || !decorated.detached.Load() {
+		t.Fatalf("stop finalized/failures/failed/detached = %d/%d/%v/%v", finalized, failures, decorated.failed.Load(), decorated.detached.Load())
+	}
+	decorated.detach()
+	if application.beforeDraw != nil || application.afterDraw != nil {
+		t.Fatal("cleanup after Stop left the probe lifecycle hooks installed")
+	}
+}
+
+func TestTermwrightScreenFiniUnderUnrelatedWriterFailsClosedWithoutBlocking(t *testing.T) {
+	application := NewApplication()
+	underlying := termwrightNewTestScreen(t)
+	commits := 0
+	decorated := termwrightDecorator(application, underlying, func(Primitive, tcell.Screen) {
+		commits++
+	})
+	failures := make(chan string, 1)
+	decorated.fail = func(code, message string) {
+		if code != "adapter-guarantee-violation" || message == "" {
+			t.Errorf("unexpected failure %q: %q", code, message)
+		}
+		failures <- message
+	}
+
+	application.Lock()
+	decorated.Fini()
+	application.Unlock()
+	<-failures
+	underlying.onShow = func() {}
+	decorated.Show()
+	if commits != 0 || !decorated.failed.Load() || !decorated.detached.Load() {
+		t.Fatalf("writer collision commits/failed/detached = %d/%v/%v", commits, decorated.failed.Load(), decorated.detached.Load())
+	}
+	decorated.detach()
+	application.Lock()
+	application.screen = nil
+	application.Unlock()
+}
+
+func TestTermwrightQueuePressureRequestsOneFreshAuthoritativeDraw(t *testing.T) {
+	application := NewApplication()
+	root := NewTextView().SetText("latest")
+	application.SetRoot(root, true)
+	underlying := termwrightNewTestScreen(t)
+	underlying.onShow = func() {}
+	commits := 0
+	termwrightDecorator(application, underlying, func(got Primitive, _ tcell.Screen) {
+		if got != root {
+			t.Fatalf("recovery committed %T, want latest root", got)
+		}
+		commits++
+	})
+	probe := &termwrightProbeState{
+		application:  application,
+		recoveryStop: make(chan struct{}),
+	}
+	sink := &termwrightControlledPublicationSink{ready: make(chan struct{})}
+
+	probe.onPublishFailed(sink, protocol.ErrPublicationQueueFull)
+	probe.onPublishFailed(sink, protocol.ErrPublicationQueueFull)
+	if sink.failures.Load() != 0 || probe.dropped.Load() != 2 {
+		t.Fatalf("recoverable pressure failures/drops = %d/%d, want 0/2", sink.failures.Load(), probe.dropped.Load())
+	}
+	select {
+	case <-application.updates:
+		t.Fatal("redraw was queued before publication capacity returned")
+	default:
+	}
+
+	close(sink.ready)
+	update := <-application.updates
+	update.f()
+	if commits != 1 || probe.recoveryPending.Load() {
+		t.Fatalf("authoritative redraw commits/pending = %d/%v, want 1/false", commits, probe.recoveryPending.Load())
+	}
+	close(probe.recoveryStop)
+	probe.recoveryWorkers.Wait()
+}
+
+func TestTermwrightAdmissionContentionDefersOneFreshAuthoritativeDraw(t *testing.T) {
+	application := NewApplication()
+	root := NewTextView().SetText("after-contention")
+	application.SetRoot(root, true)
+	underlying := termwrightNewTestScreen(t)
+	underlying.onShow = func() {}
+	commits := 0
+	termwrightDecorator(application, underlying, func(got Primitive, _ tcell.Screen) {
+		if got != root {
+			t.Fatalf("deferred draw committed %T, want latest root", got)
+		}
+		commits++
+	})
+	probe := &termwrightProbeState{
+		application:  application,
+		recoveryStop: make(chan struct{}),
+	}
+	sink := &termwrightControlledPublicationSink{ready: make(chan struct{})}
+
+	probe.onPublishFailed(sink, protocol.ErrPublicationQueueBusy)
+	probe.onPublishFailed(sink, protocol.ErrPublicationQueueBusy)
+	update := <-application.updates
+	update.f()
+	if sink.failures.Load() != 0 || probe.dropped.Load() != 2 || commits != 1 || probe.recoveryPending.Load() {
+		t.Fatalf(
+			"contention failures/drops/commits/pending = %d/%d/%d/%v, want 0/2/1/false",
+			sink.failures.Load(), probe.dropped.Load(), commits, probe.recoveryPending.Load(),
+		)
+	}
+	close(probe.recoveryStop)
+	probe.recoveryWorkers.Wait()
+}
+
+func TestTermwrightNonPressurePublicationRefusalStillFailsClosed(t *testing.T) {
+	probe := &termwrightProbeState{recoveryStop: make(chan struct{})}
+	sink := &termwrightControlledPublicationSink{ready: make(chan struct{})}
+	probe.onPublishFailed(sink, errors.New("invalid snapshot"))
+	if sink.failures.Load() != 1 || probe.dropped.Load() != 1 {
+		t.Fatalf("hard refusal failures/drops = %d/%d, want 1/1", sink.failures.Load(), probe.dropped.Load())
+	}
+	close(probe.recoveryStop)
+}

package/dist/index.d.ts

@@ -39,49 +39,33 @@ declare function roleFor(frameworkType: string): SemanticRole;
  */
 declare function recognize(frame: ProbeFrame, options: RecognizeOptions): SemanticSnapshot;
 
-/**
- * The one call a launcher makes.
- *
- * Everything else in this package is a step: read the workspace, materialise a
- * copy, patch it, key the cache, write the file. A user should not assemble
- * those, and neither should a test — the assembly order is where the mistakes
- * live, and there is exactly one correct one.
- */
-/** Module path of the framework this probe instruments. */
+/** Capability-driven, add-only compiler injection for tview. */
 declare const FRAMEWORK = "github.com/rivo/tview";
-/** Module path of the protocol client the injected probe imports. */
 declare const CLIENT_MODULE = "github.com/gorce-ai/termwright/clients/go";
-/** Version of this probe; part of the cache key, so a new patch set invalidates copies. */
-declare const PROBE_VERSION = "0.1.0";
+declare const PROBE_VERSION = "0.3.1";
 interface PrepareOptions {
-    /** Directory of the Go module to build. */
     readonly moduleDir: string;
-    /** Framework version to instrument, e.g. `v0.42.0`. */
+    /** Advisory expectation; runtime capability compilation is authoritative. */
     readonly frameworkVersion?: string;
-    /** Where the protocol client lives on disk. Defaults to the copy shipped here. */
-    readonly clientDir?: string;
-    /** Where the generated workspace is written. Defaults to inside the copy's cache entry. */
-    readonly workspaceFile?: string;
-    /** Environment the build will run with; checked, never mutated. */
+    readonly outputDir?: string;
     readonly env?: NodeJS.ProcessEnv;
 }
 interface PreparedBuild {
-    /** Hand this to the build as `GOWORK`. */
-    readonly workspaceFile: string;
-    /** The instrumented copy, for a canary check or for diagnosis. */
-    readonly copyDir: string;
-    /** Environment to build with: the caller's, plus GOWORK. */
+    /** Canonical module directory that must be used as the build cwd. */
+    readonly moduleDir: string;
+    /** Insert after `go build` or `go test`. */
+    readonly goArgs: readonly [string, string];
     readonly env: NodeJS.ProcessEnv;
-    /** True when the copy was built during this call rather than reused. */
-    readonly built: boolean;
+    readonly wrapperFile: string;
+    readonly configDigest: string;
+    readonly frameworkVersion: string;
+    readonly sourceDigests: readonly string[];
 }
 /**
- * Makes a build of `moduleDir` compile against the instrumented framework.
- *
- * Does not build anything and does not spawn the application: a launcher owns
- * that. This returns what the build needs and nothing else, which keeps the
- * package testable and keeps the decision about *how* to run the user's build
- * where it belongs.
+ * Prepares one official Go `-toolexec` wrapper. It adds compilation units to
+ * package namespaces selected by TOOLEXEC_IMPORTPATH and therefore works for
+ * module-cache, workspace, replacement, and vendored dependency layouts.
+ * No upstream path is copied, patched, or hashed.
  */
 declare function prepareInstrumentedBuild(options: PrepareOptions): Promise<PreparedBuild>;