specter

package module
v0.0.2 Latest Latest
Warning

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

Go to latest
Published: Aug 29, 2024 License: MIT Imports: 19 Imported by: 1

README

Specter

Go

Specter is a development toolkit in Go that allows you to develop configuration file processors based on HashiCorp Configuration Language (HCL). With Specter, you can define your own Domain-Specific Language (DSL) using HCL and create a processing pipeline to validate, lint, resolve dependencies, and generate code or artifact files from these DSL configuration files.

Features

  • Develop your own DSL using HCL
  • Validate and lint configuration files
  • Resolve dependencies between configuration files
  • Generate code or artifact files from configuration files

Getting Started

To start using Specter, you need to install Go and set up your Go workspace. Then, you can install Specter using the following command:

go get github.com/morebec/specter

Next, you can create a new configuration file processor by defining your DSL in HCL and implementing the processing pipeline. You can find more detailed instructions and examples in the documentation.

Examples

Here are some examples of what you can do with Specter:

Contributions

We welcome contributions to Specter! If you have an idea for a new feature or have found a bug, please open an issue to discuss it. If you want to contribute code, please follow our contribution guidelines and open a pull request.

License

Specter is licensed under the MIT License.

Documentation

Index

Constants

View Source
const DefaultJSONArtifactRegistryFileName = ".specter.json"
View Source
const InvalidHCLErrorCode = "invalid_hcl"
View Source
const LinterResultArtifactID = "_linting_processor_results"
View Source
const LintingErrorCode = "linting_error"
View Source
const ResolvedDependenciesArtifactID = "_resolved_dependencies"
View Source
const (
	// Unknown is used for attributes where the actual type is unknown.
	Unknown = "any"
)
View Source
const UnsupportedSourceErrorCode = "unsupported_source"

UnsupportedSourceErrorCode ErrorSeverity code returned by a SpecificationLoader when a given loader does not support a certain source.

View Source
const WriteFileArtifactsProcessorErrorCode = "write_file_artifacts_processor_error"

Variables

This section is empty.

Functions

func CheckContextDone

func CheckContextDone(ctx context.Context) error

CheckContextDone checks if the context has been canceled or timed out. If the context is done, it returns the context error, which can be either a cancellation error or a deadline exceeded error. If the context is not done, it returns nil.

This function is useful for early exits in long-running or blocking operations when you then to respond to context cancellations in a clean and consistent manner.

func GetContextArtifact

func GetContextArtifact[T Artifact](ctx ProcessingContext, id ArtifactID) T

func MapSpecGroup

func MapSpecGroup[T any](g SpecificationGroup, p func(s Specification) T) []T

MapSpecGroup performs a map operation on a SpecificationGroup

Types

type Artifact

type Artifact interface {
	// ID is a unique identifier of the artifact, which helps in distinguishing and referencing
	// the artifact within a processing context.
	ID() ArtifactID
}

Artifact represents a result or output generated by a SpecificationProcessor. An artifact is a unit of data or information produced as part of the processing workflow. It can be a transient, in-memory object, or it might represent more permanent entities such as files on disk, records in a database, deployment units, or other forms of data artifacts.

type ArtifactID added in v0.0.2

type ArtifactID string

type ArtifactProcessingContext

type ArtifactProcessingContext struct {
	context.Context
	Specifications SpecificationGroup
	Artifacts      []Artifact
	Logger         Logger

	ArtifactRegistry ProcessorArtifactRegistry
	// contains filtered or unexported fields
}

type ArtifactProcessor

type ArtifactProcessor interface {
	// Process performs the processing of artifacts generated by SpecificationProcessor.
	Process(ctx ArtifactProcessingContext) error

	// Name returns the name of this processor.
	Name() string
}

ArtifactProcessor are services responsible for processing artifacts of SpecProcessors.

type ArtifactRegistry

