projen 0.70.2 → 0.70.4

package/lib/.types-compat/ts3.9/lib/typescript/typescript-typedoc.d.ts

@@ -0,0 +1,7 @@
+import { TypeScriptProject } from "../typescript";
+/**
+  Adds a simple Typescript documentation generator
+ */
+export declare class TypedocDocgen {
+    constructor(project: TypeScriptProject);
+}

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

@@ -0,0 +1,163 @@
+import { Eslint, EslintOptions, NodeProject, NodeProjectOptions, TypescriptConfig, TypescriptConfigOptions } from "../javascript";
+import { Task } from "../task";
+import { ProjenrcOptions as ProjenrcTsOptions } from "../typescript";
+export interface TypeScriptProjectOptions extends NodeProjectOptions {
+    /**
+     * Typescript  artifacts output directory
+     *
+     * @default "lib"
+     */
+    readonly libdir?: string;
+    /**
+     * Typescript sources directory.
+     *
+     * @default "src"
+     */
+    readonly srcdir?: string;
+    /**
+     * Jest tests directory. Tests files should be named `xxx.test.ts`.
+     *
+     * If this directory is under `srcdir` (e.g. `src/test`, `src/__tests__`),
+     * then tests are going to be compiled into `lib/` and executed as javascript.
+     * If the test directory is outside of `src`, then we configure jest to
+     * compile the code in-memory.
+     *
+     * @default "test"
+     */
+    readonly testdir?: string;
+    /**
+     * Setup eslint.
+     *
+     * @default true
+     */
+    readonly eslint?: boolean;
+    /**
+     * Eslint options
+     * @default - opinionated default options
+     */
+    readonly eslintOptions?: EslintOptions;
+    /**
+     * TypeScript version to use.
+     *
+     * NOTE: Typescript is not semantically versioned and should remain on the
+     * same minor, so we recommend using a `~` dependency (e.g. `~1.2.3`).
+     *
+     * @default "latest"
+     */
+    readonly typescriptVersion?: string;
+    /**
+     * Docgen by Typedoc
+     *
+     * @default false
+     */
+    readonly docgen?: boolean;
+    /**
+     * Docs directory
+     *
+     * @default "docs"
+     */
+    readonly docsDirectory?: string;
+    /**
+     * Custom TSConfig
+     * @default - default options
+     */
+    readonly tsconfig?: TypescriptConfigOptions;
+    /**
+     * Custom tsconfig options for the development tsconfig.json file (used for testing).
+     * @default - use the production tsconfig options
+     */
+    readonly tsconfigDev?: TypescriptConfigOptions;
+    /**
+     * The name of the development tsconfig.json file.
+     *
+     * @default "tsconfig.dev.json"
+     */
+    readonly tsconfigDevFile?: string;
+    /**
+     * Do not generate a `tsconfig.json` file (used by jsii projects since
+     * tsconfig.json is generated by the jsii compiler).
+     *
+     * @default false
+     */
+    readonly disableTsconfig?: boolean;
+    /**
+     * Generate one-time sample in `src/` and `test/` if there are no files there.
+     * @default true
+     */
+    readonly sampleCode?: boolean;
+    /**
+     * The .d.ts file that includes the type declarations for this module.
+     * @default - .d.ts file derived from the project's entrypoint (usually lib/index.d.ts)
+     */
+    readonly entrypointTypes?: string;
+    /**
+     * Use TypeScript for your projenrc file (`.projenrc.ts`).
+     *
+     * @default false
+     */
+    readonly projenrcTs?: boolean;
+    /**
+     * Options for .projenrc.ts
+     */
+    readonly projenrcTsOptions?: ProjenrcTsOptions;
+}
+/**
+ * TypeScript project
+ * @pjid typescript
+ */
+export declare class TypeScriptProject extends NodeProject {
+    readonly docgen?: boolean;
+    readonly docsDirectory: string;
+    readonly eslint?: Eslint;
+    readonly tsconfigEslint?: TypescriptConfig;
+    readonly tsconfig?: TypescriptConfig;
+    /**
+     * A typescript configuration file which covers all files (sources, tests, projen).
+     */
+    readonly tsconfigDev: TypescriptConfig;
+    /**
+     * The directory in which the .ts sources reside.
+     */
+    readonly srcdir: string;
+    /**
+     * The directory in which compiled .js files reside.
+     */
+    readonly libdir: string;
+    /**
+     * The directory in which tests reside.
+     */
+    readonly testdir: string;
+    /**
+     * The "watch" task.
+     */
+    readonly watchTask: Task;
+    constructor(options: TypeScriptProjectOptions);
+    /**
+     * Tests are compiled to `lib/TESTDIR`, so we don't need jest to compile them
+     * for us. just run them directly from javascript.
+     */
+    private addJestCompiled;
+    private addJestNoCompile;
+}
+/**
+ * TypeScript app.
+ *
+ * @pjid typescript-app
+ */
+export declare class TypeScriptAppProject extends TypeScriptProject {
+    constructor(options: TypeScriptProjectOptions);
+}
+/**
+ * @deprecated use `TypeScriptProject`
+ */
+export declare class TypeScriptLibraryProject extends TypeScriptProject {
+}
+/**
+ * @deprecated use TypeScriptProjectOptions
+ */
+export interface TypeScriptLibraryProjectOptions extends TypeScriptProjectOptions {
+}
+/**
+ * @internal
+ */
+export declare function mergeTsconfigOptions(...options: (TypescriptConfigOptions | undefined)[]): TypescriptConfigOptions;

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

