execscope

package
v0.3.0 Latest Latest
Warning

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

Go to latest
Published: Oct 14, 2026 License: MIT Imports: 20 Imported by: 0

Documentation

Overview

Package execscope derives bounded write scopes without executing the user's program.

Index

Constants

View Source
const Budget = 200 * time.Millisecond
View Source
const ListingLimit = 4096
View Source
const SourceLimit = 1 << 20

Variables

This section is empty.

Functions

func GoFormatterWrites

func GoFormatterWrites(identity string, args []string) bool

execGoFormatterWrites is shared by capture and display-only segment tracking. GoFormatterWrites identifies formatter invocations whose write segment determines a preview lifetime.

func ReadSource

func ReadSource(input Interpreter) (source, script, reason string)

execProgramSource selects literal eval/stdin/script input without evaluating it.

Types

type BindingState

type BindingState struct {
	Paths    map[string][]string
	Segments map[string][]string
	Aliases  map[string]string
}

BindingState holds syntax-derived candidates. Preview consumers rebind them in statement order; they never represent values obtained by running a program.

type Bindings

type Bindings struct {
	// contains filtered or unexported fields
}

Bindings shares source path derivation with ordered literal previews. Each instance belongs to one parse tree and one consumer.

func NewBindings

func NewBindings(input SourceInput) *Bindings

func (*Bindings) Analyze

func (b *Bindings) Analyze(node *sitter.Node) SourceResult

func (*Bindings) Literal

func (b *Bindings) Literal(node *sitter.Node) (string, bool)

func (*Bindings) Paths

func (b *Bindings) Paths(node *sitter.Node) []string

func (*Bindings) Segments

func (b *Bindings) Segments(node *sitter.Node) []string

func (*Bindings) State

func (b *Bindings) State() *BindingState

func (*Bindings) Text

func (b *Bindings) Text(node *sitter.Node) string

type ChangeResolution

type ChangeResolution struct {
	Paths            []string
	InvalidArguments bool
}

type ChangeResolver

type ChangeResolver func(arguments []string, directory string, deadline time.Time) ChangeResolution

ChangeResolver resolves literal mutation arguments in the selected directory. InvalidArguments distinguishes parser rejection from unavailable retained paths.

type Class

type Class int

Class orders how much of a command's file effect is known statically. A program takes the most open class of its statements.

const (
	Neutral Class = iota
	Declared
	Scoped
	Opaque
)

func (Class) String

func (c Class) String() string

type Entry

type Entry struct {
	Origin   string `json:",omitempty"`
	Kind     Kind
	Operands []Operand
	Dest     string `json:",omitempty"`
	// DestDir forces directory semantics (-t, or several sources).
	DestDir bool `json:",omitzero"`
	// NoTarget forbids directory semantics (-T).
	NoTarget      bool `json:",omitzero"`
	NoDereference bool `json:",omitzero"`
	// Recursive maps whole source trees to the destination.
	Recursive bool `json:",omitzero"`
	// Sources marks sources as changed too (mv).
	Sources bool `json:",omitzero"`
	// Copies marks targets that receive their source's content (cp, install).
	Copies bool `json:",omitzero"`
	// Backup adds DEST~ style backups written by -b.
	Backup string `json:",omitempty"`
	// Through marks writes that follow an existing symlink to its target.
	Through bool `json:",omitzero"`
}

Entry is one statically derived part of a command's write scope. Destinations depend on filesystem state, so they resolve at capture time.

type Input

type Input struct {
	Command      string
	Directory    string
	Shell        string
	Deadline     time.Time
	Changes      ChangeResolver
	AuthoredOnly bool
}

Input carries the execution metadata selected by the request.

type Interpreter

type Interpreter struct {
	Identity  string
	Arguments []string
	Directory string
	Stdin     string
}

Interpreter names literal interpreter input. Source files are read only within SourceLimit.

type Kind

type Kind string
const (
	// File captures each operand path itself.
	File Kind = "file"
	// Tree captures each operand, and every file below it when it is
	// a directory.
	Tree Kind = "tree"
	// Into resolves coreutils destination rules at capture time:
	// each source maps to Dest, or to Dest/basename(source) when Dest is a
	// directory.
	Into Kind = "into"
)

type Operand

type Operand struct {
	Path          string
	Glob          bool `json:",omitzero"`
	AbsoluteInput bool `json:",omitzero"`
}

Operand is an absolute path, or a shell glob expanded read-only at capture time.

type Program

type Program struct {
	Label string
	// Direct marks statements whose targets and content the agent chose:
	// interpreter programs, inline shell, and file operations with operands
	// only known at run time. Other programs are tool-managed.
	Direct bool `json:",omitzero"`
	// VCS marks invocations that may import or discard working-tree content.
	VCS bool `json:",omitzero"`
}

Program names an undeclared statement for effect attribution.

type Result

type Result struct {
	Class  Class
	Labels []string
	Scope  []Entry
	Reason string
	// Programs are the statements whose effects are not derived, in order.
	Programs []Program
}

func Classify

func Classify(input Input) Result

Classify keeps unknown effects distinct from known write operands.

func StatementIntent

func StatementIntent(statement *syntax.Stmt) Result

StatementIntent derives only explicit rm/mv/sed operands for display. It neither resolves filesystem metadata nor claims observed execution effects.

type SourceInput

type SourceInput struct {
	Source       []byte
	Script       string
	Directory    string
	Deadline     time.Time
	Python       bool
	IntentOnly   bool
	TemporaryEnv map[string]string
}

SourceInput selects syntax and bounds. IntentOnly forbids file/provider reads.

type SourceResult

type SourceResult struct {
	Scope      []Entry
	Writes     bool
	Unresolved bool
}

Jump to

Keyboard shortcuts

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