source

Documentation

Overview

Package source defines the Source abstraction over scan targets (ARCHITECTURE.md §7): a Source couples a Walker (push-style, ignore-aware enumeration feeding phase 1), a Resolver (pull-style access for phase-2 project detectors), content identity (image digest, git HEAD, dir realpath), layer IDs for blob-cache granularity, and SourceInfo provenance.

The interface is shaped by the WORST source — a squashed OCI tar stream: sequential, non-seekable, consume-during-walk; the directory case is the easy specialization. Concrete implementations live in the dirsource, gitsource, imagesource, and k8ssource subpackages. One resolver abstraction keeps every detector — including third-party — automatically source-agnostic.

Index

• type Entry
• type Info
• type Kind
• type ReaderAtCloser
• type Resolver
• type Source
• type TargetKind
  • func DetectTarget(target string) (TargetKind, string, error)
• type Unknown
• type WalkFunc
• type WalkStats

Types

type Entry

type Entry struct {
	Ref      classify.FileRef
	Open     func() (io.ReadCloser, error)
	ReaderAt func() (ReaderAtCloser, error)
}

Entry is one enumerated file: classified identity plus lazy content access. For dir sources Open is reusable and ReaderAt is available; for stream sources Open is one-shot (spool-backed) and ReaderAt is nil.

type Info

type Info struct {
	Kind   Kind
	Target string
}

Info is the provenance root for a scan's output (§7). Phase 6 sources extend it with git/image/k8s fields.

type Kind

type Kind string

Kind identifies a source implementation (ARCHITECTURE.md §7).

const (
	KindDir   Kind = "dir"
	KindRepo  Kind = "repo"
	KindImage Kind = "image"
	KindK8s   Kind = "k8s"
)

The four §7 source kinds. Dir is implemented in Phase 4; repo, image, and k8s land in Phase 6 (repo delegates to dir after a shallow clone).

type ReaderAtCloser

type ReaderAtCloser interface {
	io.ReaderAt
	io.Closer
}

ReaderAtCloser is random access with explicit ownership: whoever obtains one closes it.

type Resolver

type Resolver interface {
	FilesByGlob(ctx context.Context, patterns ...string) ([]classify.FileRef, error)
	Open(path string) (io.ReadCloser, error)
	Stat(path string) (classify.FileRef, error)
}

Resolver is the pull-side file query API (§6.1, §7). Paths are source-root-relative with forward slashes. Implementations honor the same ignore rules as Walk.

type Source

type Source interface {
	Name() string
	Kind() Kind
	// ID is the source's content identity (dir realpath; later: image
	// digest, git HEAD) — a cache-key ingredient.
	ID() string
	// Walk streams entries (ignore-aware, files only). It returns after
	// every callback has returned; walk-level failures are recorded as
	// Unknowns, not errors (P6) — the returned error is reserved for
	// cancellation and catastrophic source failure.
	Walk(ctx context.Context, fn WalkFunc) error
	// WalkUnknowns returns the walk-level Unknown records accumulated by
	// the most recent Walk. Valid after Walk returns.
	WalkUnknowns() []Unknown
	// WalkStats returns the most recent Walk's exclusion accounting: what the
	// walk deliberately did not enumerate. Sources with no ignore rules
	// (image archives, rendered manifests) return the zero value, which is
	// the honest answer: nothing was excluded.
	WalkStats() WalkStats
	// Resolver is the pull-style query API for phase-2 project detectors.
	Resolver() Resolver
	Info() Info
	Close() error
}

Source is the engine-facing contract every acquisition implements (§7).

type TargetKind

type TargetKind string

TargetKind is the result of `airom scan` scheme auto-detection (docs/cli.md). It is deliberately narrower than the full set of source implementations: k8s has its own command and never comes through Detect.

const (
	TargetDir   TargetKind = "dir"
	TargetRepo  TargetKind = "repo"
	TargetImage TargetKind = "image"
)

The three kinds `airom scan` can auto-detect (docs/cli.md).

func DetectTarget

func DetectTarget(target string) (TargetKind, string, error)

DetectTarget implements the `airom scan` scheme auto-detection order from docs/cli.md:

1. Explicit prefix (dir:, repo:, image:) forces the kind.
2. An existing local path is a filesystem scan.
3. A git-shaped URL is a repo scan.
4. Anything else is treated as an image reference.

It returns the detected kind and the target with any forcing prefix stripped.

type Unknown

type Unknown struct {
	Path   string
	Stage  string // "walk", "stat", ...
	Reason string
}

Unknown records a file or directory the walk could not fully process (permission denied, races, IO errors) — surfaced in the output, never silently dropped (invariant P6).

type WalkFunc

type WalkFunc func(Entry) error

WalkFunc receives entries during a streaming walk. Returning an error aborts the walk with that error. The callback may be invoked from multiple goroutines (fastwalk); the engine's task channel serializes downstream.

type WalkStats

type WalkStats struct {
	FilesIgnored int64
	DirsPruned   int64
}

WalkStats is a Walk's exclusion accounting, feeding the scan assurance block (ScanStats): FilesIgnored counts files the ignore rules excluded; DirsPruned counts directories excluded whole, whose contents were never enumerated — one line per directory, because the walker cannot count what it never listed.