@@ -0,0 +1,43 @@
+export declare enum TargetName {
+    JAVA = 0,
+    DOTNET = 1,
+    PYTHON = 2,
+    GO = 3,
+    JAVASCRIPT = 4
+}
+/**
+ * Converts a SemVer range expression to a Maven version range expression.
+ *
+ * @param semverRange the SemVer range expression to convert.
+ * @param suffix      the suffix to add to versions in the range.
+ *
+ * @see https://cwiki.apache.org/confluence/display/MAVENOLD/Dependency+Mediation+and+Conflict+Resolution
+ */
+export declare function toMavenVersionRange(semverRange: string, suffix?: string): string;
+/**
+ * Converts a SemVer range expression to a NuGet version range expression.
+ *
+ * @param semverRange the SemVer range expression to convert.
+ *
+ * @see https://docs.microsoft.com/en-us/nuget/concepts/package-versioning#version-ranges-and-wildcards
+ */
+export declare function toNuGetVersionRange(semverRange: string): string;
+/**
+ * Converts a SemVer range expression to a Python setuptools compatible version
+ * constraint expression.
+ *
+ * @param semverRange the SemVer range expression to convert.
+ */
+export declare function toPythonVersionRange(semverRange: string): string;
+/**
+ * Converts an original version number from the NPM convention to the target
+ * language's convention for expressing the same. For versions that do not
+ * include a prerelease identifier, this always returns the assembly version
+ * unmodified.
+ *
+ * @param assemblyVersion the assembly version being released
+ * @param target          the target language for which the version is destined
+ *
+ * @returns the version that should be serialized
+ */
+export declare function toReleaseVersion(assemblyVersion: string, target: TargetName): string;

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

@@ -0,0 +1,42 @@
+import { Project } from "../project";
+/**
+ * Options for the Snapshot synthesis
+ */
+export interface SnapshotOptions {
+    /**
+     * Parse .json files as a JS object for improved inspection.
+     * This will fail if the contents are invalid JSON.
+     *
+     * @default true parse .json files into an object
+     */
+    readonly parseJson?: boolean;
+}
+export interface SynthOutput {
+    [filePath: string]: any;
+}
+/**
+ * Creates a snapshot of the files generated by a project. Ignores any non-text
+ * files so that the snapshots are human readable.
+ */
+export declare function synthSnapshot(project: Project, options?: SnapshotOptions): SynthOutput;
+export interface DirectorySnapshotOptions extends SnapshotOptions {
+    /**
+     * Globs of files to exclude.
+     * @default [] include all files
+     */
+    readonly excludeGlobs?: string[];
+    /**
+     * Only snapshot the names of files and not their contents.
+     * The value for a path will be `true` if it exists.
+     *
+     * @default false include file content
+     */
+    readonly onlyFileNames?: boolean;
+    /**
+     * Parses files with different parser, supporting comments
+     * inside .json files.
+     * @default false
+     */
+    readonly supportJsonComments?: boolean;
+}
+export declare function directorySnapshot(root: string, options?: DirectorySnapshotOptions): SynthOutput;

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

