Fathom

Turn any repository into clean release notes, a living documentation site, and a dependency/license bill of materials — in one command.

Zero runtime dependencies · Works offline · Open-core (MIT)

---

Fathom is an engineering tool for people who ship. It reads your git history, your source files and your dependency manifests, then produces everything a maintainer needs to release and communicate with confidence:

Command	Produces
fathom changelog	A Keep-a-Changelog / Semantic-Versioning CHANGELOG.md from your commits
fathom sbom	A CycloneDX / SPDX bill of materials + license policy report
fathom docs	A searchable, themed static documentation site
fathom build	All of the above into one deployable output
fathom serve	A local web server to preview the result

Why Fathom

Release notes people actually read. Fathom groups conventional commits (feat, fix, perf, docs, chore, …), detects breaking changes, and links issue references — so the changelog reads like an editorial release, not a log dump.

Compliance without a compliance team. The SBOM command inventories every dependency, resolves versions and licenses where possible, and flags copyleft licenses against your own policy. This is the kind of evidence auditors and customers ask for (EU CRA, US EO 14028, SOC 2, MSSN).

Documentation that stays in sync. Docs are generated from the repo itself, so they never drift from the code. A README becomes a landing page, your docs/ folder becomes the guide, and source symbols become a searchable API index.

Single binary, zero setup. No runtime dependencies, no config ceremony, no network calls. One npm i -g @stealth-alpha/fathom and you're shipping.

Installation

npm install --global @stealth-alpha/fathom

Requires Node 18+ and git on your PATH. Works on macOS, Linux and Windows.

Quick start

cd my-project
fathom init          # create fathom.config.json
fathom build         # CHANGELOG.md + sbom.json + a docs site in fathom-dist/
fathom serve --port 8080

Open http://localhost:8080 to explore your generated docs, changelog and SBOM.

Using the changelog

git log --oneline
# 2d502be chore: bump lodash to 4.17.21
# 4689f01 docs: update installation guide
# 1db8e5d feat!: rewrite pricing engine with v2 business rules
# 7cf71ee fix(api): handle null user response in users endpoint
# b03286b feat(auth): add OAuth login flow

fathom changelog --write

fathom changelog understands conventional commits, BREAKING CHANGE: notes and #42 / GH-42 / JIRA-42 references. Use --range v1.0.0..HEAD for a single release, and --format json for CI.

Using the SBOM

fathom sbom                          # CycloneDX (default)
fathom sbom --format spdx            # SPDX 2.3 tag-value
fathom sbom --format md --write     # LICENSES.md compliance report

Fathom detects package.json, requirements.txt, go.mod, Cargo.{toml,lock}, composer.json, Gemfile.lock and pubspec.yaml. Add a policy to block or warn on specific licenses:

{
  "sbom": {
    "policy": {
      "blockLicenses": ["GPL-3.0", "AGPL-3.0"],
      "warnLicenses": ["GPL-2.0", "MPL-2.0"]
    }
  }
}

Configuration

fathom init writes a fully documented fathom.config.json. The most useful fields:

{
  "name": "acme-api",
  "changelog": { "file": "CHANGELOG.md", "unreleased": true },
  "sbom": { "formats": ["cyclonedx", "md"] },
  "docs": {
    "title": "Acme API Docs",
    "theme": "dark",
    "primary": "#6366f1",
    "source": ["."]
  },
  "build": { "output": "fathom-dist" }
}

CLI reference

Command	Description
fathom init	Create fathom.config.json
fathom changelog	Generate release notes (md / json / html)
fathom sbom	Generate a dependency + license bill of materials
fathom docs	Build a static documentation site
fathom build	Run changelog + sbom + docs into one output
fathom serve	Serve the build output locally
fathom version	Print the version

Run fathom help for all flags.

CI & pre-commit

Add the GitHub Action in docs.yml to regenerate your docs, changelog and SBOM on every push and publish them to GitHub Pages:

- run: npm install --global @stealth-alpha/fathom
- run: fathom build --out site
- uses: actions/upload-pages-artifact@v3
  with: { path: site }

Keep your changelog fresh with the pre-commit hook:

# .pre-commit-config.yaml
- repo: local
  hooks:
    - id: fathom
      entry: fathom changelog --write
      language: node
      pass_filenames: false

Dogfooding

Fathom documents itself. Every push to main regenerates this repo's changelog, docs site and SBOM with Fathom itself (see .github/workflows/docs.yml):

• Live docs site: stealth-alpha.github.io/fathom
• CHANGELOG.md — release notes generated from git history
• sbom.json — CycloneDX bill of materials (it lists zero components: Fathom has zero runtime dependencies)
• LICENSES.md — the human-readable license report

Pro (open-core)

The core CLI is free and open source under MIT. Fathom Pro adds the things teams need once they grow past a single repo — see docs/pro.md and PRICING.md.

Contributing

Contributions are welcome. Read CONTRIBUTING.md, then:

npm install
npm test

License

MIT

---

Part of the stealth-alpha toolkit — eight zero-dependency CLIs for release automation, agent security, and repo hygiene.