projen 0.70.2 → 0.70.4

package/lib/.types-compat/ts3.9/lib/github/github-credentials.d.ts

@@ -0,0 +1,58 @@
+import { JobStep, AppPermissions } from "./workflows-model";
+/**
+ * Options for `GithubCredentials.fromPersonalAccessToken`
+ */
+export interface GithubCredentialsPersonalAccessTokenOptions {
+    readonly secret?: string;
+}
+/**
+ * Options for `GithubCredentials.fromApp`
+ */
+export interface GithubCredentialsAppOptions {
+    readonly appIdSecret?: string;
+    readonly privateKeySecret?: string;
+    /**
+     * The permissions granted to the token.
+     *
+     * @default - all permissions granted to the app
+     */
+    readonly permissions?: AppPermissions;
+}
+/**
+ * Represents a method of providing GitHub API access for projen workflows.
+ */
+export declare class GithubCredentials {
+    private readonly options;
+    /**
+     * Provide API access through a GitHub personal access token.
+     *
+     * The token must be added as a secret to the GitHub repo, and the name of the
+     * secret can be specified here.
+     *
+     * @see https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token
+     * @default - a secret named "PROJEN_GITHUB_TOKEN"
+     */
+    static fromPersonalAccessToken(options?: GithubCredentialsPersonalAccessTokenOptions): GithubCredentials;
+    /**
+     * Provide API access through a GitHub App.
+     *
+     * The GitHub App must be installed on the GitHub repo, its App ID and a
+     * private key must be added as secrets to the repo. The name of the secrets
+     * can be specified here.
+     *
+     * @see https://docs.github.com/en/developers/apps/building-github-apps/creating-a-github-app
+     * @see https://projen.io/github.html#github-app
+     * @default - app id stored in "PROJEN_APP_ID" and private key stored in "PROJEN_APP_PRIVATE_KEY" with all permissions attached to the app
+     */
+    static fromApp(options?: GithubCredentialsAppOptions): GithubCredentials;
+    private constructor();
+    /**
+     * Setup steps to obtain GitHub credentials.
+     */
+    get setupSteps(): JobStep[];
+    /**
+     * The value to use in a workflow when a GitHub token is expected. This
+     * typically looks like "${{ some.path.to.a.value }}".
+     */
+    get tokenRef(): string;
+}

package/lib/.types-compat/ts3.9/lib/github/github-project.d.ts

