@atomist/sdm

@atomist/sdm

Version 2.1.6
Published 3 years ago
10.2 MB
65 dependencies
Apache-2.0 license

Install

npm i @atomist/sdm

yarn add @atomist/sdm

pnpm add @atomist/sdm

Overview

Atomist Software Delivery Machine SDK

Index

Variables

variable AddressNoChannels

const AddressNoChannels: AddressChannels;

Throw away contents. Use when we know that there can be no linked channels.

variable and

const and: (...pushTests: PushTestOrProjectPredicate[]) => PushTest;

Wrap all these PushTests or ProjectPredicates in a single PushTest AND: Return true if all are satisfied

variable AnyPush

const AnyPush: PushTest;

Match on any push
Parameter p

variable ApproveGoalIfErrorComments

const ApproveGoalIfErrorComments: ReviewListenerRegistration;

Listener that requires approval on the code inspection if the review has any error comments.

variable ApproveGoalIfWarnComments

const ApproveGoalIfWarnComments: ReviewListenerRegistration;

Listener that requires approval on the code inspection if the review has any warn comments.

variable AtomistContinuationMimeType

const AtomistContinuationMimeType: string;

variable AutofixProgressReporter

const AutofixProgressReporter: ReportProgress;

Default ReportProgress for running autofixes

variable AutofixProgressTests

const AutofixProgressTests: ProgressTest[];

variable BaseContext

const BaseContext: string;

variable CFamilyLanguageSourceFiles

const CFamilyLanguageSourceFiles: string;

Glob patterns for C family languages

variable CloningProjectLoader

const CloningProjectLoader: ProjectLoader;

Non caching ProjectLoader that uses a separate clone for each project accessed

variable createEphemeralProgressLog

const createEphemeralProgressLog: ProgressLogFactory;

variable DefaultCancelOptions

const DefaultCancelOptions: CancelOptions;

variable DefaultExtractAuthor

const DefaultExtractAuthor: ExtractAuthor;

variable DefaultGoalNameGenerator

const DefaultGoalNameGenerator: SourceLocationGoalNameGenerator;

variable DefaultMockOptions

const DefaultMockOptions: MockOptions;

Default mock options to be merged into custom options provided on configuration.sdm.mock

variable DefaultPredicateMappingCostAnalyzer

const DefaultPredicateMappingCostAnalyzer: PredicateMappingCostAnalyzer<any>;

Estimate cost by looking at code to see if it goes through a project
Parameter pm
{any}

variable DefaultQueueOptions

const DefaultQueueOptions: QueueOptions;

variable DoNotSetAnyGoals

const DoNotSetAnyGoals: Goals;

Constant to indicate we should never match. {any}

variable DoNotSetAnyGoalsAndLock

const DoNotSetAnyGoalsAndLock: Goals;

Should be used in additive goal setting when no more goals should be scheduled.

variable DryRunParameter

const DryRunParameter: any;

variable FailGoalIfErrorComments

const FailGoalIfErrorComments: ReviewListenerRegistration;

Listener that fails the code inspection if the review has any error comments.

variable FailGoalIfWarnComments

const FailGoalIfWarnComments: ReviewListenerRegistration;

Listener that fails the code inspection if the review has any warn comments.

variable FromAtomist

const FromAtomist: PushTest;

Is this a push originated by Atomist? Note that we can't look at the committer, as if a user invoked a command handler, their credentials will be used
Parameter p
{boolean}

variable GeneratorTag

const GeneratorTag: string;

variable GitBranchRegExp

const GitBranchRegExp: BaseParameter;

variable GitHubNameRegExp

const GitHubNameRegExp: BaseParameter;

variable githubTeamVoter

const githubTeamVoter: (team?: string) => GoalApprovalRequestVoter;

Deprecated
since 1.0.0 use gitHubTeamVoter instead

variable GitShaRegExp

const GitShaRegExp: BaseParameter;

variable GoalSetGoalCompletionListener

const GoalSetGoalCompletionListener: Function1<I, Promise<R>>;

Update the state of the SdmGoalSet as the goals progress
Parameter gcl

variable HasTravisFile

const HasTravisFile: PredicatePushTest;

Does this project use Travis?

variable Immaterial

const Immaterial: GoalWithFulfillment;

Goal that should be scheduled for immaterial changes. Uses a no-op goalExecutor.

variable ImmaterialGoals

const ImmaterialGoals: Goals;

Goals instance for Immaterial changes

variable IndependentOfEnvironment

const IndependentOfEnvironment: GoalEnvironment;

variable InspectionTag

const InspectionTag: string;

variable IsDeployEnabled

const IsDeployEnabled: PushTest;

Is repo enabled for deployment
Parameter pi

variable IsPushToBranchWithPullRequest

const IsPushToBranchWithPullRequest: PushTest;

Is this push to a non-default branch that has an open pull request?

variable JobDescriptionParameter

const JobDescriptionParameter: any;

variable JobNameParameter

const JobNameParameter: any;

variable JobRequiredParameter

const JobRequiredParameter: any;

variable Locking

const Locking: Goal;

variable LogSuppressor

const LogSuppressor: InterpretLog<any>;

Use when we don't want to report the log to the user under any circumstances {InterpretedLog}

variable MsgIdParameter

const MsgIdParameter: any;

variable NamedSeedRepo

const NamedSeedRepo: PushTest;

Is this a seed repo, based on the naming convention that such repos have "-seed" in their name
Parameter pi

variable NonEmpty

const NonEmpty: PredicatePushTest;

PushTest that returns true if project is non empty {PredicatePushTest}

variable NoOpExtractAuthor

const NoOpExtractAuthor: ExtractAuthor;

variable NoParameterPrompt

