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

…2604)

In order to properly attribute a license to the generated code, so it
shows up on the godoc.org website, we must produce a `LICENSE` file with
the appropriate content.

We now copy the `LICENSE` file from the source package's root if one
exists, otherwise we attempt to generate one using the SPDX standard
license text.

We also copy the `NOTICE` file from the source package's root if one
exists (but there is no fallback here, as we cannot infer the contents
of it).

See: https://pkg.go.dev/license-policy

This was applied uniformly across all existing bindings.

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 '.';
  }