Including all changes and additions to date

.gitattributes

@@ -0,0 +1,65 @@
+# Line-ending policy for the Halcyon repository.
+#
+# The repository's canonical form is LF: every blob already committed uses LF.
+# Without this file, git had no line-ending policy at all (no .gitattributes,
+# core.autocrlf unset), so a working tree checked out or edited by a Windows
+# tool acquired CRLF and every one of the ~5,300 tracked files reported as
+# modified. That made `git diff`, `git blame` and code review unusable.
+#
+# `text=auto eol=lf` normalizes to LF on commit and checks out LF on every
+# platform, so the working tree cannot drift back regardless of which git
+# binary (WSL or Windows) last touched it.
+
+* text=auto eol=lf
+
+# --- Explicit text types -----------------------------------------------------
+# Declared rather than left to git's heuristic, so a file that happens to
+# contain a NUL byte early on is still treated as source.
+*.java      text eol=lf
+*.js        text eol=lf
+*.mjs       text eol=lf
+*.ts        text eol=lf
+*.map       text eol=lf
+*.css       text eol=lf
+*.scss      text eol=lf
+*.less      text eol=lf
+*.html      text eol=lf
+*.ftl       text eol=lf
+*.xml       text eol=lf
+*.yml       text eol=lf
+*.yaml      text eol=lf
+*.json      text eol=lf
+*.jsonld    text eol=lf
+*.ttl       text eol=lf
+*.md        text eol=lf
+*.txt       text eol=lf
+*.ini       text eol=lf
+*.properties text eol=lf
+*.svg       text eol=lf
+
+# Executable scripts must be LF or the shebang breaks.
+*.sh        text eol=lf
+*.py        text eol=lf
+
+# --- Binary: never normalize, never diff as text -----------------------------
+*.png       binary
+*.jpg       binary
+*.jpeg      binary
+*.gif       binary
+*.ico       binary
+*.icns      binary
+*.webp      binary
+*.woff      binary
+*.woff2     binary
+*.ttf       binary
+*.eot       binary
+*.otf       binary
+*.wasm      binary
+*.jar       binary
+*.war       binary
+*.zip       binary
+*.gz        binary
+*.pdf       binary
+*.h5        binary
+*.svs       binary
+*.dcm       binary

.github/workflows/changelog-and-contributors.yml

@@ -6,12 +6,25 @@ on:
   #   branches:
   #     - master
 
+# L16: this job commits and pushes, so it needs contents: write — but it should get
+# exactly that and nothing else, rather than inheriting the repository default.
+permissions:
+  contents: write
+
 jobs:
   generate_changelog:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
-
+      # L16: pinned by SHA — a mutable tag lets the action's owner run new code with
+      # this job's push-capable token. (Was @v3; the SHA below is that same v3 line.)
+      - uses: actions/checkout@f43a0e5ff2bd294095638e18286ca9a3d1956744 # v3.6.0
+        with:
+          # The changelog is built from `git log` and `git describe --tags`, both of
+          # which see nothing useful in the default depth-1 checkout: no history and
+          # no tags, so "last_tag" was always empty and the "since last tag" branch
+          # below could never be taken.
+          fetch-depth: 0
+
       - name: Generate Changelog and Contributors
         run: |
           # Install necessary tools
@@ -32,13 +45,22 @@ jobs:
           # Generate a list of contributors
           output=$(git log --format='%aN' | sort -u)
           echo "$output" > contributors.txt
-          
+
       - name: Commit and Push Changes
+        # L16: github.ref goes through env rather than being interpolated into the
+        # script, same reasoning as the release-tag uploads in main.yml. Also: commit
+        # only when something actually changed — an unconditional `git commit` fails
+        # the job on a no-op run, which is why this workflow is dispatch-only.
         run: |
           git config --local user.name "github-actions[bot]"
           git config --local user.email "github-actions[bot]@users.noreply.github.com"
           git add changelog.md contributors.txt
-          git commit -m "chore: update changelog and contributors"
-          git push origin HEAD:${{ github.ref }}
+          if git diff --staged --quiet; then
+            echo "No changelog or contributor changes to commit."
+          else
+            git commit -m "chore: update changelog and contributors"
+            git push origin "HEAD:$TARGET_REF"
+          fi
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          TARGET_REF: ${{ github.ref }}

.github/workflows/ci.yml

