feat(pacmak): emit LICENSE file with SPDX license text, NOTICE file

gh-pages/content/user-guides/lib-author/configuration/index.md

@@ -51,9 +51,40 @@ _license_, in order to be valid for publishing.
   package for third-party consumption, `UNLICENSED` (not to be confused with `Unlicense`) is a valid option.
 
 [npm-author]: https://docs.npmjs.com/files/package.json#people-fields-author-contributors
-[npm-license]: https://docs.npmjs.com/files/package.json#license
+[npm-license]: https://docs.npmjs.com/cli/v6/configuring-npm/package-json#license
 [spdx license id]: https://spdx.org/licenses/
 
+#### Important License Information
+
+You are free to decide which license you want to distribute your code under. The bindings generated by `jsii-pacmak`
+will use the exact same license as the source **TypeScript** library they were based on. You are responsible for
+correctly applying your chosen license to your work (most licenses have documentations outlining how to correctly apply
+the license), and for complying with the terms of the licenses of packages your work depends on (this is particularly
+important when dependencies are bundled, as discussed later in this section).
+
+In addition to the `license` field present in the `package.json` file, we stronly recommend adding a `LICENSE` file in
+the package's root directory which contains the standardized text for the license (those can be found on the
+[SPDX website](https://spdx.org/licenses/)).
+
+!!! danger
+    Unless you know exactly what you are doing, you should copy the license text **verbatim** in the `LICENSE` file.
+    Many organizations have license scanners that will only recognize the standard license text, and editing that may
+    cause undesired friction before users in those organizations can use your library, and may void your license choice.
+
+A `NOTICE` file is often desirable. In particular, if you are developing the library as part of your employment, you
+should ask your employer's legal team (or equivalent) for specific instructions.
+
+!!! danger
+    If your library includes bundled dependencies (via the [`bundledDependencies`/`bundleDependencies`][npm-bundled] key
+    in the `package.json` file), you are required to comply with those dependencies' licenses provisions pertaining to
+    re-distribution. This often means providing attribution to these in your `NOTICE` file, among other requirements.
+
+    [npm-bundled]: https://docs.npmjs.com/cli/v6/configuring-npm/package-json#bundleddependencies
+
+The `LICENSE` and `NOTICE` files, when present, will be copied into generated binding's source code. If no `LICENSE`
+file exists in the source package, the standard SPDX license text will be produced into a `LICENSE` file in generated
+bindings whenever possible.
+
 ### Source Control Information
 
 The [`repository`][npm-repository] field must be set to the URL of the source-control system (such as a `git`

gh-pages/content/user-guides/lib-author/quick-start/set-up.md

@@ -51,6 +51,11 @@ points, such as _Maven Central_):
 }
 ```
 
+!!! important
+    Before publishing your work, be sure to review the [Important License Information][license-info] documentation.
+
+    [license-info]: ../configuration/index.md#important-license-information
+
 ## Setting up the _jsii_ configuration
 
 Finish up the configuration by running `jsii-config`, and letting the assistant guide you through the process:

packages/jsii-pacmak/lib/generator.ts

@@ -46,11 +46,35 @@ export interface IGenerator {
 
   /**
    * Determine if the generated artifacts for this generator are already up-to-date.
+   *
    * @param outDir the directory where generated artifacts would be placed.
+   * @param tarball the tarball of the bundled node library
+   * @param legalese the license and notice file contents (if any)
+   *
    * @return ``true`` if no generation is necessary
    */
   upToDate(outDir: string): Promise<boolean>;
-  save(outdir: string, tarball: string): Promise<any>;
+
+  /**
+   * Saves the generated code in the provided output directory.
+   *
+   * @param outdir the directory in which to place generated code.
+   * @param tarball the bundled npm library backing the generated code.
+   * @param legalese the LICENSE & NOTICE contents for this package.
+   */
+  save(outdir: string, tarball: string, legalese: Legalese): Promise<any>;
+}
+
+export interface Legalese {
+  /**
+   * The text of the SPDX license associated with this package, if any.
+   */
+  readonly license?: string;
+
+  /**
+   * The contents of the NOTICE file for this package, if any.
+   */
+  readonly notice?: string;
 }
 
 /**
@@ -140,14 +164,29 @@ export abstract class Generator implements IGenerator {
   /**
    * Saves all generated files to an output directory, creating any subdirs if needed.
    */
-  public async save(outdir: string, tarball: string) {
+  public async save(
+    outdir: string,
+    tarball: string,
+    { license, notice }: Legalese,
+  ) {
     const assemblyDir = this.getAssemblyOutputDir(this.assembly);
     if (assemblyDir) {
       const fullPath = path.resolve(
         path.join(outdir, assemblyDir, this.getAssemblyFileName()),
       );
       await fs.mkdirp(path.dirname(fullPath));
       await fs.copy(tarball, fullPath, { overwrite: true });
+
+      if (license) {
+        await fs.writeFile(path.resolve(outdir, 'LICENSE'), license, {
+          encoding: 'utf8',
+        });
+      }
+      if (notice) {
+        await fs.writeFile(path.resolve(outdir, 'NOTICE'), notice, {
+          encoding: 'utf8',
+        });
+      }
     }
 
     return this.code.save(outdir);

packages/jsii-pacmak/lib/target.ts

@@ -3,6 +3,7 @@ import * as fs from 'fs-extra';
 import * as reflect from 'jsii-reflect';
 import { Rosetta } from 'jsii-rosetta';
 import * as path from 'path';
+import * as spdx from 'spdx-license-list/full';
 
 import { traverseDependencyGraph } from './dependency-graph';
 import { IGenerator } from './generator';
@@ -39,7 +40,18 @@ export abstract class Target {
 
     if (this.force || !(await this.generator.upToDate(outDir))) {
       this.generator.generate(this.fingerprint);
-      await this.generator.save(outDir, tarball);
+
+      const licenseFile = path.join(this.packageDir, 'LICENSE');
+      const license = (await fs.pathExists(licenseFile))
+        ? await fs.readFile(licenseFile, 'utf8')
+        : spdx[this.assembly.license]?.licenseText;
+
+      const noticeFile = path.join(this.packageDir, 'NOTICE');
+      const notice = (await fs.pathExists(noticeFile))
+        ? await fs.readFile(noticeFile, 'utf8')
+        : undefined;
+
+      await this.generator.save(outDir, tarball, { license, notice });
     } else {
       logging.info(
         `Generated code for ${this.targetName} was already up-to-date in ${outDir} (use --force to re-generate)`,

packages/jsii-pacmak/lib/targets/dotnet/dotnetgenerator.ts

@@ -5,7 +5,7 @@ import * as reflect from 'jsii-reflect';
 import { Rosetta } from 'jsii-rosetta';
 import * as path from 'path';
 
-import { Generator } from '../../generator';
+import { Generator, Legalese } from '../../generator';
 import { DotNetDocGenerator } from './dotnetdocgenerator';
 import { DotNetRuntimeGenerator } from './dotnetruntimegenerator';
 import { DotNetTypeResolver } from './dotnettyperesolver';
@@ -75,7 +75,11 @@ export class DotNetGenerator extends Generator {
     super.generate(fingerprint);
   }
 
-  public async save(outdir: string, tarball: string): Promise<string[]> {
+  public async save(
+    outdir: string,
+    tarball: string,
+    { license, notice }: Legalese,
+  ): Promise<string[]> {
     // Generating the csproj and AssemblyInfo.cs files
     const tarballFileName = path.basename(tarball);
     const filegen = new FileGenerator(
@@ -101,6 +105,17 @@ export class DotNetGenerator extends Generator {
     // Create an anchor file for the current model
     this.generateDependencyAnchorFile();
 
+    if (license) {
+      await fs.writeFile(path.join(outdir, packageId, 'LICENSE'), license, {
+        encoding: 'utf8',
+      });
+    }
+    if (notice) {
+      await fs.writeFile(path.join(outdir, packageId, 'NOTICE'), notice, {
+        encoding: 'utf8',
+      });
+    }
+
     // Saving the generated code.
     return this.code.save(outdir);
   }

packages/jsii-pacmak/lib/targets/go.ts

@@ -4,7 +4,7 @@ import { Assembly } from 'jsii-reflect';
 import { Rosetta } from 'jsii-rosetta';
 import * as path from 'path';
 
-import { IGenerator } from '../generator';
+import { IGenerator, Legalese } from '../generator';
 import * as logging from '../logging';
 import { findLocalBuildDirs, Target, TargetOptions } from '../target';
 import { shell } from '../util';
@@ -147,11 +147,27 @@ class GoGenerator implements IGenerator {
     });
   }
 
-  public async save(outDir: string, tarball: string): Promise<any> {
+  public async save(
+    outDir: string,
+    tarball: string,
+    { license, notice }: Legalese,
+  ): Promise<any> {
     await this.embedTarball(tarball);
 
     const output = path.join(outDir, goPackageName(this.assembly.name));
     await this.code.save(output);
+
+    if (license) {
+      await fs.writeFile(path.join(output, 'LICENSE'), license, {
+        encoding: 'utf8',
+      });
+    }
+
+    if (notice) {
+      await fs.writeFile(path.join(output, 'NOTICE'), notice, {
+        encoding: 'utf8',
+      });
+    }
   }
 
   private async embedTarball(source: string) {

packages/jsii-pacmak/lib/targets/js.ts

@@ -1,6 +1,6 @@
 import * as spec from '@jsii/spec';
 
-import { Generator } from '../generator';
+import { Generator, Legalese } from '../generator';
 import { PackageInfo, Target } from '../target';
 import { toReleaseVersion } from './version-utils';
 
@@ -62,6 +62,11 @@ export default class JavaScript extends Target {
 // ##################
 
 class PackOnly extends Generator {
+  public async save(outdir: string, tarball: string, _: Legalese) {
+    // Intentionally ignore the Legalese field here... it's not useful here.
+    return super.save(outdir, tarball, {});
+  }
+
   protected getAssemblyOutputDir(_mod: spec.Assembly) {
     return '.';
   }