Migrate build system from Maven to Node.js/Gulp/semantic-release

[joewiz]

Summary

• Replaces Apache Maven build with Node.js + Gulp for building XAR packages, modeled on the approach used in the roaster project
• Adds semantic-release for fully automated versioning and GitHub releases triggered by conventional commits
• Drops eXist-db 4.x support (breaking change); minimum version is now 5.0.0
• Preserves all existing XQSuite tests, now run via XML-RPC against a Docker eXist-db service in CI (or local instance for development)

Key changes

• New build toolchain: package.json, gulpfile.js, expath-pkg.xml.tmpl, repo.xml.tmpl
• Automated releases: .releaserc configures semantic-release to bump versions, commit package.json, and publish XAR as a GitHub release asset
• Automated changelog: scripts/update-repo-changelog.js — called by semantic-release's prepare step; reads conventional commits since the last tag (via conventional-commits-parser) and inserts a new <change> entry into repo.xml.tmpl
• Test runner: test/run-tests.js — Node.js script that invokes XQSuite via @existdb/node-exist (XML-RPC) and parses results with @xmldom/xmldom
• CI: .github/workflows/build.yml replaces old ci.yml + ci-docker-dev.yml; runs against eXist-db latest, release, and 5.0.0 Docker images using Node.js LTS
• Conventional commits: commitlint + husky enforce the Conventional Commits spec locally via a commit-msg hook
• Ant wrapper: build.xml for backward compatibility (ant xar → npm run build)
• File layout: src/main/xquery/semver.xqm → content/semver.xqm; src/test/xquery/*.xqm → test/*.xqm; icon.png moved to root
• Removed: pom.xml, xar-assembly.xml, xquery-license-style.xml, src/
• Updated: .gitignore (Maven → Node.js entries), dependabot.yml (maven → npm), README.md (build/test/release instructions)

The feat! commit uses the conventional commit format with a BREAKING CHANGE: footer, so semantic-release will bump from 3.0.1 → 4.0.0 when merged to master.

Test plan

• npm install succeeds
• npm run build produces dist/semver-xq-3.0.1.xar
• CI workflow triggers on push and runs against all three eXist-db versions
• With a local eXist-db: cp .env.example .env && npm test passes all XQSuite tests
• On merge to master: semantic-release creates a 4.0.0 GitHub release with XAR attached

🤖 Generated with Claude Code

[joewiz]

Development notes for reviewers

This PR was developed iteratively with CI feedback. Here's a summary of the key decisions and problems solved, to help reviewers understand the shape of the implementation.

roaster as the model

Throughout development we used the roaster project as the reference implementation. The gulpfile structure, template handling, connection options, and CI approach are all closely modeled on roaster. Where we diverged (e.g., the test runner), we noted the reasons.

Why HTTPS on port 8443 (not HTTP on 8080)

@existdb/gulp-exist v5 defaults to secure: true, which means HTTPS. Attempts to override this to HTTP caused SSL connection errors in CI because node-exist's compatibility shim converts the secure boolean to a protocol string, overriding any http: protocol set via environment variable. Rather than fighting this, we aligned with roaster's approach: roaster's CI also uses port 8443 (HTTPS) with no EXISTDB_SERVER override, relying on the default. This is why build.yml maps port 8443 and run-tests.js defaults to https://localhost:8443 with rejectUnauthorized: false for the self-signed cert that eXist-db's Docker image ships with.

expath-pkg.xml

The <file> path in the <xquery> component declaration is just semver.xqm (not content/semver.xqm) because eXist-db's EXPath resolver automatically prepends the package's content/ directory — using content/semver.xqm causes a content/content/semver.xqm not found error in eXist-db 5.0.0 (though 6.x is more forgiving). This was confirmed by consulting roaster's expath-pkg.xml.tmpl.

XQSuite test runner

The test runner uses inspect:module-functions(xs:anyURI("xmldb:exist:///db/apps/semver-xq/tests/...")) to collect test functions and passes them to test:suite(). Two things to note:

• The xmldb:exist:/// URI scheme is required — bare /db/... paths return an empty sequence from inspect:module-functions(), causing test:suite() to fail with a cardinality error. This pattern is taken from xbow's test runner.
• The XQuery is submitted via eXist-db's REST API using the XML query document format (Content-Type: application/xml, <query xmlns="http://exist.sourceforge.net/NS/exist"> wrapper) rather than form-encoded POST, which proved more reliable.

Commit structure

The branch has two commits to keep the diff readable:

1. chore: restructure repository layout — pure file moves and deletions, no functional changes
2. feat!: replace Maven build with Node.js/Gulp/semantic-release — all new tooling, with BREAKING CHANGE: footer to trigger a 4.0.0 release via semantic-release on merge

🤖 Generated with Claude Code

[duncdrum]

For uploads to GitHub having xar files without version numbers *e.g.(semver-xq.xar) actually helps with automated consumption. For uploads to public-repo you need xar files with version numbers. Just an observation to make sure this is what your want.

[line-o]

I am strongly in favour of keeping the version numbers.

[joewiz]

Thanks for the note. Given line-o's strong preference for versioned filenames (see below), we're keeping the current naming — which, as you point out, is the right choice for GitHub release assets. [-Claude]

[joewiz]

Agreed — versioned filenames it is. Thank you for the clear steer. [-Claude]

[duncdrum]

should the maven switch appear here? I would a release to be triggered after merging

[joewiz]

Good point. We've added scripts/update-repo-changelog.js (commit 5c6bfa5), which semantic-release calls during its prepare step. It reads conventional commits since the last tag, groups them by type, and inserts a new <change> element into repo.xml.tmpl using @xmldom/xmldom for proper XML DOM manipulation — no string editing of XML. The template is then committed alongside package.json in the release commit, so a 4.0.0 changelog entry will be generated automatically when this PR merges. [-Claude]

[joewiz]

@line-o It was originally going to use string manipulation, but I asked Claude to find a less brittle method. I mentioned XSLT, and it said this would add a dependency of xsltproc, and instead recommended a node-native approach of xmldom, which I decided to go with. Looks clean enough to me. I'm open to other ideas, of course.

[line-o]

The changelog creation is the one thing that is still lacking in the current gulp-exist setup.

[line-o]

this PR would fix #13

[line-o]

The test output has the string "unknown" where I would expect the test suite name. Maybe this can be improved.

Running XQSuite tests...
  [PASS] unknown: 0 tests, 0 failures, 0 errors
  [PASS] unknown: 8 tests, 0 failures, 0 errors
  [PASS] unknown: 22 tests, 0 failures, 0 errors
  [PASS] unknown: 14 tests, 0 failures, 0 errors
  [PASS] unknown: 1 tests, 0 failures, 0 errors
  [PASS] unknown: 3 tests, 0 failures, 0 errors
  [PASS] unknown: 7 tests, 0 failures, 0 errors

[line-o]

A really good start! There are some loose ends and a few thing we should discuss.

[line-o]

Unless we set up this repository to explicitly use conventional commits the ! will not be recognised as an indicator for breaking changes.
semantic-release uses Angular Commit Message format by default.

[joewiz]

Good point. To confirm: @semantic-release/commit-analyzer uses the Angular preset by default, which does recognise \! per the Conventional Commits specification. That said, you're right that it should be made explicit. We've added @commitlint/config-conventional + a Husky commit-msg hook in commit 2d122e7 to enforce the convention locally, and updated the README to reference the spec. [-Claude]

[line-o]

I fear that my previous statement was misunderstood.

Unless we set up this repository to explicitly use conventional commits the ! will not be recognised as an indicator for breaking changes.

The commit-analyser used by semantic-release must be configured to use conventional commits.

Addtionally, a commit linting action could be added to the GitHub actions. An example for such a setup can be found in https://github.com/eXist-db/xst/blob/main/.github/workflows/commitlint.yml

[joewiz]

Thanks for the clarification, @line-o — addressed in commit cdcb9be. Both @semantic-release/commit-analyzer and @semantic-release/release-notes-generator are now configured with "preset": "conventionalcommits", with conventional-changelog-conventionalcommits added as a dependency. The commitlint.yml workflow is also in place, modeled on https://github.com/eXist-db/xst. [-Claude]

[line-o]

Sweet! We need this in a easy-to-use form so that all our libs and apps can benefit from this.

[joewiz]

Agreed! ;)

[line-o]

this PR will close #24

[line-o]

For some reason no actions are run anymore. -- my hunch was wrong --

[joewiz]

Agreed, and addressed in commit 5c6bfa5. We've added scripts/update-repo-changelog.js, which semantic-release calls as part of its prepare step: it reads conventional commits since the last tag, groups them by type, and inserts a new <change> element into repo.xml.tmpl using @xmldom/xmldom for proper XML DOM manipulation. The updated template is then committed alongside package.json on each release. [-Claude]

[joewiz]

Yes — the new build.yml runs the test suite against existdb/existdb:latest, existdb/existdb:release, and existdb/existdb:5.0.0 on every push, which directly addresses the multi-version CI coverage described in #13. [-Claude]

[joewiz]

The test output has the string "unknown" where I would expect the test suite name. Maybe this can be improved.

Running XQSuite tests...
  [PASS] unknown: 0 tests, 0 failures, 0 errors
  [PASS] unknown: 8 tests, 0 failures, 0 errors
  [PASS] unknown: 22 tests, 0 failures, 0 errors
  [PASS] unknown: 14 tests, 0 failures, 0 errors
  [PASS] unknown: 1 tests, 0 failures, 0 errors
  [PASS] unknown: 3 tests, 0 failures, 0 errors
  [PASS] unknown: 7 tests, 0 failures, 0 errors

@line-o With Claude's latest commits, now this appears as follows:

Running XQSuite tests...
  [PASS] http://exist-db.org/xquery/semver/test/coerce: 8 tests, 0 failures, 0 errors
  [PASS] http://exist-db.org/xquery/semver/test/compare: 24 tests, 0 failures, 0 errors
  [PASS] http://exist-db.org/xquery/semver/test/expath-package-semver-template: 14 tests, 0 failures, 0 errors
  [PASS] http://exist-db.org/xquery/semver/test/serialize: 1 tests, 0 failures, 0 errors
  [PASS] http://exist-db.org/xquery/semver/test/sort: 3 tests, 0 failures, 0 errors
  [PASS] http://exist-db.org/xquery/semver/test/parse: 7 tests, 0 failures, 0 errors

Is that what you had in mind?

And to you and @duncdrum I think Claude and I have addressed all questions now—hopefully in not too annoying a fashion.

Here's the log of my session (search for ❯ to see my prompts): https://gist.github.com/joewiz/6243291159fadeaeb1ce739deb686d60

[line-o]

The changelog generation code would benefit from being even more tightly integrated with the underlying library conventional-changelog
From my research it seems possible to overwrite / customize the templates used to generate the standard changelog.md.
In a perfect world we would create and maintain our own changelog generator - making programmatic use of the writer - that reads and extends a repo.xml.tmpl and commits the amended version to the repository and adds the repo.xml to the build artifact.

[joewiz]

The changelog generation code would benefit from being even more tightly integrated with the underlying library conventional-changelog … making programmatic use of the writer — that reads and extends a repo.xml.tmpl and commits the amended version to the repository and adds the repo.xml to the build artifact.

Done in commit 94b1204. update-repo-changelog.js now loads both parserOpts and writerOpts from the conventional-changelog-conventionalcommits preset (the same one semantic-release uses internally), so commit classification is fully consistent with the rest of the toolchain.

A custom Handlebars template replaces the default markdown output with plain <li> lines. The preset's transform is wrapped to inject a prefix field (New, Fix, Improvement, Revert) on each commit based on its section title, which the template renders as <li>{{prefix}}: {{subject}}</li>. Breaking-change notes surface via noteGroups as <li>Breaking change: …</li>; to avoid a duplicate commit line, the transform also sets a temporary isBreaking flag on the in-memory commit object, and the template uses {{#unless isBreaking}} to suppress it. The resulting <li> strings are then parsed by @xmldom/xmldom and inserted into repo.xml.tmpl exactly as before. [-Claude]

[joewiz]

@line-o p.s. Here's the session that produced the most recent commit and comment addressing your comment from earlier today: https://gist.github.com/joewiz/3af7c6c88c87e46a6ae0dec2fff734f2.