feat: support npm release history baselines (#14)

Author: jasonsaayman

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -26,7 +26,7 @@ body:
     id: inputs
     attributes:
       label: Action inputs
-      description: Include values such as `path`, `tarball-uri`, `files`, `output-file`, and whether `comment-pr` is enabled. Redact private URLs if needed.
+      description: Include values such as `path`, `package-name`, `files`, `output-file`, and whether `comment-pr` is enabled.
       render: yaml
     validations:
       required: false

.github/workflows/bundle-size.yml

@@ -94,7 +94,7 @@ jobs:
         uses: ./
         with:
           path: "bundle-size-fixture"
-          tarball-uri: "https://registry.npmjs.org/axios/-/axios-1.16.1.tgz"
+          package-name: "is-number"
           files: |
             index.js
           output-file: "bundle-size-comparison.json"

AGENTS.md

@@ -8,9 +8,10 @@ This repo is a TypeScript GitHub Action for comparing bundle sizes. The action r
 
 Core behavior today:
 
-- Accepts a `tarball-uri` baseline archive.
+- Accepts an npm `package-name` baseline.
 - Accepts newline-delimited `files` to compare.
 - Resolves local files under `path`.
+- Resolves npm release tarballs for the latest release plus up to 10 previous stable releases.
 - Resolves tarball files relative to the archive root, stripping a single shared top-level directory such as `package/`.
 - Measures gzip-compressed byte size.
 - Writes a JSON comparison report.
@@ -24,6 +25,7 @@ Current modules:
 
 - `src/action.ts`: orchestrates the GitHub Action run and action outputs.
 - `src/config.ts`: reads and validates `@actions/core` inputs.
+- `src/npm.ts`: resolves npm package metadata and release tarball baselines.
 - `src/paths.ts`: normalizes configured paths and prevents path traversal.
 - `src/tarball.ts`: downloads tarballs and extracts regular files from `.tar.gz` archives.
 - `src/comparison.ts`: computes gzip sizes and per-file/totals deltas.
@@ -56,7 +58,7 @@ When asked to commit changes in this repository, use Conventional Commit message
 - Runtime dependencies should stay small. Prefer Node built-ins when they are clear and maintainable.
 - Do not assume the caller has installed dependencies at action runtime.
 - Do not build the target project inside the action; workflows should build artifacts before invoking this action.
-- Treat missing configured files as errors. A comparison report should only be produced from trustworthy inputs.
+- Treat missing configured local files and latest-release baseline files as errors. Historical previous-release missing files may be reported as incomplete context.
 
 ## Tarball And Path Handling
 
@@ -103,13 +105,13 @@ This repo uses OpenSpec for scoped changes.
 
 When implementing a spec-driven change, read proposal, design, specs, and tasks before editing. Mark tasks complete as they are implemented. If a change introduces or modifies requirements, sync the delta spec into `openspec/specs/` before archiving.
 
-The current tarball gzip behavior is captured in `openspec/specs/tarball-gzip-comparison/spec.md`.
+The current tarball gzip behavior is captured in `openspec/specs/tarball-gzip-comparison/spec.md`. Npm release baseline behavior is captured in `openspec/specs/npm-release-baselines/spec.md` after the corresponding change is archived.
 
 ## Workflow Lessons Learned
 
 - Keep action code modular early. A single `index.ts` becomes difficult to review once config parsing, tarball handling, path safety, gzip measurement, reporting, and GitHub outputs are all mixed together.
 - Preserve `path` as the local project root. New inputs should not overload it.
-- Treat the tarball URI as an explicit baseline contract. Do not add package-manager shorthand such as `npm:axios@latest` unless a spec/proposal calls for registry resolution.
+- Treat the npm package name as the release baseline contract. Do not add package-manager shorthand such as `npm:axios@latest` unless a spec/proposal calls for it.
 - Build comparison files on PRs from already-built local artifacts. On GitHub pull requests, the checkout/build represents the merge result when using the default PR merge ref.
 - Avoid target-size enforcement in the current capability. Reporting and enforcing are different product behaviors and should remain separate changes.
 - Keep `dist/index.js` synchronized with `src/`; otherwise the committed action will not match the reviewed TypeScript.

COLLABORATOR_GUIDE.md

@@ -57,7 +57,7 @@ For issues and discussions:
 - Keep unsupported feature requests open only when they fit the project direction.
 - Close issues that are duplicates, out of scope, or cannot be reproduced after reasonable follow-up.
 
-This action compares already-built files. If a report is wrong, first verify the configured `path`, `files`, `tarball-uri`, and `output-file` values before assuming comparison logic is faulty.
+This action compares already-built files. If a report is wrong, first verify the configured `path`, `files`, `package-name`, and `output-file` values before assuming comparison logic is faulty.
 
 ## Security Reports
 

CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contributing
 
-Thanks for helping improve `axios/bundle-size`. This repository contains a TypeScript GitHub Action that compares gzip bundle sizes against a tarball baseline.
+Thanks for helping improve `axios/bundle-size`. This repository contains a TypeScript GitHub Action that compares gzip bundle sizes against npm release baselines.
 
 Please follow the [Code of Conduct](./CODE_OF_CONDUCT.md) when participating in this project.
 
@@ -36,6 +36,7 @@ Keep `src/index.ts` thin. Prefer focused modules for behavior:
 
 - `src/action.ts`: action orchestration and outputs.
 - `src/config.ts`: action input parsing and validation.
+- `src/npm.ts`: npm registry release resolution.
 - `src/paths.ts`: path normalization and traversal protection.
 - `src/tarball.ts`: tarball download and parsing.
 - `src/comparison.ts`: gzip size calculation and report construction.
@@ -47,7 +48,7 @@ Keep `src/index.ts` thin. Prefer focused modules for behavior:
 - Keep changes small and focused.
 - Add or update tests for behavior changes.
 - Preserve the JSON report as machine-readable output.
-- Treat configured paths, tarball contents, and pull request input as untrusted.
+- Treat configured paths, npm metadata, tarball contents, and pull request input as untrusted.
 - Avoid new runtime dependencies unless there is a clear need.
 - Do not make the action build the caller's project; workflows should build artifacts before invoking this action.
 

README.md

@@ -1,6 +1,6 @@
 # Bundle Size Action
 
-A custom GitHub Action that compares gzip bundle sizes for built artifacts against matching files from a tarball baseline.
+A custom GitHub Action that compares gzip bundle sizes for built artifacts against matching files from npm release baselines.
 
 ---
 
@@ -47,8 +47,8 @@ There is no normal `lib/` workflow. Vite bundles the action directly from TypeSc
 | Name | Required | Default | Description |
 |------|----------|---------|-------------|
 | `path` | No | `.` | Path to the local project root containing built artifacts. |
-| `tarball-uri` | Yes | | HTTP(S) URI of the `.tar.gz` baseline archive to compare against. |
-| `files` | Yes | | Newline-delimited file paths to compare in the local project and tarball baseline. |
+| `package-name` | Yes | | npm package name whose latest and previous releases provide baseline archives. |
+| `files` | Yes | | Newline-delimited file paths to compare in the local project and npm release baselines. |
 | `output-file` | No | `bundle-size-comparison.json` | Path, relative to `path`, where the JSON comparison report will be written. |
 | `comment-pr` | No | `false` | Post or update a bundle size summary comment on pull requests. |
 | `github-token` | No | | GitHub token used to post pull request comments when `comment-pr` is enabled. |
@@ -60,8 +60,8 @@ There is no normal `lib/` workflow. Vite bundles the action directly from TypeSc
 | `size` | Total current gzip size in bytes for all compared files. |
 | `comparison-file` | Absolute path to the generated JSON comparison file. |
 | `total-current-gzip-size` | Total current gzip size in bytes for all compared files. |
-| `total-baseline-gzip-size` | Total baseline gzip size in bytes for all compared files. |
-| `total-delta-gzip-size` | Difference in gzip bytes between current and baseline totals. |
+| `total-baseline-gzip-size` | Total latest-release baseline gzip size in bytes for all compared files. |
+| `total-delta-gzip-size` | Difference in gzip bytes between current and latest-release baseline totals. |
 
 ---
 
@@ -84,7 +84,7 @@ steps:
     uses: axios/bundle-size@main
     with:
       path: '.'
-      tarball-uri: 'https://registry.npmjs.org/axios/-/axios-1.6.8.tgz'
+      package-name: 'axios'
       files: |
         dist/axios.js
         dist/axios.min.js
@@ -109,7 +109,7 @@ steps:
   - name: Compare Bundle Size
     uses: axios/bundle-size@main
     with:
-      tarball-uri: 'https://registry.npmjs.org/axios/-/axios-1.6.8.tgz'
+      package-name: 'axios'
       files: |
         dist/axios.js
         dist/axios.min.js
@@ -124,7 +124,9 @@ The comparison file is JSON:
 ```json
 {
   "metric": "gzip",
+  "packageName": "axios",
   "baseline": {
+    "version": "1.6.8",
     "uri": "https://registry.npmjs.org/axios/-/axios-1.6.8.tgz"
   },
   "localRoot": "/home/runner/work/project/project",
@@ -142,17 +144,52 @@ The comparison file is JSON:
     "currentBytes": 14512,
     "deltaBytes": 279,
     "deltaPercent": 1.96
-  }
+  },
+  "history": [
+    {
+      "version": "1.6.8",
+      "uri": "https://registry.npmjs.org/axios/-/axios-1.6.8.tgz",
+      "latest": true,
+      "complete": true,
+      "missingFiles": [],
+      "files": [
+        {
+          "path": "dist/axios.min.js",
+          "baselineBytes": 14233,
+          "currentBytes": 14512,
+          "deltaBytes": 279,
+          "deltaPercent": 1.96
+        }
+      ],
+      "totals": {
+        "baselineBytes": 14233,
+        "currentBytes": 14512,
+        "deltaBytes": 279,
+        "deltaPercent": 1.96
+      }
+    },
+    {
+      "version": "1.6.7",
+      "uri": "https://registry.npmjs.org/axios/-/axios-1.6.7.tgz",
+      "latest": false,
+      "complete": false,
+      "missingFiles": ["dist/axios.min.js"],
+      "files": [],
+      "totals": null
+    }
+  ]
 }
 ```
 
+The latest npm release is the primary baseline for top-level `baseline`, `files`, `totals`, and action outputs. The `history` array includes the latest release plus up to 10 previous stable releases ordered by npm publish time. Previous releases that do not contain every configured file are marked as incomplete instead of failing the action.
+
 Because this repository *is* the action, a workflow inside the same repo can reference it with `./` after preparing local files to compare:
 
 ```yaml
 - uses: ./
   with:
     path: 'bundle-size-fixture'
-    tarball-uri: 'https://registry.npmjs.org/is-number/-/is-number-7.0.0.tgz'
+    package-name: 'is-number'
     files: |
       index.js
 ```
@@ -222,17 +259,18 @@ node dist/index.js
 To simulate GitHub Actions inputs locally, set the corresponding environment variables before running:
 
 ```bash
-INPUT_PATH="." \
-INPUT_TARBALL_URI="https://registry.npmjs.org/axios/-/axios-1.6.8.tgz" \
-INPUT_FILES=$'dist/axios.js\ndist/axios.min.js' \
-node dist/index.js
+env \
+  'INPUT_PATH=.' \
+  'INPUT_PACKAGE-NAME=axios' \
+  INPUT_FILES=$'dist/axios.js\ndist/axios.min.js' \
+  node dist/index.js
 ```
 
 ---
 
 ## Current Behavior
 
-The action downloads the configured tarball, reads regular file entries, strips a single shared top-level directory such as `package/`, and compares the configured paths against local files under `path`. It measures gzip-compressed bytes for each file and writes a JSON report. It does not enforce budgets or target sizes.
+The action fetches npm registry metadata for `package-name`, resolves the `latest` dist-tag plus up to 10 previous stable releases, downloads each selected release tarball, reads regular file entries, strips a single shared top-level directory such as `package/`, and compares the configured paths against local files under `path`. It measures gzip-compressed bytes for each file and writes a JSON report. It does not enforce budgets or target sizes.
 
 Suggested next steps:
 
@@ -241,7 +279,7 @@ Suggested next steps:
 | Threshold validation             | Accept `max-size` input; call `core.setFailed` on breach   |
 | Artifact uploads                 | Use `actions/upload-artifact` to persist the size report   |
 | Multi-framework support          | Auto-detect `vite.config.*`, `webpack.config.*`, etc.      |
-| Package URI resolution           | Resolve package manager aliases such as `npm:axios@latest` |
+| Private registry auth            | Authenticate npm metadata and tarball requests             |
 
 ---
 

SECURITY.md

@@ -57,7 +57,7 @@ Out of scope examples:
 
 ## Secure Usage
 
-- Use immutable `https:` tarball URLs for `tarball-uri` when possible.
+- Configure the intended npm `package-name` and review reports for the resolved latest release version.
 - Keep `files` and `output-file` relative to the configured `path` root.
 - Use minimal workflow permissions. JSON-only comparisons should not need write permissions.
 - Enable `comment-pr` only when PR comments are needed, and pass the default `${{ github.token }}` unless a stronger token is strictly required.