@@ -0,0 +1,131 @@
+/// <reference types="node" />
+import * as path from "path";
+/**
+ * Executes a command with STDOUT > STDERR.
+ */
+export declare function exec(command: string, options: {
+    cwd: string;
+}): void;
+/**
+ * Executes command and returns STDOUT. If the command fails (non-zero), throws an error.
+ */
+export declare function execCapture(command: string, options: {
+    cwd: string;
+}): Buffer;
+/**
+ * Executes `command` and returns its value or undefined if the command failed.
+ */
+export declare function execOrUndefined(command: string, options: {
+    cwd: string;
+}): string | undefined;
+export interface WriteFileOptions {
+    /**
+     * Whether the generated file should be marked as executable.
+     *
+     * @default false
+     */
+    executable?: boolean;
+    /**
+     * Whether the generated file should be readonly.
+     *
+     * @default false
+     */
+    readonly?: boolean;
+}
+export declare function getFilePermissions(options: WriteFileOptions): string;
+export declare function writeFile(filePath: string, data: any, options?: WriteFileOptions): void;
+/**
+ * Decamelizes the keys of an object structure, recursing through child objects and arrays.
+ * @experimental
+ */
+export interface DecamelizeRecursivelyOptions {
+    /**
+     * Max depth to recurse before erroring.
+     * @default 10
+     */
+    maxDepth?: number;
+    /**
+     * Returns true when a key should be decamelized
+     * @default - all keys are decamelized
+     */
+    shouldDecamelize?: (path: string[], value: any) => boolean;
+    /**
+     * Separator for decamelizing.
+     * @default "_"
+     */
+    separator?: string;
+    /**
+     * Current path.
+     * @internal
+     */
+    path?: string[];
+}
+export declare function decamelizeKeysRecursively(input: any, opt?: DecamelizeRecursivelyOptions): any;
+/**
+ * Returns false if value is unset or a falsey value, and true otherwise.
+ * @param value an environment variable
+ */
+export declare function isTruthy(value: string | undefined): boolean;
+/**
+ * Type of a map mapping strings to some arbitrary type
+ */
+export type Obj<T> = {
+    [key: string]: T;
+};
+/**
+ * Return whether the given value is an object
+ *
+ * Even though arrays and instances of classes technically are objects, we
+ * usually want to treat them differently, so we return false in those cases.
+ */
+export declare function isObject(x: any): x is Obj<any>;
+/**
+ * Recursively merge objects together
+ *
+ * The leftmost object is mutated and returned. Arrays are not merged
+ * but overwritten just like scalars.
+ *
+ * If an object is merged into a non-object, the non-object is lost.
+ *
+ * `undefined`s will cause a value to be deleted if destructive is enabled.
+ */
+export declare function deepMerge(objects: Array<Obj<any> | undefined>, destructive?: boolean): Obj<any>;
+export declare function dedupArray<T>(array: T[]): T[];
+/**
+ * Returns a sorted version of `x` or `undefined` if it is an empty array or object.
+ */
+export declare function sorted<T>(x: T): unknown[] | T | undefined;
+export declare function formatAsPythonModule(name: string): string;
+/**
+ * Extract git version number from command line
+ *
+ * @param gitVersionOutput the output from `git version` CLI
+ * @returns the version of git
+ */
+export declare function getGitVersion(gitVersionOutput: string): string;
+export declare function kebabCaseKeys<T = unknown>(obj: T, recursive?: boolean): T;
+export declare function snakeCaseKeys<T = unknown>(obj: T, recursive?: boolean, exclusiveForRecordKeys?: string[]): T;
+export declare function tryReadFile(file: string): Promise<string>;
+export declare function tryReadFileSync(file: string): string | undefined;
+export declare function isWritable(file: string): boolean;
+export declare function isExecutable(file: string): boolean;
+export declare function getNodeMajorVersion(): number | undefined;
+export declare function anySelected(options: (boolean | undefined)[]): boolean;
+export declare function multipleSelected(options: (boolean | undefined)[]): boolean;
+/**
+ * Checks if a path is a FS root
+ *
+ * Optional uses a provided OS specific path implementation,
+ * defaults to use the implementation for the current OS.
+ *
+ * @internal
+ */
+export declare function isRoot(dir: string, osPathLib?: typeof path): boolean;
+/**
+ * Run up project tree to find a file or directory
+ *
+ * @param lookFor the file or directory to look for
+ * @param cwd current working directory, must be an absolute path
+ * @returns path to the file or directory we are looking for, undefined if not found
+ */
+export declare function findUp(lookFor: string, cwd?: string): string | undefined;

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