type ArtifactRegistry interface {
	// Load the registry state from persistent storage. If an error occurs, it
	// should be returned to indicate the failure of the loading operation.
	Load() error

	// Save the current state of the registry to persistent storage. If an
	// error occurs, it should be returned to indicate the failure of the saving operation.
	Save() error

	// Add registers an ArtifactID under a specific processor name. This method
	// should ensure that the file path is associated with the given processor name
	// in the registry.
	Add(processorName string, e ArtifactRegistryEntry) error

	// Remove a given ArtifactID artifact registration for a specific processor name. This
	// method should ensure that the file path is disassociated from the given
	// processor name in the registry.
	Remove(processorName string, artifactID ArtifactID) error

	// FindByID finds an entry by its ArtifactID.
	FindByID(processorName string, artifactID ArtifactID) (entry ArtifactRegistryEntry, found bool, err error)

	// FindAll returns all the entries in the registry.
	FindAll(processorName string) ([]ArtifactRegistryEntry, error)
}

ArtifactRegistry provides an interface for managing a registry of artifacts. This registry tracks artifacts generated during processing runs, enabling clean-up in subsequent runs to avoid residual artifacts and maintain a clean slate.

Implementations of the ArtifactRegistry interface must be thread-safe to handle concurrent calls to TrackFile and UntrackFile methods. Multiple goroutines may access the registry simultaneously, so appropriate synchronization mechanisms should be implemented to prevent race conditions and ensure data integrity.

type ArtifactRegistryEntry added in v0.0.2

type ArtifactRegistryEntry struct {
	ArtifactID ArtifactID
	Metadata   map[string]any
}

type AttributeType

type AttributeType string

AttributeType represents the type of attribute

type AttributeValue

type AttributeValue interface {
	String() string
}

type DefaultLogger

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

func NewDefaultLogger

func NewDefaultLogger(c DefaultLoggerConfig) *DefaultLogger

func (*DefaultLogger) Error

func (l *DefaultLogger) Error(msg string)

func (*DefaultLogger) Info

func (l *DefaultLogger) Info(msg string)

func (*DefaultLogger) Log

func (l *DefaultLogger) Log(msg string)

func (*DefaultLogger) Success

func (l *DefaultLogger) Success(msg string)

func (*DefaultLogger) Trace

func (l *DefaultLogger) Trace(msg string)

func (*DefaultLogger) Warning

func (l *DefaultLogger) Warning(msg string)

type DefaultLoggerConfig

type DefaultLoggerConfig struct {
	DisableColors bool
	Writer        io.Writer
}

type DependencyProvider

type DependencyProvider interface {
	Supports(s Specification) bool
	Provide(s Specification) []SpecificationName
}

type DependencyResolutionProcessor

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

func NewDependencyResolutionProcessor

func NewDependencyResolutionProcessor(providers ...DependencyProvider) *DependencyResolutionProcessor

func (DependencyResolutionProcessor) Name

func (DependencyResolutionProcessor) Process

type ExecutionMode

type ExecutionMode string
const FullMode ExecutionMode = "full"

FullMode will cause a Specter instance to be run fully.

const LintMode ExecutionMode = "lint"

LintMode will cause a Specter instance to run until the lint step only.

const PreviewMode ExecutionMode = "preview"

PreviewMode will cause a Specter instance to run until the processing step only, no artifact will be processed.

type FileArtifact

type FileArtifact struct {
	Path      string
	Data      []byte
	FileMode  os.FileMode
	WriteMode WriteMode
}

FileArtifact is a data structure that can be used by a SpecificationProcessor to generate file artifacts that can be written by the FileArtifactProcessor.

func NewDirectoryArtifact added in v0.0.2

func NewDirectoryArtifact(path string, fileMode os.FileMode, writeMode WriteMode) *FileArtifact

func (FileArtifact) ID added in v0.0.2

func (a FileArtifact) ID() ArtifactID

func (FileArtifact) IsDir added in v0.0.2

func (a FileArtifact) IsDir() bool

type FileArtifactProcessor added in v0.0.2

type FileArtifactProcessor struct {
	FileSystem FileSystem
}

FileArtifactProcessor is a processor responsible for writing Artifact referring to files. To perform its work this processor looks at the processing context for any FileArtifact.