const NoParameterPrompt: ParameterPrompt<any>;

No-op NoParameterPrompt implementation that never prompts for new parameters

variable NoPreferenceStore

const NoPreferenceStore: PreferenceStore;

NoOp PreferenceStore implementation useful for situations in which the SDM does not support preferences or tests.

variable NoProgressReport

const NoProgressReport: ReportProgress;

Don't report any progress

variable not

const not: <F>(t: PredicateMapping<F>) => PredicateMapping<F>;

Return the opposite of this push test

variable or

const or: (...pushTests: PushTestOrProjectPredicate[]) => PushTest;

Wrap all these PushTests or ProjectPredicates in a single PushTest OR: Return true if any is satisfied

variable ProductionEnvironment

const ProductionEnvironment: GoalEnvironment;

variable ProjectDisposalEnvironment

const ProjectDisposalEnvironment: GoalEnvironment;

variable SemVerRegExp

const SemVerRegExp: BaseParameter;

Validation pattern for semantic versions {{displayName: string; description: string; pattern: RegExp; validInput: string; minLength: number; maxLength: number}}

variable ServiceRegistrationGoalDataKey

const ServiceRegistrationGoalDataKey: string;

Key under which services can be found in goal data.

variable StagingEnvironment

const StagingEnvironment: GoalEnvironment;

variable SuccessIsReturn0ErrorFinder

const SuccessIsReturn0ErrorFinder: ErrorFinder;

Default ErrorFinder that regards everything but a return code of 0 as failure.
Parameter code
process exit status true if exit status is not zero

variable ToDefaultBranch

const ToDefaultBranch: PushTest;

variable TransformTag

const TransformTag: string;

variable UnanimousGoalApprovalRequestVoteDecisionManager

const UnanimousGoalApprovalRequestVoteDecisionManager: GoalApprovalRequestVoteDecisionManager;

Default GoalApprovalRequestVoteDecisionManager that decides unanimously on votes. One denied vote will deny the approval request; all granted votes with grant the request. All other votes with result in an abstained approval request.
Parameter votes

Functions

function actionableButton

actionableButton: <T extends ParameterType>(
    buttonSpec: ButtonSpecification,
    commandHandlerRegistration: CommandRegistration<T> | string,
    parameters?: ParameterType
) => Action;

Create an actionable button invoking the given command
Parameter buttonSpec
Parameter commandHandlerRegistration
command registration or command name
Parameter parameters
parameters to the command

function actionableMenu

actionableMenu: <T extends ParameterType>(
    menuSpec: MenuSpecification,
    commandHandlerRegistration: CommandRegistration<T> | string,
    parameterName: string,
    parameters?: ParameterType
) => Action;

Create an actionable menu invoking the given command
Parameter menuSpec
Parameter commandHandlerRegistration
command registration or command name
Parameter parameterName
name of the parameter to bind the menu to
Parameter parameters
parameters to the command

function adaptHandleCommand

adaptHandleCommand: (
    maker: Maker<HandleCommand<any>>
) => CommandHandlerRegistration;

Convert an decorator-style HandleCommand to a SDM-style CommandHandlerRegistration

function addMappedParameters

addMappedParameters: (
    p: NamedMappedParameter,
    ...more: NamedMappedParameter[]
) => ParametersBuilder;

Declare a new mapped parameter for the given command {ParametersBuilder}

function addParameters

addParameters: (
    p: NamedParameter,
    ...more: NamedParameter[]
) => ParametersBuilder;

Declare a new parameter for the given command {ParametersBuilder}

function addressChannelsFor

addressChannelsFor: (
    hasChannels: HasChannels,
    ctx: HandlerContext
) => AddressChannels;

Address the chat channels associated with this object. Typically used to address channels associated with a repo.
Parameter hasChannels
Parameter ctx
{AddressChannels}

function addressChannelsProgressLog

addressChannelsProgressLog: (
    name: string,
    hasChannels: HasChannels,
    ctx: HandlerContext
) => ProgressLog;

Stream the ProgressLog output to any channels associated with the current model element (such a repo) in Slack or elswhere.
Parameter name
name for the log. Should relate to the activity we're logging
Parameter hasChannels
Parameter ctx
{ProgressLog}

function addressDestinations

addressDestinations: (
    ctx: HandlerContext,
    ...destinations: Destination[]
) => AddressChannels;

function addSecrets

addSecrets: (s: NamedSecret, ...more: NamedSecret[]) => ParametersBuilder;

Declare a new secret parameter for the given command {ParametersBuilder}

function addValues

addValues: (s: NamedValue, ...more: NamedValue[]) => ParametersBuilder;

Declare a new configuration value parameter for the given command {ParametersBuilder}

function afterListener

afterListener: (listener: PrepareForGoalExecution) => GoalProjectListener;

Convenience function that takes a PrepareForGoalExecution and invokes it for after goal project events.
Parameter listener

function all

all: <F>(
    predicates: Array<PredicateMapping<F>>,
    analyzer?: PredicateMappingCostAnalyzer<F>
) => PredicateMapping<F>;

Wrap all these predicates in a single predicate AND: Return true if all are satisfied
Parameter predicates
Parameter analyzer
analyzer to use for performance optimization {PredicateMapping}

function allOf

allOf: <F>(
    pred1: PredicateMappingTerm<F>,
    ...preds: Array<PredicateMappingTerm<F>>
) => PredicateMapping<F>;

Predicate mapping DSL method. Allows use of booleans and functions returning boolean in predicate expressions
Parameter pred1
Parameter preds

function allPredicatesSatisfied

allPredicatesSatisfied: (...predicates: ProjectPredicate[]) => ProjectPredicate;