@@ -0,0 +1,45 @@
+import { Component } from "./component";
+import { Project } from "./project";
+import { Task } from "./task";
+/**
+ * Options for `Version`.
+ */
+export interface VersionOptions {
+    /**
+     * A name of a .json file to set the `version` field in after a bump.
+     *
+     * @example "package.json"
+     */
+    readonly versionInputFile: string;
+    /**
+     * The name of the directory into which `changelog.md` and `version.txt` files
+     * are emitted.
+     */
+    readonly artifactsDirectory: string;
+    /**
+     * Custom configuration for versionrc file used by standard-release
+     */
+    readonly versionrcOptions?: Record<string, any>;
+    /**
+     * The tag prefix corresponding to this version.
+     */
+    readonly tagPrefix?: string;
+}
+export declare class Version extends Component {
+    static readonly STANDARD_VERSION = "standard-version@^9";
+    readonly bumpTask: Task;
+    readonly unbumpTask: Task;
+    /**
+     * The name of the changelog file (under `artifactsDirectory`).
+     */
+    readonly changelogFileName: string;
+    /**
+     * The name of the file that contains the version (under `artifactsDirectory`).
+     */
+    readonly versionFileName: string;
+    /**
+     * The name of the file that contains the release tag (under `artifactsDirectory`).
+     */
+    readonly releaseTagFileName: string;
+    constructor(project: Project, options: VersionOptions);
+}

package/lib/.types-compat/ts3.9/lib/vscode/devcontainer.d.ts

