diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index db8433e..2752398 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -8,7 +8,9 @@ # ichava-js-icon-components--.tgz one pack, every flavour and export, as the # package @ichava/js-icon-components- # SHA256SUMS over the tarballs -# Each is `npm pack` output, checked by scripts/check-tarball.mjs before upload. +# Each is `npm pack` output, checked by scripts/check-tarball.mjs before upload, and the full +# tarball's name is checked against prepare.mjs's tarballUrl() by scripts/check-release-name.mjs. +# A pre-release tag (vX.Y.Z-rc.N) gets the same tarballs, on a GitHub pre-release. # # A tag is the only legitimate `push` trigger in this ecosystem; everything else # runs on `pull_request`. @@ -214,6 +216,12 @@ jobs: (cd release && sha256sum -- *.tgz > SHA256SUMS) ls -l release + # The full tarball must carry the exact name and tag scripts/prepare.mjs's tarballUrl() + # prints for a `"install": "tarball"` refusal, and SHA256SUMS must list it, or that + # command and the documented install line break. This fails before anything is published. + - name: Check the tarball matches the install URL + run: node scripts/check-release-name.mjs release "$TAG" + - name: Publish uses: softprops/action-gh-release@8a0cd651e5b2365bd640854a3fa5dfc70e4875f3 # v3.0.4 with: diff --git a/CHANGELOG.md b/CHANGELOG.md index a74cbd0..c5af433 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,14 @@ All notable changes to `@ichava/js-icon-components` follow [Keep a Changelog](ht ## [Unreleased] +### Added + +- **The release checks its tarball against the install URL.** `scripts/check-release-name.mjs` runs in `release.yml` after packing and before publishing, and fails unless the release directory holds the full tarball under the exact name `tarballUrl()` in `scripts/prepare.mjs` gives for the tag (the command an `"install": "tarball"` refusal prints) and `SHA256SUMS` lists it. Pre-release tags are checked the same way. `tests/release-name.test.ts` covers final and pre-release tags, a drifted name and the workflow step's place (proven red by renaming the file in `tarballUrl()`, and by removing the step). + +### Changed + +- **The install docs offer both paths in order.** The README's Install and `docs/installation.md` lead with the release tarball (`npm install` of the release URL, and the `SHA256SUMS` check), for an install with no build, then the git install, for contributors or a pinned commit. The git install itself is unchanged. + ## [0.1.0] - 2026-11-13 First release. diff --git a/README.md b/README.md index ff0ddd6..68d5e31 100644 --- a/README.md +++ b/README.md @@ -22,15 +22,26 @@ Node 24 or newer to install. The framework is an optional peer, for the flavour ## Install -Two paths, chosen per application. The prebuilt release tarball has every pack, flavour and export -and builds nothing: +Two ways, both supported. **The release tarball** is the one to use in an application: it is built +once when a release is tagged, holds every pack, flavour and export, and installs with no build, +compiler or `git`: ```bash npm install https://github.com/ichava/js-icon-components/releases/download/v0.1.0/ichava-js-icon-components-0.1.0.tgz ``` -A git build compiles only what you choose, with environment variables or the same keys under -`"ichava": { "icons": { … } }` in your `package.json`. It needs `git` on the path: +To check it against the release's `SHA256SUMS` first: + +```bash +curl -sLO https://github.com/ichava/js-icon-components/releases/download/v0.1.0/ichava-js-icon-components-0.1.0.tgz +curl -sL https://github.com/ichava/js-icon-components/releases/download/v0.1.0/SHA256SUMS | grep ichava-js-icon-components-0.1.0.tgz | shasum -a 256 -c +npm install ./ichava-js-icon-components-0.1.0.tgz +``` + +**The git install** is for contributors, or for pinning a commit that has no release yet. npm runs +the `prepare` build, with the compilers (several hundred MB) in npm's temporary clone, in 24 to +69 s. It compiles only what you choose, with environment variables or the same keys under +`"ichava": { "icons": { … } }` in your `package.json`, and needs `git` on the path: ```bash ICHAVA_ICONS_PACKS=tabler ICHAVA_ICONS_FLAVOURS=react \ @@ -44,9 +55,9 @@ ICHAVA_ICONS_PACKS=tabler ICHAVA_ICONS_FLAVOURS=react \ | `ICHAVA_ICONS_SKIP_BUILD=1` | `"skipBuild": true` | builds nothing | | `ICHAVA_ICONS_INSTALL=tarball` | `"install": "tarball"` | refuses the git build and names the release tarball | -The release also attaches one tarball per pack (`@ichava/js-icon-components-`) and -`SHA256SUMS`. An import of a pack or flavour that was not built throws, naming the variable that adds -it. See [Installation](docs/installation.md) for the per-pack tarballs, checksums, sizes and times. +The release also attaches one tarball per pack (`@ichava/js-icon-components-`). An import of +a pack or flavour that was not built throws, naming the variable that adds it. See +[Installation](docs/installation.md) for the per-pack tarballs, checksums, sizes and times. ## Quick start guide and usage diff --git a/docs/installation.md b/docs/installation.md index 60c7488..81bbacd 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -1,11 +1,16 @@ # Installation -There are two ways in. Pick one per application: +There are two ways in, and both are supported. Pick one per application: | Path | Choose it when | What npm does | |---|---|---| -| **Release tarball** | You want every pack and flavour, installed fast | Downloads the prebuilt `dist/`; builds nothing, needs no `git` or compiler | -| **Git build** | You want only some packs or flavours, or to pin a commit | Clones the repository and builds `dist/` for your selection | +| **Release tarball** | Installing into an application: every pack and flavour, installed fast | Downloads the prebuilt `dist/`; builds nothing, needs no `git` or compiler | +| **Git build** | Contributing, pinning a commit that has no release, or building only some packs or flavours | Clones the repository and runs the `prepare` build for your selection | + +The release tarball is built once, by `release.yml`, when a `vX.Y.Z` tag is pushed (and for a +`vX.Y.Z-rc.N` tag, on a GitHub pre-release). It is attached to that release as +`ichava-js-icon-components-X.Y.Z.tgz`, with its checksum in `SHA256SUMS`. A git install builds +instead, with the compilers (several hundred MB) in npm's temporary clone; see [Size and time](#size-and-time). `"ichava": { "icons": { "install": "tarball" } }` in your application's `package.json` (or `ICHAVA_ICONS_INSTALL=tarball`) makes the choice binding: a git install then stops with the tarball @@ -28,7 +33,10 @@ npm install https://github.com/ichava/js-icon-components/releases/download/v0.1. } ``` -The tarball is `npm pack` output, built once by `release.yml` when the release is tagged. It +The tarball is `npm pack` output, built once by `release.yml` when the release is tagged. Its name +is the one `scripts/prepare.mjs` prints for an `"install": "tarball"` refusal: `release.yml` runs +`scripts/check-release-name.mjs` before publishing and fails on any other name, or a `SHA256SUMS` +that does not list it. It holds `dist/` for every pack, flavour and asset export and nothing else: no source, no tests, and no dependencies. npm runs no build for a tarball, so no compiler, `git` or network access to the packs is needed. Then import the flavour you use, as in the [README](../README.md#quick-start-guide-and-usage). diff --git a/docs/release.md b/docs/release.md index a30f0e4..3ed2265 100644 --- a/docs/release.md +++ b/docs/release.md @@ -33,7 +33,10 @@ Each tarball is `npm pack` output, written by `scripts/pack-tarball.mjs` (which tarball its own package name while it packs, then restores `package.json`) and checked by `scripts/check-tarball.mjs` before upload: `dist/` for everything its manifest says was built, a stand-in for the rest, the Elm module and every export of each built pack, the package name its -contents call for, nothing from the development tree, and no dependencies. To rebuild them for a tag, which creates or updates that tag's release +contents call for, nothing from the development tree, and no dependencies. Then +`scripts/check-release-name.mjs` checks the full tarball is named exactly as `tarballUrl()` in +`scripts/prepare.mjs` builds its download URL, and that `SHA256SUMS` lists it; a mismatch fails the +run before anything is published, so the install command `prepare` prints cannot drift from the asset. To rebuild them for a tag, which creates or updates that tag's release only: ```bash diff --git a/scripts/check-release-name.mjs b/scripts/check-release-name.mjs new file mode 100644 index 0000000..cbca999 --- /dev/null +++ b/scripts/check-release-name.mjs @@ -0,0 +1,48 @@ +// @ts-check +/** + * Checks that a release attaches the full tarball under the exact name and tag `prepare` points a + * reader to. `tarballUrl()` in prepare.mjs is what a `"install": "tarball"` refusal prints, and + * the docs install from the same URL, so a release whose tarball is named any other way breaks + * that command for every reader of it. Used by release.yml after packing, and by the tests. + * + * node scripts/check-release-name.mjs + * + * `` is `vX.Y.Z` or `vX.Y.Z-rc.N`; a pre-release tarball carries the pre-release version. + */ +import { existsSync, readdirSync, readFileSync } from 'node:fs'; +import { basename, join, resolve } from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { tarballUrl } from './prepare.mjs'; + +/** + * @param {{ tag: string, files: string[], sums?: string }} input + * `files` are the names in the release directory; `sums` is its SHA256SUMS text, when written. + * @returns {string[]} the problems found; empty when the release matches `tarballUrl()` + */ +export function releaseNameProblems({ tag, files, sums }) { + if (!/^v\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/.test(tag)) return [`'${tag}' is not a vX.Y.Z or vX.Y.Z-rc.N release tag`]; + const url = tarballUrl(tag.slice(1)); + const name = basename(url); + const problems = []; + if (!url.endsWith(`/releases/download/${tag}/${name}`)) problems.push(`tarballUrl() points at ${url}, which is not a download from the ${tag} release`); + if (!files.includes(name)) { + const tgz = files.filter((f) => f.endsWith('.tgz')); + problems.push(`the release has no ${name}, the name tarballUrl() gives (it has ${tgz.length === 0 ? 'no tarball' : tgz.join(', ')})`); + } + if (sums !== undefined && !sums.split('\n').some((line) => line.trim().endsWith(` ${name}`))) problems.push(`SHA256SUMS does not list ${name}`); + return problems; +} + +function main() { + const [dir, tag] = process.argv.slice(2); + if (dir === undefined || tag === undefined) throw new Error('usage: check-release-name.mjs '); + const sumsFile = join(dir, 'SHA256SUMS'); + const problems = releaseNameProblems({ tag, files: readdirSync(dir), ...(existsSync(sumsFile) ? { sums: readFileSync(sumsFile, 'utf8') } : {}) }); + if (problems.length > 0) { + for (const p of problems) console.error(`::error::${p}`); + process.exit(1); + } + console.log(`${join(dir, basename(tarballUrl(tag.slice(1))))}: matches ${tarballUrl(tag.slice(1))}`); +} + +if (process.argv[1] !== undefined && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) main(); diff --git a/tests/release-name.test.ts b/tests/release-name.test.ts new file mode 100644 index 0000000..1dd2524 --- /dev/null +++ b/tests/release-name.test.ts @@ -0,0 +1,78 @@ +import { spawnSync } from 'node:child_process'; +import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { afterAll, describe, expect, it } from 'vitest'; +import { parse } from 'yaml'; +import { releaseNameProblems } from '../scripts/check-release-name.mjs'; +import { tarballUrl } from '../scripts/prepare.mjs'; +import { ROOT } from './helpers.ts'; + +/** + * The release attaches the full tarball under the name `tarballUrl()` gives, so the command a + * `"install": "tarball"` refusal prints, and the documented install line, never drift from what + * release.yml uploads. release.yml runs scripts/check-release-name.mjs after packing. + */ +const work = mkdtempSync(join(tmpdir(), 'ichava-release-name-')); +afterAll(() => rmSync(work, { recursive: true, force: true })); + +const SUMS = (name: string) => `${'0'.repeat(64)} ${name}\n`; + +type Step = { name?: string; run?: string }; +const workflow = parse(readFileSync(join(ROOT, '.github/workflows/release.yml'), 'utf8')) as { + on: { push: { tags: string[] } }; + jobs: { release: { steps: Step[] } }; +}; +const steps = workflow.jobs.release.steps; + +describe('the release tarball name', () => { + it('matches tarballUrl() for a final tag', () => { + const name = 'ichava-js-icon-components-0.2.0.tgz'; + expect(tarballUrl('0.2.0')).toBe(`https://github.com/ichava/js-icon-components/releases/download/v0.2.0/${name}`); + expect(releaseNameProblems({ tag: 'v0.2.0', files: [name, 'SHA256SUMS'], sums: SUMS(name) })).toEqual([]); + }); + + it('matches tarballUrl() for a pre-release tag, which packs with its own version', () => { + const name = 'ichava-js-icon-components-0.2.0-rc.1.tgz'; + expect(releaseNameProblems({ tag: 'v0.2.0-rc.1', files: [name], sums: SUMS(name) })).toEqual([]); + }); + + it('refuses a release whose tarball is named differently, or that SHA256SUMS does not list', () => { + expect(releaseNameProblems({ tag: 'v0.2.0', files: ['js-icon-components-0.2.0.tgz'], sums: SUMS('js-icon-components-0.2.0.tgz') })).toEqual([ + 'the release has no ichava-js-icon-components-0.2.0.tgz, the name tarballUrl() gives (it has js-icon-components-0.2.0.tgz)', + 'SHA256SUMS does not list ichava-js-icon-components-0.2.0.tgz', + ]); + expect(releaseNameProblems({ tag: 'v0.2.0', files: [] })).toEqual(['the release has no ichava-js-icon-components-0.2.0.tgz, the name tarballUrl() gives (it has no tarball)']); + expect(releaseNameProblems({ tag: '0.2.0', files: [] })).toEqual(["'0.2.0' is not a vX.Y.Z or vX.Y.Z-rc.N release tag"]); + }); + + it('the script exits non-zero on a drifted name and zero on the right one', () => { + const good = 'ichava-js-icon-components-0.2.0.tgz'; + writeFileSync(join(work, 'js-icon-components-0.2.0.tgz'), ''); + writeFileSync(join(work, 'SHA256SUMS'), SUMS('js-icon-components-0.2.0.tgz')); + const run = () => spawnSync('node', [join(ROOT, 'scripts/check-release-name.mjs'), work, 'v0.2.0'], { encoding: 'utf8' }); + const red = run(); + expect(red.status).toBe(1); + expect(red.stderr).toContain(`the release has no ${good}`); + + writeFileSync(join(work, good), ''); + writeFileSync(join(work, 'SHA256SUMS'), SUMS(good)); + expect(run().status).toBe(0); + }); +}); + +describe('release.yml', () => { + it('runs on final and pre-release tags', () => { + expect(workflow.on.push.tags).toEqual(['v*.*.*', 'v*.*.*-*']); + }); + + it('checks the tarball name against tarballUrl() after packing and before publishing', () => { + const at = (match: (s: Step) => boolean) => steps.findIndex(match); + const pack = at((s) => s.run?.includes('scripts/pack-tarball.mjs') === true); + const check = at((s) => s.run?.trim() === 'node scripts/check-release-name.mjs release "$TAG"'); + const publish = at((s) => s.name === 'Publish'); + expect(pack).toBeGreaterThan(-1); + expect(check).toBeGreaterThan(pack); + expect(publish).toBeGreaterThan(check); + }); +}); diff --git a/tests/tarball.test.ts b/tests/tarball.test.ts index cc54685..88605e4 100644 --- a/tests/tarball.test.ts +++ b/tests/tarball.test.ts @@ -1,10 +1,11 @@ import { execFileSync, spawnSync } from 'node:child_process'; import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs'; import { tmpdir } from 'node:os'; -import { join } from 'node:path'; +import { basename, join } from 'node:path'; import { afterAll, beforeAll, describe, expect, it } from 'vitest'; import { readTarball, tarballProblems } from '../scripts/check-tarball.mjs'; import { packTarball } from '../scripts/pack-tarball.mjs'; +import { tarballUrl } from '../scripts/prepare.mjs'; import type { Manifest } from '../src/generator/generate.ts'; import { ASSET_TARGETS } from '../src/shared/index.ts'; import { packs, ROOT } from './helpers.ts'; @@ -32,6 +33,8 @@ describe('the release tarball', () => { it('is named as the release download URL expects', () => { const { version } = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf8')) as { version: string }; expect(tgz.endsWith(`/ichava-js-icon-components-${version}.tgz`)).toBe(true); + // The name a `"install": "tarball"` refusal prints, so the two cannot drift. + expect(basename(tgz)).toBe(basename(tarballUrl(version))); }); it('holds dist/ for every pack and flavour, and nothing from the development tree', () => {