func (FileArtifactProcessor) Name added in v0.0.2

func (p FileArtifactProcessor) Name() string

func (FileArtifactProcessor) Process added in v0.0.2

type FileSystem

type FileSystem interface {
	// Abs converts a relative file path to an absolute one. The implementation may
	// differ depending on the underlying file system.
	Abs(location string) (string, error)

	// Rel a relative path that is lexically equivalent to targetPath when joined to basepath with an
	// intervening separator.
	// [Join](basepath, Rel(basepath, targpath)) is equivalent to targpath itself.
	Rel(basePath, targetPath string) (string, error)

	// StatPath returns file information for the specified location. This typically
	// includes details like size, modification time, and whether the path is a file
	// or directory.
	StatPath(location string) (os.FileInfo, error)

	// WalkDir traverses the directory tree rooted at the specified path, calling the
	// provided function for each file or directory encountered. This allows for
	// efficient processing of large directory structures and can handle errors for
	// individual files or directories.
	WalkDir(dirPath string, f func(path string, d fs.DirEntry, err error) error) error

	// ReadFile reads the contents of the specified file and returns it as a byte
	// slice. This method abstracts away the specifics of how the file is accessed,
	// making it easier to work with files across different types of file systems.
	ReadFile(filePath string) ([]byte, error)

	// WriteFile writes data to the specified file path with the given permissions.
	// If the file exists, it will be overwritten.
	WriteFile(path string, data []byte, perm fs.FileMode) error

	// Mkdir creates a new directory at the specified path along with any necessary
	// parents, and returns nil, If the directory already exists, the implementation
	// may either return an error or ignore the request, depending on the file
	// system. This method abstracts the underlying mechanism of directory creation
	// across different file systems.
	Mkdir(dirPath string, mode fs.FileMode) error

	// Remove removes the named file or (empty) directory.
	// If there is an error, it will be of type *PathError.
	Remove(path string) error
}

FileSystem is an abstraction layer over various types of file systems. It provides a unified interface to interact with different file system implementations, whether they are local, remote, or virtual.

Implementations of this interface allow consumers to perform common file system operations such as obtaining absolute paths, retrieving file information, walking through directories, and reading files.

type FileSystemLoader

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

FileSystemLoader is an implementation of a SourceLoader that loads files from a FileSystem.

func NewFileSystemLoader added in v0.0.2

func NewFileSystemLoader(fs FileSystem) *FileSystemLoader

NewFileSystemLoader FileSystem

func NewLocalFileSourceLoader

func NewLocalFileSourceLoader() FileSystemLoader

func (FileSystemLoader) Load

func (l FileSystemLoader) Load(location string) ([]Source, error)

func (FileSystemLoader) Supports

func (l FileSystemLoader) Supports(target string) bool

type GenericSpecAttribute

type GenericSpecAttribute struct {
	Name  string
	Value AttributeValue
}

GenericSpecAttribute represents an attribute of a specification. It relies on cty.Value to represent the loaded value.

type GenericSpecification

type GenericSpecification struct {
	Attributes []GenericSpecAttribute
	// contains filtered or unexported fields
}

GenericSpecification is a generic implementation of a Specification that saves its attributes in a list of attributes for introspection. these can be useful for loaders that are looser in what they allow.

func NewGenericSpecification

func NewGenericSpecification(name SpecificationName, typ SpecificationType, source Source) *GenericSpecification

func (*GenericSpecification) Attribute

func (s *GenericSpecification) Attribute(name string) *GenericSpecAttribute

Attribute returns an attribute by its FilePath or nil if it was not found.

func (*GenericSpecification) Description

func (s *GenericSpecification) Description() string

func (*GenericSpecification) HasAttribute

func (s *GenericSpecification) HasAttribute(name string) bool

HasAttribute indicates if a specification has a certain attribute or not.

func (*GenericSpecification) Name

func (*GenericSpecification) SetSource

func (s *GenericSpecification) SetSource(src Source)

func (*GenericSpecification) Source

func (s *GenericSpecification) Source() Source

func (*GenericSpecification) Type

type GenericValue