@@ -0,0 +1,86 @@
+import { Component } from "../component";
+import { DevEnvironmentDockerImage, DevEnvironmentOptions, IDevEnvironment } from "../dev-env";
+import { Project } from "../project";
+import { Task } from "../task";
+/**
+ * devcontainer features options
+ * @see https://containers.dev/implementors/features/#devcontainer-json-properties
+ */
+export interface DevContainerFeature {
+    /**
+     * feature name
+     */
+    readonly name: string;
+    /**
+     * feature version
+     * @default latest
+     */
+    readonly version?: string;
+}
+/**
+ * Constructor options for the DevContainer component.
+ *
+ * The default docker image used for GitHub Codespaces is defined here:
+ * @see https://github.com/microsoft/vscode-dev-containers/tree/master/containers/codespaces-linux
+ */
+export interface DevContainerOptions extends DevEnvironmentOptions {
+    /**
+     * An array of VSCode features that specify the features that should be
+     * installed inside the container when it is created.
+     */
+    readonly features?: DevContainerFeature[];
+}
+export interface IDevContainerEnvironment extends IDevEnvironment {
+    /**
+     * Adds a list of VSCode features that should be automatically installed
+     * in the container.
+     *
+     * @param features featureName and version(optional default: latest)
+     */
+    addFeatures(...features: DevContainerFeature[]): void;
+}
+/**
+ * A development environment running VSCode in a container; used by GitHub
+ * codespaces.
+ */
+export declare class DevContainer extends Component implements IDevContainerEnvironment {
+    private dockerImage;
+    private readonly postCreateTasks;
+    private readonly ports;
+    private readonly vscodeExtensions;
+    private readonly features;
+    /**
+     * Direct access to the devcontainer configuration (escape hatch)
+     */
+    readonly config: any;
+    constructor(project: Project, options?: DevContainerOptions);
+    addDockerImage(image: DevEnvironmentDockerImage): void;
+    /**
+     * Adds tasks to run when the container starts. Tasks will be run in sequence.
+     *
+     * @param tasks The new tasks
+     */
+    addTasks(...tasks: Task[]): void;
+    /**
+     * Adds ports that should be exposed (forwarded) from the container.
+     *
+     * @param ports The new ports
+     */
+    addPorts(...ports: string[]): void;
+    /**
+     * Adds a list of VSCode extensions that should be automatically installed
+     * in the container.
+     *
+     * @param extensions The extension IDs
+     */
+    addVscodeExtensions(...extensions: string[]): void;
+    /**
+     * Adds a list of VSCode features that should be automatically installed
+     * in the container.
+     *
+     * @param features featureName and version(optional default: latest)
+     */
+    addFeatures(...features: DevContainerFeature[]): void;
+    private renderTasks;
+    private renderFeatures;
+}

package/lib/.types-compat/ts3.9/lib/vscode/extensions.d.ts

@@ -0,0 +1,36 @@
+import { VsCode } from "./vscode";
+import { Component } from "../component";
+/**
+ * VS Code Workspace recommended extensions
+ * Source: https://code.visualstudio.com/docs/editor/extension-marketplace#_workspace-recommended-extensions
+ */
+export declare class VsCodeRecommendedExtensions extends Component {
+    /**
+     * List of extensions which should be recommended for users of this workspace.
+     * The identifier of an extension is always '${publisher}.${name}'. For example: 'ms-python.python'.
+     *
+     * @default - no recommendations are made
+     */
+    private readonly recommendations;
+    /**
+     * List of extensions recommended by VS Code that should not be recommended for users of this workspace.
+     * The identifier of an extension is always '${publisher}.${name}'. For example: 'ms-python.python'.
+     *
+     * @default - no recommendations are marked unwanted
+     */
+    private readonly unwantedRecommendations;
+    constructor(vscode: VsCode);
+    /**
+     * Adds a list of VS Code extensions as recommendations for this workspace.
+     *
+     * @param extensions The extension IDs
+     */
+    addRecommendations(...extensions: string[]): void;
+    /**
+     * Marks a list of VS Code extensions as unwanted recommendations for this workspace.
+     * VS Code should not be recommend these extensions for users of this workspace.
+     *
+     * @param extensions The extension IDs
+     */
+    addUnwantedRecommendations(...extensions: string[]): void;
+}

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

@@ -0,0 +1,5 @@
+export * from "./devcontainer";
+export * from "./extensions";
+export * from "./launch-config";
+export * from "./settings";
+export * from "./vscode";

package/lib/.types-compat/ts3.9/lib/vscode/launch-config.d.ts