Wrap all these ProjectPredicates in a single ProjectPredicate AND: Return true if all are satisfied
Parameter predicates
{ProjectPredicate}

function allReposInTeam

allReposInTeam: (rrr: RepoRefResolver) => RepoFinder;

Use a GraphQL query to find all repos for the current team
Parameter rrr
RepoRefResolver used to find RepoRef from GraphQL result

function allSatisfied

allSatisfied: (...pushTests: PushTestOrProjectPredicate[]) => PushTest;

Wrap all these PushTests or ProjectPredicates in a single PushTest AND: Return true if all are satisfied
Parameter pushTests
{PushTest}

function announceTransformResults

announceTransformResults: (
    trs: TransformResult[],
    cli: CommandListenerInvocation
) => Promise<void>;

This is a useful function to pass to CodeTransformRegistration.onTransformResults. It sends a message per repository describing any errors that occurred while saving the transforms, and also where the transform was applied. It gives you the branch name.
Parameter trs
results of transforms
Parameter cli
original command invocation

function any

any: <F>(
    predicates: Array<PredicateMapping<F>>,
    analyzer?: PredicateMappingCostAnalyzer<F>
) => PredicateMapping<F>;

Wrap all these predicates in a single predicate OR: Return true if any is satisfied
Parameter predicates
Parameter analyzer
analyzer to use for performance optimization {PredicateMapping}

function anyFileChanged

anyFileChanged: (
    options: MaterialChangeOptions,
    changedFiles: string[]
) => boolean;

function anyFileChangedSuchThat

anyFileChangedSuchThat: (
    changedFilePaths: string[],
    test: (path: string) => boolean
) => boolean;

Does a file satisfying this text exist within the set of changed files?
Parameter changedFilePaths
Parameter test
test for the file change {boolean}

function anyFileChangedWithExtension

anyFileChangedWithExtension: (
    changedFilePaths: string[],
    extensions: string[]
) => boolean;

function anyPredicateSatisfied

anyPredicateSatisfied: (...predicates: ProjectPredicate[]) => ProjectPredicate;

Wrap all these ProjectPredicates in a single ProjectPredicate OR: Return true if any is satisfied
Parameter predicates
{ProjectPredicate}

function anySatisfied

anySatisfied: (...pushTests: PushTestOrProjectPredicate[]) => PushTest;

Wrap all these PushTests or ProjectPredicates in a single PushTest OR: Return true if any is satisfied
Parameter pushTests
{PushTest}

function appendOrCreateFileContent

appendOrCreateFileContent: (
    command: AppendOrCreateCommand
) => SimpleProjectEditor;

Return an editor to append the given content to the end of the file at the specified path, creating the file with only this content if it doesn't exist. Adds no whitespace.
Parameter command
command {SimpleProjectEditor}

function attachFacts

attachFacts: <FACT, F extends SdmContext = PushListenerInvocation>(
    compute: (f: F) => Promise<FACT>
) => GoalContribution<F>;

Enrich the invocation, attaching some facts. The returned object will be merged with any facts already on the invocation.
Parameter compute
additional facts. {GoalContribution}

function beforeListener

beforeListener: (listener: PrepareForGoalExecution) => GoalProjectListener;

Convenience function that takes a PrepareForGoalExecution and invokes it for before goal project events.
Parameter listener

function branchAwareCodeTransform

branchAwareCodeTransform: (
    codeTransformRegistration: CodeTransformRegistration<any>,
    sdm: SoftwareDeliveryMachine
) => CommandHandlerRegistration<RepoTargetingParameters>;

Wrap a CodeTransform to determine the target branch of the transform.
If the target branch, as expressed by the CodeTransformRegistration.transformPresentation, already exists, the wrapped CodeTransform will run against that branch instead of the requested branch.
Parameter codeTransformRegistration
Parameter sdm

function cacheKey

cacheKey: (params: ProjectLoadingParameters) => string;

Compute a cache key from the given ProjectLoadingParameters.
In this context undefined and false are functionally equivalent, so undefined values are coerced to false.
Parameter id
{any}

function cancelableGoal

cancelableGoal: (
    sdmGoal: SdmGoalEvent,
    configuration: Configuration
) => Promise<boolean>;

Can goal be canceled

function chattyDryRunAwareEditor

chattyDryRunAwareEditor: (
    ctr: CodeTransformRegistration<any>,
    underlyingEditor: AnyProjectEditor
) => ProjectEditor;

Wrap this editor to make it chatty, so it responds to Slack if there's nothing to do. It also honors the dryRun parameter flag to just capture the git diff and send it back to Slack instead of pushing changes to Git.

function chooseAndSetGoals

chooseAndSetGoals: (
    rules: ChooseAndSetGoalsRules,
    parameters: {
        context: HandlerContext;
        credentials: ProjectOperationCredentials;
        push: PushFields.Fragment;
    }
) => Promise<Goals | undefined>;

Choose and set goals for this push
Parameter rules
: configuration for handling incoming pushes
Parameter parameters
details of incoming request {Promise<Goals | undefined>}

function codeInspectionRegistrationToCommand

codeInspectionRegistrationToCommand: <R>(
    sdm: MachineOrMachineOptions,
    cir: CodeInspectionRegistration<R, any>
) => Maker<HandleCommand>;

function codeTransformRegistrationToCommand

codeTransformRegistrationToCommand: (
    sdm: MachineOrMachineOptions,
    ctr: CodeTransformRegistration<any>
) => Maker<HandleCommand>;

function commandHandlerRegistrationToCommand

commandHandlerRegistrationToCommand: <P = NoParameters>(
    sdm: MachineOrMachineOptions,
    c: CommandHandlerRegistration<P>
) => Maker<HandleCommand<P>>;

function commandRequestParameterPromptFactory

