source

Documentation

Overview

Package source provides implementations of mutate.SourceProvider — objects that can hand the Mutator a source tree, commit message, and commit metadata for a given git SHA.

v0.1 implementations:

• GitSource: backed by go-git; HEAD-only. Future versions add --since support via temp worktrees.
• DirSource: trivial filesystem-only source. Useful for tests and for analyzing directories that aren't git repositories.

Index

• type DirSource
  • func OpenDir(dir string) (*DirSource, error)
  • func (d *DirSource) CheckoutSource(_ context.Context, sourceSha string) (string, func() error, error)
  • func (d *DirSource) CommitMessage(_ context.Context, _ string) (string, error)
  • func (d *DirSource) CommitMeta(_ context.Context, _ string) (string, int64, error)
  • func (d *DirSource) HeadSha() (string, error)
  • func (d *DirSource) Parents(_ context.Context, _ string) ([]string, error)
  • func (d *DirSource) RepoID(alias string) (string, error)
• type GitSource
  • func OpenGit(repoPath string) (*GitSource, error)
  • func (s *GitSource) CheckoutSource(ctx context.Context, sourceSha string) (string, func() error, error)
  • func (s *GitSource) CommitMessage(_ context.Context, sourceSha string) (string, error)
  • func (s *GitSource) CommitMeta(_ context.Context, sourceSha string) (string, int64, error)
  • func (s *GitSource) HeadSha() (string, error)
  • func (s *GitSource) Parents(_ context.Context, sourceSha string) ([]string, error)
  • func (s *GitSource) RepoID(alias string) (string, error)
  • func (s *GitSource) WalkCommitsTopo(ctx context.Context, from string, fromInclusive bool) ([]string, error)

Types

type DirSource

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

DirSource is a trivial source provider for directories that aren't git repos (or for tests). The "source SHA" is a content hash of the directory's logical name; messages and authors are empty.

func OpenDir

func OpenDir(dir string) (*DirSource, error)

OpenDir wraps an arbitrary directory. The source SHA is derived from dir + current modtime so distinct analyzes accumulate distinct KCs.

func (*DirSource) CheckoutSource

func (d *DirSource) CheckoutSource(_ context.Context, sourceSha string) (string, func() error, error)

func (*DirSource) CommitMessage

func (d *DirSource) CommitMessage(_ context.Context, _ string) (string, error)

func (*DirSource) CommitMeta

func (d *DirSource) CommitMeta(_ context.Context, _ string) (string, int64, error)

func (*DirSource) HeadSha

func (d *DirSource) HeadSha() (string, error)

func (*DirSource) Parents

func (d *DirSource) Parents(_ context.Context, _ string) ([]string, error)

func (*DirSource) RepoID

func (d *DirSource) RepoID(alias string) (string, error)

type GitSource

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

GitSource implements mutate.SourceProvider for a directory that is a git repository. v0.1 only supports HEAD-only analysis (and analyze of the SHA that is currently HEAD); --since walking will land in v0.1.x when temp-worktree checkout is implemented.

func OpenGit

func OpenGit(repoPath string) (*GitSource, error)

OpenGit opens the git repo at repoPath.

func (*GitSource) CheckoutSource

func (s *GitSource) CheckoutSource(ctx context.Context, sourceSha string) (string, func() error, error)

CheckoutSource implements mutate.SourceProvider.

If sourceSha == HEAD, returns the repo path directly (no checkout). Otherwise, creates a temporary `git worktree` at sourceSha and returns its path. The cleanup func tears the worktree down and prunes it.

Errors if sourceSha doesn't exist in the source repo.

func (*GitSource) CommitMessage

func (s *GitSource) CommitMessage(_ context.Context, sourceSha string) (string, error)

CommitMessage returns the commit's message body.

func (*GitSource) CommitMeta

func (s *GitSource) CommitMeta(_ context.Context, sourceSha string) (string, int64, error)

CommitMeta returns the author "name <email>" and unix timestamp.

func (*GitSource) HeadSha

func (s *GitSource) HeadSha() (string, error)

HeadSha returns the current HEAD commit SHA.

func (*GitSource) Parents

func (s *GitSource) Parents(_ context.Context, sourceSha string) ([]string, error)

Parents returns the source-repo git parent SHAs of sourceSha. Implements pipeline.CommitGraph.

func (*GitSource) RepoID

func (s *GitSource) RepoID(alias string) (string, error)

RepoID returns a stable per-repo identifier following FOUNDATION §6.2. Resolution order: explicit alias (handled by caller) > remote origin slug > root commit fallback.

func (*GitSource) WalkCommitsTopo

func (s *GitSource) WalkCommitsTopo(ctx context.Context, from string, fromInclusive bool) ([]string, error)

WalkCommitsTopo returns the source SHAs from `from` (exclusive if fromInclusive=false) up to HEAD, in topological order with chronological tiebreaker (oldest first), per ADR-001 §C3.

from may be:

• "" or "root": all commits reachable from HEAD
• a ref name (e.g., "main", "v1.0")
• a commit SHA
• a date in YYYY-MM-DD or RFC3339 format

fromInclusive: include the boundary commit itself in the result.