Documentation
¶
Overview ¶
Package application contains the example-function harvesting use case: reading a module's zip from the blob store, scanning _test.go files for Example* functions, extracting their bodies and output comments via the Go AST, and persisting an ExampleRecord.
The use case depends on domain types and port interfaces only. It has no knowledge of SQLite or filesystem mechanics.
No fetched code is executed. All extraction operates on source as inert text. Extraction is downstream of fetch: a module must have a FactRecord before its examples can be harvested.
Index ¶
- Constants
- Variables
- type Config
- type ExtractExampleUseCase
- type ExtractRequest
- type ExtractResult
- type QueryExamplesUseCase
- func (uc *QueryExamplesUseCase) ExampleHistory(ctx context.Context, coord coordinate.ModuleCoordinate, pipelineVersion string) ([]domain.ExampleRecord, error)
- func (uc *QueryExamplesUseCase) FindBySymbol(ctx context.Context, symbol, pipelineVersion string, ...) ([]exampleports.ExampleRef, error)
- func (uc *QueryExamplesUseCase) FindBySymbolInModule(ctx context.Context, coord coordinate.ModuleCoordinate, ...) ([]exampleports.ExampleRef, error)
- func (uc *QueryExamplesUseCase) GetExampleRecord(ctx context.Context, coord coordinate.ModuleCoordinate, pipelineVersion string) (domain.ExampleRecord, bool, error)
- func (uc *QueryExamplesUseCase) ListExampleRecords(ctx context.Context, filter exampleports.ExampleFilter) ([]exampleports.ExampleSummary, error)
- func (uc *QueryExamplesUseCase) PipelinesHeld(ctx context.Context, coord coordinate.ModuleCoordinate) ([]string, error)
Constants ¶
const PipelineVersion = "0.3.0"
PipelineVersion identifies this release of the example extraction pipeline. Bump this constant whenever extraction logic changes to ensure old records are not confused with new ones.
Variables ¶
var ErrNoExampleHistory = errors.New("this example store keeps no generation history")
ErrNoExampleHistory is returned by ExampleHistory when the configured store cannot produce one. It is not "there is no history": it says the store this build was wired with does not keep generations, which is a different answer from a module that has only ever been extracted once.
var ErrNoPipelineListing = errors.New("this example store cannot list the pipelines a coordinate is held at")
ErrNoPipelineListing is returned by PipelinesHeld when the configured store cannot list the pipelines a coordinate is held at.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
Facts fetchports.FactStore
Blobs fetchports.BlobStore
Examples ports.ExampleStore
Parser ports.ExampleParser
Clock fetchports.Clock
Stopwatch fetchports.Stopwatch
PipelineVersion string // defaults to PipelineVersion constant
Logger *slog.Logger
}
Config holds all construction parameters for ExtractExampleUseCase.
type ExtractExampleUseCase ¶
type ExtractExampleUseCase struct {
// contains filtered or unexported fields
}
ExtractExampleUseCase harvests Example* functions from a module's _test.go files and persists an ExampleRecord.
func NewExtractExampleUseCase ¶
func NewExtractExampleUseCase(cfg Config) *ExtractExampleUseCase
NewExtractExampleUseCase constructs an ExtractExampleUseCase from a Config.
func (*ExtractExampleUseCase) Execute ¶
func (uc *ExtractExampleUseCase) Execute(ctx context.Context, req ExtractRequest) (_ ExtractResult, retErr error)
Execute runs the example extraction pipeline for the given module.
The module must have been fetched first. If not, ErrModuleNotFetched is returned.
Extraction failures (unreadable zip, zip parse errors) are recorded in the ExampleRecord with status ExtractionFailed — they do not make Execute return an error. Only infrastructure errors (store access, blob I/O) return errors.
func (*ExtractExampleUseCase) WithAudit ¶
func (uc *ExtractExampleUseCase) WithAudit(sink ports.AuditSink) *ExtractExampleUseCase
WithAudit wires an audit sink so extraction appends one examples_extracted event per persisted generation. It is optional — a nil sink (the default) disables emission — and returns the receiver for chaining, mirroring the other stages' optional-dependency builders.
type ExtractRequest ¶
type ExtractRequest struct {
Coordinate coordinate.ModuleCoordinate
// Force re-extracts even if a record for this pipeline version exists.
Force bool
}
ExtractRequest is the input to Execute.
type ExtractResult ¶
type ExtractResult struct {
Record domain2.ExampleRecord
FromCache bool
// Reused says the extraction ran and came back identical to a generation the
// ledger already holds, so nothing was appended and Record is that held
// generation.
//
// It is deliberately not FromCache. A cache hit means no extraction happened;
// this means one did, and its result was already recorded. Reporting them as
// one fact would tell a reader chasing a stale answer that the tree was never
// read, when it was.
Reused bool
}
ExtractResult is the output of Execute.
type QueryExamplesUseCase ¶
type QueryExamplesUseCase struct {
// contains filtered or unexported fields
}
QueryExamplesUseCase provides read-only access to stored example records.
Every method that takes a pipeline version reads PipelineVersion when given an empty one.
func NewQueryExamplesUseCase ¶
func NewQueryExamplesUseCase(store exampleports.ExampleStore) *QueryExamplesUseCase
NewQueryExamplesUseCase constructs a QueryExamplesUseCase.
func (*QueryExamplesUseCase) ExampleHistory ¶
func (uc *QueryExamplesUseCase) ExampleHistory(ctx context.Context, coord coordinate.ModuleCoordinate, pipelineVersion string) ([]domain.ExampleRecord, error)
ExampleHistory returns every generation the ledger holds for a coordinate, in the order they were appended, oldest first.
This is the read that an overwriting store could not answer. The composed record says what is found now; this says what was found before, each entry naming the artefact it was computed from.
func (*QueryExamplesUseCase) FindBySymbol ¶
func (uc *QueryExamplesUseCase) FindBySymbol(ctx context.Context, symbol, pipelineVersion string, scope coordinate.ModuleSet) ([]exampleports.ExampleRef, error)
FindBySymbol returns all examples associated with the given symbol, restricted to the modules in scope (the zero ModuleSet imposes no restriction).
func (*QueryExamplesUseCase) FindBySymbolInModule ¶
func (uc *QueryExamplesUseCase) FindBySymbolInModule(ctx context.Context, coord coordinate.ModuleCoordinate, symbol, pipelineVersion string) ([]exampleports.ExampleRef, error)
FindBySymbolInModule returns examples for a symbol scoped to a specific module@version.
func (*QueryExamplesUseCase) GetExampleRecord ¶
func (uc *QueryExamplesUseCase) GetExampleRecord(ctx context.Context, coord coordinate.ModuleCoordinate, pipelineVersion string) (domain.ExampleRecord, bool, error)
GetExampleRecord retrieves the example record for a module coordinate.
func (*QueryExamplesUseCase) ListExampleRecords ¶
func (uc *QueryExamplesUseCase) ListExampleRecords(ctx context.Context, filter exampleports.ExampleFilter) ([]exampleports.ExampleSummary, error)
ListExampleRecords returns summaries matching the given filter.
func (*QueryExamplesUseCase) PipelinesHeld ¶
func (uc *QueryExamplesUseCase) PipelinesHeld(ctx context.Context, coord coordinate.ModuleCoordinate) ([]string, error)
PipelinesHeld returns the pipeline versions the ledger holds coord at, oldest first.
Source Files