@@ -0,0 +1,177 @@
+import { AutoApprove, AutoApproveOptions } from "./auto-approve";
+import { AutoMergeOptions } from "./auto-merge";
+import { GitHub, GitHubOptions } from "./github";
+import { GithubCredentials } from "./github-credentials";
+import { MergifyOptions } from "./mergify";
+import { StaleOptions } from "./stale";
+import { Gitpod } from "../gitpod";
+import { Project, ProjectOptions, ProjectType } from "../project";
+import { SampleReadmeProps } from "../readme";
+import { DevContainer, VsCode } from "../vscode";
+/**
+ * Options for `GitHubProject`.
+ */
+export interface GitHubProjectOptions extends ProjectOptions {
+    /**
+     * Add a Gitpod development environment
+     *
+     * @default false
+     */
+    readonly gitpod?: boolean;
+    /**
+     * Enable VSCode integration.
+     *
+     * Enabled by default for root projects. Disabled for non-root projects.
+     *
+     * @default true
+     */
+    readonly vscode?: boolean;
+    /**
+     * Enable GitHub integration.
+     *
+     * Enabled by default for root projects. Disabled for non-root projects.
+     *
+     * @default true
+     */
+    readonly github?: boolean;
+    /**
+     * Options for GitHub integration
+     *
+     * @default - see GitHubOptions
+     */
+    readonly githubOptions?: GitHubOptions;
+    /**
+     * Whether mergify should be enabled on this repository or not.
+     *
+     * @default true
+     * @deprecated use `githubOptions.mergify` instead
+     */
+    readonly mergify?: boolean;
+    /**
+     * Options for mergify
+     *
+     * @default - default options
+     * @deprecated use `githubOptions.mergifyOptions` instead
+     */
+    readonly mergifyOptions?: MergifyOptions;
+    /**
+     * Add a VSCode development environment (used for GitHub Codespaces)
+     *
+     * @default false
+     */
+    readonly devContainer?: boolean;
+    /**
+     * Add a `clobber` task which resets the repo to origin.
+     * @default - true, but false for subprojects
+     */
+    readonly clobber?: boolean;
+    /**
+     * The README setup.
+     *
+     * @default - { filename: 'README.md', contents: '# replace this' }
+     * @example "{ filename: 'readme.md', contents: '# title' }"
+     */
+    readonly readme?: SampleReadmeProps;
+    /**
+     * Which type of project this is (library/app).
+     * @default ProjectType.UNKNOWN
+     * @deprecated no longer supported at the base project level
+     */
+    readonly projectType?: ProjectType;
+    /**
+     * Enable and configure the 'auto approve' workflow.
+     * @default - auto approve is disabled
+     */
+    readonly autoApproveOptions?: AutoApproveOptions;
+    /**
+     * Enable automatic merging on GitHub. Has no effect if `github.mergify`
+     * is set to false.
+     * @default true
+     */
+    readonly autoMerge?: boolean;
+    /**
+     * Configure options for automatic merging on GitHub. Has no effect if
+     * `github.mergify` or `autoMerge` is set to false.
+     *
+     * @default - see defaults in `AutoMergeOptions`
+     */
+    readonly autoMergeOptions?: AutoMergeOptions;
+    /**
+     * Auto-close stale issues and pull requests. To disable set `stale` to `false`.
+     *
+     * @default - see defaults in `StaleOptions`
+     */
+    readonly staleOptions?: StaleOptions;
+    /**
+     * Auto-close of stale issues and pull request. See `staleOptions` for options.
+     *
+     * @default false
+     */
+    readonly stale?: boolean;
+    /**
+     * Choose a method of providing GitHub API access for projen workflows.
+     *
+     * @default - use a personal access token named PROJEN_GITHUB_TOKEN
+     */
+    readonly projenCredentials?: GithubCredentials;
+    /**
+     * The name of a secret which includes a GitHub Personal Access Token to be
+     * used by projen workflows. This token needs to have the `repo`, `workflows`
+     * and `packages` scope.
+     *
+     * @default "PROJEN_GITHUB_TOKEN"
+     * @deprecated use `projenCredentials`
+     */
+    readonly projenTokenSecret?: string;
+}
+/**
+ * GitHub-based project.
+ *
+ * @deprecated This is a *temporary* class. At the moment, our base project
+ * types such as `NodeProject` and `JavaProject` are derived from this, but we
+ * want to be able to use these project types outside of GitHub as well. One of
+ * the next steps to address this is to abstract workflows so that different
+ * "engines" can be used to implement our CI/CD solutions.
+ */
+export declare class GitHubProject extends Project {
+    /**
+     * Access all github components.
+     *
+     * This will be `undefined` for subprojects.
+     */
+    readonly github: GitHub | undefined;
+    /**
+     * Access all VSCode components.
+     *
+     * This will be `undefined` for subprojects.
+     */
+    readonly vscode: VsCode | undefined;
+    /**
+     * Access for Gitpod
+     *
+     * This will be `undefined` if gitpod boolean is false
+     */
+    readonly gitpod: Gitpod | undefined;
+    /**
+     * Access for .devcontainer.json (used for GitHub Codespaces)
+     *
+     * This will be `undefined` if devContainer boolean is false
+     */
+    readonly devContainer: DevContainer | undefined;
+    readonly projectType: ProjectType;
+    /**
+     * Auto approve set up for this project.
+     */
+    readonly autoApprove?: AutoApprove;
+    constructor(options: GitHubProjectOptions);
+    /**
+     * Marks the provided file(s) as being generated. This is achieved using the
+     * github-linguist attributes. Generated files do not count against the
+     * repository statistics and language breakdown.
+     *
+     * @param glob the glob pattern to match (could be a file path).
+     *
+     * @see https://github.com/github/linguist/blob/master/docs/overrides.md
+     */
+    annotateGenerated(glob: string): void;
+}

package/lib/.types-compat/ts3.9/lib/github/github.d.ts

