@entro314labs/release-kit 2.2.0 → 2.2.2

package/README.md

@@ -305,6 +305,10 @@ Anything else runs as written with no preflight. The project name comes from the
 `name` in `package.json`, `Cargo.toml` or `pyproject.toml`, `module` in `go.mod` — falling
 back to the repository directory.
 
+With no `versionFile` configured it is detected from the repository — `package.json`,
+`pyproject.toml`, `Cargo.toml`, then `VERSION` — so most projects need no config for it at
+all. Set it explicitly to override, or to `null` for a repository that versions by tag.
+
 The format is inferred from the file name: `.json` reads the `"version"` field, `.toml`
 reads the first `version = "x.y.z"` line, and any other file is treated as containing just
 the version. Only the version itself is rewritten, so comments and formatting survive — and
@@ -346,6 +350,37 @@ name, `%d` npm dist-tag. In the `publish` command line the substituted values ar
 shell-quoted, so a version carrying shell metacharacters is passed through as one literal
 argument.
 
+### Continuous integration
+
+Non-interactive by default: the confirmation prompt is skipped when stdin is not a TTY, and
+`gh` picks up `GITHUB_TOKEN` on its own. Pass `--yes` to be explicit.
+
+```yaml
+- uses: actions/checkout@v5
+  with:
+    fetch-depth: 0 # release notes and the last-tag lookup need real history
+- id: release
+  run: npx @entro314labs/release-kit@2.1.0 minor --yes
+  env:
+    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+- run: echo "shipped ${{ steps.release.outputs.tag }} ${{ steps.release.outputs.release-url }}"
+```
+
+On success it writes to `$GITHUB_OUTPUT`, so later steps can act on what happened instead of
+re-deriving it: `version`, `tag`, `name`, `dist-tag`, `steps`, `published`, `release-url`.
+Nothing is written on a dry run, and an unwritable `$GITHUB_OUTPUT` never fails a release
+that already completed.
+
+Three things CI does that are worth knowing about:
+
+- **`fetch-depth: 0`.** The default checkout is a shallow clone, which hides the history
+  release notes are drafted from. It still releases correctly, but the notes describe a
+  fraction of the work, so a shallow clone is called out as a warning.
+- **Detached HEAD.** Tag and pull-request checkouts leave no branch to push, which is a
+  preflight failure rather than a confusing push error.
+- **Signing.** Runners have no signing key, so disable it for the run rather than shipping
+  keys around: `git -c commit.gpgsign=false -c tag.gpgsign=false`.
+
 ### Signing
 
 Signing is git's, not this tool's: commits and tags are made with plain `git commit` and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@entro314labs/release-kit",
-  "version": "2.2.0",
+  "version": "2.2.2",
   "description": "Single-file, zero-dependency release mechanism for JS/TS/Node projects: version bump, changelog roll, commit, annotated tag, push, publish, GitHub release",
   "keywords": [
     "changelog",

package/release.mjs

@@ -32,7 +32,14 @@
  */
 
 import { execFileSync, execSync } from 'node:child_process'
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs'
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  writeFileSync,
+} from 'node:fs'
 import { homedir, tmpdir } from 'node:os'
 import { basename, join, relative, resolve, sep } from 'node:path'
 import { createInterface } from 'node:readline/promises'
@@ -51,8 +58,8 @@ import { createInterface } from 'node:readline/promises'
  *   branch          string   the only branch a release may run from; null to allow any
  *   remote          string   git remote to push to
  *   changelog       string   changelog path; null to disable changelog handling
- *   versionFile     string|object|null  where the project's version lives; null when the
- *                            repository versions by git tag alone
+ *   versionFile     string|object|null  where the project's version lives. Detected from
+ *                            the repository when unset; null when it versions by tag alone
  *   versionFiles    array    further files whose version is kept in sync; each is a path
  *                            or { path, pattern }
  *   publish         string   publish command; null to skip publishing entirely
