locallink

type ConsumerResult struct {
	Consumer string `json:"consumer"`
	// Repository is the consumer's owner/repository when stream state knows
	// it.
	Repository string `json:"repository,omitempty"`
	// Skipped is set when the consumer declares none of the library's
	// published identities. Such a consumer is reported and skipped rather
	// than linked to something it does not use.
	Skipped bool   `json:"skipped,omitempty"`
	Reason  string `json:"reason,omitempty"`
	// Links are the links created (or removed, under --undo).
	Links []streams.Link `json:"links,omitempty"`
	// SkippedChecks name guarantees that could not be evaluated at all, so a
	// silent pass is never mistaken for a proven one.
	SkippedChecks []string `json:"skipped_checks,omitempty"`
	// Verification is the single-worker run against the linked copy.
	Verification *Verification `json:"verification,omitempty"`
	// Notes are informational outcomes that are not failures — for example
	// `--undo` finding a link already superseded by a published package and
	// clearing its record without touching the filesystem.
	Notes []string `json:"notes,omitempty"`
	// Errors are per-consumer failures. One consumer's failure never stops
	// the pass: the point of a stream is to learn about every consumer at
	// once.
	Errors []string `json:"errors,omitempty"`
}

type Engine struct {
	Store *streams.Store
	Git   Git
	// Node builds and links npm packages.
	Node Node
	// Verifier runs the consumer's own lint and tests.
	Verifier Verifier
	// CacheRoot is where built library dists are cached by content hash.
	CacheRoot string
	Now       func() time.Time
}

type ExecGit struct {
	Timeout time.Duration
}

type ExecNode struct {
	// CacheRoot holds built dists keyed by the library's content hash.
	CacheRoot string
	// ContentHash identifies the library tree the current build belongs to.
	ContentHash string
	Timeout     time.Duration
}

type Git interface {
	// ContentHash identifies a working tree, including modified and untracked
	// files. The library is uncommitted by construction, so it has no SHA;
	// dirty reports whether the tree differs from HEAD.
	ContentHash(ctx context.Context, dir string) (hash string, dirty bool, err error)
	// TrackedChanges lists paths of *tracked* files that differ from HEAD.
	// Untracked paths are excluded: a link creates untracked artefacts by
	// design, and only a tracked change is a violation.
	TrackedChanges(ctx context.Context, dir string) ([]string, error)
	// ExcludePath adds one pattern to the worktree's own Git exclude file,
	// resolved through `git rev-parse --git-path info/exclude` so the path is
	// the one Git will actually read for this worktree.
	ExcludePath(ctx context.Context, dir, pattern string) error
	// ExcludedPatterns reads that exclude file.
	ExcludedPatterns(ctx context.Context, dir string) ([]string, error)
}

type LiveLink struct {
	// Source is "stream-state" or "go.work": the two signals are independent
	// on purpose.
	Source string `json:"source"`
	// Detail names the offending link or `use` entry.
	Detail string `json:"detail"`
	// Sanctioned is the exact command that clears it.
	Sanctioned string `json:"sanctioned_command"`
}

type LiveLinkSource struct {
	// Stream names the open stream recording the link.
	Stream string `json:"stream"`
	// Consumer names the repository still resolving this worktree locally.
	Consumer string `json:"consumer"`
	// Detail names the offending link.
	Detail string `json:"detail"`
	// Sanctioned is the exact command that clears it.
	Sanctioned string `json:"sanctioned_command"`
}

type LiveLinkSourceStore interface {
	LinkSourcesForWorktree(worktree string) ([]streams.StreamLinkSource, error)
}

type LiveLinkStore interface {
	LiveLinksForWorktree(worktree string) ([]streams.StreamLink, error)
}

