@existdb/repo-xml-changelog-generator 1.0.1 → 1.0.2

package/README.md

@@ -42,7 +42,12 @@ Add to your `.releaserc` plugin chain. Place it after the commit-analyzer / rele
 }
 ```
 
-**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.
+The plugin works with or without `@semantic-release/git` — the choice decides where your changelog history lives:
+
+- **Without it** (in-memory mode), the mutation happens only 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. Note that each built XAR then contains only the entries curated in the template plus the *current* release's generated entry — the entries generated for previous releases are not carried forward.
+- **With it** (commit-back mode), add `@semantic-release/git` *after* this plugin with `repo.xml.tmpl` (and typically `package.json` + `package-lock.json`) as assets. Each release then commits the new `<change>` entry back to the default branch, so the changelog accumulates and every released XAR carries the full history. This is the model `eXist-db/monex` adopted by community vote ([monex#453](https://github.com/eXist-db/monex/pull/453)); it requires branch protection to allow the GitHub Actions app to push.
+
+See [Design rationale](#design-rationale) below.
 
 ## Configuration
 
@@ -76,6 +81,8 @@ For each conventional commit since `context.lastRelease.gitTag`:
   - `Revert` (for `revert:`)
   - or the literal type for other categories.
 - Render breaking changes as `Breaking change: <text>` from `BREAKING CHANGE:` footers.
+- Render issue/PR references (e.g. `#398`) as XHTML `<a>` links, with URLs derived from semantic-release's `repositoryUrl`; on non-GitHub remotes they are kept as plain text.
+- Hard-wrapped commit subjects are folded into a single line, and hard-wrapped `BREAKING CHANGE:` footers are collapsed to single-line items.
 
 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).
 