type GenericValue struct {
	cty.Value
}

GenericValue represents a generic value that is mostly unknown in terms of type and intent.

func (GenericValue) String

func (d GenericValue) String() string

type HCLFileConfig

type HCLFileConfig interface {
	Specifications() []Specification
}

type HCLGenericSpecLoader

type HCLGenericSpecLoader struct {
	hclparse.Parser
}

HCLGenericSpecLoader this SpecificationLoader loads Specifications as GenericSpecification.

func NewHCLGenericSpecLoader

func NewHCLGenericSpecLoader() *HCLGenericSpecLoader

NewHCLGenericSpecLoader this SpecificationLoader will load all Specifications to instances of GenericSpecification.

func (HCLGenericSpecLoader) Load

func (HCLGenericSpecLoader) SupportsSource

func (l HCLGenericSpecLoader) SupportsSource(s Source) bool

type HCLSpecLoader

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

HCLSpecLoader this loader allows to load Specifications to typed structs by providing a HCLFileConfig.

func NewHCLFileConfigSpecLoader

func NewHCLFileConfigSpecLoader(fileConfigProvider HCLSpecLoaderFileConfigurationProvider) *HCLSpecLoader

func (HCLSpecLoader) Load

func (l HCLSpecLoader) Load(s Source) ([]Specification, error)

func (HCLSpecLoader) SupportsSource

func (l HCLSpecLoader) SupportsSource(s Source) bool

type HCLSpecLoaderFileConfigurationProvider

type HCLSpecLoaderFileConfigurationProvider func() HCLFileConfig

type HCLVariableConfig

type HCLVariableConfig struct {
	Name        string    `hcl:"FilePath,label"`
	Description string    `hcl:"description,optional"`
	Value       cty.Value `hcl:"value"`
}

HCLVariableConfig represents a block configuration that allows defining variables.

type HasDependencies

type HasDependencies interface {
	Specification
	Dependencies() []SpecificationName
}

HasDependencies is an interface that can be implemented by specifications that define their dependencies from their field values. This interface can be used in conjunction with the HasDependenciesProvider to easily resolve dependencies.

type HasDependenciesProvider

type HasDependenciesProvider struct{}

func (HasDependenciesProvider) Provide

func (HasDependenciesProvider) Supports

type HasVersion

type HasVersion interface {
	Specification

	Version() SpecificationVersion
}

type InMemoryArtifactRegistry

type InMemoryArtifactRegistry struct {
	ArtifactMap map[string][]ArtifactRegistryEntry
	// contains filtered or unexported fields
}

func (*InMemoryArtifactRegistry) Add added in v0.0.2

func (*InMemoryArtifactRegistry) FindAll added in v0.0.2

func (r *InMemoryArtifactRegistry) FindAll(processorName string) ([]ArtifactRegistryEntry, error)

func (*InMemoryArtifactRegistry) FindByID added in v0.0.2

func (r *InMemoryArtifactRegistry) FindByID(processorName string, artifactID ArtifactID) (entry ArtifactRegistryEntry, found bool, err error)

func (*InMemoryArtifactRegistry) Load

func (r *InMemoryArtifactRegistry) Load() error

func (*InMemoryArtifactRegistry) Remove added in v0.0.2

func (r *InMemoryArtifactRegistry) Remove(processorName string, artifactID ArtifactID) error

func (*InMemoryArtifactRegistry) Save

func (r *InMemoryArtifactRegistry) Save() error

type JSONArtifactRegistry

type JSONArtifactRegistry struct {
	FileSystem          FileSystem       `json:"-"`
	FilePath            string           `json:"-"`
	CurrentTimeProvider func() time.Time `json:"-"`

	GeneratedAt time.Time                              `json:"generatedAt"`
	Entries     map[string][]JsonArtifactRegistryEntry `json:"entries"`
	// contains filtered or unexported fields
}

JSONArtifactRegistry implementation of a ArtifactRegistry that is saved as a JSON file.

func NewJSONArtifactRegistry

func NewJSONArtifactRegistry(fileName string, fs FileSystem) *JSONArtifactRegistry