type Node interface {
	// FrozenInstall proves a clean frozen install of the unlinked consumer
	// tree, so a link never masks a lockfile or manifest mismatch.
	FrozenInstall(ctx context.Context, dir string) error
	// Build runs the library repository's own build target and returns the
	// directory holding the built package.
	Build(ctx context.Context, libraryDir, packageDir string) (dist string, err error)
	// Link stages dist beside the consumer's installed package so framework
	// peer dependencies resolve from the consumer, points node_modules at that
	// stage, and reports every generated path. It preserves what was there so
	// --undo restores it exactly and must not modify any manifest.
	Link(ctx context.Context, consumerDir, packageName, dist string) (result NodeLinkResult, err error)
	// Unlink restores the node_modules entry recorded by Link.
	//
	// note is empty for a normal restore. It carries an informational
	// message when the consumer's own package manager already replaced the
	// WB-staged link with a published copy (a governed `pnpm install`, most
	// often) before undo ran: the record is cleared and the filesystem is
	// left exactly as the package manager left it.
	Unlink(ctx context.Context, consumerDir, packageName string) (note string, err error)
	// LinkSiblings wires runtime dependency edges between packages that WB has
	// staged from the same provider. External peers continue to resolve from
	// the consumer's installed dependency context.
	LinkSiblings(ctx context.Context, consumerDir string, packageNames []string) error
}

type NodeLinkResult struct {
	Previous  string
	Artifacts []string
}

type Options struct {
	// Library is the library worktree whose working tree the consumers build
	// against. It may be empty for --undo, where the record is the source of
	// truth.
	Library string
	// Consumers are the consumer worktrees to link or unlink.
	Consumers []string
	// Undo restores published versions and removes the links.
	Undo bool
	// Verify runs each consumer's lint and tests against the linked copy,
	// single-worker, plus the GOWORK=off build and vet the pre-landing gate
	// requires.
	Verify bool
	// Timeout bounds every child process. Zero uses a sensible default.
	Timeout time.Duration
	// Stream names the stream whose state records the links. Empty resolves
	// the stream that holds the first consumer worktree.
	Stream string
}

type QualityVerifier struct {
	Options quality.RunOptions
}

type Refusal struct {
	Code       string
	Message    string
	Sanctioned []string
}

type Result struct {
	Library string `json:"library,omitempty"`
	// LibraryRepository is the library's owner/repository, which survives the
	// worktree being removed.
	LibraryRepository string `json:"library_repository,omitempty"`
	// ContentHash identifies the library working tree the links exposed,
	// including modified and untracked files. The library is uncommitted by
	// construction, so it has no SHA.
	ContentHash string `json:"content_hash,omitempty"`
	// Dirty reports whether the library working tree differs from its HEAD.
	Dirty bool `json:"dirty,omitempty"`
	// Identities are the published identities discovered from the library
	// worktree itself.
	Identities []streams.Identity `json:"identities,omitempty"`
	Stream     string             `json:"stream,omitempty"`
	Consumers  []ConsumerResult   `json:"consumers"`
	// Plan states the checks this invocation will run, before it runs them.
	Plan []string `json:"plan,omitempty"`
}

type SkippedCheck struct {
	Check  string
	Reason string
}

type Verification struct {
	// Statement is the sentence every run under a live link must print, so a
	// local result is never mistaken for a published-dependency result.
	Statement string `json:"statement"`
	// ActiveLinks names the links in effect, the published version each
	// replaced, and the content hash verified against, so a result can be tied
	// to an exact library tree after the fact.
	ActiveLinks []string        `json:"active_links"`
	Linked      VerificationRun `json:"linked"`
	// PublishedBaseline is the GOWORK=off build and vet: the pre-landing check
	// proving the consumer still resolves its published dependency.
	PublishedBaseline VerificationRun `json:"published_baseline"`
	Passed            bool            `json:"passed"`
}

type VerificationRun struct {
	Passed  bool     `json:"passed"`
	Command string   `json:"command,omitempty"`
	Details []string `json:"details,omitempty"`
}

type Verifier interface {
	// Verify runs the consumer's lint and tests, constrained to a single
	// worker, with env applied on top of the process environment.
	Verify(ctx context.Context, dir string, env []string) (VerificationRun, error)
	// BuildAndVet runs a build and vet with GOWORK=off, which is the
	// pre-landing check proving the consumer still resolves its *published*
	// dependency.
	BuildAndVet(ctx context.Context, dir string) (VerificationRun, error)
}