@@ -95,9 +102,11 @@ The rendered items are wrapped in a `<change version="X.Y.Z"><ul xmlns="http://w
 
 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.
+The alternative — used by `@existdb/xst`, `@existdb/node-exist`, `@existdb/gulp-exist`, 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.
+
+The trade-off: for npm packages the version history lives in the npm registry anyway, but for XAR packages the `<changelog>` in the shipped descriptor is itself the history — and in-memory mode drops each generated entry after its release. `eXist-db/monex` used in-memory mode from 2026-05-19 until a community vote switched it to commit-back ([monex#453](https://github.com/eXist-db/monex/pull/453)) after its 5.1.0 XAR shipped without the generated 5.0.0 entry. Branch protection there allows the GitHub Actions app to push, so no PAT or custom App is needed.
 
-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.)
+This plugin supports both workflows; pick per repository.
 
 ### Why not just publish the existing script as-is?
 
@@ -114,7 +123,7 @@ semantic-release itself is a Node tool and runs in Node. The plugin API is Node-
 
 ## 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).
+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 in-memory workflow described above — a natural fit here, since an npm package's version history lives in the registry).
 
 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.
 

package/index.js

@@ -16,10 +16,11 @@
  *     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.
+ *     Writes the descriptor back to disk. Whether that mutation stays
+ *     in-memory on the CI runner or is committed back to the default branch
+ *     (so the changelog accumulates across releases) depends on whether
+ *     @semantic-release/git is in the plugin chain — both workflows are
+ *     supported. See README for the trade-offs.
  *
  * Config options (all optional):
  *
@@ -82,7 +83,8 @@ export async function prepare (pluginConfig, context) {
   const items = await buildChangeItems({
     prevTag: lastRelease.gitTag,
     version: nextRelease.version,
-    cwd: context.cwd
+    cwd: context.cwd,
+    repositoryUrl: context.options?.repositoryUrl
   })
 
   if (items.length === 0) {

package/lib/changelog.js

@@ -16,6 +16,7 @@ import conventionalChangelogConventionalCommits from 'conventional-changelog-con
 
 const REPO_NS = 'http://exist-db.org/xquery/repo'
 const HTML_NS = 'http://www.w3.org/1999/xhtml'
+const MD_LINK = /\[([^\]]+)\]\(([^)\s]+)\)/g
 
 const SECTION_PREFIX = {
   Features: 'New',
@@ -24,17 +25,40 @@ const SECTION_PREFIX = {
   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 escapeXml (text) {
+  return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+}
+
+// Replaces the writer's default markdown template (conventional-changelog-writer
+// v9+ takes a template function, no longer a handlebars string).
+function xmlTemplate (context) {
+  const lines = []
+  for (const group of context.noteGroups ?? []) {
+    for (const note of group.notes) {
+      lines.push(`<li>Breaking change: ${escapeXml(note.text)}</li>`)
+    }
+  }
+  for (const group of context.commitGroups ?? []) {
+    for (const commit of group.commits) {
+      if (commit.isBreaking) continue
+      const scope = commit.scope ? `${commit.scope}: ` : ''
+      lines.push(`<li>${escapeXml(`${commit.prefix}: ${scope}${commit.subject}`)}</li>`)
+    }
+  }
+  return lines.join('\n')
+}
+
+/**
+ * Derive the {host, owner, repository} link context from a repository URL
+ * (semantic-release's `context.options.repositoryUrl`). Returns null when
+ * the URL is not a recognizable GitHub remote; issue references are then
+ * left as plain text instead of rendered with broken URLs.
+ */
+export function githubContext (repositoryUrl) {
+  const m = (repositoryUrl ?? '').match(/github\.com[/:]([^/]+)\/([^/]+?)(?:\.git)?$/)
+  if (!m) return null
+  return { host: 'https://github.com', owner: m[1], repository: m[2] }
+}
 
 function tagExists (tag, cwd) {
   try {
@@ -54,12 +78,14 @@ function getRawCommits ({ prevTag, cwd }) {
   const hashes = execSync(`git log ${ref}..HEAD --format=%H`, { encoding: 'utf8', cwd })
     .trim().split('\n').filter(Boolean)
 
+  // %s folds a hard-wrapped subject paragraph into a single line; %B would
+  // keep the line break and the parser would truncate the subject there.
   return hashes.map(hash =>
-    execSync(`git log -1 --format=%B ${hash}`, { encoding: 'utf8', cwd }).trim()
+    execSync(`git log -1 --format=%s%n%n%b ${hash}`, { encoding: 'utf8', cwd }).trim()
   )
 }
 
-export async function buildChangeItems ({ prevTag, version, cwd }) {
+export async function buildChangeItems ({ prevTag, version, cwd, repositoryUrl }) {
   const rawCommits = getRawCommits({ prevTag, cwd })
   if (rawCommits.length === 0) return []
 
@@ -72,10 +98,7 @@ export async function buildChangeItems ({ prevTag, version, cwd }) {
   const presetTransform = writerOpts.transform
   const writerOptions = {
     ...writerOpts,
-    mainTemplate: XML_MAIN_TEMPLATE,
-    headerPartial: '',
-    commitPartial: '',
-    footerPartial: '',
+    template: xmlTemplate,
     transform (commit, context) {
       const transformed = presetTransform(commit, context)
       if (!transformed) return null
@@ -88,7 +111,8 @@ export async function buildChangeItems ({ prevTag, version, cwd }) {
     }
   }
 
-  const output = await writeChangelogString(parsed, { version }, writerOptions)
+  const linkContext = githubContext(repositoryUrl)
+  const output = await writeChangelogString(parsed, { version, ...linkContext }, writerOptions)
 
   const doc = new DOMParser().parseFromString(
     `<ul xmlns="${HTML_NS}">${output}</ul>`,
@@ -97,12 +121,37 @@ export async function buildChangeItems ({ prevTag, version, cwd }) {
   const liNodes = doc.getElementsByTagNameNS(HTML_NS, 'li')
   const items = []
   for (let i = 0; i < liNodes.length; i++) {
-    const text = liNodes.item(i).textContent
+    // Collapse line breaks left over from hard-wrapped BREAKING CHANGE footers.
+    let text = liNodes.item(i).textContent.replace(/\s+/g, ' ').trim()
+    if (!linkContext) {
+      // Without a link context the preset renders references as markdown
+      // links with `undefined` URLs — reduce them to their label text.
+      text = text.replace(MD_LINK, '$1')
+    }
     if (text) items.push(text)
   }
   return items
 }
 
+// Item text may contain markdown links produced by the conventional-changelog
+// preset (issue refs, mentions); render them as XHTML anchors.
+function appendItemContent (doc, li, text) {
+  let last = 0
+  for (const match of text.matchAll(MD_LINK)) {
+    if (match.index > last) {
+      li.appendChild(doc.createTextNode(text.slice(last, match.index)))
+    }
+    const a = doc.createElementNS(HTML_NS, 'a')
+    a.setAttribute('href', match[2])
+    a.appendChild(doc.createTextNode(match[1]))
+    li.appendChild(a)
+    last = match.index + match[0].length
+  }
+  if (last < text.length) {
+    li.appendChild(doc.createTextNode(text.slice(last)))
+  }
+}
+
 export function insertChangeEntry ({ tmplPath, version, items }) {
   const tmpl = readFileSync(tmplPath, 'utf8')
   const doc = new DOMParser().parseFromString(tmpl, 'text/xml')
@@ -118,7 +167,7 @@ export function insertChangeEntry ({ tmplPath, version, items }) {
   for (const item of items) {
     ul.appendChild(doc.createTextNode('\n                '))
     const li = doc.createElementNS(HTML_NS, 'li')
-    li.textContent = item
+    appendItemContent(doc, li, item)
     ul.appendChild(li)
   }
   ul.appendChild(doc.createTextNode('\n            '))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@existdb/repo-xml-changelog-generator",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "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",
@@ -46,8 +46,8 @@
   },
   "dependencies": {
     "@xmldom/xmldom": "^0.9.12",
-    "conventional-changelog-conventionalcommits": "^9.0.0",
-    "conventional-changelog-writer": "^8.0.0",
+    "conventional-changelog-conventionalcommits": "^9.3.1",
+    "conventional-changelog-writer": "^9.0.0",
     "conventional-commits-parser": "^6.0.0"
   },
   "devDependencies": {