commandRequestParameterPromptFactory: <T>(
    ctx: HandlerContext
) => ParameterPrompt<T>;

Default ParameterPromptFactory that uses the WebSocket connection to send parameter prompts to the backend.
Parameter ctx

function computeShaOf

computeShaOf: (s: string) => string;

Compute the sha of the given string
Parameter s
{string}

function computeStartingPoint

computeStartingPoint: <P extends SeedDrivenGeneratorParameters>(
    params: P,
    ctx: HandlerContext,
    repoLoader: RepoLoader,
    details: GeneratorCommandDetails<any>,
    startingPoint: StartingPoint<P>,
    cr: CommandRegistration<P>,
    sdmo: SoftwareDeliveryMachineOptions
) => Promise<Project>;

Retrieve a seed. Set the seed location on the parameters if possible and necessary.

function confirmEditedness

confirmEditedness: (editResult: EditResult) => Promise<EditResult>;

Try to work out whether a project was edited, looking at git status if we can't find out from the edit result
Parameter editResult
{Promise}

function constructGoalSet

constructGoalSet: (
    ctx: HandlerContext,
    goalSetId: string,
    goalSet: string,
    sdmGoals: SdmGoalMessage[],
    tags: GoalSetTag[],
    push: OnPushToAnyBranch.Push
) => SdmGoalSetMessage;

function constructProvenance

constructProvenance: (ctx: HandlerContext) => SdmProvenance;

function constructSdmGoal

constructSdmGoal: (
    ctx: HandlerContext,
    parameters: {
        goalSet: string;
        goalSetId: string;
        goal: Goal;
        state: SdmGoalState;
        id: RemoteRepoRef;
        providerId: string;
        url?: string;
        fulfillment?: SdmGoalFulfillment;
    }
) => SdmGoalMessage;

function constructSdmGoalImplementation

constructSdmGoalImplementation: (
    gi: GoalImplementation,
    registration: string
) => SdmGoalFulfillment;

function copyFileFromUrl

copyFileFromUrl: (url: string, path: string) => CodeTransform;

Add the downloaded content to the given project
Parameter url
url of the content. Must be publicly accessible
Parameter path

function copyFiles

copyFiles: (
    donorProject: Project,
    fileMappings: Array<FileMapping | string>
) => CodeTransform;

function copyFilesFrom

copyFilesFrom: (
    donorProjectId: RemoteRepoRef,
    fileMappings: Array<FileMapping | string>,
    credentials: ProjectOperationCredentials
) => CodeTransform;

Take the specified files from the donor project
Parameter donorProjectId
Parameter fileMappings
Parameter credentials
{SimpleProjectEditor}

function createCommand

createCommand: <PARAMS = NoParameters>(
    sdm: MachineOrMachineOptions,
    commandMaker: (sdm: MachineOrMachineOptions) => OnCommand<PARAMS>,
    name: string,
    paramsMaker?: Maker<PARAMS>,
    details?: CommandDetails
) => HandleCommand<PARAMS>;

Wrap a function in a command handler, allowing use of custom parameters. Targeting (targets property) is handled automatically if the parameters do not implement TargetsParams
Parameter sdm
machine or options
Parameter commandMaker
function to create command function
Parameter name
command name
Parameter paramsMaker
parameters factory, typically the name of a class with a no arg constructor
Parameter details
optional details to customize behavior Add intent "edit "

function createJob

createJob: <T extends ParameterType>(
    details: JobDetails<T>,
    ctx: HandlerContext
) => Promise<{ id: string }>;

Create a Job in the backend with the provided name and tasks
A job can execute any registered command in the same or other connected SDM:
command: name of the CommandRegistration or the registration instance itself registration: optional name of the SDM this job should be send to; defaults to the current SDM parameters: Record type with all required parameters for this command name: optional name of the job description: optional description of the job used to display to the user in chat or web

function createPredicatedGoal

createPredicatedGoal: (
    egi: EssentialGoalInfo,
    goalExecutor: ExecuteGoal,
    w: WaitRules
) => Goal;

Create a goal from the given executor, waiting until a condition is satisfied, with a given timeout.
Parameter egi
Parameter goalExecutor
Parameter w
rules for waiting {Goal}

function createPredicatedGoalExecutor

createPredicatedGoalExecutor: (
    uniqueName: string,
    goalExecutor: ExecuteGoal,
    w: WaitRules,
    unref?: boolean
) => ExecuteGoal;

Wrap provided ExecuteGoal instance with WaitRules processing
Parameter uniqueName
Parameter goalExecutor
Parameter w
rules for waiting {ExecuteGoal}

function createPushImpactListenerInvocation

createPushImpactListenerInvocation: (
    goalInvocation: GoalInvocation,
    project: GitProject
) => Promise<PushImpactListenerInvocation>;

Create a PushImpactListenerInvocation from the given context. Includes both the complete project and the changed files.
Parameter goalInvocation
Parameter project
{Promise}

function createRetryingGoalExecutor

createRetryingGoalExecutor: (
    uniqueName: string,
    goalExecutor: ExecuteGoal,
    retry: RetryOptions
) => ExecuteGoal;

function createSkillContext

createSkillContext: <C extends Record<string, any> = any>(
    ctx: HandlerContext
) => SkillContext<C>;

Helper function to create a SkillContext instance from the passed in HandlerContext

function decode

decode: (coded: string) => string;

Decode the given Base 64 string
Parameter coded
{string}

function descriptionFromState

descriptionFromState: (
    goal: Goal,
    state: SdmGoalState,
    goalEvent?: SdmGoalEvent
) => string;

function determineGoals

