# @git.zone/notices

The third-party notices format of git.zone's build tools: find the license and notice files of the npm packages a build contains, merge the notices its prebuilt artifacts such as WebAssembly binaries carry, and read, merge, render and write the `<file>.third-party-notices.json` and `.txt` files that travel beside a build output.

## Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.

## Install

```bash
pnpm add @git.zone/notices
```

It needs Node.js 22.14 or later and depends only on Node.js builtins and `@push.rocks/smartconfig`. It is the notices module of `@git.zone/tsrepo` (`ts_bundle_notices/`, also exported there as `@git.zone/tsrepo/bundle/notices`), published on its own so that tools which write or read notices, `@git.zone/rsrepo` among them, need neither tsrepo nor its bundlers. It does not depend on `@git.zone/tsrepo` or `@git.zone/rsrepo`.

## The format

`renderThirdPartyNoticesJson()` writes, and `parseThirdPartyNotices()` reads and validates, one JSON document:

```ts
interface IThirdPartyNotices {
  generator: string; // the tool that wrote it; '@git.zone/tsbundle' unless a caller names another
  packages: Array<{
    name: string;
    version: string;
    license: string | null; // as declared in the package's package.json
    files: Array<{
      name: string; // path relative to the package root, '/' separators
      origin: 'package' | 'supplement';
      suppliedBy?: string; // for a supplement: 'project', 'build options' or '<name>@<version>'
      sha256: string; // hex SHA-256 of the file as read
      text: string;
    }>;
  }>;
}
```

`renderThirdPartyNoticesText()` renders the same document as plain text. Both are byte-identical on every machine: packages and files are ordered by code unit.

### Notices beside an artifact

Every output carries its notices beside it, `<file>.third-party-notices.json` and `<file>.third-party-notices.txt` (`getThirdPartyNoticesPaths(file)`), whichever tool wrote the file: a bundle, an executable, a WebAssembly binary. `@git.zone/rsrepo` writes the pair beside each `dist_wasm/<name>.wasm` with `renderThirdPartyNoticesJson()`, its crates named `cargo:<crate>` (npm package names never contain `:`). A bundle that emits or inlines such a binary passes it to `resolveThirdPartyNotices()` as an `artifactPaths` entry, which reads the JSON file and merges its packages with `mergeThirdPartyNoticePackages()`: one entry per `name@version` across the npm packages and every artifact, each file (origin, supplier, name and digest) once, and a second license or text for one of them is an error. The bundle's `generator` stays its own. When the result lists such components, `renderThirdPartyNoticesText()` describes them next to the npm packages.

## API

- `resolveThirdPartyNotices({ projectDirectory, modulePaths, packageDirectories, compiledPackageDirectories, artifactPaths, generator, supplements, optionSupplements })`: attributes every module path to the npm package whose `node_modules` folder holds it and collects each package's `LICENSE`, `LICENCE`, `COPYING`, `NOTICE` and `THIRD-PARTY-NOTICES` files (at every depth for `compiledPackageDirectories`). A package that ships none needs a supplement, else it throws `ThirdPartyNoticesError` naming every such package. Each of `artifactPaths`, a prebuilt artifact the output embeds or carries such as a WebAssembly binary, must carry its own notices beside it (see "Notices beside an artifact"); their packages are merged into the result, else it throws `ThirdPartyNoticesArtifactError` naming every such artifact and the file it lacks (`missingArtifacts`).
- `readArtifactThirdPartyNotices(artifactPath)`: the notices beside one artifact, parsed and validated by `parseThirdPartyNotices()`; `undefined` when there are none.
- `resolveThirdPartyNoticesSettings({ projectDirectory, production, options })`: whether a build writes notices, and its supplements, from the options and the project's `.smartconfig.json` (`"@git.zone/tsrepo".bundle.thirdPartyNotices`, else the legacy `"@git.zone/tsbundle".thirdPartyNotices`; a project configured under both is refused). Bundled packages may ship supplements in their own `.smartconfig.json` under the same keys.
- `parseThirdPartyNotices(json, source?)`, `mergeThirdPartyNoticePackages(packageLists)` (one entry per `name@version`; a second license or a second text for one file throws), `createThirdPartyNoticeFile(options)`: read, combine and build notices; a document or entry the format does not allow throws `ThirdPartyNoticesFormatError`.
- `renderThirdPartyNoticesJson(notices)`, `renderThirdPartyNoticesText(notices)`, `renderThirdPartyNoticePackageSections(packages)`, `writeThirdPartyNotices(outputPath, notices)`: write the two files beside an output; `getThirdPartyNoticesPaths(outputPath)` names them (`thirdPartyNoticesJsonSuffix`, `thirdPartyNoticesTextSuffix`).
- `getPackageDirectory(modulePath)` and `getEsbuildMetafileModulePaths(metafile, workingDirectory)`: package attribution helpers.
- Types: `IThirdPartyNotices`, `IThirdPartyNoticesMissingArtifact`, `IThirdPartyNoticePackage`, `IThirdPartyNoticeFile`, `IThirdPartyNoticeSupplement`, `IThirdPartyNoticesConfig`, `IResolvedThirdPartyNoticesSettings` and the option interfaces.

## License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [license](./license.md) file.

**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

### Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

### Company Information

Task Venture Capital GmbH
Registered at District Court Bremen HRB 35230 HB, Germany

For any legal inquiries or further information, please contact us via email at hello@task.vc.

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.
