feat(node): deprecate "xxxDependencies" in favor of "xxxDeps" (warning)

Mark the `xxxDependencies` options as deprecated and issue a warning during synthesis. The alternative is to use the `xxxDeps` option which allows managing versions in `package.json` file. This is a superior approach as it allows external tools such as dependabot to manage your module versions.

Instead of:

  dependencies: { 'express': Server.caret('2.0.0') }

Use:

  deps: [ 'express' ]

Or if you need a specific version (unlikely):

  deps: [ 'express@^2' ]

When a version is not specified, projen will behave like `npm i` or `yarn add`. It will install the latest version and record it as a caret dependency in your `package.json` file. From here on out,
the version will be managed in your `package.json` file.

.projenrc.js

@@ -1,4 +1,4 @@
-const { JsiiProject, JsonFile } = require('./lib');
+const { JsiiProject, JsonFile, Semver } = require('./lib');
 
 const project = new JsiiProject({
   name: 'projen',

src/logging.ts

@@ -4,7 +4,7 @@ let enabled = true;
 
 function log(color: chalk.ChalkFunction, ...text: any[]) {
   if (!enabled) { return; }
-  console.error(`🤖 ${chalk.bold(color(...text))}`);
+  console.error(`🤖 ${color(...text)}`);
 }
 
 export function verbose(...text: any[]) {

src/node-project.ts

@@ -34,16 +34,95 @@ export enum NodePackageManager {
 }
 
 export interface NodeProjectCommonOptions {
+  /**
+   * Runtime dependencies of this module.
+   *
+   * The recommendation is to only specify the module name here (e.g.
+   * `express`). This will behave similar to `yarn add` or `npm install` in the
+   * sense that it will add the module as a dependency to your `package.json`
+   * file with the latest version (`^`). You can specify semver requirements in
+   * the same syntax passed to `npm i` or `yarn add` (e.g. `express@^2`) and
+   * this will be what you `package.json` will eventually include.
+   *
+   * @example [ 'express', 'lodash', 'foo@^2' ]
+   * @default []
+   */
+  readonly deps?: string[];
+
+  /**
+   * Build dependencies for this module. These dependencies will only be
+   * available in your build environment but will not be fetched when this
+   * module is consumed.
+   *
+   * The recommendation is to only specify the module name here (e.g.
+   * `express`). This will behave similar to `yarn add` or `npm install` in the
+   * sense that it will add the module as a dependency to your `package.json`
+   * file with the latest version (`^`). You can specify semver requirements in
+   * the same syntax passed to `npm i` or `yarn add` (e.g. `express@^2`) and
+   * this will be what you `package.json` will eventually include.
+   *
+   * @example [ 'typescript', '@types/express' ]
+   * @default []
+   */
+  readonly devDeps?: string[];
+
+  /**
+   * Peer dependencies for this module. Dependencies listed here are required to
+   * be installed (and satisfied) by the _consumer_ of this library. Using peer
+   * dependencies allows you to ensure that only a single module of a certain
+   * library exists in the `node_modules` tree of your consumers.
+   *
+   * Note that prior to npm@7, peer dependencies are _not_ automatically
+   * installed, which means that adding peer dependencies to a library will be a
+   * breaking change for your customers.
+   *
+   * Unless `peerDependencyOptions.pinnedDevDependency` is disabled (it is
+   * enabled by default), projen will automatically add a dev dependency with a
+   * pinned version for each peer dependency. This will ensure that you build &
+   * test your module against the lowest peer version required.
+   *
+   * @default []
+   */
+  readonly peerDeps?: string[];
+
+  /**
+   * List of dependencies to bundle into this module. These modules will be
+   * added both to the `dependencies` section and `peerDependencies` section of
+   * your `package.json`.
+   *
+   * The recommendation is to only specify the module name here (e.g.
+   * `express`). This will behave similar to `yarn add` or `npm install` in the
+   * sense that it will add the module as a dependency to your `package.json`
+   * file with the latest version (`^`). You can specify semver requirements in
+   * the same syntax passed to `npm i` or `yarn add` (e.g. `express@^2`) and
+   * this will be what you `package.json` will eventually include.
+   */
+  readonly bundledDeps?: string[];
+
+  /**
+   * @deprecated use `bundledDeps`
+   */
   readonly bundledDependencies?: string[];
+
+  /**
+   * @deprecated use `deps`
+   */
   readonly dependencies?: Record<string, Semver>;
+
+  /**
+   * @deprecated use `devDeps`
+   */
   readonly devDependencies?: Record<string, Semver>;
+
+  /**
+   * @deprecated use `peerDeps`
+   */
   readonly peerDependencies?: Record<string, Semver>;
-  readonly peerDependencyOptions?: PeerDependencyOptions;
 
-  readonly bundledDeps?: string[];
-  readonly deps?: string[];
-  readonly devDeps?: string[];
-  readonly peerDeps?: string[];
+  /**
+   * Options for `peerDeps`.
+   */
+  readonly peerDependencyOptions?: PeerDependencyOptions;
 
   /**
    * Binary programs vended with your module.
@@ -833,6 +912,9 @@ export class NodeProject extends Project {
     }
   }
 
+  /**
+   * @deprecated use `addDeps()`
+   */
   public addDependencies(deps: { [module: string]: Semver }, bundle = false) {
     for (const [k, v] of Object.entries(deps)) {
       this.dependencies[k] = typeof(v) === 'string' ? v : v.spec;
@@ -843,6 +925,9 @@ export class NodeProject extends Project {
     }
   }
 
+  /**
+   * @deprecated use `addBundledDeps()`
+   */
   public addBundledDependencies(...deps: string[]) {
     if (deps.length && !this.allowLibraryDependencies) {
       throw new Error(`cannot add bundled dependencies to an APP project: ${deps.join(',')}`);
@@ -861,12 +946,18 @@ export class NodeProject extends Project {
     }
   }
 
+  /**
+   * @deprecated use `addDevDeps()`
+   */
   public addDevDependencies(deps: { [module: string]: Semver }) {
     for (const [k, v] of Object.entries(deps ?? {})) {
       this.devDependencies[k] = typeof(v) === 'string' ? v : v.spec;
     }
   }
 
+  /**
+   * @deprecated use `addPeerDeps()`
+   */
   public addPeerDependencies(deps: { [module: string]: Semver }, options?: PeerDependencyOptions) {
     if (Object.keys(deps).length && !this.allowLibraryDependencies) {
       throw new Error(`cannot add peer dependencies to an APP project: ${Object.keys(deps).join(',')}`);
@@ -1085,6 +1176,17 @@ export class NodeProject extends Project {
   }
 
   private processDeps(options: NodeProjectCommonOptions) {
+    const deprecate = (key: string, alt: string) => {
+      if (Object.keys((options as any)[key] ?? {}).length) {
+        logging.warn(`The option "${key}" will soon be deprecated, use "${alt}" instead (see API docs)`);
+      }
+    };
+
+    deprecate('dependencies', 'deps');
+    deprecate('peerDependencies', 'peerDeps');
+    deprecate('devDependencies', 'devDeps');
+    deprecate('bundledDependencies', 'bundledDeps');
+
     this.addDependencies(options.dependencies ?? {});
     this.addPeerDependencies(options.peerDependencies ?? {});
     this.addDevDependencies(options.devDependencies ?? {});

src/semver.ts

@@ -1,5 +1,10 @@
 import * as semver from 'semver';
 
+/**
+ * @deprecated This class will be removed in upcoming releases. if you wish to
+ * specify semver requirements in `deps`, `devDeps`, etc, specify them like so
+ * `express@^2.1`.
+ */
 export class Semver {
 
   public static of(spec: string) { return new Semver(spec); }