projen 0.76.5 → 0.76.7

package/docs/cdk8s.md

@@ -1,39 +0,0 @@
-# CDK8s Projects
-
-We support two types of projects for Kubernetes powered by the CDK8s:
-**apps** and **libraries**. Apps represent complete Kubernetes applications
-while libraries vend constructs which can be consumed by other libraries or
-by apps. Libraries are published to public or internal package managers (npm,
-PyPI, Maven, NuGet, etc) while apps are deployed into Kubernetes clusters.
-
-This section describes features that are available in both CDK8s libraries and
-applications.
-
-## Integration Snapshot Tests
-
-Files in the `test/` tree with the `.integ.ts` suffix are recognized as
-*integration snapshot tests*.
-
-Each test is a simple CDK8s app which exercises certain construct(s) within
-the project. A test is considered passing if the app can be successfully
-deployed.
-
-To create/update the snapshot, developers are expected to execute the task
-`integ:NAME:deploy` with a kubectl configuration for their personal development
-environment, such as K3s, Microk8s, Kind, Rancher Desktop, or otherwise. This
-task will deploy the test app by applying it with kubectl. Upon successful
-deployment (i.e. the test passed), the snapshot will be captured and stored
-under a directory called `xxx.integ.snapshot` next to the test entrypoint. This
-directory should be committed to the repository.
-
-During builds (either local or within a workflow), the task `integ:NAME:assert`
-will be executed. This task synthesizes the test app and compares the output to
-the captured snapshot. The build will fail if the output differs.
-
-For each integration test, the following set of tasks are created:
-
-|Task|Description|
-|----|-----------|
-|`integ:NAME:deploy`|Deploys the test app and updates the snapshot.|
-|`integ:NAME:assert`|Synthesizes the test app and compares it with the snapshot (this is the task that runs during build)|
-|`integ:NAME:snapshot`|Synthesizes the test app and updates the snapshot (not recommended to use because it bypasses deployment).|

package/docs/circleci.md

