Reproducibility: ROBOT install path under-specified; canonical `make ontology` likely never runs locally or in CI

[mzargham]

Summary

The canonical make ontology build target — which the Makefile header at Makefile:5 calls "the canonical build path. CI runs it on every push" — relies on obo-robot being on PATH, but the install instructions are under-specified, and the committed ontology/assembly_manifest.json shows the ROBOT path has never been exercised on the machine that produced the committed artifact. This makes the canonical path effectively un-reproducible for a new contributor and a silent regression risk.

I'm filing this from a sister project (DynamicalSystemsGroup/sms_rdf) that copied the ADCS Makefile pattern verbatim and hit the same wall. We fixed it with a small bundled install script; this issue proposes ADCS adopt the same fix.

Evidence

1. Manifest proves the canonical path has not run:

   ontology/assembly_manifest.json:102-103 on main (HEAD 58a1dba):

     \"notes\": \"Python assembly only (\`make ontology-python\`; run \`make ontology\` with Java + obo-robot installed for ROBOT/ELK verification).\",
     \"robot_used\": false,

   The committed artifact was produced by make ontology-python (the no-Java escape hatch), not make ontology. The canonical path's ROBOT/ELK merge+reason+report has not been executed on any machine that committed the manifest.

2. Install path is under-specified. Makefile:80 says Install obo-robot (http://robot.obolibrary.org) or override the command name. The linked OBO docs describe a multi-step manual install (download robot.jar from ontodev/robot releases + author a wrapper script + put both on PATH). There is no obo-robot or robot formula in homebrew-core (the only matches under brew search robot are robot-framework — the Python test tool — and robotfindskitten). A new contributor following the Makefile's pointer has to read OBO's docs, hand-author a wrapper, decide a path/layout, and chmod it themselves — and ADCS has no reference implementation to crib from.

3. CI doesn't catch this. I haven't audited .github/workflows/ here, but the manifest's robot_used: false on a main-committed artifact implies the canonical target either isn't in CI or CI is silently using ontology-python. Either way the contract "CI runs it on every push" in the Makefile header is not currently true.

Recommended fix (cribbing the sister repo's pattern)

The sister repo sms_rdf hit this same wall today and resolved it in commit e4274ba. The three pieces:

1. Ship a scripts/install_robot.sh — idempotent one-command install that:

   • downloads robot.jar (default: latest release; overridable via ROBOT_VERSION=v1.9.10) from https://github.com/ontodev/robot/releases into \$(brew --prefix)/opt/robot/libexec/robot.jar,
   • writes a wrapper at \$(brew --prefix)/bin/obo-robot that hard-codes \$(brew --prefix)/opt/openjdk/bin/java (with fallbacks to `$JAVA_HOME` and command -v java),
   • works on Apple Silicon, Intel Mac, and Linuxbrew transparently.

   Reference implementation: sms_rdf:scripts/install_robot.sh (~60 lines, Apache-2.0).

2. Update the _robot-preflight error message to point at the script:

   echo \"  Install via: ./scripts/install_robot.sh\"
   echo \"  (or override the command name: ROBOT=/path/to/robot make ontology)\"

3. Auto-detect JAVA_HOME cross-platform. Makefile:27 hard-codes JAVA_HOME ?= /usr/local/opt/openjdk — the Intel-Mac brew prefix. On Apple Silicon brew lives at /opt/homebrew/opt/openjdk; on Linuxbrew at /home/linuxbrew/.linuxbrew/opt/openjdk. The fix:

   JAVA_HOME ?= \$(shell brew --prefix openjdk 2>/dev/null || echo /usr/local/opt/openjdk)

   Falls back to the current hard-coded value when brew isn't on PATH, so SDKMAN/asdf/system-JDK users can still override via JAVA_HOME=/path/to/jdk make ontology. Surface both knobs (ROBOT, JAVA_HOME) in make help with their currently-effective values so contributors can verify auto-detection worked.

4. Make CI run the canonical target. Add an actions/setup-java step and invoke make ontology (not make ontology-python) in the workflow. The commit that lands Promote ROBOT/ELK validation to default ontology build path #2 should add a CI job that proves ROBOT/ELK actually runs.

Why this matters

ADCS is the reference implementation for the engineering-RTM + ROBOT pattern that several downstream repos (including sms_rdf) are cribbing. If ADCS's canonical build path has never been exercised end-to-end, downstream copies inherit an untested toolchain assumption. The robot_used: false in the manifest is honest evidence that the verification step is currently aspirational, not real.

Scope

This is install/CI plumbing — no code changes to the actual ontology, pipeline, or Stage 0/2/3 artifacts. Estimated effort: ~1 hour (port install_robot.sh, update _robot-preflight message, change JAVA_HOME default, add Java to CI, verify make ontology is green).

Filed by

Michael Zargham / sms_rdf project. Happy to open a PR cribbing the sms_rdf:e4274ba fix if you'd like — confirm and I'll do the port.