determineGoals: (
    rules: {
        projectLoader: ProjectLoader;
        repoRefResolver: RepoRefResolver;
        goalSetter: GoalSetter;
        implementationMapping: GoalImplementationMapper;
        enrichGoal: EnrichGoal;
        tagGoalSet?: TagGoalSet;
    },
    circumstances: {
        credentials: ProjectOperationCredentials;
        id: RemoteRepoRef;
        context: HandlerContext;
        configuration: Configuration;
        push: PushFields.Fragment;
        addressChannels: AddressChannels;
        preferences?: PreferenceStore;
        goalSetId: string;
    }
) => Promise<{
    determinedGoals: Goals | undefined;
    goalsToSave: SdmGoalMessage[];
    tags: GoalSetTag[];
}>;

function doWithProject

doWithProject: (
    action: (pa: ProjectAwareGoalInvocation) => Promise<void | ExecuteGoalResult>,
    cloneOptions?: CloneOptions & { readOnly: boolean }
) => ExecuteGoal;

Convenience method to create goal implementations that require a local clone of the project.
Parameter action
Parameter cloneOptions
Returns
{ExecuteGoal}

function doWithRepos

doWithRepos: (
    sdm: SoftwareDeliveryMachine,
    i: SdmContext,
    action: WithLoadedProject<any>
) => Promise<any>;

Perform an action on all accessible repos in parallel up to a configurable max concurrency limit. This is normally readonly. If you want to perform an update, use a CodeTransform.
Parameter sdm
Parameter i
Parameter action
{Promise}

function encode

encode: (str: string) => string;

Base 64 encode the given string
Parameter str
{string}

function enrichGoalSetters

enrichGoalSetters: <F extends SdmContext = StatefulPushListenerInvocation<any>>(
    mapping: GoalContribution<F>,
    contributor: GoalContribution<F>,
    ...contributors: Array<GoalContribution<F>>
) => Mapping<F, Goals> & GoalSettingStructure<F, Goals>;

Enrich the given push mapping with our own contributions
Parameter mapping
Parameter contributor
Parameter contributors
{Mapping<F extends SdmContext, Goals>}

function environmentFromGoal

environmentFromGoal: (goal: Goal) => string;

function eventHandlerRegistrationToEvent

eventHandlerRegistrationToEvent: (
    sdm: MachineOrMachineOptions,
    e: EventHandlerRegistration<any, any>
) => Maker<HandleEvent>;

function executeAutofixes

executeAutofixes: (
    registrations: AutofixRegistration[],
    transformPresentation?: TransformPresentation<GoalInvocationParameters>,
    extractAuthor?: ExtractAuthor
) => ExecuteGoal;

Execute autofixes against this push Throw an error on failure
Parameter registrations
ExecuteGoal

function executeAutoInspects

executeAutoInspects: (options: AutoInspectOptions) => ExecuteGoal;

Execute auto inspections and route or react to review results using review listeners
Parameter autoInspectRegistrations
Parameter reviewListeners
listeners to respond to reviews {ExecuteGoal}

function executeCancelGoalSets

executeCancelGoalSets: (options: CancelOptions, name: string) => ExecuteGoal;

Cancel any pending goals that are on the previous commit of the goal's branch
Parameter options
Parameter name

function executeGoal

executeGoal: (
    rules: {
        projectLoader: ProjectLoader;
        goalExecutionListeners: GoalExecutionListener[];
    },
    implementation: GoalImplementation,
    gi: GoalInvocation
) => Promise<ExecuteGoalResult>;

Central function to execute a goal with progress logging

function executeHook

executeHook: (
    rules: { projectLoader: ProjectLoader },
    goalInvocation: GoalInvocation,
    sdmGoal: SdmGoalEvent,
    stage: 'post' | 'pre'
) => Promise<HandlerResult>;

function executePushImpact

executePushImpact: (
    registrations: PushImpactListenerRegisterable[]
) => ExecuteGoal;

Execute arbitrary code reactions against a codebase
Parameter registrations
{ExecuteGoal}

function executeSendMessageToSlack

executeSendMessageToSlack: (msg: string | SlackMessage) => ExecuteGoal;

* Execute a goal by sending a message to the linked Slack channels
Parameter msg
{ExecuteGoal}

function fakeCommandListenerInvocation

fakeCommandListenerInvocation: <P>(
    opts?: Partial<CommandListenerInvocation<P>>
) => CommandListenerInvocation<P>;

function fakeContext

fakeContext: (workspaceId?: string) => HandlerContext & AutomationContextAware;

Convenient function to allow creating fake contexts. Useful for testing
Parameter workspaceId
{any}

function fakeGoalInvocation

fakeGoalInvocation: (
    id: RemoteRepoRef,
    options?: SoftwareDeliveryMachineOptions
) => GoalInvocation;

Useful testing support
Parameter id
{GoalInvocation}

function fakePush

fakePush: (
    project?: Project,
    pli?: Partial<PushListenerInvocation>
) => PushListenerInvocation;

Used for testing
Parameter project
Parameter pli
{PushListenerInvocation}

function fetchCommitForSdmGoal

fetchCommitForSdmGoal: (
    ctx: HandlerContext,
    goal: SdmGoalFields.Fragment & SdmGoalRepo.Fragment
) => Promise<CommitForSdmGoal.Commit>;

function fetchGoalsForCommit

fetchGoalsForCommit: (
    ctx: HandlerContext,
    id: RemoteRepoRef,
    providerId: string,
    goalSetId?: string
) => Promise<SdmGoalEvent[]>;

function fetchGoalsFromPush

fetchGoalsFromPush: (sdmGoal: SdmGoalEvent) => SdmGoalEvent[];

function fileContent

fileContent: (
    token: string,
    rr: GitHubRepoRef,
    path: string
) => Promise<string | undefined>;