@@ -0,0 +1,90 @@
+import { VsCode } from "./vscode";
+import { Component } from "../component";
+/**
+ * Controls where to launch the debug target
+ * Source: https://code.visualstudio.com/docs/editor/debugging#_launchjson-attributes
+ */
+export declare enum Console {
+    INTERNAL_CONSOLE = "internalConsole",
+    INTEGRATED_TERMINAL = "integratedTerminal",
+    EXTERNAL_TERMINAL = "externalTerminal"
+}
+/**
+ * Controls the visibility of the VSCode Debug Console panel during a debugging session
+ * Source: https://code.visualstudio.com/docs/editor/debugging#_launchjson-attributes
+ */
+export declare enum InternalConsoleOptions {
+    NEVER_OPEN = "neverOpen",
+    OPEN_ON_FIRST_SESSION_START = "openOnFirstSessionStart",
+    OPEN_ON_SESSION_START = "openOnSessionStart"
+}
+/**
+ * VSCode launch configuration Presentation interface
+ * "using the order, group, and hidden attributes in the presentation object you can sort,
+ * group, and hide configurations and compounds in the Debug configuration dropdown
+ * and in the Debug quick pick."
+ * Source: https://code.visualstudio.com/docs/editor/debugging#_launchjson-attributes
+ */
+export interface Presentation {
+    readonly hidden: boolean;
+    readonly group: string;
+    readonly order: number;
+}
+/**
+ * VSCode launch configuration ServerReadyAction interface
+ * "if you want to open a URL in a web browser whenever the program under debugging
+ * outputs a specific message to the debug console or integrated terminal."
+ * Source: https://code.visualstudio.com/docs/editor/debugging#_launchjson-attributes
+ */
+export interface ServerReadyAction {
+    readonly action: string;
+    readonly pattern?: string;
+    readonly uriFormat?: string;
+}
+/**
+ * Options for a 'VsCodeLaunchConfigurationEntry'
+ * Source: https://code.visualstudio.com/docs/editor/debugging#_launchjson-attributes
+ */
+export interface VsCodeLaunchConfigurationEntry {
+    readonly type: string;
+    readonly request: string;
+    readonly name: string;
+    readonly args?: string[];
+    readonly debugServer?: number;
+    readonly internalConsoleOptions?: InternalConsoleOptions;
+    readonly runtimeArgs?: string[];
+    readonly postDebugTask?: string;
+    readonly preLaunchTask?: string;
+    readonly presentation?: Presentation;
+    readonly program?: string;
+    readonly serverReadyAction?: ServerReadyAction;
+    readonly skipFiles?: string[];
+    readonly outFiles?: string[];
+    readonly url?: string;
+    readonly webRoot?: string;
+    /**
+     * Set value to `false` to unset an existing environment variable
+     */
+    readonly env?: Record<string, string | false>;
+    readonly envFile?: string;
+    readonly cwd?: string;
+    readonly port?: number;
+    readonly stopOnEntry?: boolean;
+    readonly console?: Console;
+    readonly disableOptimisticBPs?: boolean;
+}
+/**
+ * VSCode launch configuration file (launch.json), useful for enabling in-editor debugger
+ */
+export declare class VsCodeLaunchConfig extends Component {
+    private static renderLaunchConfig;
+    private readonly content;
+    constructor(vscode: VsCode);
+    /**
+     * Adds a VsCodeLaunchConfigurationEntry (e.g. a node.js debugger) to `.vscode/launch.json.
+     * Each configuration entry has following mandatory fields: type, request and name.
+     * See https://code.visualstudio.com/docs/editor/debugging#_launchjson-attributes for details.
+     * @param cfg VsCodeLaunchConfigurationEntry
+     */
+    addConfiguration(cfg: VsCodeLaunchConfigurationEntry): void;
+}

package/lib/.types-compat/ts3.9/lib/vscode/settings.d.ts

@@ -0,0 +1,24 @@
+import { VsCode } from "./vscode";
+import { Component } from "../component";
+/**
+ * VS Code Workspace settings
+ * Source: https://code.visualstudio.com/docs/getstarted/settings#_workspace-settings
+ */
+export declare class VsCodeSettings extends Component {
+    private readonly content;
+    constructor(vscode: VsCode);
+    /**
+     * Adds a workspace setting
+     *
+     * @param setting The setting ID
+     * @param value The value of the setting
+     * @param language Scope the setting to a specific language
+     */
+    addSetting(setting: string, value: unknown, language?: string): void;
+    /**
+     * Adds a workspace setting
+     *
+     * @param settings Array structure: [setting: string, value: any, languages?: string[]]
+     */
+    addSettings(settings: Record<string, unknown>, languages?: string | string[]): void;
+}