@existdb/repo-xml-changelog-generator 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,10 @@
+GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 2.1, February 1999
+
+Copyright (C) 1991, 1999 Free Software Foundation, Inc.
+51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+
+[This work is licensed under the GNU Lesser General Public License,
+version 2.1 or later. Full text at https://www.gnu.org/licenses/lgpl-2.1.txt.]

package/README.md

@@ -1,3 +1,130 @@
-# Temporary Holding Version
+# @existdb/repo-xml-changelog-generator
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A [semantic-release](https://github.com/semantic-release/semantic-release) plugin that injects a new `<change>` entry into an [EXPath package descriptor](https://expath.org/spec/pkg) (typically `repo.xml.tmpl` for eXist-db XAR packages) based on the Conventional Commits between the previous release tag and the current release.
+
+## What problem this solves
+
+eXist-db apps and libraries that already use [semantic-release](https://github.com/semantic-release/semantic-release) for automated tagging and GitHub Releases still need to keep the in-XAR EXPath `<change>` history up to date. Previously, every adopter (monex, function-documentation, semver.xq) maintained its own copy of an `update-repo-changelog.js` script invoked via `@semantic-release/exec`. This plugin productizes that script into a single, configurable semantic-release plugin so the script doesn't need to be copy-pasted into every repo.
+
+## Install
+
+```bash
+npm install --save-dev @existdb/repo-xml-changelog-generator
+```
+
+## Usage
+
+Add to your `.releaserc` plugin chain. Place it after the commit-analyzer / release-notes-generator (so `lastRelease` and `nextRelease` are populated) and before any plugin that builds the XAR (so the injected change is included in the built artifact):
+
+```jsonc
+{
+  "branches": ["master"],
+  "plugins": [
+    ["@semantic-release/commit-analyzer",        { "preset": "conventionalcommits" }],
+    ["@semantic-release/release-notes-generator", { "preset": "conventionalcommits" }],
+
+    // 1) bump the version in-memory on the CI runner
+    ["@semantic-release/exec", {
+      "prepareCmd": "npm version ${nextRelease.version} --no-git-tag-version --allow-same-version"
+    }],
+
+    // 2) inject the <change> entry into repo.xml.tmpl
+    "@existdb/repo-xml-changelog-generator",
+
+    // 3) build the XAR (now sees both the bumped version + the injected <change>)
+    ["@semantic-release/exec", { "publishCmd": "npm run build" }],
+
+    // 4) tag + GitHub Release + asset upload via REST
+    ["@semantic-release/github", {
+      "assets": [{ "path": "dist/*.xar", "label": "EXPath Package (XAR)" }]
+    }]
+  ]
+}
+```
+
+**Do not** include `@semantic-release/git` in the plugin chain. The mutation this plugin performs is in-memory on the CI runner; the on-disk `repo.xml.tmpl` in your default branch stays at its development-placeholder state, and the per-release changelog history lives in git tags + GitHub Releases. See [Design rationale](#design-rationale) below.
+
+## Configuration
+
+| Option | Type | Default | Notes |
+|--------|------|---------|-------|
+| `tmplPath` | string | `'repo.xml.tmpl'` | Path to the EXPath repo descriptor template, relative to `cwd`. |
+
+```jsonc
+["@existdb/repo-xml-changelog-generator", { "tmplPath": "src/repo.xml.tmpl" }]
+```
+
+## What it does
+
+### `verifyConditions` (runs early, before any release work)
+
+- Confirms `tmplPath` exists.
+- Confirms the descriptor contains a `<changelog xmlns="http://exist-db.org/xquery/repo">` element.
+
+If either check fails, semantic-release aborts before doing anything. This is the right place to surface configuration mistakes, not the middle of a release.
+
+### `prepare` (runs after version is computed)
+
+For each conventional commit since `context.lastRelease.gitTag`:
+
+- Skip non-typed commits (those that don't match the Conventional Commits grammar).
+- Group by type using `conventional-changelog-conventionalcommits`.
+- Render each commit as `Prefix: scope: subject` where Prefix is one of:
+  - `New` (for `feat:`)
+  - `Fix` (for `fix:`)
+  - `Improvement` (for `perf:`)
+  - `Revert` (for `revert:`)
+  - or the literal type for other categories.
+- Render breaking changes as `Breaking change: <text>` from `BREAKING CHANGE:` footers.
+
+The rendered items are wrapped in a `<change version="X.Y.Z"><ul xmlns="http://www.w3.org/1999/xhtml">…</ul></change>` and inserted at the **top** of the existing `<changelog>` element (most recent first).
+
+### Edge cases
+
+| Situation | Behavior |
+|-----------|----------|
+| No `lastRelease.gitTag` (first release) | Skip injection. Log a note. Curate the initial `<change>` entry manually in the template. |
+| No conventional commits since last tag | Skip injection. Log "no notable commits". |
+| Configured `tmplPath` doesn't exist | `verifyConditions` aborts the release with a clear error. |
+| `<changelog>` element missing | `verifyConditions` aborts with instructions to add an empty `<changelog/>`. |
+| `lastRelease.gitTag` is e.g. `1.2.3` but the actual tag is `v1.2.3` | Both forms are tried; the first one that resolves wins. |
+
+## Design rationale
+
+### Why in-memory, not push-back?
+
+The default approach for many semantic-release setups is to use `@semantic-release/git` to commit the mutated files (`package.json`, `CHANGELOG.md`, etc.) back to the default branch. For eXist-db org repos with branch protection that requires PRs, this means the GitHub Actions token can't push the release commit — you need a PAT or a GitHub App to bypass protection. That's operational overhead (PAT rotation, App installation per repo, secret management).
+
+The alternative — used by `@existdb/xst`, `@existdb/node-exist`, `@existdb/gulp-exist`, and (since 2026-05-19) `eXist-db/monex` and `eXist-db/function-documentation` — is to **pin the default-branch version to `0.0.0-development` permanently**, do all the version + changelog work in-memory on the CI runner, and let the built XAR carry the real version. No push-back, no token plumbing, branch protection works as intended.
+
+This plugin is designed for that workflow. (It would also work alongside `@semantic-release/git`, but the apps in the org don't need that path.)
+
+### Why not just publish the existing script as-is?
+
+Because every adopter would still have to copy it into their repo and invoke it via `@semantic-release/exec` prepareCmd. The plugin form:
+
+- Hooks into semantic-release's lifecycle directly (gets `lastRelease`, `nextRelease`, `logger`, `cwd` natively).
+- Adds proper `verifyConditions` so misconfiguration is caught early.
+- Lets adopters install it as an npm dependency instead of vendoring a 170-line script.
+- Centralizes future improvements (e.g. cross-link PRs/issues, support `expath-pkg.xml.tmpl` version sync, support custom commit-type → prefix mappings).
+
+### Why a Node plugin, not an XQuery one?
+
+semantic-release itself is a Node tool and runs in Node. The plugin API is Node-native. Reimplementing in XQuery would mean either (a) standing up a separate XQuery runtime in CI just to run the changelog hook, or (b) calling out to it via HTTP/shell. Both add complexity for no user-visible benefit. The plugin's output (the `<change>` element it emits) is the data that lives in the XQuery world — the producer can be in any language.
+
+## Releasing this package
+
+This plugin releases itself with semantic-release, eating its own dog food. Merges to `main` run the [CI workflow](.github/workflows/release.yml): the test matrix runs, then `semantic-release` analyzes the Conventional Commits, computes the next version, publishes to npm (`@existdb` scope), and creates the GitHub Release. The in-tree `version` stays pinned at `0.0.0-development`; the real version is set in-memory at release time (the same no-push pattern this plugin advocates for adopters).
+
+Commit messages are linted against [Conventional Commits](https://www.conventionalcommits.org/) via commitlint — locally through a husky `commit-msg` hook, and in CI on every pull request.
+
+## Acknowledgements
+
+- The core changelog logic was originally written for [eXist-db/semver.xq#69](https://github.com/eXist-db/semver.xq/pull/69) and adopted in [eXist-db/monex](https://github.com/eXist-db/monex) and [eXist-db/function-documentation](https://github.com/eXist-db/function-documentation). This plugin is a refactor of that proven logic.
+- @line-o pointed out that the no-push pattern matches what `@existdb/xst`, `@existdb/node-exist`, and `@existdb/gulp-exist` already do. That feedback shaped this plugin's design.
+
+This plugin corresponds to §5.3 of a broader release-strategy proposal being circulated among the eXist-db devs for automating EXPath package releases.
+
+## License
+
+LGPL-2.1-or-later (matching the eXist-db org convention).

package/index.js

@@ -0,0 +1,100 @@
+/**
+ * @existdb/repo-xml-changelog-generator
+ *
+ * semantic-release plugin that injects a new `<change>` entry into an EXPath
+ * package descriptor (typically `repo.xml.tmpl`) based on the Conventional
+ * Commits between the previous release tag and the current release.
+ *
+ * Lifecycle hooks:
+ *
+ *   verifyConditions(pluginConfig, context)
+ *     Confirms the configured descriptor file exists and contains a
+ *     `<changelog xmlns="http://exist-db.org/xquery/repo">` element. Fails
+ *     fast (before the release is computed) with an actionable error if not.
+ *
+ *   prepare(pluginConfig, context)
+ *     Reads conventional commits since `context.lastRelease.gitTag`, builds
+ *     a list of human-readable change items, and inserts a new `<change
+ *     version="X.Y.Z">` element with those items at the top of `<changelog>`.
+ *     Writes the descriptor back to disk. The mutation is in-memory on the
+ *     CI runner — pair with @semantic-release/github (REST-based release
+ *     creation) and DO NOT use @semantic-release/git, so the on-disk file
+ *     in master stays at its dev-placeholder state. See README for details.
+ *
+ * Config options (all optional):
+ *
+ *   tmplPath: string  (default: 'repo.xml.tmpl')
+ *     Path to the EXPath repo descriptor template, relative to cwd.
+ */
+
+import { existsSync } from 'fs'
+import { join } from 'path'
+import { buildChangeItems, insertChangeEntry } from './lib/changelog.js'
+
+const REPO_NS = 'http://exist-db.org/xquery/repo'
+
+function resolveTmplPath (pluginConfig, context) {
+  return join(context.cwd ?? process.cwd(), pluginConfig.tmplPath ?? 'repo.xml.tmpl')
+}
+
+async function readChangelogContainer (tmplPath) {
+  const { readFileSync } = await import('fs')
+  const { DOMParser } = await import('@xmldom/xmldom')
+  const tmpl = readFileSync(tmplPath, 'utf8')
+  const doc = new DOMParser().parseFromString(tmpl, 'text/xml')
+  return doc.getElementsByTagNameNS(REPO_NS, 'changelog').item(0)
+}
+
+export async function verifyConditions (pluginConfig, context) {
+  const { logger } = context
+  const tmplPath = resolveTmplPath(pluginConfig, context)
+
+  if (!existsSync(tmplPath)) {
+    throw new Error(
+      `[repo-xml-changelog-generator] Template not found: ${tmplPath}\n` +
+      `Set the \`tmplPath\` plugin option if your descriptor lives elsewhere.`
+    )
+  }
+
+  const changelog = await readChangelogContainer(tmplPath)
+  if (!changelog) {
+    throw new Error(
+      `[repo-xml-changelog-generator] No <changelog xmlns="${REPO_NS}"> element found in ${tmplPath}.\n` +
+      `Add an empty <changelog/> child inside <meta> to enable change-entry injection.`
+    )
+  }
+
+  logger.log(`[repo-xml-changelog-generator] verified ${tmplPath}`)
+}
+
+export async function prepare (pluginConfig, context) {
+  const { logger, lastRelease, nextRelease } = context
+  const tmplPath = resolveTmplPath(pluginConfig, context)
+
+  if (!lastRelease?.gitTag) {
+    logger.log(
+      '[repo-xml-changelog-generator] No previous release tag — skipping changelog injection. ' +
+      '(First-release entries should be curated manually in repo.xml.tmpl.)'
+    )
+    return
+  }
+
+  const items = await buildChangeItems({
+    prevTag: lastRelease.gitTag,
+    version: nextRelease.version,
+    cwd: context.cwd
+  })
+
+  if (items.length === 0) {
+    logger.log(`[repo-xml-changelog-generator] No notable commits since ${lastRelease.gitTag} — skipping.`)
+    return
+  }
+
+  insertChangeEntry({
+    tmplPath,
+    version: nextRelease.version,
+    items
+  })
+
+  logger.log(`[repo-xml-changelog-generator] inserted ${items.length} change item(s) for ${nextRelease.version} into ${tmplPath}`)
+}

package/lib/changelog.js

@@ -0,0 +1,141 @@
+/**
+ * Core changelog logic, factored out of the plugin entry so it can be
+ * exercised by unit tests with mock git input.
+ *
+ * Lifted from eXist-db/semver.xq's update-repo-changelog.js and adapted
+ * to the semantic-release plugin shape (read tags from arguments, not
+ * CLI flags; resolve paths against an explicit cwd).
+ */
+
+import { execSync } from 'child_process'
+import { readFileSync, writeFileSync } from 'fs'
+import { DOMParser, XMLSerializer } from '@xmldom/xmldom'
+import { CommitParser } from 'conventional-commits-parser'
+import { writeChangelogString } from 'conventional-changelog-writer'
+import conventionalChangelogConventionalCommits from 'conventional-changelog-conventionalcommits'
+
+const REPO_NS = 'http://exist-db.org/xquery/repo'
+const HTML_NS = 'http://www.w3.org/1999/xhtml'
+
+const SECTION_PREFIX = {
+  Features: 'New',
+  'Bug Fixes': 'Fix',
+  'Performance Improvements': 'Improvement',
+  Reverts: 'Revert'
+}
+
+const XML_MAIN_TEMPLATE =
+  '{{#each noteGroups}}' +
+  '{{#each notes}}' +
+  '<li>Breaking change: {{text}}</li>\n' +
+  '{{/each}}' +
+  '{{/each}}' +
+  '{{#each commitGroups}}' +
+  '{{#each commits}}' +
+  '{{#unless isBreaking}}<li>{{prefix}}: {{#if scope}}{{scope}}: {{/if}}{{subject}}</li>\n{{/unless}}' +
+  '{{/each}}' +
+  '{{/each}}'
+
+function tagExists (tag, cwd) {
+  try {
+    execSync(`git rev-parse "${tag}"`, { stdio: 'pipe', cwd })
+    return true
+  } catch {
+    return false
+  }
+}
+
+function getRawCommits ({ prevTag, cwd }) {
+  const ref = tagExists(prevTag, cwd) ? prevTag
+    : tagExists(`v${prevTag}`, cwd) ? `v${prevTag}`
+      : null
+  if (!ref) throw new Error(`[repo-xml-changelog-generator] Tag not found: ${prevTag} or v${prevTag}`)
+
+  const hashes = execSync(`git log ${ref}..HEAD --format=%H`, { encoding: 'utf8', cwd })
+    .trim().split('\n').filter(Boolean)
+
+  return hashes.map(hash =>
+    execSync(`git log -1 --format=%B ${hash}`, { encoding: 'utf8', cwd }).trim()
+  )
+}
+
+export async function buildChangeItems ({ prevTag, version, cwd }) {
+  const rawCommits = getRawCommits({ prevTag, cwd })
+  if (rawCommits.length === 0) return []
+
+  const { parser: parserOpts, writer: writerOpts } = await conventionalChangelogConventionalCommits()
+  const commitParser = new CommitParser(parserOpts)
+
+  const parsed = rawCommits.map(msg => commitParser.parse(msg)).filter(c => c.type)
+  if (parsed.length === 0) return []
+
+  const presetTransform = writerOpts.transform
+  const writerOptions = {
+    ...writerOpts,
+    mainTemplate: XML_MAIN_TEMPLATE,
+    headerPartial: '',
+    commitPartial: '',
+    footerPartial: '',
+    transform (commit, context) {
+      const transformed = presetTransform(commit, context)
+      if (!transformed) return null
+      if (transformed.notes.length > 0) {
+        transformed.isBreaking = true
+        return transformed
+      }
+      transformed.prefix = SECTION_PREFIX[transformed.type] ?? transformed.type
+      return transformed
+    }
+  }
+
+  const output = await writeChangelogString(parsed, { version }, writerOptions)
+
+  const doc = new DOMParser().parseFromString(
+    `<ul xmlns="${HTML_NS}">${output}</ul>`,
+    'text/xml'
+  )
+  const liNodes = doc.getElementsByTagNameNS(HTML_NS, 'li')
+  const items = []
+  for (let i = 0; i < liNodes.length; i++) {
+    const text = liNodes.item(i).textContent
+    if (text) items.push(text)
+  }
+  return items
+}
+
+export function insertChangeEntry ({ tmplPath, version, items }) {
+  const tmpl = readFileSync(tmplPath, 'utf8')
+  const doc = new DOMParser().parseFromString(tmpl, 'text/xml')
+
+  const changelog = doc.getElementsByTagNameNS(REPO_NS, 'changelog').item(0)
+  if (!changelog) throw new Error(`[repo-xml-changelog-generator] <changelog> not found in ${tmplPath}`)
+
+  const change = doc.createElementNS(REPO_NS, 'change')
+  change.setAttribute('version', version)
+  change.appendChild(doc.createTextNode('\n            '))
+
+  const ul = doc.createElementNS(HTML_NS, 'ul')
+  for (const item of items) {
+    ul.appendChild(doc.createTextNode('\n                '))
+    const li = doc.createElementNS(HTML_NS, 'li')
+    li.textContent = item
+    ul.appendChild(li)
+  }
+  ul.appendChild(doc.createTextNode('\n            '))
+
+  change.appendChild(ul)
+  change.appendChild(doc.createTextNode('\n        '))
+
+  let firstChange = null
+  for (let i = 0; i < changelog.childNodes.length; i++) {
+    if (changelog.childNodes.item(i).nodeType === 1) {
+      firstChange = changelog.childNodes.item(i)
+      break
+    }
+  }
+
+  changelog.insertBefore(change, firstChange)
+  changelog.insertBefore(doc.createTextNode('\n        '), firstChange)
+
+  writeFileSync(tmplPath, new XMLSerializer().serializeToString(doc))
+}

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@existdb/repo-xml-changelog-generator",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "semantic-release plugin: inject conventional-commit changelog entries into EXPath package repo.xml descriptors (eXist-db / BaseX / MarkLogic XAR packages)",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "lib/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test 'test/**/*.test.js'",
+    "prepare": "husky || true"
+  },
+  "keywords": [
+    "semantic-release",
+    "semantic-release-plugin",
+    "expath",
+    "exist-db",
+    "xar",
+    "changelog"
+  ],
+  "author": "Joe Wicentowski",
+  "license": "LGPL-2.1-or-later",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/eXist-db/repo-xml-changelog-generator.git"
+  },
+  "bugs": {
+    "url": "https://github.com/eXist-db/repo-xml-changelog-generator/issues"
+  },
+  "homepage": "https://github.com/eXist-db/repo-xml-changelog-generator#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "peerDependencies": {
+    "semantic-release": ">=22"
+  },
+  "dependencies": {
+    "@xmldom/xmldom": "^0.9.12",
+    "conventional-changelog-conventionalcommits": "^9.0.0",
+    "conventional-changelog-writer": "^8.0.0",
+    "conventional-commits-parser": "^6.0.0"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^19.0.0",
+    "@commitlint/config-conventional": "^19.0.0",
+    "husky": "^9.0.0",
+    "semantic-release": "^25.0.9"
+  }
+}