NewJSONArtifactRegistry returns a new artifact file registry.

func (*JSONArtifactRegistry) Add added in v0.0.2

func (r *JSONArtifactRegistry) Add(processorName string, e ArtifactRegistryEntry) error

func (*JSONArtifactRegistry) FindAll added in v0.0.2

func (r *JSONArtifactRegistry) FindAll(processorName string) ([]ArtifactRegistryEntry, error)

func (*JSONArtifactRegistry) FindByID added in v0.0.2

func (r *JSONArtifactRegistry) FindByID(processorName string, artifactID ArtifactID) (ArtifactRegistryEntry, bool, error)

func (*JSONArtifactRegistry) Load

func (r *JSONArtifactRegistry) Load() error

func (*JSONArtifactRegistry) Remove added in v0.0.2

func (r *JSONArtifactRegistry) Remove(processorName string, artifactID ArtifactID) error

func (*JSONArtifactRegistry) Save

func (r *JSONArtifactRegistry) Save() error

type JsonArtifactRegistryEntry added in v0.0.2

type JsonArtifactRegistryEntry struct {
	ArtifactID ArtifactID     `json:"artifactId"`
	Metadata   map[string]any `json:"metadata"`
}

type LinterResult

type LinterResult struct {
	Severity LinterResultSeverity
	Message  string
}

type LinterResultSet

type LinterResultSet []LinterResult

LinterResultSet represents a set of LinterResult.

func GetLintingResultsFromContext

func GetLintingResultsFromContext(ctx ProcessingContext) LinterResultSet

func (LinterResultSet) Errors

func (s LinterResultSet) Errors() errors.Group

Errors returns a list of LinterResult as errors.

func (LinterResultSet) HasErrors

func (s LinterResultSet) HasErrors() bool

HasErrors returns if this result set has any result representing an error.

func (LinterResultSet) HasWarnings

func (s LinterResultSet) HasWarnings() bool

HasWarnings returns if this result set has any result representing a warning.

func (LinterResultSet) ID added in v0.0.2

func (s LinterResultSet) ID() ArtifactID

func (LinterResultSet) Warnings

func (s LinterResultSet) Warnings() LinterResultSet

Warnings returns another LinterResultSet with only warnings.

type LinterResultSeverity

type LinterResultSeverity string
const (
	ErrorSeverity   LinterResultSeverity = "error"
	WarningSeverity LinterResultSeverity = "warning"
)

type LintingProcessor

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

func NewLintingProcessor

func NewLintingProcessor(linters ...SpecificationLinter) *LintingProcessor

func (LintingProcessor) Name

func (l LintingProcessor) Name() string

func (LintingProcessor) Process

func (l LintingProcessor) Process(ctx ProcessingContext) (artifacts []Artifact, err error)

type LocalFileSystem

type LocalFileSystem struct{}

LocalFileSystem is an implementation of a FileSystem that works on the local file system where this program is running.

func (LocalFileSystem) Abs

func (l LocalFileSystem) Abs(location string) (string, error)

func (LocalFileSystem) Mkdir

func (l LocalFileSystem) Mkdir(dirPath string, mode fs.FileMode) error

func (LocalFileSystem) ReadFile

func (l LocalFileSystem) ReadFile(filePath string) ([]byte, error)

func (LocalFileSystem) Rel added in v0.0.2

func (l LocalFileSystem) Rel(basePath, targetPath string) (string, error)

func (LocalFileSystem) Remove

func (l LocalFileSystem) Remove(path string) error

func (LocalFileSystem) StatPath

func (l LocalFileSystem) StatPath(location string) (os.FileInfo, error)

func (LocalFileSystem) WalkDir

func (l LocalFileSystem) WalkDir(dirPath string, f func(path string, d fs.DirEntry, err error) error) error

func (LocalFileSystem) WriteFile

func (l LocalFileSystem) WriteFile(path string, data []byte, perm fs.FileMode) error

type Logger