function filesChangedSince

filesChangedSince: (
    project: GitProject,
    push: PushFields.Fragment
) => Promise<string[] | undefined>;

Use git to list the files changed since the given sha or undefined if we cannot determine it
Parameter project
Parameter push
{Promise<string[]>}

function filteredView

filteredView: <P extends Project = Project>(
    p: Project,
    filter: (path: string) => boolean
) => P;

Create a filtered view of the given project. Changes to the filtered view will affect the source project.
Parameter p
Parameter filter
function to filter file paths. Return true to eliminate a file {Promise}

function filterImmediateAutofixes

filterImmediateAutofixes: (
    autofixes: AutofixRegistration[],
    gi: GoalInvocation
) => AutofixRegistration[];

Filter any provided autofixes whose results were included in the commits of the current push.
Parameter autofixes
Parameter gi
Returns
{AutofixRegistration[]}

function findSdmGoalOnCommit

findSdmGoalOnCommit: (
    ctx: HandlerContext,
    id: RemoteRepoRef,
    providerId: string,
    goal: Goal
) => Promise<SdmGoalEvent>;

function firstAvailableProgressLog

firstAvailableProgressLog: (
    log: ProgressLog,
    ...moreLogs: ProgressLog[]
) => Promise<ProgressLog>;

Return the first available progress log. Error if none is available: Pass in a fallback that's always available.
Parameter log
first log
Parameter moreLogs
{Promise}

function format

format: (msg: string, ...args: any[]) => string;

Returns a formatted string replacing any placeholders in msg with provided args
See npm springf-js for more details on what args and placeholder patterns are supported.

function formatDate

formatDate: (date?: Date, format?: string, utc?: boolean) => string;

Format the date with provided format. Defaults to formatting the current UTC date with 'yyyymmddHHMMss' format.
Parameter date
Date object to format
Parameter format
dateformat compatible format
Parameter utc
if true, use UTC time, otherwise use local time zone properly formatted date string

function formatReviewerError

formatReviewerError: (err: ReviewerError) => slack.SlackMessage;

function generateCommitMessageForAutofix

generateCommitMessageForAutofix: (autofix: AutofixRegistration) => string;

Generate a commit message for the provided autofix.
Parameter autofix
Returns
{string}

function generatorCommand

generatorCommand: <P>(
    sdm: MachineOrMachineOptions,
    editorFactory: EditorFactory<P>,
    name: string,
    paramsMaker: Maker<P>,
    fallbackTarget: Maker<RepoCreationParameters>,
    startingPoint: StartingPoint<P>,
    details: Partial<GeneratorCommandDetails<any>>,
    cr: GeneratorRegistration<P>
) => HandleCommand;

Create a command handler for project generation
Parameter sdm
this machine or its options
Parameter editorFactory
to create editorCommand to perform transformation
Parameter paramsMaker
Parameter name
Parameter details
{HandleCommand}

function generatorRegistrationToCommand

generatorRegistrationToCommand: <P = any>(
    sdm: MachineOrMachineOptions,
    e: GeneratorRegistration<P>
) => Maker<HandleCommand<P>>;

function getGoalDefinitionFrom

getGoalDefinitionFrom: (
    goalDetails: FulfillableGoalDetails | string,
    uniqueName: string,
    definition?: GoalDefinition
) => { uniqueName: string } | PredicatedGoalDefinition;

Construct a PredicatedGoalDefinition from the provided goalDetails
Parameter goalDetails
Parameter uniqueName
Parameter definition

function gitBranchCompatible

gitBranchCompatible: (name: string) => string;

Takes a potential git branch name and returns a legalised iteration of it
Parameter name
the git branch name to sanitise.

function gitHubTeamVoter

gitHubTeamVoter: (team?: string) => GoalApprovalRequestVoter;

Goal approval request vote implementation that checks for GitHub team membership of the person who is requesting the approval .
Parameter team

function given

given: <V>(...givenPushTests: PushTest[]) => TreeContext<V>;

Simple DSL to create a decision tree. Trees and subtrees can compute variables as interim values for future use. Example usage, showing computed state:

let count = 0;  // Initialize a counter we'll use later
const pm: PushMapping<Goals> = given<Goals>(TruePushTest, ...) // Use any push tests
   .init(() => count = 0) // Init to set state
   .itMeans("no frogs coming")
   .then(
       given<Goals>(TruePushTest, ...).itMeans("case1")
          .compute(() => count++)   // Increment the counter for this branch
          .then(
             // Compute terminal rules
             whenPushSatisfies(count > 0, FalsePushTest).itMeans("nope").setGoals(NoGoals),
             whenPushSatisfies(TruePushTest).itMeans("yes").setGoals(HttpServiceGoals),
          ),
      );

Parameter givenPushTests

PushTests interim DSL structure

function goal

goal: (
    details?: FulfillableGoalDetails,
    goalExecutor?: ExecuteGoal,
    options?: {
        pushTest?: PushTest;
        logInterpreter?: InterpretLog;
        progressReporter?: ReportProgress;
        plan?: (
            pli: StatefulPushListenerInvocation,
            goals: Goals
        ) => Promise<PlannedGoals | PlannedGoal>;
    }
) => GoalWithFulfillment;

Creates a new GoalWithFulfillment instance using conventions if overwrites aren't provided
Call this from your machine.ts where you configure your sdm to create a custom goal.
Caution: if you wrap this in another function, then you MUST provide details.uniqueName, because the default is based on where in the code this goal function is called.
Parameter details
It is highly recommended that you supply at least uniqueName.
Parameter goalExecutor
Parameter options

function goalContributors

goalContributors: <F extends SdmContext = StatefulPushListenerInvocation<any>>(
    contributor: GoalContribution<F>,
    ...contributors: Array<GoalContribution<F>>
) => Mapping<F, Goals>;