@@ -0,0 +1,72 @@
+name: ci
+
+# F2: the whole point of this file. Before it, the ONLY workflows were
+# main.yml (`on: release`) and publish.yml (`on: workflow_dispatch`) — so nothing
+# was built or tested until a release was cut, and a broken tree could sit on
+# develop indefinitely. That is exactly how the JDK-21-vs-`--release 25` breakage
+# (H15) survived: no build ever ran to notice it.
+#
+# `next` is listed because it is where development actually lands: master was 127
+# commits behind it, so every branch this workflow watched was dormant. The gap was
+# not theoretical — BeakGraphQueryCapabilityTest kept calling the 13-argument
+# LwsResource constructor after the record gained a 14th component (sha256), and
+# that testCompile failure sat on next unnoticed because no workflow built it.
+# Any branch developers push to belongs in both lists below.
+on:
+  push:
+    branches: [ master, next, develop ]
+  pull_request:
+    branches: [ master, next, develop ]
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+# Least privilege: this workflow only reads the repo. It needs no token scope,
+# and deliberately holds no Maven credentials — it must never publish.
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: mvn verify (JDK 25)
+    runs-on: ubuntu-latest
+    # A hung surefire fork would otherwise burn the 6-hour default.
+    timeout-minutes: 45
+
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+
+      # M27/H15: must match <maven.compiler.release> in the root pom. javac cannot
+      # target a release newer than the JDK running it, and the root pom's
+      # requireJavaVersion enforcer fails fast if these drift apart.
+      - name: Set up JDK 25
+        uses: actions/setup-java@c1e323688fd81a25caa38c78aa6df2d33d3e20d9 # v4.8.0
+        with:
+          distribution: temurin
+          java-version: '25'
+          # M28: cache ~/.m2 so a green build does not re-pull every artifact.
+          # This is not only speed: the private repo (cursus) answers 403 under
+          # request pressure, so a cold full download is itself a failure mode.
+          cache: maven
+
+      # The first-party artifacts (BeakGraph, dcm2rdf, cygnus, vandegraph) live on
+      # the Halcyon repo, which serves them anonymously — no credentials needed to
+      # BUILD, only to publish. If this step starts failing on 403s for random
+      # artifacts, that is the rate limiter, not the poms (see M28).
+      #
+      # -C (--strict-checksums) fails on a checksum mismatch rather than warning and
+      # using the artifact anyway, which is Maven's default (M28).
+      - name: Build and test
+        run: mvn -B -C -ntp verify
+
+      - name: Upload surefire reports
+        if: failure()
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: surefire-reports
+          # Multi-module: reports live under each module's target/, never at the root.
+          path: '**/target/surefire-reports'
+          if-no-files-found: warn
+          retention-days: 7

.github/workflows/main.yml

@@ -3,23 +3,42 @@ on:
   release:
     types: [created]
 
+# L16: least privilege. With no permissions block at all the GITHUB_TOKEN takes the
+# repository default, which for repos created before Feb 2023 is write-all — so every
+# job, and everything it shells out to (including Maven plugins), held a token that
+# could push code rather than merely read it. The three jobs that attach release
+# assets raise themselves to contents: write below; nothing else can.
+permissions:
+  contents: read
+
 jobs:
   package-ubuntu:
     runs-on: ubuntu-latest
+    permissions:
+      contents: write        # gh release upload
     steps:
       - name: Checkout code from the repository
-        uses: actions/checkout@v4
+        # L16: actions are pinned by commit SHA, not by tag. A tag is mutable —
+        # whoever controls the action's repository can repoint v4 at new code, which
+        # would then run here with our GITHUB_TOKEN and our Maven deploy credentials
+        # already in scope. The trailing comment records the human-readable version
+        # the SHA was taken from; re-resolve it when bumping.
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
 
       # Set up JDK
+      # H15: this MUST match <maven.compiler.release> in the root pom (25). javac
+      # cannot target a release newer than itself, so on JDK 21 every module died with
+      # "error: release version 25 not supported" and the release pipeline never
+      # compiled a single class. If the pom's release level moves, move this with it.
       - name: Set up JDK
-        uses: actions/setup-java@v4
+        uses: actions/setup-java@c1e323688fd81a25caa38c78aa6df2d33d3e20d9 # v4.8.0
         with:
-          java-version: '21'
+          java-version: '25'
           distribution: 'temurin'
 
       # Set up the Maven settings (credentials)
       - name: Configure Maven settings