type Logger interface {
	// Trace should only be used for debugging purposes.
	Trace(msg string)

	// Info is used to indicate informative messages.
	Info(msg string)

	// Warning is used to indicate events that could be problematic but that do not constitute errors.
	Warning(msg string)

	// Error is used to indicate that an error has occurred within specter.
	Error(msg string)

	// Success is used to indicate that a given action was performed successfully.
	// This can be used in stdout for example to format specific colors for successful actions as opposed to Info.
	Success(msg string)
}

Logger interface to be used by specter and processors to perform logging. implementations can be made for different scenarios, such as artifactting to a file, stderr, silencing the logger etc. The logger only provides contextual logging.

type NoopArtifactRegistry

type NoopArtifactRegistry struct{}

func (NoopArtifactRegistry) Add added in v0.0.2

func (n NoopArtifactRegistry) Add(processorName string, e ArtifactRegistryEntry) error

func (NoopArtifactRegistry) FindAll added in v0.0.2

func (n NoopArtifactRegistry) FindAll(processorName string) ([]ArtifactRegistryEntry, error)

func (NoopArtifactRegistry) FindByID added in v0.0.2

func (n NoopArtifactRegistry) FindByID(processorName string, artifactID ArtifactID) (_ ArtifactRegistryEntry, _ bool, _ error)

func (NoopArtifactRegistry) Load

func (n NoopArtifactRegistry) Load() error

func (NoopArtifactRegistry) Remove added in v0.0.2

func (n NoopArtifactRegistry) Remove(processorName string, artifactID ArtifactID) error

func (NoopArtifactRegistry) Save

func (n NoopArtifactRegistry) Save() error

type ObjectValue

type ObjectValue struct {
	Type       AttributeType
	Attributes []GenericSpecAttribute
}

ObjectValue represents a type of attribute value that is a nested data structure as opposed to a scalar value.

func (ObjectValue) String

func (o ObjectValue) String() string

type Option

type Option func(s *Specter)

Option represents an option to configure a specter instance.

func WithArtifactProcessors

func WithArtifactProcessors(processors ...ArtifactProcessor) Option

WithArtifactProcessors configures the ArtifactProcessor of a Specter instance.

func WithArtifactRegistry

func WithArtifactRegistry(r ArtifactRegistry) Option

func WithDefaultLogger

func WithDefaultLogger() Option

func WithExecutionMode

func WithExecutionMode(m ExecutionMode) Option

WithExecutionMode configures the ExecutionMode of a Specter instance.

func WithJSONArtifactRegistry added in v0.0.2

func WithJSONArtifactRegistry(fileName string, fs FileSystem) Option

func WithLoaders

func WithLoaders(loaders ...SpecificationLoader) Option

WithLoaders configures the SpecificationLoader of a Specter instance.

func WithLogger

func WithLogger(l Logger) Option

WithLogger configures the Logger of a Specter instance.

func WithProcessors

func WithProcessors(processors ...SpecificationProcessor) Option

WithProcessors configures the SpecProcess of a Specter instance.

func WithSourceLoaders

func WithSourceLoaders(loaders ...SourceLoader) Option

WithSourceLoaders configures the SourceLoader of a Specter instance.

type ProcessingContext

type ProcessingContext struct {
	context.Context
	Specifications SpecificationGroup
	Artifacts      []Artifact
	Logger         Logger
}

func (ProcessingContext) Artifact

func (c ProcessingContext) Artifact(id ArtifactID) Artifact

Artifact returns the artifact associated with a given processor.

type ProcessorArtifactRegistry added in v0.0.2

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

func (ProcessorArtifactRegistry) Add added in v0.0.2

func (n ProcessorArtifactRegistry) Add(artifactID ArtifactID, metadata map[string]any) error

func (ProcessorArtifactRegistry) FindAll added in v0.0.2

func (ProcessorArtifactRegistry) FindByID added in v0.0.2

func (n ProcessorArtifactRegistry) FindByID(artifactID ArtifactID) (_ ArtifactRegistryEntry, _ bool, _ error)

func (ProcessorArtifactRegistry) Remove added in v0.0.2

func (n ProcessorArtifactRegistry) Remove(artifactID ArtifactID) error

type ResolvedDependencies

type ResolvedDependencies SpecificationGroup

ResolvedDependencies represents an ordered list of Specification that should be processed in that specific order to avoid unresolved types.

func GetResolvedDependenciesFromContext

func GetResolvedDependenciesFromContext(ctx ProcessingContext) ResolvedDependencies

func (ResolvedDependencies) ID added in v0.0.2

type RunResult

type RunResult struct {
	Sources       []Source
	Specification []Specification
	Artifacts     []Artifact
	Stats         Stats
}

type Source

type Source struct {
	// Location of the source, this can be a local file or a remote file.
	Location string

	// Data is the raw content of the source.
	Data []byte

	// Format corresponds to the format that was detected for the source.
	Format SourceFormat
}

Source represents the source code that was used to load a given specification.

type SourceFormat

type SourceFormat string

SourceFormat represents the format or syntax of a source.

const (
	HCLSourceFormat SourceFormat = "hcl"
)

type SourceLoader

type SourceLoader interface {
	// Supports indicates if this loader supports a given location.
	// This function should always be called before Load.
	Supports(location string) bool

	// Load will read a source at given location and return a Source object representing the bytes read.
	// Implementations of this function can take for granted that this loader supports the given location.
	// Therefore, the Supports method should always be called on the location before it can be passed to the Load method.
	Load(location string) ([]Source, error)
}

SourceLoader are services responsible for loading sources from specific locations These could be a file system, or a database for example.

type Specification

type Specification interface {
	// Name returns the unique Name of this specification.
	Name() SpecificationName

	// Type returns the type of this specification.
	Type() SpecificationType

	// Description of this specification.
	Description() string

	// Source returns the source of this specification.
	Source() Source

	// SetSource sets the source of the specification.
	// This method should only be used by loaders.
	SetSource(s Source)
}

Specification is a general purpose data structure to represent a specification as loaded from a file regardless of the loader used. It is the responsibility of the application using specter to convert a specification to an appropriate data structure representing the intent of a given Specification.

type SpecificationGroup

type SpecificationGroup []Specification

SpecificationGroup Represents a list of Specification.

func NewSpecGroup

func NewSpecGroup(s ...Specification) SpecificationGroup

func (SpecificationGroup) Exclude

func (SpecificationGroup) ExcludeNames

func (g SpecificationGroup) ExcludeNames(names ...SpecificationName) SpecificationGroup

func (SpecificationGroup) ExcludeType

func (SpecificationGroup) Merge

Merge Allows merging a group with another one.

func (SpecificationGroup) Select

Select allows filtering the group for certain specifications.

func (SpecificationGroup) SelectName

func (SpecificationGroup) SelectNames

func (SpecificationGroup) SelectType

type SpecificationLinter

type SpecificationLinter interface {
	Lint(specifications SpecificationGroup) LinterResultSet
}

SpecificationLinter represents a function responsible for linting specifications.

func HasVersionMustHaveAVersionLinter

func HasVersionMustHaveAVersionLinter(severity LinterResultSeverity) SpecificationLinter

type SpecificationLinterFunc

type SpecificationLinterFunc func(specifications SpecificationGroup) LinterResultSet

SpecificationLinterFunc implementation of a SpecificationLinter that relies on a func

func CompositeSpecificationLinter

func CompositeSpecificationLinter(linters ...SpecificationLinter) SpecificationLinterFunc

CompositeSpecificationLinter A Composite linter is responsible for running multiple linters as one.

func SpecificationMustNotHaveUndefinedNames

func SpecificationMustNotHaveUndefinedNames(severity LinterResultSeverity) SpecificationLinterFunc

SpecificationMustNotHaveUndefinedNames ensures that no specification has an undefined name

func SpecificationsDescriptionsMustEndWithPeriod

func SpecificationsDescriptionsMustEndWithPeriod(severity LinterResultSeverity) SpecificationLinterFunc

SpecificationsDescriptionsMustEndWithPeriod ensures that specification descriptions end with a period.