Contribute goals based on a series of contribution rules.
Instead of stopping at the first match, each push will get _all_ the goals it qualifies for.
Duplicates will be removed.
Parameter contributor
first contributor
Parameter contributors
a mapping to goals

function goalCorrespondsToSdmGoal

goalCorrespondsToSdmGoal: (goal: Goal, sdmGoal: SdmGoalKey) => boolean;

function goalData

goalData: (sdmGoal: SdmGoalEvent) => any;

Read and parse goal event data. If the goal event has no data, return an empty object. Note: this purposely only works if the data field is stringified JSON.
Parameter sdmGoal
JSON parsed goal event data property

function goalKeyEquals

goalKeyEquals: (a: SdmGoalKey, b: SdmGoalKey) => boolean;

function goalKeyString

goalKeyString: (gk: SdmGoalKey) => string;

function goals

goals: (name: string) => Goals & GoalsBuilder;

Create Goals instance using a fluent API.
const simpleGoals = goals("Simple Goals") .plan(CodeInspectionGoal) .plan(BuildGoal, Autofix).after(CodeInspectionGoal) .plan(StagingEndpointGoal).after(BuildGoal) .plan(ProductionDeploymentGoal).after(BuildGoal, StagingEndpointGoal);
Parameter name
Returns
{Goals & GoalsBuilder}

function goalSetState

goalSetState: (
    goals: Array<Pick<SdmGoalMessage, 'name' | 'state'>>
) => SdmGoalState;

function goalTest

goalTest: (
    name: string,
    goalMapping: (
        goal: SdmGoalEvent,
        pli: StatefulPushListenerInvocation
    ) => Promise<boolean>,
    pushTest?: PushTest
) => GoalTest;

function handleSdmGoalSetEvent

handleSdmGoalSetEvent: (
    options: QueueOptions,
    definition: GoalDefinition,
    configuration: SoftwareDeliveryMachineConfiguration
) => OnEvent<OnAnySdmGoalSetSubscription>;

function hasCommit

hasCommit: (test: RegExp) => PushTest;

Push test that tests commit messages for a provided regular expression match

function hasFile

hasFile: (path: string) => PredicatePushTest;

Return a PushTest testing for the existence of the given file
Parameter path
{PushTest}

function hasFileContaining

hasFileContaining: (pattern: string | string[], content?: RegExp) => PushTest;

Return a PushTest testing for the existence of the given file containing the pattern
Parameter path
Parameter pattern
regex to look for {PushTest}

function hasFileWithExtension

hasFileWithExtension: (extension: string) => PredicatePushTest;

Is there at least one file with the given extension?
Parameter extension
{PredicatePushTest}

function hasGoalSettingStructure

hasGoalSettingStructure: <F, V>(
    m: Mapping<F, V>
) => m is GoalSettingStructure<F, V>;

function hasPreconditions

hasPreconditions: (goal: Goal) => goal is GoalWithPrecondition;

function hasResourceProvider

hasResourceProvider: (
    type: 'docker' | 'npm' | 'maven2',
    name?: string
) => PushTest;

Return a PushTest that checks if a certain resource provider exists in the graph

function isBranch

isBranch: (re: RegExp) => PushTest;

Return a push test that matches the repository branch against regular expression.
Parameter re
Regular expression to match against using RegExp.test() Push test performing the match

function isDeployEnabled

isDeployEnabled: (parameters: {
    context: HandlerContext;
    id: RepoRef;
}) => Promise<boolean>;

function isExplicableMapping

isExplicableMapping: <F, V>(
    input: Mapping<F, V>
) => input is ExplicableMapping<F, V, V>;

function isFailure

isFailure: (result: ExecuteGoalResult | void) => boolean;

Assert if a given ExecuteGoalResult describe a failure result
Parameter result

function isGoal

isGoal: (options?: {
    name?: string | RegExp;
    state?: SdmGoalState;
    output?: string | RegExp;
    pushTest?: PushTest;
    data?: string | RegExp;
}) => GoalTest;

function isGoalCanceled

isGoalCanceled: (sdmGoal: SdmGoalEvent, ctx: HandlerContext) => Promise<boolean>;

Check if current goal is already canceled

function isGoalDefinition

isGoalDefinition: (f: Goal | GoalDefinition) => f is GoalDefinition;

function isGoalFulfillment

isGoalFulfillment: (g: {
    fulfillment?: PlannedGoal['fulfillment'];
}) => g is { fulfillment: PlannedGoal['fulfillment'] };

function isGoalImplementation

isGoalImplementation: (f: GoalFulfillment) => f is GoalImplementation;

function isGoals

isGoals: (a: any) => a is Goals;

function isGoalSideEffect

isGoalSideEffect: (f: GoalFulfillment) => f is GoalSideEffect;

function isImplementation

isImplementation: (f: Fulfillment) => f is Implementation;

function isLazyProjectLoader

isLazyProjectLoader: (pl: ProjectLoader) => pl is LazyProjectLoader;

function isMapping

isMapping: (a: any) => a is Mapping<any, any>;

function isMaterialChange

isMaterialChange: (options?: MaterialChangeOptions) => PushTest;

Check if a Push represents a material change.
Material changes are changes to files that should trigger certain activity or goals. Often simple changes to MD or html files should not trigger a full CI/CD process.

function isPredicatedStaticValue

isPredicatedStaticValue: <T>(
    pushMapping: PushMapping<T>
) => pushMapping is StaticPushMapping<T> & Predicated<PushListenerInvocation>;

function isRepo

isRepo: (re: RegExp) => PushTest;