@@ -0,0 +1,110 @@
+import { GitHubActionsProvider } from "./actions-provider";
+import { Dependabot, DependabotOptions } from "./dependabot";
+import { GithubCredentials } from "./github-credentials";
+import { Mergify, MergifyOptions } from "./mergify";
+import { PullRequestTemplate } from "./pr-template";
+import { PullRequestLintOptions } from "./pull-request-lint";
+import { GithubWorkflow } from "./workflows";
+import { Component } from "../component";
+import { Project } from "../project";
+export interface GitHubOptions {
+    /**
+     * Whether mergify should be enabled on this repository or not.
+     *
+     * @default true
+     */
+    readonly mergify?: boolean;
+    /**
+     * Options for Mergify.
+     *
+     * @default - default options
+     */
+    readonly mergifyOptions?: MergifyOptions;
+    /**
+     * Enables GitHub workflows. If this is set to `false`, workflows will not be created.
+     *
+     * @default true
+     */
+    readonly workflows?: boolean;
+    /**
+     * Add a workflow that performs basic checks for pull requests, like
+     * validating that PRs follow Conventional Commits.
+     *
+     * @default true
+     */
+    readonly pullRequestLint?: boolean;
+    /**
+     * Options for configuring a pull request linter.
+     *
+     * @default - see defaults in `PullRequestLintOptions`
+     */
+    readonly pullRequestLintOptions?: PullRequestLintOptions;
+    /**
+     * Choose a method of providing GitHub API access for projen workflows.
+     *
+     * @default - use a personal access token named PROJEN_GITHUB_TOKEN
+     */
+    readonly projenCredentials?: GithubCredentials;
+    /**
+     * The name of a secret which includes a GitHub Personal Access Token to be
+     * used by projen workflows. This token needs to have the `repo`, `workflows`
+     * and `packages` scope.
+     *
+     * @default "PROJEN_GITHUB_TOKEN"
+     * @deprecated - use `projenCredentials`
+     */
+    readonly projenTokenSecret?: string;
+    /**
+     * Download files in LFS in workflows
+     *
+     * @default true if the associated project has `lfsPatterns`, `false` otherwise
+     */
+    readonly downloadLfs?: boolean;
+}
+export declare class GitHub extends Component {
+    /**
+     * Returns the `GitHub` component of a project or `undefined` if the project
+     * does not have a GitHub component.
+     */
+    static of(project: Project): GitHub | undefined;
+    /**
+     * The `Mergify` configured on this repository. This is `undefined` if Mergify
+     * was not enabled when creating the repository.
+     */
+    readonly mergify?: Mergify;
+    /**
+     * Are workflows enabled?
+     */
+    readonly workflowsEnabled: boolean;
+    /**
+     * GitHub API authentication method used by projen workflows.
+     */
+    readonly projenCredentials: GithubCredentials;
+    /**
+     *
+     */
+    readonly actions: GitHubActionsProvider;
+    private readonly _downloadLfs?;
+    constructor(project: Project, options?: GitHubOptions);
+    /**
+     * All workflows.
+     */
+    get workflows(): GithubWorkflow[];
+    /**
+     * Adds a workflow to the project.
+     * @param name Name of the workflow
+     * @returns a GithubWorkflow instance
+     */
+    addWorkflow(name: string): GithubWorkflow;
+    addPullRequestTemplate(...content: string[]): PullRequestTemplate;
+    addDependabot(options?: DependabotOptions): Dependabot;
+    /**
+     * Finds a GitHub workflow by name. Returns `undefined` if the workflow cannot be found.
+     * @param name The name of the GitHub workflow
+     */
+    tryFindWorkflow(name: string): undefined | GithubWorkflow;
+    /**
+     * Whether downloading from LFS is enabled for this GitHub project
+     */
+    get downloadLfs(): boolean;
+}

package/lib/.types-compat/ts3.9/lib/github/index.d.ts

@@ -0,0 +1,15 @@
+export * from "./github";
+export * from "./dependabot";
+export * from "./workflows";
+export * from "./actions-provider";
+export * from "./mergify";
+export * from "./pr-template";
+export * from "./mergify";
+export * from "./auto-merge";
+export * from "./auto-approve";
+export * from "./stale";
+export * from "./pull-request-lint";
+export * from "./github-credentials";
+export * from "./task-workflow";
+export * from "./github-project";
+export * as workflows from "./workflows-model";

package/lib/.types-compat/ts3.9/lib/github/mergify.d.ts

@@ -0,0 +1,81 @@
+import { GitHub } from "./github";
+import { Component } from "../component";
+/**
+ * The Mergify conditional operators that can be used are: `or` and `and`.
+ * Note: The number of nested conditions is limited to 3.
+ * @see https://docs.mergify.io/conditions/#combining-conditions-with-operators
+ */
+export interface MergifyConditionalOperator {
+    readonly or?: MergifyCondition[];
+    readonly and?: MergifyCondition[];
+}
+export type MergifyCondition = string | MergifyConditionalOperator;
+export interface MergifyRule {
+    /**
+     * The name of the rule. This is not used by the engine directly,
+     * but is used when reporting information about a rule.
+     */
+    readonly name: string;
+    /**
+     * A list of Conditions string that must match against the
+     * pull request for the rule to be applied.
+     * @see https://docs.mergify.io/conditions/#conditions
+     */
+    readonly conditions: MergifyCondition[];
+    /**
+     * A dictionary made of Actions that will be executed on the
+     * matching pull requests.
+     * @see https://docs.mergify.io/actions/#actions
+     */
+    readonly actions: {
+        [action: string]: any;
+    };
+}
+export interface MergifyQueue {
+    /**
+     * The name of the queue.
+     */
+    readonly name: string;
+    /**
+     * Merge method to use.
+     *
+     * Possible values are `merge`, `squash`, `rebase` or `fast-forward`.
+     * `fast-forward` is not supported on queues with `speculative_checks` > 1, `batch_size` > 1, or with `allow_inplace_checks` set to false.
+     *
+     * @default "merge"
+     */
+    readonly mergeMethod?: string;
+    /**
+     * Method to use to update the pull request with its base branch when the speculative check is done in-place.
+     *
+     * Possible values:
+     *  - `merge` to merge the base branch into the pull request.
+     *  - `rebase` to rebase the pull request against its base branch.
+     *
+     * Note that the `rebase` method has some drawbacks, see Mergify docs for details.
+     *
+     * @see https://docs.mergify.com/actions/queue/#queue-rules
+     *
+     * @default - `merge` for all merge methods except `fast-forward` where `rebase` is used
+     */
+    readonly updateMethod?: string;
+    /**
+     * A list of Conditions string that must match against the
+     * pull request for the pull request to be added to the queue.
+     * @see https://docs.mergify.com/conditions/#conditions
+     */
+    readonly conditions: MergifyCondition[];
+}
+export interface MergifyOptions {
+    readonly rules?: MergifyRule[];
+    readonly queues?: MergifyQueue[];
+}
+export declare class Mergify extends Component {
+    private readonly rules;
+    private readonly queues;
+    private yamlFile?;
+    constructor(github: GitHub, options?: MergifyOptions);
+    private createYamlFile;
+    addRule(rule: MergifyRule): void;
+    addQueue(queue: MergifyQueue): void;
+}

package/lib/.types-compat/ts3.9/lib/github/pr-template.d.ts

@@ -0,0 +1,19 @@
+import { GitHub } from "./github";
+import { TextFile } from "../textfile";
+/**
+ * Options for `PullRequestTemplate`.
+ */
+export interface PullRequestTemplateOptions {
+    /**
+     * The contents of the template. You can use `addLine()` to add additional lines.
+     *
+     * @default - a standard default template will be created.
+     */
+    readonly lines?: string[];
+}
+/**
+ * Template for GitHub pull requests.
+ */
+export declare class PullRequestTemplate extends TextFile {
+    constructor(github: GitHub, options?: PullRequestTemplateOptions);
+}

package/lib/.types-compat/ts3.9/lib/github/pull-request-lint.d.ts

@@ -0,0 +1,48 @@
+import { GitHub } from ".";
+import { Component } from "../component";
+/**
+ * Options for PullRequestLint
+ */
+export interface PullRequestLintOptions {
+    /**
+     * Validate that pull request titles follow Conventional Commits.
+     *
+     * @default true
+     * @see https://www.conventionalcommits.org/
+     */
+    readonly semanticTitle?: boolean;
+    /**
+     * Options for validating the conventional commit title linter.
+     * @default - title must start with "feat", "fix", or "chore"
+     */
+    readonly semanticTitleOptions?: SemanticTitleOptions;
+    /**
+     * Github Runner selection labels
+     * @default ["ubuntu-latest"]
+     */
+    readonly runsOn?: string[];
+}
+/**
+ * Options for linting that PR titles follow Conventional Commits.
+ * @see https://www.conventionalcommits.org/
+ */
+export interface SemanticTitleOptions {
+    /**
+     * Configure a list of commit types that are allowed.
+     * @default ["feat", "fix", "chore"]
+     */
+    readonly types?: string[];
+    /**
+     * Configure that a scope must always be provided.
+     * e.g. feat(ui), fix(core)
+     * @default false
+     */
+    readonly requireScope?: boolean;
+}
+/**
+ * Configure validations to run on GitHub pull requests.
+ * Only generates a file if at least one linter is configured.
+ */
+export declare class PullRequestLint extends Component {
+    constructor(github: GitHub, options?: PullRequestLintOptions);
+}

package/lib/.types-compat/ts3.9/lib/github/stale-util.d.ts

@@ -0,0 +1,8 @@
+import { StaleBehavior } from "./stale";
+interface Options {
+    readonly stale: number;
+    readonly close: number;
+    readonly type: string;
+}
+export declare function renderBehavior(behavior: StaleBehavior | undefined, opts: Options): Partial<StaleBehavior>;
+export {};

package/lib/.types-compat/ts3.9/lib/github/stale.d.ts

@@ -0,0 +1,85 @@
+import { GitHub } from "./github";
+import { Component } from "../component";
+/**
+ * Options for `Stale`.
+ */
+export interface StaleOptions {
+    /**
+     * How to handle stale pull requests.
+     *
+     * @default - By default, pull requests with no activity will be marked as
+     * stale after 14 days and closed within 2 days with relevant comments.
+     */
+    readonly pullRequest?: StaleBehavior;
+    /**
+     * How to handle stale issues.
+     *
+     * @default - By default, stale issues with no activity will be marked as
+     * stale after 60 days and closed within 7 days.
+     */
+    readonly issues?: StaleBehavior;
+    /**
+     * Github Runner selection labels
+     * @default ["ubuntu-latest"]
+     */
+    readonly runsOn?: string[];
+}
+/**
+ * Stale behavior.
+ */
+export interface StaleBehavior {
+    /**
+     * Determines if this behavior is enabled.
+     *
+     * Same as setting `daysBeforeStale` and `daysBeforeClose` to `-1`.
+     *
+     * @default true
+     */
+    readonly enabled?: boolean;
+    /**
+     * How many days until the issue or pull request is marked as "Stale". Set to -1 to disable.
+     * @default -
+     */
+    readonly daysBeforeStale?: number;
+    /**
+     * Days until the issue/PR is closed after it is marked as "Stale". Set to -1 to disable.
+     * @default -
+     */
+    readonly daysBeforeClose?: number;
+    /**
+     * The comment to add to the issue/PR when it becomes stale.
+     * @default "This pull request is now marked as stale because hasn\'t seen activity for a while. Add a comment or it will be closed soon."
+     */
+    readonly staleMessage?: string;
+    /**
+     * The comment to add to the issue/PR when it's closed
+     *
+     * @default "Closing this pull request as it hasn\'t seen activity for a while. Please add a comment @mentioning a maintainer when you are ready to continue."
+     */
+    readonly closeMessage?: string;
+    /**
+     * The label to apply to the issue/PR when it becomes stale.
+     * @default "stale"
+     */
+    readonly staleLabel?: string;
+    /**
+     * Label which exempt an issue/PR from becoming stale. Set to `[]` to disable.
+     *
+     * @default - ["backlog"]
+     */
+    readonly exemptLabels?: string[];
+}
+/**
+ * Warns and then closes issues and PRs that have had no activity for a specified amount of time.
+ *
+ * The default configuration will:
+ *
+ *  * Add a "Stale" label to pull requests after 14 days and closed after 2 days
+ *  * Add a "Stale" label to issues after 60 days and closed after 7 days
+ *  * If a comment is added, the label will be removed and timer is restarted.
+ *
+ * @see https://github.com/actions/stale
+ */
+export declare class Stale extends Component {
+    constructor(github: GitHub, options?: StaleOptions);
+}