func SpecificationsDescriptionsMustStartWithACapitalLetter

func SpecificationsDescriptionsMustStartWithACapitalLetter(severity LinterResultSeverity) SpecificationLinterFunc

SpecificationsDescriptionsMustStartWithACapitalLetter ensures that specification descriptions start with a capital letter.

func SpecificationsMustHaveDescriptionAttribute

func SpecificationsMustHaveDescriptionAttribute(severity LinterResultSeverity) SpecificationLinterFunc

SpecificationsMustHaveDescriptionAttribute ensures that all specifications have a description.

func SpecificationsMustHaveUniqueNames

func SpecificationsMustHaveUniqueNames(severity LinterResultSeverity) SpecificationLinterFunc

SpecificationsMustHaveUniqueNames ensures that names are unique amongst specifications.

func (SpecificationLinterFunc) Lint

type SpecificationLoader

type SpecificationLoader interface {
	// Load loads a slice of Specification from a Source, or returns an error if it encountered a failure.
	Load(s Source) ([]Specification, error)

	// SupportsSource indicates if this loader supports a certain source or not.
	SupportsSource(s Source) bool
}

SpecificationLoader is a service responsible for loading Specifications from Sources.

type SpecificationName

type SpecificationName string
const UndefinedSpecificationName SpecificationName = ""

UndefinedSpecificationName constant used to test against undefined SpecificationName.

type SpecificationProcessor

type SpecificationProcessor interface {
	// Name returns the unique name of this processor.
	// This name can appear in logs to report information about a given processor.
	Name() string

	// Process processes a group of specifications.
	Process(ctx ProcessingContext) ([]Artifact, error)
}

SpecificationProcessor are services responsible for performing work using Specifications and which can possibly generate artifacts.

type SpecificationType

type SpecificationType string

type SpecificationVersion

type SpecificationVersion string

type Specter

type Specter struct {
	SourceLoaders      []SourceLoader
	Loaders            []SpecificationLoader
	Processors         []SpecificationProcessor
	ArtifactProcessors []ArtifactProcessor
	ArtifactRegistry   ArtifactRegistry
	Logger             Logger
	ExecutionMode      ExecutionMode
}

Specter is the service responsible to run a specter pipeline.

func New

func New(opts ...Option) *Specter

New allows creating a new specter instance using the provided options.

func (Specter) LoadSources

func (s Specter) LoadSources(ctx context.Context, sourceLocations []string) ([]Source, error)

LoadSources only performs the Load sources step.

func (Specter) LoadSpecifications

func (s Specter) LoadSpecifications(ctx context.Context, sources []Source) ([]Specification, error)

LoadSpecifications performs the loading of Specifications.

func (Specter) ProcessArtifacts

func (s Specter) ProcessArtifacts(ctx context.Context, specifications []Specification, artifacts []Artifact) error

ProcessArtifacts sends a list of ProcessingArtifacts to the registered ArtifactProcessors.

func (Specter) ProcessSpecifications

func (s Specter) ProcessSpecifications(ctx context.Context, specs []Specification) ([]Artifact, error)

ProcessSpecifications sends the specifications to processors.

func (Specter) Run

func (s Specter) Run(ctx context.Context, sourceLocations []string) (RunResult, error)

Run the pipeline from start to finish.

type Stats

type Stats struct {
	StartedAt         time.Time
	EndedAt           time.Time
	NbSourceLocations int
	NbSources         int
	NbSpecifications  int
	NbArtifacts       int
}

func (Stats) ExecutionTime

func (s Stats) ExecutionTime() time.Duration

type WriteMode added in v0.0.2

type WriteMode string
const (
	// RecreateMode mode indicating that the artifact should be recreated on every run.
	RecreateMode WriteMode = "RECREATE"

	// WriteOnceMode is used to indicate that a file should be created only once, and not be recreated for subsequent
	// executions of the processing. This can be useful in situations where scaffolding is required.
	WriteOnceMode WriteMode = "WRITE_ONCE"
)
const DefaultWriteMode WriteMode = WriteOnceMode

Jump to

Keyboard shortcuts

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