Return a push test that matches the repository owner/repo slug against regular expression.
Parameter re
Regular expression to match against using RegExp.test() Push test performing the match

function isRepoTargetingParameters

isRepoTargetingParameters: (p: any) => p is RepoTargetingParameters;

function isSdmEnabled

isSdmEnabled: (name: string) => PushTest;

Is this SDM enabled on the current project. Checks the .atomist/config.json at key sdm.enabled to see if the current SDM is listed.

function isSeedDrivenGeneratorParameters

isSeedDrivenGeneratorParameters: (p: any) => p is SeedDrivenGeneratorParameters;

function isSideEffect

isSideEffect: (f: Fulfillment) => f is SideEffect;

function isSuccess

isSuccess: (result: ExecuteGoalResult | void) => boolean;

Assert if a given ExecuteGoalResult describe a successful result
Parameter result

function isTransformModeSuggestion

isTransformModeSuggestion: (p: any) => p is TransformModeSuggestion;

function isValidationError

isValidationError: (vr: ValidationResult) => vr is ValidationError;

function killAndWait

killAndWait: (childProcess: ChildProcess, wait?: number) => Promise<void>;

Kill the process and wait for it to shut down. This can take a while as processes may have shut down hooks. On win32, the process is killed and the Promise is rejected if the process does not exit within wait milliseconds. On other platforms, first the process is sent the default signal, SIGTERM. After wait milliseconds, it is sent SIGKILL. After another wait milliseconds, an error is thrown.
Parameter childProcess
Child process to kill
Parameter wait
Number of milliseconds to wait before sending SIGKILL and then erroring, default is 30000 ms

function lastLinesLogInterpreter

lastLinesLogInterpreter: (message: string, lines?: number) => InterpretLog;

Generally useful InterpretLog that takes the last n logs of the log
Parameter message
Parameter lines
number of lines to take {InterpretLog}

function mapKeyToGoal

mapKeyToGoal: <T extends SdmGoalKey>(goals: T[]) => (k: SdmGoalKey) => T;

function mapMapping

mapMapping: <F, V1, V2>(
    inputMapping: Mapping<F, V1>,
    f: (v1: V1) => V2
) => Mapping<F, V2> & ExplicableMapping<F, V2, V1>;

function markStatus

markStatus: (parameters: {
    context: HandlerContext;
    goalEvent: SdmGoalEvent;
    goal: Goal;
    result: ExecuteGoalResult;
    error?: Error;
    progressLogUrl: string;
}) => Promise<void>;

function matchStringOrRegexp

matchStringOrRegexp: (pattern: string | RegExp, toMatch: string) => boolean;

function memoize

memoize: (pt: PushTest) => PushTest;

Cache the PushTest results for this push. The results will be cached based on the name of the pushTest and the ID of the push. Make sure your push test has a unique name!
Parameter pt
{PushTest}

function mergeGoalData

mergeGoalData: (data: any, sdmGoal: SdmGoalEvent) => any;

Return a shallow merge the provided data and the goal event data property, parsed as JSON. Properties in data take precedence over those in the parsed goal event data object.
Parameter data
Parameter sdmGoal
shallow merge of data and SDM goal event data property

function mergeOptions

mergeOptions: <OPTIONS>(
    defaults: OPTIONS,
    explicit: OPTIONS,
    configurationPath?: string
) => OPTIONS;

Merge Goal configuration options into a final options object. Starts off by merging the explicitly provided options over the provided defaults; finally merges the configuration values at the given configuration path (prefixed with sdm.) over the previous merge.
Parameter defaults
Parameter explicit
Parameter configurationPath

@atomist/sdm

Install

Overview

Index

Variables

Functions

Classes

Interfaces

Enums

Type Aliases

Namespaces

Variables

variable AddressNoChannels

variable and

variable AnyPush

Parameter p

variable ApproveGoalIfErrorComments

variable ApproveGoalIfWarnComments

variable AtomistContinuationMimeType

variable AutofixProgressReporter

variable AutofixProgressTests

variable BaseContext

variable CFamilyLanguageSourceFiles

variable CloningProjectLoader

variable createEphemeralProgressLog

variable DefaultCancelOptions

variable DefaultExtractAuthor

variable DefaultGoalNameGenerator

variable DefaultMockOptions

variable DefaultPredicateMappingCostAnalyzer

Parameter pm

variable DefaultQueueOptions

variable DoNotSetAnyGoals

variable DoNotSetAnyGoalsAndLock

variable DryRunParameter

variable FailGoalIfErrorComments

variable FailGoalIfWarnComments

variable FromAtomist

Parameter p

variable GeneratorTag

variable GitBranchRegExp

variable GitHubNameRegExp

variable githubTeamVoter

Deprecated

variable GitShaRegExp

variable GoalSetGoalCompletionListener

Parameter gcl

variable HasTravisFile

variable Immaterial

variable ImmaterialGoals

variable IndependentOfEnvironment

variable InspectionTag

variable IsDeployEnabled

Parameter pi

variable IsPushToBranchWithPullRequest

variable JobDescriptionParameter

variable JobNameParameter

variable JobRequiredParameter

variable Locking

variable LogSuppressor

variable MsgIdParameter

variable NamedSeedRepo

Parameter pi

variable NonEmpty

variable NoOpExtractAuthor

variable NoParameterPrompt

variable NoPreferenceStore

variable NoProgressReport

variable not

variable or

variable ProductionEnvironment

variable ProjectDisposalEnvironment

variable SemVerRegExp

variable ServiceRegistrationGoalDataKey

variable StagingEnvironment

variable SuccessIsReturn0ErrorFinder

Parameter code

variable ToDefaultBranch

variable TransformTag

variable UnanimousGoalApprovalRequestVoteDecisionManager