hercules.v9: gopkg.in/src-d/hercules.v9/internal/core Index | Files

package core

import "gopkg.in/src-d/hercules.v9/internal/core"


Package Files

forks.go pipeline.go registry.go


const (
    // ConfigPipelineDAGPath is the name of the Pipeline configuration option (Pipeline.Initialize())
    // which enables saving the items DAG to the specified file.
    ConfigPipelineDAGPath = "Pipeline.DAGPath"
    // ConfigPipelineDryRun is the name of the Pipeline configuration option (Pipeline.Initialize())
    // which disables Configure() and Initialize() invocation on each PipelineItem during the
    // Pipeline initialization.
    // Subsequent Run() calls are going to fail. Useful with ConfigPipelineDAGPath=true.
    ConfigPipelineDryRun = "Pipeline.DryRun"
    // ConfigPipelineCommits is the name of the Pipeline configuration option (Pipeline.Initialize())
    // which allows to specify the custom commit sequence. By default, Pipeline.Commits() is used.
    ConfigPipelineCommits = "Pipeline.Commits"
    // ConfigPipelineDumpPlan is the name of the Pipeline configuration option (Pipeline.Initialize())
    // which outputs the execution plan to stderr.
    ConfigPipelineDumpPlan = "Pipeline.DumpPlan"
    // ConfigPipelineHibernationDistance is the name of the Pipeline configuration option (Pipeline.Initialize())
    // which is the minimum number of actions between two sequential usages of
    // a branch to activate the hibernation optimization (cpu-memory trade-off). 0 disables.
    ConfigPipelineHibernationDistance = "Pipeline.HibernationDistance"
    // ConfigPipelinePrintActions is the name of the Pipeline configuration option (Pipeline.Initialize())
    // which enables printing the taken actions of the execution plan to stderr.
    ConfigPipelinePrintActions = "Pipeline.PrintActions"
    // DependencyCommit is the name of one of the three items in `deps` supplied to PipelineItem.Consume()
    // which always exists. It corresponds to the currently analyzed commit.
    DependencyCommit = "commit"
    // DependencyIndex is the name of one of the three items in `deps` supplied to PipelineItem.Consume()
    // which always exists. It corresponds to the currently analyzed commit's index.
    DependencyIndex = "index"
    // DependencyIsMerge is the name of one of the three items in `deps` supplied to PipelineItem.Consume()
    // which always exists. It indicates whether the analyzed commit is a merge commit.
    // Checking the number of parents is not correct - we remove the back edges during the DAG simplification.
    DependencyIsMerge = "is_merge"
    // MessageFinalize is the status text reported before calling LeafPipelineItem.Finalize()-s.
    MessageFinalize = "finalize"


var Registry = &PipelineItemRegistry{
    provided:     map[string][]reflect.Type{},
    registered:   map[string]reflect.Type{},
    flags:        map[string]reflect.Type{},
    featureFlags: arrayFeatureFlags{Flags: []string{}, Choices: map[string]bool{}},

Registry contains all known pipeline item types.

func EnablePathFlagTypeMasquerade Uses

func EnablePathFlagTypeMasquerade()

EnablePathFlagTypeMasquerade changes the type of all "path" command line arguments from "string" to "path". This operation cannot be canceled and is intended to be used for better --help output.

func LoadCommitsFromFile Uses

func LoadCommitsFromFile(path string, repository *git.Repository) ([]*object.Commit, error)

LoadCommitsFromFile reads the file by the specified FS path and generates the sequence of commits by interpreting each line as a Git commit hash.

func PathifyFlagValue Uses

func PathifyFlagValue(flag *pflag.Flag)

PathifyFlagValue changes the type of a string command line argument to "path".

type CommonAnalysisResult Uses

type CommonAnalysisResult struct {
    // BeginTime is the time of the first commit in the analysed sequence.
    BeginTime int64
    // EndTime is the time of the last commit in the analysed sequence.
    EndTime int64
    // CommitsNumber is the number of commits in the analysed sequence.
    CommitsNumber int
    // RunTime is the duration of Pipeline.Run().
    RunTime time.Duration
    // RunTimePerItem is the time elapsed by each PipelineItem.
    RunTimePerItem map[string]float64

CommonAnalysisResult holds the information which is always extracted at Pipeline.Run().

func MetadataToCommonAnalysisResult Uses

func MetadataToCommonAnalysisResult(meta *Metadata) *CommonAnalysisResult

MetadataToCommonAnalysisResult copies the data from a Protobuf message.

func (*CommonAnalysisResult) BeginTimeAsTime Uses

func (car *CommonAnalysisResult) BeginTimeAsTime() time.Time

BeginTimeAsTime converts the UNIX timestamp of the beginning to Go time.

func (CommonAnalysisResult) Copy Uses

func (car CommonAnalysisResult) Copy() CommonAnalysisResult

Copy produces a deep clone of the object.

func (*CommonAnalysisResult) EndTimeAsTime Uses

func (car *CommonAnalysisResult) EndTimeAsTime() time.Time

EndTimeAsTime converts the UNIX timestamp of the ending to Go time.

func (*CommonAnalysisResult) FillMetadata Uses

func (car *CommonAnalysisResult) FillMetadata(meta *pb.Metadata) *pb.Metadata

FillMetadata copies the data to a Protobuf message.

func (*CommonAnalysisResult) Merge Uses

func (car *CommonAnalysisResult) Merge(other *CommonAnalysisResult)

Merge combines the CommonAnalysisResult with an other one. We choose the earlier BeginTime, the later EndTime, sum the number of commits and the elapsed run times.

type ConfigurationOption Uses

type ConfigurationOption struct {
    // Name identifies the configuration option in facts.
    Name string
    // Description represents the help text about the configuration option.
    Description string
    // Flag corresponds to the CLI token with "--" prepended.
    Flag string
    // Type specifies the kind of the configuration option's value.
    Type ConfigurationOptionType
    // Default is the initial value of the configuration option.
    Default interface{}

ConfigurationOption allows for the unified, retrospective way to setup PipelineItem-s.

func (ConfigurationOption) FormatDefault Uses

func (opt ConfigurationOption) FormatDefault() string

FormatDefault converts the default value of ConfigurationOption to string. Used in the command line interface to show the argument's default value.

type ConfigurationOptionType Uses

type ConfigurationOptionType int

ConfigurationOptionType represents the possible types of a ConfigurationOption's value.

const (
    // BoolConfigurationOption reflects the boolean value type.
    BoolConfigurationOption ConfigurationOptionType = iota
    // IntConfigurationOption reflects the integer value type.
    // StringConfigurationOption reflects the string value type.
    // FloatConfigurationOption reflects a floating point value type.
    // StringsConfigurationOption reflects the array of strings value type.
    // PathConfigurationOption reflects the file system path value type.

func (ConfigurationOptionType) String Uses

func (opt ConfigurationOptionType) String() string

String() returns an empty string for the boolean type, "int" for integers and "string" for strings. It is used in the command line interface to show the argument's type.

type FeaturedPipelineItem Uses

type FeaturedPipelineItem interface {
    // Features returns the list of names which enable this item to be automatically inserted
    // in Pipeline.DeployItem().
    Features() []string

FeaturedPipelineItem enables switching the automatic insertion of pipeline items on or off.

type HibernateablePipelineItem Uses

type HibernateablePipelineItem interface {
    // Hibernate signals that the item is temporarily not needed and it's memory can be optimized.
    Hibernate() error
    // Boot signals that the item is needed again and must be de-hibernate-d.
    Boot() error

HibernateablePipelineItem is the interface to allow pipeline items to be frozen (compacted, unloaded) while they are not needed in the hosting branch.

type LeafPipelineItem Uses

type LeafPipelineItem interface {
    // Flag returns the cmdline switch to run the analysis. Should be dash-lower-case
    // without the leading dashes.
    Flag() string
    // Description returns the text which explains what the analysis is doing.
    // Should start with a capital letter and end with a dot.
    Description() string
    // Finalize returns the result of the analysis.
    Finalize() interface{}
    // Serialize encodes the object returned by Finalize() to YAML or Protocol Buffers.
    Serialize(result interface{}, binary bool, writer io.Writer) error

LeafPipelineItem corresponds to the top level pipeline items which produce the end results.

type Metadata Uses

type Metadata = pb.Metadata

Metadata is defined in internal/pb/pb.pb.go - header of the binary file.

type NoopMerger Uses

type NoopMerger struct {

NoopMerger provides an empty Merge() method suitable for PipelineItem.

func (*NoopMerger) Merge Uses

func (merger *NoopMerger) Merge(branches []PipelineItem)

Merge does nothing.

type OneShotMergeProcessor Uses

type OneShotMergeProcessor struct {
    // contains filtered or unexported fields

OneShotMergeProcessor provides the convenience method to consume merges only once.

func (*OneShotMergeProcessor) Initialize Uses

func (proc *OneShotMergeProcessor) Initialize()

Initialize resets OneShotMergeProcessor.

func (*OneShotMergeProcessor) ShouldConsumeCommit Uses

func (proc *OneShotMergeProcessor) ShouldConsumeCommit(deps map[string]interface{}) bool

ShouldConsumeCommit returns true on regular commits. It also returns true upon the first occurrence of a particular merge commit.

type Pipeline Uses

type Pipeline struct {
    // OnProgress is the callback which is invoked in Analyse() to output it's
    // progress. The first argument is the number of complete steps, the
    // second is the total number of steps and the third is some description of the current action.
    OnProgress func(int, int, string)

    // HibernationDistance is the minimum number of actions between two sequential usages of
    // a branch to activate the hibernation optimization (cpu-memory trade-off). 0 disables.
    HibernationDistance int

    // DryRun indicates whether the items are not executed.
    DryRun bool

    // DumpPlan indicates whether to print the execution plan to stderr.
    DumpPlan bool

    // PrintActions indicates whether to print the taken actions during the execution.
    PrintActions bool
    // contains filtered or unexported fields

Pipeline is the core Hercules entity which carries several PipelineItems and executes them. See the extended example of how a Pipeline works in doc.go

func NewPipeline Uses

func NewPipeline(repository *git.Repository) *Pipeline

NewPipeline initializes a new instance of Pipeline struct.

func (*Pipeline) AddItem Uses

func (pipeline *Pipeline) AddItem(item PipelineItem) PipelineItem

AddItem inserts a PipelineItem into the pipeline. It does not check any dependencies. See also: DeployItem().

func (*Pipeline) Commits Uses

func (pipeline *Pipeline) Commits(firstParent bool) ([]*object.Commit, error)

Commits returns the list of commits from the history similar to `git log` over the HEAD. `firstParent` specifies whether to leave only the first parent after each merge (`git log --first-parent`) - effectively decreasing the accuracy but increasing performance.

func (*Pipeline) DeployItem Uses

func (pipeline *Pipeline) DeployItem(item PipelineItem) PipelineItem

DeployItem inserts a PipelineItem into the pipeline. It also recursively creates all of it's dependencies (PipelineItem.Requires()). Returns the same item as specified in the arguments.

func (*Pipeline) GetFact Uses

func (pipeline *Pipeline) GetFact(name string) interface{}

GetFact returns the value of the fact with the specified name.

func (*Pipeline) GetFeature Uses

func (pipeline *Pipeline) GetFeature(name string) (bool, bool)

GetFeature returns the state of the feature with the specified name (enabled/disabled) and whether it exists. See also: FeaturedPipelineItem.

func (*Pipeline) Initialize Uses

func (pipeline *Pipeline) Initialize(facts map[string]interface{}) error

Initialize prepares the pipeline for the execution (Run()). This function resolves the execution DAG, Configure()-s and Initialize()-s the items in it in the topological dependency order. `facts` are passed inside Configure(). They are mutable.

func (*Pipeline) Len Uses

func (pipeline *Pipeline) Len() int

Len returns the number of items in the pipeline.

func (*Pipeline) RemoveItem Uses

func (pipeline *Pipeline) RemoveItem(item PipelineItem)

RemoveItem deletes a PipelineItem from the pipeline. It leaves all the rest of the items intact.

func (*Pipeline) Run Uses

func (pipeline *Pipeline) Run(commits []*object.Commit) (map[LeafPipelineItem]interface{}, error)

Run method executes the pipeline.

`commits` is a slice with the git commits to analyse. Multiple branches are supported.

Returns the mapping from each LeafPipelineItem to the corresponding analysis result. There is always a "nil" record with CommonAnalysisResult.

func (*Pipeline) SetFact Uses

func (pipeline *Pipeline) SetFact(name string, value interface{})

SetFact sets the value of the fact with the specified name.

func (*Pipeline) SetFeature Uses

func (pipeline *Pipeline) SetFeature(name string)

SetFeature sets the value of the feature with the specified name. See also: FeaturedPipelineItem.

func (*Pipeline) SetFeaturesFromFlags Uses

func (pipeline *Pipeline) SetFeaturesFromFlags(registry ...*PipelineItemRegistry)

SetFeaturesFromFlags enables the features which were specified through the command line flags which belong to the given PipelineItemRegistry instance. See also: AddItem().

type PipelineItem Uses

type PipelineItem interface {
    // Name returns the name of the analysis.
    Name() string
    // Provides returns the list of keys of reusable calculated entities.
    // Other items may depend on them.
    Provides() []string
    // Requires returns the list of keys of needed entities which must be supplied in Consume().
    Requires() []string
    // ListConfigurationOptions returns the list of available options which can be consumed by Configure().
    ListConfigurationOptions() []ConfigurationOption
    // Configure performs the initial setup of the object by applying parameters from facts.
    // It allows to create PipelineItems in a universal way.
    Configure(facts map[string]interface{}) error
    // Initialize prepares and resets the item. Consume() requires Initialize()
    // to be called at least once beforehand.
    Initialize(*git.Repository) error
    // Consume processes the next commit.
    // deps contains the required entities which match Depends(). Besides, it always includes
    // DependencyCommit and DependencyIndex.
    // Returns the calculated entities which match Provides().
    Consume(deps map[string]interface{}) (map[string]interface{}, error)
    // Fork clones the item the requested number of times. The data links between the clones
    // are up to the implementation. Needed to handle Git branches. See also Merge().
    // Returns a slice with `n` fresh clones. In other words, it does not include the original item.
    Fork(n int) []PipelineItem
    // Merge combines several branches together. Each is supposed to have been created with Fork().
    // The result is stored in the called item, thus this function returns nothing.
    // Merge() must update all the branches, not only self. When several branches merge, some of
    // them may continue to live, hence this requirement.
    Merge(branches []PipelineItem)

PipelineItem is the interface for all the units in the Git commits analysis pipeline.

func ForkCopyPipelineItem Uses

func ForkCopyPipelineItem(origin PipelineItem, n int) []PipelineItem

ForkCopyPipelineItem clones items by copying them by value from the origin.

func ForkSamePipelineItem Uses

func ForkSamePipelineItem(origin PipelineItem, n int) []PipelineItem

ForkSamePipelineItem clones items by referencing the same origin.

type PipelineItemRegistry Uses

type PipelineItemRegistry struct {
    // contains filtered or unexported fields

PipelineItemRegistry contains all the known PipelineItem-s.

func (*PipelineItemRegistry) AddFlags Uses

func (registry *PipelineItemRegistry) AddFlags(flagSet *pflag.FlagSet) (
    map[string]interface{}, map[string]*bool)

AddFlags inserts the cmdline options from PipelineItem.ListConfigurationOptions(), FeaturedPipelineItem().Features() and LeafPipelineItem.Flag() into the global "flag" parser built into the Go runtime. Returns the "facts" which can be fed into PipelineItem.Configure() and the dictionary of runnable analysis (LeafPipelineItem) choices. E.g. if "BurndownAnalysis" was activated through "-burndown" cmdline argument, this mapping would contain ["BurndownAnalysis"] = *true.

func (*PipelineItemRegistry) CollectAllDependencies Uses

func (registry *PipelineItemRegistry) CollectAllDependencies(item PipelineItem) []PipelineItem

CollectAllDependencies recursively builds the list of all the items on which the specified item depends.

func (*PipelineItemRegistry) GetFeaturedItems Uses

func (registry *PipelineItemRegistry) GetFeaturedItems() map[string][]PipelineItem

GetFeaturedItems returns all FeaturedPipelineItem-s registered.

func (*PipelineItemRegistry) GetLeaves Uses

func (registry *PipelineItemRegistry) GetLeaves() []LeafPipelineItem

GetLeaves returns all LeafPipelineItem-s registered.

func (*PipelineItemRegistry) GetPlumbingItems Uses

func (registry *PipelineItemRegistry) GetPlumbingItems() []PipelineItem

GetPlumbingItems returns all non-LeafPipelineItem-s registered.

func (*PipelineItemRegistry) Register Uses

func (registry *PipelineItemRegistry) Register(example PipelineItem)

Register adds another PipelineItem to the registry.

func (*PipelineItemRegistry) Summon Uses

func (registry *PipelineItemRegistry) Summon(providesOrName string) []PipelineItem

Summon searches for PipelineItem-s which provide the specified entity or named after the specified string. It materializes all the found types and returns them.

type ResultMergeablePipelineItem Uses

type ResultMergeablePipelineItem interface {
    // Deserialize loads the result from Protocol Buffers blob.
    Deserialize(pbmessage []byte) (interface{}, error)
    // MergeResults joins two results together. Common-s are specified as the global state.
    MergeResults(r1, r2 interface{}, c1, c2 *CommonAnalysisResult) interface{}

ResultMergeablePipelineItem specifies the methods to combine several analysis results together.

Package core imports 22 packages (graph) and is imported by 6 packages. Updated 2019-03-19. Refresh now. Tools for package owners.