parity

package
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 29, 2026 License: MIT Imports: 9 Imported by: 0

README

Upstream parity tripwires

This package detects extension API and runtime-contract drift against the exact Pi release pinned in internal/coding/pigversion/pigversion.go and materialized under .upstream/current.

These tests complement the compiler-derived inventories under test/parity/interfaces/. They are narrow regression tripwires. They do not prove that a declaration has a production caller or behavioral parity scenario.

Contents

Area Purpose
parser and registry tests compare extension events, methods, result types, and JSON fields
dispatch and context tests check host dispatch and context surface correspondence
mirror tests bind the local mirror to the pinned release and commit
divergence tests validate divergence records and call-site markers
layout tests protect intentional public package boundaries
script tests verify maintained scheduling and policy commands

Run the tests

go test ./test/upstream-parity -count=1

make test and make check include this package.

Respond to drift

  1. Read the changed declaration and its callers under .upstream/current.
  2. Probe observable Pi behavior before changing PiG.
  3. Port the behavior and add caller-level evidence.
  4. Add a divergence only when the observable difference is intentional and approved under AGENTS.md.
  5. Regenerate the affected inventories through their Make targets.
  6. Run the focused tests, the owning parity family, and make check.

If the parser smoke test fails after an upstream change, update its fixture and parser only after confirming the new TypeScript syntax. The TypeScript compiler inventory remains the completeness authority.

Documentation

Overview

Package parity parses upstream pi TypeScript declarations to drive parity tests. It extracts the ExtensionAPI surface (events + methods) and every Event / EventResult interface from .upstream/current/packages/coding-agent/src/core/extensions/types.ts.

The parser is regex-based and intentionally narrow. It does not implement a general TypeScript grammar: it relies on the upstream file using a consistent style (single-line `on(event: "...")` overloads, top-level `export interface XxxEvent {` blocks, etc.). If upstream restructures the file in a way that breaks the parser, the parser tests will fail loudly.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func CamelToGoField

func CamelToGoField(s string) string

CamelToGoField converts upstream camelCase to Go PascalCase with idiomatic Go initialism handling at word boundaries.

Examples:

"toolCallId"        → "ToolCallID"
"newLeafId"         → "NewLeafID"
"baseUrl"           → "BaseURL"
"apiKey"            → "APIKey"   (leading initialism)
"jsonValue"         → "JSONValue"
"id"                → "ID"
"customInstructions" → "CustomInstructions" (no change)

Word boundaries are detected as transitions from lower-case to upper-case after CamelToPascal is applied to the input. Each segment is tested against [goInitialisms]; matches are upper-cased.

func CamelToPascal

func CamelToPascal(s string) string

CamelToPascal converts upstream camelCase to Go PascalCase. "registerTool" -> "RegisterTool", "exec" -> "Exec".

This helper is for METHOD names where Go style is plain PascalCase. For FIELD names that need idiomatic Go initialism handling (Id→ID, Url→URL, Api→API, Json→JSON), use CamelToGoField instead.

func SnakeEventToOnMethod

func SnakeEventToOnMethod(event string) string

SnakeEventToOnMethod converts an upstream event name to its expected Go `On*` method name. "tool_call" -> "OnToolCall", "session_before_compact" -> "OnSessionBeforeCompact".

Types

type EventTypeDecl

type EventTypeDecl struct {
	Name   string            // e.g. "ToolCallEvent"
	Fields map[string]string // fieldName -> raw TS type string
	// FieldOrder preserves declaration order (maps don't).
	FieldOrder []string
}

EventTypeDecl is the parsed shape of one `export interface XxxEvent {…}` or `XxxEventResult {…}` block.

type ExtensionAPISurface

type ExtensionAPISurface struct {
	// Events is the list of event names registrable via `on(event: "...")`,
	// in declaration order, lower_snake_case as they appear in upstream.
	Events []string

	// Methods is the list of method names on ExtensionAPI other than `on`,
	// in declaration order, camelCase as they appear in upstream.
	Methods []string
}

ExtensionAPISurface is the parsed shape of upstream's ExtensionAPI interface.

type UpstreamSurface

type UpstreamSurface struct {
	API          ExtensionAPISurface
	EventTypes   []EventTypeDecl // *Event interfaces (excluding *EventResult)
	EventResults []EventTypeDecl // *EventResult interfaces
}

UpstreamSurface is the full parsed snapshot.

func LoadUpstream

func LoadUpstream() (*UpstreamSurface, error)

LoadUpstream parses the upstream types.ts at the well-known path.

func LoadUpstreamFrom

func LoadUpstreamFrom(src string) (*UpstreamSurface, error)

LoadUpstreamFrom parses TypeScript source from an explicit string. Used by parser self-tests against fixture inputs.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL