projen 0.52.21 → 0.52.25

package/lib/javascript/node-project.d.ts

@@ -9,155 +9,130 @@ import { Bundler, BundlerOptions } from "./bundler";
 import { Jest, JestOptions } from "./jest";
 import { NodePackage, NodePackageManager, NodePackageOptions } from "./node-package";
 import { ProjenrcOptions } from "./projenrc";
-/**
- * @experimental
- */
 export interface NodeProjectOptions extends GitHubProjectOptions, NodePackageOptions, ReleaseProjectOptions {
     /**
-     * (experimental) License copyright owner.
+     * License copyright owner.
      *
      * @default - defaults to the value of authorName or "" if `authorName` is undefined.
-     * @experimental
      */
     readonly copyrightOwner?: string;
     /**
-     * (experimental) The copyright years to put in the LICENSE file.
+     * The copyright years to put in the LICENSE file.
      *
      * @default - current year
-     * @experimental
      */
     readonly copyrightPeriod?: string;
     /**
-     * (experimental) Version of projen to install.
+     * Version of projen to install.
      *
      * @default - Defaults to the latest version.
-     * @experimental
      */
     readonly projenVersion?: string;
     /**
-     * (experimental) Indicates of "projen" should be installed as a devDependency.
+     * Indicates of "projen" should be installed as a devDependency.
      *
      * @default true
-     * @experimental
      */
     readonly projenDevDependency?: boolean;
     /**
-     * (experimental) Define a GitHub workflow for building PRs.
-     *
+     * Define a GitHub workflow for building PRs.
      * @default - true if not a subproject
-     * @experimental
      */
     readonly buildWorkflow?: boolean;
     /**
-     * (experimental) Automatically update files modified during builds to pull-request branches.
-     *
-     * This means
+     * Automatically update files modified during builds to pull-request branches. This means
      * that any files synthesized by projen or e.g. test snapshots will always be up-to-date
      * before a PR is merged.
      *
      * Implies that PR builds do not have anti-tamper checks.
      *
      * @default true
-     * @experimental
      */
     readonly mutableBuild?: boolean;
     /**
-     * (experimental) Define a GitHub workflow step for sending code coverage metrics to https://codecov.io/ Uses codecov/codecov-action@v1 A secret is required for private repos. Configured with @codeCovTokenSecret.
-     *
+     * Define a GitHub workflow step for sending code coverage metrics to https://codecov.io/
+     * Uses codecov/codecov-action@v1
+     * A secret is required for private repos. Configured with @codeCovTokenSecret
      * @default false
-     * @experimental
      */
     readonly codeCov?: boolean;
     /**
-     * (experimental) Define the secret name for a specified https://codecov.io/ token A secret is required to send coverage for private repositories.
-     *
+     * Define the secret name for a specified https://codecov.io/ token
+     * A secret is required to send coverage for private repositories
      * @default - if this option is not specified, only public repositories are supported
-     * @experimental
      */
     readonly codeCovTokenSecret?: string;
     /**
-     * (deprecated) DEPRECATED: renamed to `release`.
+     * DEPRECATED: renamed to `release`.
      *
      * @default - true if not a subproject
      * @deprecated see `release`.
      */
     readonly releaseWorkflow?: boolean;
     /**
-     * (experimental) Add release management to this project.
+     * Add release management to this project.
      *
      * @default - true (false for subprojects)
-     * @experimental
      */
     readonly release?: boolean;
     /**
-     * (experimental) The name of the main release branch.
+     * The name of the main release branch.
      *
      * @default "main"
-     * @experimental
      */
     readonly defaultReleaseBranch: string;
     /**
-     * (experimental) Workflow steps to use in order to bootstrap this repo.
+     * Workflow steps to use in order to bootstrap this repo.
      *
      * @default "yarn install --frozen-lockfile && yarn projen"
-     * @experimental
      */
     readonly workflowBootstrapSteps?: any[];
     /**
-     * (experimental) The git identity to use in workflows.
+     * The git identity to use in workflows.
      *
      * @default - GitHub Actions
-     * @experimental
      */
     readonly workflowGitIdentity?: GitIdentity;
     /**
-     * (experimental) Automatically release to npm when new versions are introduced.
-     *
+     * Automatically release to npm when new versions are introduced.
      * @default false
-     * @experimental
      */
     readonly releaseToNpm?: boolean;
     /**
-     * (experimental) The node version to use in GitHub workflows.
+     * The node version to use in GitHub workflows.
      *
      * @default - same as `minNodeVersion`
-     * @experimental
      */
     readonly workflowNodeVersion?: string;
     /**
-     * (experimental) Use dependabot to handle dependency upgrades.
-     *
+     * Use dependabot to handle dependency upgrades.
      * Cannot be used in conjunction with `depsUpgrade`.
      *
      * @default false
-     * @experimental
      */
     readonly dependabot?: boolean;
     /**
-     * (experimental) Options for dependabot.
+     * Options for dependabot.
      *
      * @default - default options
-     * @experimental
      */
     readonly dependabotOptions?: DependabotOptions;
     /**
-     * (experimental) Use github workflows to handle dependency upgrades.
-     *
+     * Use github workflows to handle dependency upgrades.
      * Cannot be used in conjunction with `dependabot`.
      *
      * @default true
-     * @experimental
      */
     readonly depsUpgrade?: boolean;
     /**
-     * (experimental) Options for depsUpgrade.
+     * Options for depsUpgrade.
      *
      * @default - default options
-     * @experimental
      */
     readonly depsUpgradeOptions?: UpgradeDependenciesOptions;
     /**
-     * (deprecated) Periodically submits a pull request for projen upgrades (executes `yarn projen:upgrade`).
+     * Periodically submits a pull request for projen upgrades (executes `yarn
+     * projen:upgrade`).
      *
      * This setting is a GitHub secret name which contains a GitHub Access Token
      * with `repo` and `workflow` permissions.
@@ -168,11 +143,13 @@ export interface NodeProjectOptions extends GitHubProjectOptions, NodePackageOpt
      * To create a personal access token see https://github.com/settings/tokens
      *
      * @default - no automatic projen upgrade pull requests
+     *
      * @deprecated use `githubTokenSecret` instead.
      */
     readonly projenUpgradeSecret?: string;
     /**
-     * (deprecated) Automatically approve projen upgrade PRs, allowing them to be merged by mergify (if configued).
+     * Automatically approve projen upgrade PRs, allowing them to be
+     * merged by mergify (if configued).
      *
      * Throw if set to true but `autoApproveOptions` are not defined.
      *
@@ -181,169 +158,138 @@ export interface NodeProjectOptions extends GitHubProjectOptions, NodePackageOpt
      */
     readonly projenUpgradeAutoMerge?: boolean;
     /**
-     * (experimental) Automatically approve projen upgrade PRs, allowing them to be merged by mergify (if configued).
+     * Automatically approve projen upgrade PRs, allowing them to be
+     * merged by mergify (if configued).
      *
      * Throw if set to true but `autoApproveOptions` are not defined.
      *
      * @default false
-     * @experimental
      */
     readonly autoApproveProjenUpgrades?: boolean;
     /**
-     * (experimental) Automatically approve deps upgrade PRs, allowing them to be merged by mergify (if configued).
+     * Automatically approve deps upgrade PRs, allowing them to be
+     * merged by mergify (if configued).
      *
      * Throw if set to true but `autoApproveOptions` are not defined.
      *
      * @default - true
-     * @experimental
      */
     readonly autoApproveUpgrades?: boolean;
     /**
-     * (experimental) Customize the projenUpgrade schedule in cron expression.
+     * Customize the projenUpgrade schedule in cron expression.
      *
-     * @default [ "0 6 * * *" ]
-     * @experimental
+     @default [ "0 6 * * *" ]
      */
     readonly projenUpgradeSchedule?: string[];
     /**
-     * (experimental) Defines an .npmignore file. Normally this is only needed for libraries that are packaged as tarballs.
+     * Defines an .npmignore file. Normally this is only needed for libraries that
+     * are packaged as tarballs.
      *
      * @default true
-     * @experimental
      */
     readonly npmignoreEnabled?: boolean;
     /**
-     * (deprecated) Additional entries to .npmignore.
-     *
+     * Additional entries to .npmignore.
      * @deprecated - use `project.addPackageIgnore`
      */
     readonly npmignore?: string[];
     /**
-     * (experimental) Include a GitHub pull request template.
+     * Include a GitHub pull request template.
      *
      * @default true
-     * @experimental
      */
     readonly pullRequestTemplate?: boolean;
     /**
-     * (experimental) The contents of the pull request template.
+     * The contents of the pull request template.
      *
      * @default - default content
-     * @experimental
      */
     readonly pullRequestTemplateContents?: string[];
     /**
-     * (experimental) Setup prettier.
+     * Setup prettier.
      *
      * @default false
-     * @experimental
      */
     readonly prettier?: boolean;
     /**
-     * (experimental) Prettier options.
-     *
+     * Prettier options
      * @default - default options
-     * @experimental
      */
     readonly prettierOptions?: PrettierOptions;
     /**
-     * (experimental) Additional entries to .gitignore.
-     *
-     * @experimental
+     * Additional entries to .gitignore
      */
     readonly gitignore?: string[];
     /**
-     * (experimental) Setup jest unit tests.
-     *
+     * Setup jest unit tests
      * @default true
-     * @experimental
      */
     readonly jest?: boolean;
     /**
-     * (experimental) Jest options.
-     *
+     * Jest options
      * @default - default options
-     * @experimental
      */
     readonly jestOptions?: JestOptions;
     /**
-     * (experimental) Generate (once) .projenrc.js (in JavaScript). Set to `false` in order to disable .projenrc.js generation.
+     * Generate (once) .projenrc.js (in JavaScript). Set to `false` in order to disable
+     * .projenrc.js generation.
      *
      * @default - true if projenrcJson is false
-     * @experimental
      */
     readonly projenrcJs?: boolean;
     /**
-     * (experimental) Options for .projenrc.js.
-     *
+     * Options for .projenrc.js
      * @default - default options
-     * @experimental
      */
     readonly projenrcJsOptions?: ProjenrcOptions;
     /**
-     * (experimental) Options for `Bundler`.
-     *
-     * @experimental
+     * Options for `Bundler`.
      */
     readonly bundlerOptions?: BundlerOptions;
     /**
-     * (experimental) A directory which will contain build artifacts.
+     * A directory which will contain build artifacts.
      *
      * @default "dist"
-     * @experimental
      */
     readonly artifactsDirectory?: string;
     /**
-     * (experimental) Defines a `package` task that will produce an npm tarball under the artifacts directory (e.g. `dist`).
+     * Defines a `package` task that will produce an npm tarball under the
+     * artifacts directory (e.g. `dist`).
      *
      * @default true
-     * @experimental
      */
     readonly package?: boolean;
     /**
-     * (experimental) Build workflow triggers.
-     *
+     * Build workflow triggers
      * @default "{ pullRequest: {}, workflowDispatch: {} }"
-     * @experimental
      */
     readonly buildWorkflowTriggers?: Triggers;
 }
 /**
- * (experimental) Automatic bump modes.
- *
- * @experimental
+ * Automatic bump modes
  */
 export declare enum AutoRelease {
     /**
-     * (experimental) Automatically bump & release a new version for every commit to "main".
-     *
-     * @experimental
+     * Automatically bump & release a new version for every commit to "main"
      */
     EVERY_COMMIT = 0,
     /**
-     * (experimental) Automatically bump & release a new version on a daily basis.
-     *
-     * @experimental
+     * Automatically bump & release a new version on a daily basis.
      */
     DAILY = 1
 }
 /**
- * (experimental) Node.js project.
+ * Node.js project
  *
- * @experimental
  * @pjid node
  */
 export declare class NodeProject extends GitHubProject {
     /**
-     * (experimental) API for managing the node package.
-     *
-     * @experimental
+     * API for managing the node package.
      */
     readonly package: NodePackage;
     /**
-     * (experimental) The .npmignore file.
-     *
-     * @experimental
+     * The .npmignore file.
      */
     readonly npmignore?: IgnoreFile;
     /**
@@ -355,241 +301,187 @@ export declare class NodeProject extends GitHubProject {
      */
     get entrypoint(): string;
     /**
-     * (experimental) Automatic PR merges.
-     *
-     * @experimental
+     * Automatic PR merges.
      */
     readonly autoMerge?: AutoMerge;
     /**
-     * (experimental) The PR build GitHub workflow.
-     *
-     * `undefined` if `buildWorkflow` is disabled.
-     *
-     * @experimental
+     * The PR build GitHub workflow. `undefined` if `buildWorkflow` is disabled.
      */
     readonly buildWorkflow?: BuildWorkflow;
     /**
-     * (deprecated) Package publisher.
-     *
-     * This will be `undefined` if the project does not have a
+     * Package publisher. This will be `undefined` if the project does not have a
      * release workflow.
      *
      * @deprecated use `release.publisher`.
      */
     readonly publisher?: Publisher;
     /**
-     * (experimental) Release management.
-     *
-     * @experimental
+     * Release management.
      */
     readonly release?: Release;
     /**
-     * (experimental) Minimum node.js version required by this package.
-     *
-     * @experimental
+     * Minimum node.js version required by this package.
      */
     get minNodeVersion(): string | undefined;
     /**
-     * (experimental) Maximum node version required by this pacakge.
-     *
-     * @experimental
+     * Maximum node version required by this pacakge.
      */
     get maxNodeVersion(): string | undefined;
     private readonly nodeVersion?;
     /**
-     * (deprecated) The package manager to use.
+     * The package manager to use.
      *
      * @deprecated use `package.packageManager`
      */
     get packageManager(): NodePackageManager;
     /**
-     * (experimental) The command to use to run scripts (e.g. `yarn run` or `npm run` depends on the package manager).
-     *
-     * @experimental
+     * The command to use to run scripts (e.g. `yarn run` or `npm run` depends on the package manager).
      */
     readonly runScriptCommand: string;
     /**
-     * (experimental) The Jest configuration (if enabled).
-     *
-     * @experimental
+     * The Jest configuration (if enabled)
      */
     readonly jest?: Jest;
     /**
      * @deprecated use `package.addField(x, y)`
      */
     get manifest(): any;
-    /**
-     * @experimental
-     */
     readonly bundler: Bundler;
     /**
-     * (experimental) The build output directory.
-     *
-     * An npm tarball will be created under the `js`
+     * The build output directory. An npm tarball will be created under the `js`
      * subdirectory. For example, if this is set to `dist` (the default), the npm
      * tarball will be placed under `dist/js/boom-boom-1.2.3.tg`.
-     *
-     * @experimental
      */
     readonly artifactsDirectory: string;
     /**
-     * (experimental) The location of the npm tarball after build (`${artifactsDirectory}/js`).
-     *
-     * @experimental
+     * The location of the npm tarball after build (`${artifactsDirectory}/js`).
      */
     readonly artifactsJavascriptDirectory: string;
     /**
-     * (experimental) The upgrade workflow.
-     *
-     * @experimental
+     * The upgrade workflow.
      */
     readonly upgradeWorkflow?: UpgradeDependencies;
     private readonly workflowBootstrapSteps;
     private readonly workflowGitIdentity;
-    /**
-     * @experimental
-     */
     readonly prettier?: Prettier;
-    /**
-     * @experimental
-     */
     constructor(options: NodeProjectOptions);
-    /**
-     * @experimental
-     */
     addBins(bins: Record<string, string>): void;
     /**
-     * (experimental) Replaces the contents of an npm package.json script.
+     * Replaces the contents of an npm package.json script.
      *
-     * @param name The script name.
-     * @param command The command to execute.
-     * @experimental
+     * @param name The script name
+     * @param command The command to execute
      */
     setScript(name: string, command: string): void;
     /**
-     * (experimental) Removes the npm script (always successful).
-     *
+     * Removes the npm script (always successful).
      * @param name The name of the script.
-     * @experimental
      */
     removeScript(name: string): void;
     /**
-     * (experimental) Indicates if a script by the name name is defined.
-     *
-     * @param name The name of the script.
-     * @experimental
+     * Indicates if a script by the name name is defined.
+     * @param name The name of the script
      */
     hasScript(name: string): boolean;
     /**
-     * (deprecated) DEPRECATED.
-     *
+     * DEPRECATED
      * @deprecated use `project.compileTask.exec()`
      */
     addCompileCommand(...commands: string[]): void;
     /**
-     * (deprecated) DEPRECATED.
-     *
+     * DEPRECATED
      * @deprecated use `project.testTask.exec()`
      */
     addTestCommand(...commands: string[]): void;
     /**
-     * (experimental) Directly set fields in `package.json`.
-     *
-     * @param fields The fields to set.
-     * @experimental
+     * Directly set fields in `package.json`.
+     * @param fields The fields to set
      */
     addFields(fields: {
         [name: string]: any;
     }): void;
     /**
-     * (experimental) Adds keywords to package.json (deduplicated).
-     *
-     * @param keywords The keywords to add.
-     * @experimental
+     * Adds keywords to package.json (deduplicated)
+     * @param keywords The keywords to add
      */
     addKeywords(...keywords: string[]): void;
     /**
-     * (experimental) Returns the set of workflow steps which should be executed to bootstrap a workflow.
+     * Returns the set of workflow steps which should be executed to bootstrap a
+     * workflow.
      *
      * @param options Options.
      * @returns Job steps
-     * @experimental
      */
     renderWorkflowSetup(options?: RenderWorkflowSetupOptions): JobStep[];
     /**
-     * (experimental) Defines normal dependencies.
+     * Defines normal dependencies.
      *
-     * @param deps Names modules to install.
-     * @experimental
+     * @param deps Names modules to install. By default, the the dependency will
+     * be installed in the next `npx projen` run and the version will be recorded
+     * in your `package.json` file. You can upgrade manually or using `yarn
+     * add/upgrade`. If you wish to specify a version range use this syntax:
+     * `module@^7`.
      */
     addDeps(...deps: string[]): void;
     /**
-     * (experimental) Defines development/test dependencies.
+     * Defines development/test dependencies.
      *
-     * @param deps Names modules to install.
-     * @experimental
+     * @param deps Names modules to install. By default, the the dependency will
+     * be installed in the next `npx projen` run and the version will be recorded
+     * in your `package.json` file. You can upgrade manually or using `yarn
+     * add/upgrade`. If you wish to specify a version range use this syntax:
+     * `module@^7`.
      */
     addDevDeps(...deps: string[]): void;
     /**
-     * (experimental) Defines peer dependencies.
+     * Defines peer dependencies.
      *
      * When adding peer dependencies, a devDependency will also be added on the
      * pinned version of the declared peer. This will ensure that you are testing
      * your code against the minimum version required from your consumers.
      *
-     * @param deps Names modules to install.
-     * @experimental
+     * @param deps Names modules to install. By default, the the dependency will
+     * be installed in the next `npx projen` run and the version will be recorded
+     * in your `package.json` file. You can upgrade manually or using `yarn
+     * add/upgrade`. If you wish to specify a version range use this syntax:
+     * `module@^7`.
      */
     addPeerDeps(...deps: string[]): void;
     /**
-     * (experimental) Defines bundled dependencies.
+     * Defines bundled dependencies.
      *
      * Bundled dependencies will be added as normal dependencies as well as to the
      * `bundledDependencies` section of your `package.json`.
      *
-     * @param deps Names modules to install.
-     * @experimental
+     * @param deps Names modules to install. By default, the the dependency will
+     * be installed in the next `npx projen` run and the version will be recorded
+     * in your `package.json` file. You can upgrade manually or using `yarn
+     * add/upgrade`. If you wish to specify a version range use this syntax:
+     * `module@^7`.
      */
     addBundledDeps(...deps: string[]): void;
-    /**
-     * (experimental) Exclude these files from the bundled package.
-     *
-     * Implemented by project types based on the
-     * packaging mechanism. For example, `NodeProject` delegates this to `.npmignore`.
-     *
-     * @experimental
-     */
     addPackageIgnore(pattern: string): void;
     private addLicense;
     private addDefaultGitIgnore;
     /**
-     * (experimental) Returns the shell command to execute in order to run a task.
-     *
-     * This will
+     * Returns the shell command to execute in order to run a task. This will
      * typically be `npx projen TASK`.
      *
-     * @param task The task for which the command is required.
-     * @experimental
+     * @param task The task for which the command is required
      */
     runTaskCommand(task: Task): string;
     /**
-     * (experimental) The job ID of the build workflow.
-     *
-     * @experimental
+     * The job ID of the build workflow.
      */
     get buildWorkflowJobId(): string | undefined;
 }
 /**
- * (experimental) Options for `renderInstallSteps()`.
- *
- * @experimental
+ * Options for `renderInstallSteps()`.
  */
 export interface RenderWorkflowSetupOptions {
     /**
-     * (experimental) Should the pacakge lockfile be updated?
-     *
+     * Should the pacakge lockfile be updated?
      * @default false
-     * @experimental
      */
     readonly mutable?: boolean;
 }