-        uses: s4u/maven-settings-action@v3.0.0
+        uses: s4u/maven-settings-action@7802f6aec16c9098b4798ad1f1d8ac75198194bd # v3.0.0
         with:
           servers: |
             [{
@@ -30,14 +49,18 @@ jobs:
 
       # Build and package the Maven project
       - name: Build Maven Project
-        run: mvn -B package --file pom.xml
+        # M28: -C (--strict-checksums) fails the build on a checksum mismatch instead of
+        # warning and using the artifact anyway (Maven's default). The <checksumPolicy>
+        # in the poms covers our own repos; -C additionally covers Maven Central, which
+        # no pom repository block can configure.
+        run: mvn -B -C package --file pom.xml
 
       # Deploy to Halcyon Public Maven repository
       - name: Deploy with Maven
-        run: mvn deploy
+        run: mvn -B -C deploy
 
       - name: Upload JAR
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
         with:
           name: halcyon-jar
           path: Halcyon/target/Halcyon*.jar
@@ -48,28 +71,35 @@ jobs:
           mvn jpackage:jpackage@ubuntu
 
       - name: '📦 Upload Package'
+        # L16: the tag reaches the script through env, never through ${{ }}. A
+        # ${{ ... }} expansion is textual substitution performed BEFORE the shell parses
+        # the line, so a release tag containing shell metacharacters became commands
+        # executing with GITHUB_TOKEN in scope. Referenced as "$TAG" it is only data.
         run: |
-          gh release upload ${{github.event.release.tag_name}} Halcyon/target/Halcyon*.jar
-          gh release upload ${{github.event.release.tag_name}} Halcyon/dist/halcyon*.deb
+          gh release upload "$TAG" Halcyon/target/Halcyon*.jar
+          gh release upload "$TAG" Halcyon/dist/halcyon*.deb
         env:
           GITHUB_TOKEN: ${{ github.TOKEN }}
+          TAG: ${{ github.event.release.tag_name }}
         shell: bash
 
   package-mac:
     needs: package-ubuntu
     runs-on: macos-latest
+    permissions:
+      contents: write        # gh release upload
     steps:
       - name: Checkout main branch from GitHub
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
 
       - name: Set up JDK for Mac
-        uses: actions/setup-java@v4
+        uses: actions/setup-java@c1e323688fd81a25caa38c78aa6df2d33d3e20d9 # v4.8.0
         with:
-          java-version: '21'
+          java-version: '25'
           distribution: 'temurin'
 
       - name: Download JAR
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
         with:
           name: halcyon-jar
           path: Halcyon/target
@@ -80,25 +110,29 @@ jobs:
           mvn jpackage:jpackage@mac
 
       - name: '📦 Upload macOS Package'
-        run: gh release upload ${{github.event.release.tag_name}} Halcyon/dist/Halcyon*.dmg
+        run: gh release upload "$TAG" Halcyon/dist/Halcyon*.dmg
         env:
           GITHUB_TOKEN: ${{ github.TOKEN }}
+          TAG: ${{ github.event.release.tag_name }}
+        shell: bash
 
   package-windows:
     needs: package-ubuntu
     runs-on: windows-latest
+    permissions:
+      contents: write        # gh release upload
     steps:
       - name: Checkout main branch from GitHub
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
 
       - name: Set up JDK for Windows
-        uses: actions/setup-java@v4
+        uses: actions/setup-java@c1e323688fd81a25caa38c78aa6df2d33d3e20d9 # v4.8.0
         with:
-          java-version: '21'
+          java-version: '25'
           distribution: 'temurin'
 
       - name: Download JAR
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
         with:
           name: halcyon-jar
           path: Halcyon\target
@@ -109,11 +143,13 @@ jobs:
           mvn jpackage:jpackage@win
 
       - name: '📦 Upload Windows Package'
+        # $env:TAG for the same reason as the bash jobs above.
         run: |
           $files = Get-ChildItem Halcyon\dist\Halcyon*.msi
           foreach ($file in $files) {
-            gh release upload ${{github.event.release.tag_name}} $file.FullName
+            gh release upload $env:TAG $file.FullName
           }
         shell: pwsh
         env:
           GITHUB_TOKEN: ${{ github.TOKEN }}
+          TAG: ${{ github.event.release.tag_name }}

.github/workflows/publish.yml

@@ -2,23 +2,29 @@ name: Publish project to Maven repository
 # Trigger workflow manually
 on: workflow_dispatch
 
+# L16: this job only reads the repo — it publishes to the Maven server using
+# MAVEN_NAME/MAVEN_SECRET, not the GITHUB_TOKEN — so the token gets read-only.
+permissions:
+  contents: read
+
 jobs:
   publish:
     runs-on: ubuntu-latest
     steps:
       # Checkout code from the repository
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
 
       # Set up JDK
+      # H15: must match <maven.compiler.release> in the root pom (25) — see main.yml.
       - name: Set up JDK
-        uses: actions/setup-java@v4
+        uses: actions/setup-java@c1e323688fd81a25caa38c78aa6df2d33d3e20d9 # v4.8.0
         with:
-          java-version: '21'
+          java-version: '25'
           distribution: 'temurin'
 
       # Set up the Maven settings (credentials)
       - name: Configure Maven settings
-        uses: s4u/maven-settings-action@v3.0.0
+        uses: s4u/maven-settings-action@7802f6aec16c9098b4798ad1f1d8ac75198194bd # v3.0.0
         with:
           servers: |
             [{
@@ -29,8 +35,9 @@ jobs:
 
       # Build and package the Maven project
       - name: Build Maven Project
-        run: mvn -B package --file pom.xml
+        # M28: -C = --strict-checksums (see main.yml).
+        run: mvn -B -C package --file pom.xml
 
       # Deploy to the repository
       - name: Deploy with Maven
-        run: mvn deploy
+        run: mvn -B -C deploy