projen 0.28.23 → 0.28.24

package/ARCHITECTURE.md

@@ -1,99 +0,0 @@
-# Architecture
-
-This document attempts to document the high-level architecture of projen. This
-could be useful if you're trying to contribute to projen, trying to debug an
-error message, or if you're just curious!
-
-## How are a project's files synthesized?
-
-### Bird's eye view
-
-When `npx projen` is run, the command-line process executes the project's
-projenrc file. This is usually a file like `.projenrc.js` or `projenrc.java`.
-
-> The "rc" in the name is a common convention for configuration files - see
-https://en.wikipedia.org/wiki/Configuration_file.
-
-projenrc files follow a general structure:
-
-1. they define one or more `Project` instances
-2. these projects are configured and customized
-3. `project.synth()` is called on the root project
-
-For simplicity, most of this document will just assume there is a single project
-unless otherwise specified.
-
-Steps 1 and 2 only serve to initialize an in-memory representation of the
-project. projen runs on Node.js; so in the JavaScript runtime, these steps
-create a hierarchy of objects (called `Component`'s), each with various fields
-specifying the names of files, tasks, options, and so on. The data within each
-component provides enough information to uniquely determine the structure and
-contents of the files it is responsible for. Components can add other components
-to the project, and even make changes to existing components through common
-interfaces like `project.tasks`, `project.deps`, or
-`project.tryFindObjectFile()`.
-
-Step 3 is the only step that actually performs any changes to files in the
-user's project / file system.
-
-### Synthesizing actual files
-
-The `synth()` method of `Project` performs the actual synthesizing (and
-updating) of all configuration files managed by projen. This is achieved by
-deleting all projen-managed files (if there are any), and then re-synthesizing
-them based on the latest configuration specified by the user. In code, this
-breaks down as follows (slightly simplified):
-
-1. the project's `preSynthesize()` method is called
-2. all components' `preSynthesize()` methods are called
-3. all projen-synthesized files are cleaned up
-4. all components' `synthesize()` methods are called (most files are generated)
-5. all components' `postSynthesize()` methods are called
-6. the project's `postSynthesize()` method is called
-
-In the above list, step 3 is critical since it's important that only files that
-are managed by projen get cleaned up - we don't want user source code to be
-deleted! Moreover, if a file was synthesized by projen at one point in time, but
-later a user changes their projenrc configuration so it is no longer necessary,
-we want it to be automatically cleaned up.
-
-Rather than manually keeping track of synthesized files with some form of stored
-state (which could easily get desynced by tampering from users or other tools),
-projen simply looks for files with the _magic string_ that you get by
-concatenating `"~~ Generated by "` and `"projen"`, and removes them. See
-[cleanup.ts](src/cleanup.ts).
-
-Since any file with this string gets automatically cleaned up, you should not
-include this magic string verbatim in source code files. If you are writing your
-own projen project type or component, you can simply reference this magic string
-via `FileBase.PROJEN_MARKER`.
-
-----
-
-Steps 1, 2, 4, 5, and 6 are more straightforward. `synthesize()` is used to
-generate the actual files in the user's file system (including applying
-appropriate read/write permissions). `preSynthesize()` and `postSynthesize()`
-are complementary methods that can used to enable components to perform
-additional logic before and after synthesis. See the source code of `Component`
-and `FileBase` for more details.
-
-> Note: in practice, there are many existing components for creating specific
-> types of files (such as `JsonFile` and `TextFile`), so we recommend using
-> these over hand-making components wherever possible. (Believe in the power of
-> abstractions!)
-
-Since `preSynthesize()` is called before any files are cleaned up, it can be
-used for e.g. observing any changes made to a generated file, and then adjusting
-how the file is re-synthesized based on those changes. (As an example, running
-`npm install` or `yarn install` can change the dependencies listed in the
-`package.json` file of JavaScript projects. The built-in `NodeProject` uses
-`preSynthesize()` to automatically integrate these changes to the `package.json`
-file synthesized by projen, instead of overriding them.)
-
-## How can projenrc files be written in multiple languages?
-
-The projen library is transpiled by [jsii](https://github.com/aws/jsii) so that
-projenrc files can be written in languages besides JavaScript. Under the hood,
-API calls made in projen's  Java/Python/etc. libraries communicate with a
-JavaScript runtime to deliver the same behavior as if you wrote the code in
-JavaScript. For more information, check out [jsii](https://github.com/aws/jsii).

package/CODE_OF_CONDUCT.md

@@ -1,130 +0,0 @@
-
-# Contributor Covenant Code of Conduct
-
-## Our Pledge
-
-We as members, contributors, and leaders pledge to make participation in our
-community a harassment-free experience for everyone, regardless of age, body
-size, visible or invisible disability, ethnicity, sex characteristics, gender
-identity and expression, level of experience, education, socio-economic status,
-nationality, personal appearance, race, religion, or sexual identity
-and orientation.
-
-We pledge to act and interact in ways that contribute to an open, welcoming,
-diverse, inclusive, and healthy community.
-
-## Our Standards
-
-Examples of behavior that contributes to a positive environment for our
-community include:
-
-* Demonstrating empathy and kindness toward other people
-* Being respectful of differing opinions, viewpoints, and experiences
-* Giving and gracefully accepting constructive feedback
-* Accepting responsibility and apologizing to those affected by our mistakes,
-  and learning from the experience
-* Focusing on what is best not just for us as individuals, but for the
-  overall community
-
-Examples of unacceptable behavior include:
-
-* The use of sexualized language or imagery, and sexual attention or
-  advances of any kind
-* Trolling, insulting or derogatory comments, and personal or political attacks
-* Public or private harassment
-* Publishing others' private information, such as a physical or email
-  address, without their explicit permission
-* Other conduct which could reasonably be considered inappropriate in a
-  professional setting
-
-## Enforcement Responsibilities
-
-Community leaders are responsible for clarifying and enforcing our standards of
-acceptable behavior and will take appropriate and fair corrective action in
-response to any behavior that they deem inappropriate, threatening, offensive,
-or harmful.
-
-Community leaders have the right and responsibility to remove, edit, or reject
-comments, commits, code, wiki edits, issues, and other contributions that are
-not aligned to this Code of Conduct, and will communicate reasons for moderation
-decisions when appropriate.
-
-## Scope
-
-This Code of Conduct applies within all community spaces, and also applies when
-an individual is officially representing the community in public spaces.
-Examples of representing our community include using an official e-mail address,
-posting via an official social media account, or acting as an appointed
-representative at an online or offline event.
-
-## Enforcement
-
-Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported to the community leaders responsible for enforcement at
-elad.benisrael@gmail.com. All complaints will be reviewed and investigated 
-promptly and fairly.
-
-All community leaders are obligated to respect the privacy and security of the
-reporter of any incident.
-
-## Enforcement Guidelines
-
-Community leaders will follow these Community Impact Guidelines in determining
-the consequences for any action they deem in violation of this Code of Conduct:
-
-### 1. Correction
-
-**Community Impact**: Use of inappropriate language or other behavior deemed
-unprofessional or unwelcome in the community.
-
-**Consequence**: A private, written warning from community leaders, providing
-clarity around the nature of the violation and an explanation of why the
-behavior was inappropriate. A public apology may be requested.
-
-### 2. Warning
-
-**Community Impact**: A violation through a single incident or series
-of actions.
-
-**Consequence**: A warning with consequences for continued behavior. No
-interaction with the people involved, including unsolicited interaction with
-those enforcing the Code of Conduct, for a specified period of time. This
-includes avoiding interactions in community spaces as well as external channels
-like social media. Violating these terms may lead to a temporary or
-permanent ban.
-
-### 3. Temporary Ban
-
-**Community Impact**: A serious violation of community standards, including
-sustained inappropriate behavior.
-
-**Consequence**: A temporary ban from any sort of interaction or public
-communication with the community for a specified period of time. No public or
-private interaction with the people involved, including unsolicited interaction
-with those enforcing the Code of Conduct, is allowed during this period.
-Violating these terms may lead to a permanent ban.
-
-### 4. Permanent Ban
-
-**Community Impact**: Demonstrating a pattern of violation of community
-standards, including sustained inappropriate behavior,  harassment of an
-individual, or aggression toward or disparagement of classes of individuals.
-
-**Consequence**: A permanent ban from any sort of public interaction within
-the community.
-
-## Attribution
-
-This Code of Conduct is adapted from the [Contributor Covenant][homepage],
-version 2.0, available at
-https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
-
-Community Impact Guidelines were inspired by [Mozilla's code of conduct
-enforcement ladder](https://github.com/mozilla/diversity).
-
-[homepage]: https://www.contributor-covenant.org
-
-For answers to common questions about this code of conduct, see the FAQ at
-https://www.contributor-covenant.org/faq. Translations are available at
-https://www.contributor-covenant.org/translations.
-

package/CONTRIBUTING.md

@@ -1,137 +0,0 @@
-# Contributing to projen
-
-Thanks for your interest in contributing to projen! :heart:
-
-This document describes how to set up a development environment and submit your
-contributions. Please read it carefully and let us know if it's not up-to date
-(or even better, submit a pull request with your corrections! :wink:).
-
-## Prerequisites
-
-### Manually install tools
-
-The following tools need to be installed to develop on projen locally.
-
-- [Node]
-- [Yarn]
-- [Maven]
-
-[Node]: https://nodejs.org/en/download/
-[Yarn]: https://yarnpkg.com/en/docs/install
-[Maven]: https://maven.apache.org/install
-
-## Getting Started
-
-The basic commands to get the repository cloned and built locally follow:
-
-```console
-$ git clone git@github.com:projen/projen
-$ cd projen
-$ yarn # install dependencies
-$ yarn build # build projen
-```
-
-## Code Organization
-
-Check out [this recording](https://www.youtube.com/watch?v=8dHwnuSND14) from a walkthrough of the projen codebase.
-
-### Development workflow
-
-The projen package has the following scripts:
-
-- `build` - builds the package and runs all unit tests
-- `watch` - watches for file changes and builds them progressively
-- `test` - executes all unit tests
-- `test:update` - executes all unit tests and overwrites snapshot expectations (those `.snap` files).
-- `test:watch` - runs all unit tests and reruns tests when files are changed
-- `package` - emits publishable artifacts to `dist`.
-- `eslint` - run linter against source code
-
-Each of these scripts can be executed using `yarn <script>` or `npx projen <script>`.
-
-Tests are located under `src/__tests__` and executed from javascript code, so
-make sure to compile once before running any tests.
-
-One trick for quickly iterating is to run `yarn watch` in one terminal, and
-`yarn test:watch` in another. Then, when you change your unit tests the code
-will automatically recompile, thus triggering the tests to automatically re-run.
-
-#### Linting & Formatting
-
-Eslint is used to lint and format our typescript code. The `eslint`
-script can be run from the root of the package.
-
-You can integrate the linting and formatting workflow with your editor or ide by
-installing the approporiate eslint plugin. For example, when using Visual Studio
-Code, the [eslint plugin](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint)
-exposes a number of options including "fix on save". This will auto correct lint
-and formatting errors whenever possible while saving a document.
-
-### Testing against local projects
-
-When your local version of projen builds successfully, you can test it to create
-a new project by going into another directory and invoking the binary directly:
-
-First, tell yarn to create a link from your local development copy:
-
-```console
-$ cd /path/to/local/projen
-$ yarn link
-```
-
-Now, to create new projects:
-
-```console
-$ mkdir /my/new/project
-$ cd /my/new/project
-$ yarn link projen
-$ alias pj="node_modules/projen/bin/projen"
-$ pj new TYPE
-$ yarn link projen # <-- important to run this again
-```
-
-If you already have an existing project and you want to test a new projen
-feature against it:
-
-```console
-$ cd /my/other/project
-$ yarn link projen
-$ pj
-```
-
-From now on, running `pj` in this session will use the local development version of 
-projen instead of the latest one from npm.
-
-```console
-$ yarn unlink projen
-```
-
-### Version bumping
-
-Currently projen bumps versions automatically thru a GitHub action when a commit
-pushed to master successfully builds. Projen follows [semantic versioning](https://semver.org/)
-through the [standard-version](https://github.com/conventional-changelog/standard-version)
-npm utility.
-
-## Making a pull request
-
-* Commit title and message (and PR title and description) must adhere to [conventionalcommits](https://www.conventionalcommits.org).
-  * The title must begin with `feat(module): title`, `fix(module): title`,
-  `refactor(module): title` or `chore(module): title`, where the module refers
-  to the projects or components that the change centers on.
-  The module can be omitted, so "feat: title" is okay as well.
-  * Title should be lowercase.
-  * No period at the end of the title.
-* Commit message should describe _motivation_. Think about your code reviewers and what information they need in
-  order to understand what you did. If it's a big commit (hopefully not), try to provide some good entry points so
-  it will be easier to follow.
-* Commit message should indicate which issues are fixed: `fixes #<issue>` or `closes #<issue>`.
-* Shout out to collaborators.
-* If not obvious (i.e. from unit tests), describe how you verified that your change works.
-* If this commit includes breaking changes, they must be listed at the end in the following format (notice how multiple breaking changes should be formatted):
-
-```
-BREAKING CHANGE: Description of what broke and how to achieve this behavior now
-* **module-name:** Another breaking change
-* **module-name:** Yet another breaking change
-```

package/SECURITY.md

@@ -1,18 +0,0 @@
-# Security Policy
-
-## Supported Versions
-
-Use this section to tell people about which versions of your project are
-currently being supported with security updates.
-
-| Version | Supported          |
-| ------- | ------------------ |
-| 0.x     | :white_check_mark: |
-
-## Reporting a Vulnerability
-
-Use this section to tell people how to report a vulnerability.
-
-Tell them where to go, how often they can expect to get an update on a
-reported vulnerability, what to expect if the vulnerability is accepted or
-declined, etc.

package/VISION.md

@@ -1,64 +0,0 @@
-# The vision of projen
-
-This is basically a paper napkin for ideas for the roadmap for the project. Comments/PRs are more than welcome!
-
-## Ecosystem
-
-"Batteries included" is a very powerful concept. It allows users to discover the breadth of their options using a
-single experience, instead of having to read the manual for 4 different plugins with horrible versioning conflicts.
-
-On the other hand, one of the goals of projen is to support the ever-increasing amount of tools people use in order to build software,
-and to allow teams to use projen internally for their needs and to do that, we must have an open ecosystem which allows anyone to
-freely publish and consume components and projects.
-
-So we need to solve a few problems:
-
-- Discovery: projects/components from ecosystem libraries should feel 1st class.
-- Velocity: a single codebase can easily manage breaking changes in APIs, but it's much harder to do that at the
-  ecosystem level, and usually a source of a lot of frustration.
-
-### Discovery
-
-The desired experience is that `projen new --help` will list all public project types, including types from ecosystem libraries.
-
-A simple solution that may go a long way is to create a "sources" file in the projen repo, and allow anyone to add their library
-to the file through a pull request. The source list will be basically names of npm modules. During _build_, we will process this
-list by downloading the package information from npm, and injest their `.jsii` manifests into the CLI.
-
-Yes, this means that new sources will be added only when projen is released. But projen is released for every merged PR.
-
-We will also need to indicate major version compatibility of each project/component (see "Velocity" below).
-
-### Velocity
-
-In semver (semantic versioning), the only right way to introduce a breaking change (API or behavioral) is to release 
-a new major version. It will take a couple of years for projen to stabilize, and we want the ecosystem to grow with it. 
-A monolithic module makes this less of a problem because there aren't many libraries that depend on projen, so a major
-version once in a while is tolerable.
-
-This means that projen will release major versions all the time. Think 232.4.34. 
-
-So we need our ecosystem to continuously take updates and release new versions that were tested with the new major version. 
-In most cases, projects and component won't get broken, but sometimes they will and then the maintainer will need to resolve.
-Luckily this mechanism already exists in projen (`projenUpgradeSecret`). 
-It is opt-in because it requires a the user to upload a GitHub secret, but maybe if we implement some support for secret management, 
-we could make that the default behavior.
-
-As mentioned above, when we process our "sources" during build, we can check the projen version they were tested with and
-determine if it's compatible with the version on the user's system.
-
-## Services
-
-projen should be able to deploy & manage cloud services related to your development environment. For example,
-a service to manage secrets for me in AWS Secrets Manager, a cloud development account, CI/CD infrastructure, etc.
-
-Using the CDKs (AWS CDK, CDK for Terraform, CDK for Kubernetes), complete services can be expressed as constructs
-and shared and published as libraries. It is fairly easy (#) to simply allow CDK constructs to be freely used
-inside projen components.
-
-## Ideas
-
-- [ ] Components: re-think/re-factor how components and projects interact to allow more modular and composable usage.
-- [ ] Discoverability of external components/modules through the CLI
-- [ ] Support projenrc in YAML (fully declarative, if one desires)
-- [x] CLI bash completion

package/projen.bash

@@ -1,8 +0,0 @@
-#!/bin/bash
-# ~~ Generated by projen. To modify, edit .projenrc.js and run "npx projen".
-set -euo pipefail
-if [ ! -f lib/cli/index.js ]; then
-  echo "bootstrapping..."
-  npx jsii --silence-warnings=reserved-word --no-fix-peer-dependencies
-fi
-exec bin/projen $@

package/scripts/readme-projects.js

@@ -1,5 +0,0 @@
-const inventory = require('../lib/inventory');
-
-for (const p of inventory.discover()) {
-  console.log(`* [${p.pjid}](${p.docsurl}) - ${p.docs}`);
-}