notice

notice

Generates and verifies the project's NOTICE file from direct dependencies in go.mod, frontend/package.json, and cmd/unbounded-storage/Cargo.toml plus the pinned libfabric and OpenSSL source versions in Makefile.

Usage

notice generate [--repo-root .] [--output NOTICE]
notice check    [--repo-root .] [--notice NOTICE]

The Makefile wraps these as make notice and make notice-check.

Output schema

The on-disk NOTICE is YAML preceded by a generated-file header comment. Each direct dependency contributes one entry:

- dependency: github.com/spf13/cobra      # Module path or npm package name.
  ecosystem: go                           # Stable Collector.Name() value.
  copyright:                              # Lines extracted from LICENSE/NOTICE/AUTHORS.
    - Copyright (c) 2013 Steve Francia
  license:                                # One per classified license name.
    - name: Apache License, Version 2.0
      link: https://github.com/spf13/cobra/blob/v1.10.2/LICENSE.txt

Entries are sorted alphabetically by dependency regardless of ecosystem.

Architecture

hack/cmd/notice/
  main.go                  # CLI: subcommands, flags, explicit collector slice.
  internal/
    notice/                # Core: Document, Entry, Collector iface, Build/Render/Diff,
                           # AssembleEntry helper.
    license/               # Ecosystem-agnostic helpers: Classify, FindFile,
                           # ExtractCopyright[FromDir], BuildURL, SPDXFriendly.
    gomod/                 # Collector for go.mod direct deps; Go vanity-domain
                           # repo-base heuristics.
    npm/                   # Collector for frontend/package.json direct deps.
    cargo/                 # Collector for direct non-dev Cargo dependencies.
    native/                # Collector for Makefile-pinned native dependencies.
    testutil/              # WriteTree + canonical license-text fixtures.

Adding a new ecosystem

To add a new ecosystem (e.g. PyPI, Cargo):

1. Create internal/<name>/ with a Collector implementation:

   type Collector struct { /* injectable runner/fs */ }
   func New(opts ...Option) *Collector { ... }
   func (c *Collector) Name() string                          // "pypi", "cargo", ...
   func (c *Collector) Precheck(root string) error            // verify host setup
   func (c *Collector) Collect(root string) ([]notice.Entry, error)
   

2. Reuse the shared helpers wherever possible:

   • notice.AssembleEntry(name, ecosystem, dir, repoBase, ref, declaredLicense) wraps license discovery, classification, copyright extraction, and URL construction. Most collectors only need to compute (dir, repoBase, ref) for each direct dependency and call this.
   • license.Classify, license.ExtractCopyright[FromDir], license.FindFile, license.BuildURL, and license.SPDXFriendly are ecosystem-agnostic.

3. Write hermetic tests using testutil.WriteTree to materialize fixture trees under t.TempDir(). Use the shared canonical license bodies (testutil.MITLicense, testutil.Apache2License, testutil.BSD3License) so the classifier sees realistic input. Inject fakes for any external tool the collector needs to invoke (go, pip, cargo); see internal/gomod/gomod_test.go for the pattern.

4. Append <name>.New() to the collectors() slice in main.go. No other files need editing.

Conventions

• Collect MUST NOT sort its result. notice.Build performs a single global sort by Dependency.
• Do not commit fake node_modules/, module-cache, or site-packages/ trees. Always materialize fixtures dynamically in tests via testutil.WriteTree.
• Cargo collection reads Cargo.toml and exact versions from Cargo.lock, then reads license files from the local Cargo registry source cache. Populate it with cargo fetch --manifest-path cmd/unbounded-storage/Cargo.toml --locked. Development dependencies are excluded; normal, target, build, and optional direct dependencies are included.
• Native collection is fully local. Its metadata and canonical license links are fixed by the collector while versions come from LIBFABRIC_VERSION and OPENSSL_VERSION in Makefile.
• License URL forge dispatch (GitHub, GitLab, cs.opensource.google, Bitbucket) lives in license.BuildURL as a switch on URL prefix. Add a case here when a new forge is needed.
• Copyright extraction returns the placeholder "See LICENSE file" when no attribution can be discovered in LICENSE / NOTICE / AUTHORS / CONTRIBUTORS / COPYRIGHT files. Source-file headers are intentionally not scanned.