Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 9 additions & 1 deletion .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,9 @@
# ichava-js-icon-components-<pack>-<version>.tgz one pack, every flavour and export, as the
# package @ichava/js-icon-components-<pack>
# 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`.
Expand Down Expand Up @@ -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:
Expand Down
8 changes: 8 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
25 changes: 18 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 \
Expand All @@ -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-<pack>`) 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-<pack>`). 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

Expand Down
16 changes: 12 additions & 4 deletions docs/installation.md
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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).
Expand Down
5 changes: 4 additions & 1 deletion docs/release.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
48 changes: 48 additions & 0 deletions scripts/check-release-name.mjs
Original file line number Diff line number Diff line change
@@ -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 <release-dir> <tag>
*
* `<tag>` 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 <release-dir> <tag>');
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();
78 changes: 78 additions & 0 deletions tests/release-name.test.ts
Original file line number Diff line number Diff line change
@@ -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);
});
});
5 changes: 4 additions & 1 deletion tests/tarball.test.ts
Original file line number Diff line number Diff line change
@@ -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';
Expand Down Expand Up @@ -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', () => {
Expand Down
Loading