@@ -91,7 +98,7 @@ const DEFAULTS = {
   branch: 'main',
   remote: 'origin',
   changelog: 'CHANGELOG.md',
-  versionFile: 'package.json',
+  versionFile: undefined,
   versionFiles: [],
   publish: 'npm publish --tag %d',
   commitMessage: 'chore(release): %t',
@@ -850,10 +857,8 @@ if (existsSync(localManifest) && localManifest !== rootManifest) {
 }
 process.chdir(root)
 
-const config = {
-  ...DEFAULTS,
-  ...(existsSync('release.config.json') ? readJson('release.config.json') : {}),
-}
+const userConfig = existsSync('release.config.json') ? readJson('release.config.json') : {}
+const config = { ...DEFAULTS, ...userConfig }
 const unknownKeys = Object.keys(config).filter((key) => !(key in DEFAULTS))
 if (unknownKeys.length) abort(`release.config.json has unknown keys: ${unknownKeys.join(', ')}`)
 
@@ -874,7 +879,33 @@ const parseStepList = (value) =>
  * tag alone and the version has to be passed explicitly.
  */
 const manifest = existsSync('package.json') ? readJson('package.json') : null
-const versionFile = config.versionFile ? versionSource(config.versionFile) : null
+
+/**
+ * Where this project keeps its version, when the config does not say. Checked in order of
+ * how definitively each file identifies a repository. `go.mod` resolves to null because Go
+ * modules carry no version — the tag is the version.
+ */
+function detectVersionFile() {
+  for (const candidate of ['package.json', 'pyproject.toml', 'Cargo.toml', 'VERSION']) {
+    if (existsSync(candidate)) return candidate
+  }
+  return null
+}
+
+// An explicit `versionFile: null` means "versions by tag" and must not be re-detected, so
+// the distinction is between the key being absent and the key being set to null.
+const configuredVersionFile = Object.hasOwn(userConfig, 'versionFile')
+  ? userConfig.versionFile
+  : detectVersionFile()
+const versionFile = configuredVersionFile ? versionSource(configuredVersionFile) : null
+// Only worth saying when it is not the conventional default.
+if (
+  !Object.hasOwn(userConfig, 'versionFile') &&
+  versionFile &&
+  versionFile.path !== 'package.json'
+) {
+  note(`version source: ${versionFile.path} (detected)`)
+}
 
 if (versionFile && !existsSync(versionFile.path)) {
   abort(`versionFile ${versionFile.path} does not exist`)
@@ -1106,11 +1137,21 @@ if (runs('commit') && !assistant) {
 }
 
 const branch = tryRead('git', ['rev-parse', '--abbrev-ref', 'HEAD'])
+// A detached HEAD has no branch to push, and reports itself as the literal "HEAD", which
+// would otherwise be compared against config.branch and pushed as a ref of that name.
+const detached = branch === 'HEAD'
 if (!branch) fail('could not read the current branch')
-else if (config.branch && branch !== config.branch) {
+else if (detached) {
+  fail('HEAD is detached — a release needs a branch to push. Check one out first.')
+} else if (config.branch && branch !== config.branch) {
   fail(`on '${branch}', expected '${config.branch}'`)
 } else ok(`on ${branch}`)
 
+// A shallow clone (CI checkouts default to depth 1) hides the history that release notes
+// and the last-tag lookup are derived from. It still releases correctly; the notes just
+// silently describe a fraction of the work, so say so before that happens.
+const shallow = tryRead('git', ['rev-parse', '--is-shallow-repository']) === 'true'
+
 if (!succeeds('git', ['remote', 'get-url', config.remote])) {
   fail(`no '${config.remote}' remote configured`)
 } else {
@@ -1118,7 +1159,7 @@ if (!succeeds('git', ['remote', 'get-url', config.remote])) {
   // Fetch so the tag and behind-remote checks below see the real remote state.
   if (!succeeds('git', ['fetch', '--quiet', '--tags', config.remote])) {
     fail(`could not fetch from ${config.remote}`)
-  } else if (branch) {
+  } else if (branch && !detached) {
     const upstream = `${config.remote}/${branch}`
     if (!succeeds('git', ['rev-parse', '--verify', '--quiet', `refs/remotes/${upstream}`])) {
       note(`${upstream} does not exist yet — the push will create it`)
@@ -1233,6 +1274,12 @@ function draftNotesFor(v) {
   if (!assistant) return null
   const { lastTag, subjects } = commitsSinceLastTag()
   if (!subjects.length) return null
+  if (shallow) {
+    warn(
+      `shallow clone: only ${subjects.length} commit(s) are visible, so the notes will ` +
+        'describe part of the release. Check out with full history (fetch-depth: 0).',
+    )
+  }
   note(`drafting notes from ${subjects.length} commit(s) with ${assistantName}...`)
   return draftReleaseNotes(v, subjects, lastTag)
 }
@@ -1418,6 +1465,41 @@ if (runs('release') && !releaseExists) {
   mutate('gh', args, notes ? { input: `${notes}\n` } : {})
 }
 
+/**
+ * Hand the result back to whatever is orchestrating this. GitHub Actions reads key=value
+ * pairs from $GITHUB_OUTPUT, so a workflow can gate later steps on what actually happened
+ * rather than re-deriving it from the repository.
+ */
+function emitOutputs() {
+  const file = process.env.GITHUB_OUTPUT
+  if (!file || dryRun) return
+  const releaseUrl = runs('release')
+    ? (tryRead('gh', ['release', 'view', tag, '--json', 'url', '--jq', '.url']) ?? '')
+    : ''
+  const outputs = {
+    version,
+    tag,
+    name: projectName,
+    'dist-tag': distTag,
+    steps: STEPS.filter(runs).join(','),
+    published: String(!!publishCommand && !alreadyPublished),
+    'release-url': releaseUrl,
+  }
+  try {
+    appendFileSync(
+      file,
+      `${Object.entries(outputs)
+        .map(([key, value]) => `${key}=${value}`)
+        .join('\n')}\n`,
+    )
+    note(`wrote ${Object.keys(outputs).length} outputs to $GITHUB_OUTPUT`)
+  } catch {
+    // Outputs are a convenience; never fail a completed release over them.
+  }
+}
+
+emitOutputs()
+
 console.log(
   `\n${green(bold(dryRun ? 'Dry run complete — nothing was changed.' : `Released ${tag}`))}`,
 )