@@ -1,87 +0,0 @@
-# CircleCi
-
-CircleCi uses `.circleci/config.yml` to specify the configuration of a pipeline. 
-Configuration reference can be found [here](https://circleci.com/docs/2.0/configuration-reference).
-
-Initial configuration can be created through options of [CircleCiProps](src/circleci/model.ts).
-Additionally, you can add workflows or orbs later to your pipeline.
-For full configuration example checkout [Circleci Tests](test/cirlceci/circleci.test.ts)
-
-```js
-const { circleci, typescript } = require('projen');
-
-const project = new typescript.TypeScriptProject({
-    name: 'projen-example',
-    defaultReleaseBranch: 'main',
-});
-
-const c = new circleci.Circleci(project, {
-    orbs: {
-        node: 'circleci/node@5.0.1',
-    },
-    jobs: [
-        {
-            identifier: "release",
-            resourceClass: circleci.ResourceClass.SMALL,
-            docker: [{
-                image: "cimg/node:lts"
-            }],
-            steps: [
-                "checkout",
-                {run: {command: "npx semantic-release"}},
-            ]
-        },
-        {
-            identifier: 'integ-test',
-            docker: [{
-                image: "cimg/golang:lts"
-            }],
-            steps: [
-                "checkout",
-                {
-                    "go/test": {
-                        covermode: "atomic",
-                        failfast: true,
-                        race: true,
-                    },
-                }
-            ]
-        }
-    ],
-    workflows: [
-        {
-            identifier: 'build',
-            jobs: [
-                {
-                    identifier: 'node/test',
-                    orbParameters: {
-                        "test-results-for": "jest"
-                    }
-                },
-                {
-                    identifier: "release",
-                    filters: circleci.FilterMainBranchOnly,
-                }
-            ],
-        },
-    ],
-});
-c.addOrb("go", "circleci/go@1.7.1")
-c.addWorkflow({
-    identifier: 'nightly',
-    triggers: [
-        {
-            schedule: {
-                cron: '0 0 * * *',
-                filters: circleci.FilterMainBranchOnly,
-            }
-        }
-    ],
-    jobs: [
-        {
-            identifier: 'integ-test'
-        }
-    ]
-})
-project.synth();
-```

package/docs/components.md

@@ -1,21 +0,0 @@
-# Components
-
-Components are building blocks that can be composed together into projects. They
-represent a self-contained project feature.
-
-When a component is created, it is associated with a specific project:
-
-```ts
-const p = new Project(...);
-
-new MyComponent(p);
-new YourComponent(p, { /* options */ });
-```
-
-Projects can be queried for which components have been added to them:
-
-```ts
-for (const c of p.components) {
-  // do something with `component`
-}
-```

package/docs/deps.md

@@ -1,62 +0,0 @@
-# Dependencies
-
-Dependencies are an intrinsic part of every software project.
-
-The `Dependencies` component is responsible to track the list of dependencies a
-project has, and then used by project types as the model for rendering
-project-specific dependency manifests such as the dependencies section
-`package.json` files.
-
-To add a dependency you can use a project-type specific API such as
-`nodeProject.addDeps()` or use the generic API of `project.deps`:
-
-```ts
-project.deps.addDependency(dep, type);
-```
-
-By default, `npx projen` will automatically install dependencies in your
-project if they are not already installed.
-
-## Semantic Requirements
-
-The first argument (`dep`) is a string in the form `MODULE[@VERSION]` where
-`MODULE` is the package-manager specific name of the dependency (i.e. for node
-projects, this is the npm module name) and `VERSION` is an optional [semantic
-version] requirement (e.g. `@^7`).
-
-## Dependency Types
-
-The second argument (`type`) defines the dependency type and is one of:
-
-- `DependencyType.RUNTIME`: The dependency is required for the program/library during runtime.
-- `DependencyType.PEER`: The dependency is required at runtime but only a single
-  copy of the module must exist in the dependency closure of the consumer. In
-  most package managers (PyPI, NuGet, Maven) there is no difference between
-  runtime and peer dependencies (since all dependencies are installed as peers),
-  but in npm, this is an important distinction. Prior to npm@7, peer
-  dependencies must be installed explicitly by consumers.
-- `DependencyType.BUNDLED`: A runtime dependency that is bundled and shipped
-  with the module, so consumers are not required to install it.
-- `DependencyType.BUILD`: The dependency is required to run the `build` task.
-- `DependencyType.TEST`: The dependency is required to run the `test` task.
-- `DependencyType.DEVENV`: The dependency is required for development (e.g. IDE plugins).
-
-[semantic version]: https://semver.org
-
-## Overriding Dependency Specifications
-
-If a dependency is added multiple times, the last specification will prevail.
-This allows you to override dependency specs added by projects or components.
-
-For example, if you wish to change the version of the TypeScript compiler used
-in TypeScript projects:
-
-```ts
-const { typescript } = require('projen');
-
-const project = new typescript.TypeScriptProject({ 
-  /* ... */ 
-});
-project.addDevDeps('typescript@^5');
-project.synth();
-```

package/docs/eject.md

@@ -1,30 +0,0 @@
-# Ejecting
-
-To stop from using projen to manage your project configuration,
-you can `eject` at any time and continue to manage your configuration manually.
-
-Running `projen eject` will do the following:
-
-- uninstall projen as a project dependency
-- change projen-managed files from readonly to user-writeable
-- remove "Generated by projen" markers from projen-generated files
-- remove projen metadata files
-- remove the projen synthesis step from the `build` task
-- remove the `default` and `eject` tasks
-- "backup" projenrc files to `.projenrc.xyz.bak`
-- a separate task runner file is added to the root directory (see Tasks below
-  for more information)
-
-You do not need to ever use `eject`, but the option is available if the means of
-customization provided by projen are no longer suitable your project.
-
-## Tasks
-
-A script will be added to your project so that you can continue using existing
-tasks by running `scripts/run-task <task>` in your command line (or running `npm
-run <task>` in node-based projects) if you so choose. You must retain the
-`tasks.json` file found in the `.projen/` folder to use the task runner.
-
-> Note: it is possible some tasks may not work after projen is ejected due to
-the use of projen "builtin" steps. See
-https://github.com/projen/projen/issues/1563 for more information.

package/docs/escape-hatches.md

@@ -1,113 +0,0 @@
-# Escape hatches
-
-It's possible projen doesn't have the right high-level or low-level APIs that
-you need for managing your project configuration. If you think there's an API
-that would be useful, first consider checking on GitHub to see if anyone else
-has the same problem, or consider opening an issue! But in the meantime, there
-are ways you can bypass projen's regular APIs to add special configuration code.
-
-## Object File Patches
-
-For any "object"-based files, such as JSON, YAML, TOML, or XML, you can
-patch its contents using the JSON Patch standard:
-
-```ts
-// Get the ObjectFile
-const packageJson = project.tryFindObjectFile('package.json');
-
-// Adds a value to an object or inserts it into an array at a giving position
-packageJson.patch(JsonPatch.add('/author/name', 'A. Mused'));
-packageJson.patch(JsonPatch.add('/keywords/1', 'web'));
-// Use the - character to insert at the end of an array
-packageJson.patch(JsonPatch.add('/keywords/-', 'productivity'));
-
-
-// Removes a value from an object or array
-packageJson.patch(JsonPatch.remove('/author'));
-packageJson.patch(JsonPatch.remove('/keywords/1'));
-
-
-// Copy a value from one location in the document to another
-packageJson.patch(JsonPatch.copy('/homepage', '/bugs/url'));
-
-// Replace a value. This is equivalent to a remove, followed by an add.
-packageJson.patch(JsonPatch.replace('/keywords/1', 'iot'));
-
-// Move a value. This is equivalent to a copy, followed by a remove.
-packageJson.patch(JsonPatch.move('/homepage', '/bugs/url'));
-```
-
-`ObjectFile.patch()` accepts multiple patch instructions at a time, and each set is considered an atomic operation.
-Order matters here: For example you can successfully `add('/foo', 'bar')` and then `remove('/foo')`.
-However reversing the order will fail if `/for` does not exists.
-
-### Asserting values
-
-Another feature is asserting values.
-This can be used to conditionally set values, or to assert a file is an expected state.
-Adding a `test` instruction, will run the checks in the context of the atomic operation they are part of.
-By default, atomic operations with failing tests are silently skipped.
-
-```ts
-// If the test operation passes, continue to add the new value
-// If the test operation fails, all instructions are disregarded
-packageJson.patch(
-  JsonPatch.test('/author/name', 'A. Noyed'),
-  JsonPatch.replace('/author/name', 'A. Mused'),
-  JsonPatch.add('/author/email', 'amused@example.com'),
-);
-
-// This will run regardless of the outcome previous statement
-packageJson.patch(JsonPatch.add('/keywords/-', 'productivity'));
-```
-
-In certain situations you might want to fail the whole synthesis:
-
-```ts
-// Fails synthesis completely
-packageJson.patch(
-  JsonPatch.test('/author/name', 'A. Noyed', TestFailureBehavior.FAIL_SYNTHESIS),
-);
-```
-
-## Overrides
-
-An alternative is to override properties through the `addOverride`, `addDeletionOverride`,
-`addToArray` and `patch` methods accessible on the file component:
-
-```ts
-// Get the ObjectFile
-const packageJson = project.tryFindObjectFile('package.json');
-
-// Use dot notation to address inside the object
-packageJson.addOverride('description', 'the next generation of logging!');
-packageJson.addOverride('keywords', ['experimental', 'web', 'productivity', 'exciting']);
-
-// Use one-based array indices to override specific array elements
-packageJson.addOverride('funding.2.type', 'individual');
-
-// New elements can be added to the end of an array
-packageJson.addToArray('keywords', 'logging', 'next-gen');
-
-// Values can be deleted
-packageJson.addDeletionOverride('author.organization');
-```
-
-## Removing files
-
-You can remove a file from the project through `tryRemoveFile` method on the
-`Project` class.
-
-```ts
-new TextFile(project, "hello.txt", { lines: "original" });
-
-project.tryRemoveFile("hello.txt");
-
-new TextFile(project, "hello.txt", { lines: "better" });
-```
-
-> Note: It's recommended that this used carefully since removing files may be
-unexpected for users depending on where it's used. For example, if you created a
-component named `MyFancyGitIgnore` and had it remove any existing `.gitignore`
-files in the project, then users may be surprised when customizations for their
-existing `.gitignore` file are nullified.

package/docs/github.md

@@ -1,155 +0,0 @@
-# GitHub
-
-By default, many projects are initialized with `GitHub` component to enabled GitHub as the default provider for CI/CD workflows. See <https://docs.github.com/en/actions> for more information.
-
-The use of GitHub (and generating corresponding files in `.github`) can be disabled by specifying `github: false` in your project options.
-
-## GitHub API access
-
-Several workflows generated by projen use APIs that are not available through
-the permissions of [GITHUB_TOKEN]. To use these workflows, you must provide
-either a Personal Access Token (PAT) or a GitHub App to provide API access.
-
-[GITHUB_TOKEN]: https://docs.github.com/en/actions/security-guides/automatic-token-authentication
-
-### Personal Access Token (classic)
-
-Follow the [GitHub docs
-instructions](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token#creating-a-personal-access-token-classic)
-for creating a personal access token (classic).
-When creating the classic PAT, grant the token `repo`, `workflow` and `write:packages` permissions.
-
-Add the token as a secret to your repo under the name `PROJEN_GITHUB_TOKEN`.
-
-### Fine-grained Personal Access Token (beta)
-
-Follow the [GitHub docs
-instructions](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token#creating-a-fine-grained-personal-access-token)
-for creating a fine-grained personal access token (beta).
-
-Select the repositories you want to use this token for.
-You can reuse the same token for multiple repositories if you select them here.
-However you should choose the minimal repository access that meets your needs.
-
-Under Permissions, select the following Repository Permissions:
-
-- `Contents` - Read and write
-- `Metadata` - Read-only (automatically added)
-- `Pull requests` - Read and write
-- `Workflows` - Read and write
-
-Add the token as a secret to your repo under the name `PROJEN_GITHUB_TOKEN`.
-
-### GitHub App
-
-Follow the [GitHub docs instructions](https://docs.github.com/en/developers/apps/building-github-apps/creating-a-github-app) for creating a GitHub App. Enable read & write permission for "Contents" and "Pull Request" scopes.
-
-Add the App ID as a secret to your repo under the name `PROJEN_APP_ID` and the private key you generate as a secret to your repo under the name `PROJEN_APP_PRIVATE_KEY`.
-
-Then, configure your projenrc file to use the GitHub app for API access:
-
-```ts
-const { github, javascript } = require('projen');
-
-const project = new javascript.NodeProject({
-  // ...other options
-  githubOptions: {
-    projenCredentials: github.GithubCredentials.fromApp({ ... }),
-  },
-});
-```
-
-If the GitHub app you are using has additional permissions assigned, you can limit the permissions used on the token within the jobs in the workflow to only allow access to write repository contents and create the pull request:
-
-```ts
-const { github, javascript } = require('projen');
-
-const project = new javascript.NodeProject({
-  // ...other options
-  githubOptions: {
-    projenCredentials: github.GithubCredentials.fromApp({
-      // ...other options
-      permissions: {
-        pullRequests: github.workflows.AppPermission.WRITE,
-        contents: github.workflows.AppPermission.WRITE,
-      }
-    }),
-  },
-});
-```
-
-## Workflows
-
-See the `GitHub`, `GithubWorkflow`, and `Job` types in the [API
-reference](./api/API.md) for currently available APIs.
-
-Example code of creating a GitHub workflow:
-<https://github.com/projen/projen/blob/65b4194c163f47ba4842981b0c92dbe516be787b/src/github/auto-approve.ts#L67-L105>
-
-### Actions versions
-
-Most workflows included with projen are constraint to a major version, in order for updates to be available immediately.
-However it is a good security practice to lock versions of GitHub Actions down to explicit commit hashes.
-To achieve this, you can define explicit overrides for any action used in workflows.
-
-The replace all occurrences of an action can be overridden, irregardless of the action version:
-
-```ts
-project.github.actions.set("actions/checkout", "actions/checkout@ac59398");
-```
-
-Any use of `actions/checkout` is now changed to this:
-
-```yaml
-steps:
-  - uses: actions/checkout@ac59398
-```
-
-Alternatively, any specific action version can be overridden.
-This can be useful when a specific version of an action must be used due to incompatible changes.
-Specific overrides take precedence over overrides without a version.
-
-```ts
-project.github.actions.set("actions/checkout@v3", "actions/checkout@ac59398");
-project.github.actions.set("actions/checkout", "actions/checkout@main");
-```
-
-Different versions of `actions/checkout` are resolved to different overrides:
-
-```yaml
-steps:
-  # Was: actions/checkout@v3
-  - uses: actions/checkout@ac59398
-
-  # Was: actions/checkout@v2
-  - uses: actions/checkout@main
-```
-
-Workflow creators are encouraged to use commit hashes and keep them updated, or major versions.
-Sensitive workflow actions should always use commit hashes.
-
-### Stale workflow
-
-A "stale" workflow can be added which will automatically close issues or pull
-requests on your GitHub repository after time has passed without the issue
-seeing any comments or updates. You can enable as shown below:
-
-```ts
-// or PythonProject, etc.
-new typescript.TypeScriptProject({
-  stale: true,
-  staleOptions: {
-    issues: {
-      closeMessage: "closing pull request",
-      staleLabel: "I-AM-STALE",
-      daysBeforeStale: 180,
-    },
-  }
-})
-```
-
-Check the API reference for a list of all available options.
-
-When enabled, by default issues with no activity with will be marked as stale
-after 60 days and closed within 7 days, and pull requests with no activity will
-be marked as stale after 14 days and closed within 2 days.

package/docs/gitlab.md

@@ -1,67 +0,0 @@
-# GitLab
-
-[GitLab CI/CD](https://docs.gitlab.com/ee/ci/yaml/gitlab_ci_yaml.html) uses a `.gitlab-ci.yml` file located at the root of your repository to specify continuous integration and continuous deployment processes. GitLab CI configuration files can be split into multiple files using the [include](https://docs.gitlab.com/ee/ci/yaml/#include) fields in order to increase readability or reduce duplication of the same configuration in multiple places.
-
-## Creating a configuration
-
-We support the creation of GitLab CI/CD Configurations through a `CiConfiguration` class and a higher level `GitlabConfiguration` and `NestedConfiguration` classes. To create a GitLab configuration you must first create a [project](./project.md) to assign the configuration to.
-
-When using GitLab for CI, the `.gitlab-ci.yml` is always located at the root of the project while other configuration files are located in the `.gitlab\ci-templates\` subdirectory.
-
-```js
-const { typescript, gitlab } = require('projen');
-const project = new typescript.TypeScriptProject({
-  defaultReleaseBranch: 'main',
-  name: 'my-project',
-});
-const gitlabMain = new gitlab.GitlabConfiguration(project,
-  {
-    jobs: {
-      myJob: {
-        script: 'echo Hello',
-      },
-    },
-  });
-gitlabMain.createNestedTemplates({
-  myNestedTemplate: {
-    jobs: {
-      myOtherJob: {
-        script: 'echo World!',
-      },
-    },
-  },
-});
-project.synth();
-```
-This creates the following directory structure.
-
-```shell
-├── .gitlab-ci.yml
-└── .gitlab
-    └── ci-templates
-         └── mynestedtemplate.yml
-```
-
-## Updating Nested Configurations
-
-You can modify a `NestedConfiguration` through the `nestedTemplates` property of a `GitlabConfiguration`. 
-```js
-const { typescript, gitlab } = require('projen');
-const project = new typescript.TypeScriptProject({
-  defaultReleaseBranch: 'main',
-  name: 'my-project',
-});
-const gitlabMain = new gitlab.GitlabConfiguration(project,
-  {
-    jobs: {
-      myJob: {
-        script: 'echo Hello',
-      },
-    },
-  });
-gitlabMain.createNestedTemplates({
-  myNestedTemplate: {},
-});
-gitlabMain.nestedTemplates.myNestedTemplate.addStages('stage');
-project.synth();
-```