Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
45 commits
Select commit Hold shift + click to select a range
4a87de4
Define specification - requirements for a future production release
khowe Sep 28, 2026
cc8ed5a
More detail in spec
khowe Oct 15, 2026
cd4fe10
More refinement of Spec, and addition of JSON schema for configuratio…
khowe Oct 20, 2026
52dd09a
More refinement of SPEC (including output schema)
khowe Oct 21, 2026
1d2e08b
More refinement of spec and prep for implementation
khowe Oct 22, 2026
237e0be
Moved specification to docs
khowe Oct 22, 2026
716e55c
Deactiviated CI; will reinstate for v1
khowe Oct 22, 2026
c821994
Remove prototype in preparation for v1 implementation
khowe Oct 22, 2026
52e79f7
More prep for implementation
khowe Oct 22, 2026
bb3e563
Tightened AGENTS.md
khowe Oct 22, 2026
5ac14b2
More refinement of specification and schemas
khowe Oct 23, 2026
883e9f0
Renamed adviso-validation compare to adviso-compare
khowe Oct 30, 2026
d956ba5
Restructured to accommodate future additional command-line tools
khowe Oct 30, 2026
442f0a0
Phase one of implementation completed and reviewed: establish the bas…
khowe Nov 6, 2026
054bbd0
Added command-line invocation layer
khowe Nov 6, 2026
453db37
Added input parsing (supporting JSON, and CSV/TSV as input formats)
khowe Nov 6, 2026
cd468e7
Additions to input parsing logic and tests picked up in review
khowe Nov 6, 2026
62414c5
Implemented first attempt at comparison configuration parsing and rep…
khowe Nov 6, 2026
68dfd85
Refactoring/simplificaition after review
khowe Nov 6, 2026
ba2e4c2
Tightened up requirements relating to parsing of numerical values (in…
khowe Nov 9, 2026
6bea75a
Tightened up requirements relating to parsing and representation of n…
khowe Nov 9, 2026
fdb9039
Tightening of parsing
khowe Nov 9, 2026
2ac11eb
Added support for custom keys, side-specific source-field aliases
khowe Nov 9, 2026
abe95cc
Strengthened tests
khowe Nov 9, 2026
a569f2c
Implemented contract phase of comparison
khowe Nov 9, 2026
f3ff19f
Implemented records phase of comparison
khowe Nov 9, 2026
b61400c
Implemented compararors, and values phase of comparison
khowe Nov 9, 2026
2cc635d
Implemented assembly and validation of canonical results
khowe Nov 9, 2026
2405fd8
Implemented reporting
khowe Nov 9, 2026
cdb5b77
Refactor of results/reporting code
khowe Nov 10, 2026
d1fd7a3
Implemented integration of installed CLI and execution-error boundary
khowe Nov 10, 2026
bed94ca
Added examples, and user guide
khowe Nov 10, 2026
47dbecd
Evolution of user-guide
khowe Nov 11, 2026
b360d74
Changed output folder semantics;output now written to fresh folder on…
khowe Nov 11, 2026
efc23ca
In results bundle, separate out the provenance copy of the config fro…
khowe Nov 11, 2026
21b48ab
Consistently refer to tool name in code and docs as adviso-compare
khowe Nov 12, 2026
50cc617
More updates to user guide
khowe Nov 12, 2026
a82c337
Changed structure of HTML report based on feedback
khowe Nov 12, 2026
9ed690e
Renamed org.adviso.automatic-strict-exact to adviso-compare:automatic…
khowe Nov 12, 2026
e9b0e52
Fixed issue with exception escalation
khowe Nov 12, 2026
bda751f
Splitting out the documentation
khowe Nov 12, 2026
1c702b8
Added CI
khowe Nov 12, 2026
ea51f90
Updated some tests to accommodate subtle changes to JSON error report…
khowe Nov 12, 2026
3ca21d5
Fix for windows-specific tests
khowe Nov 12, 2026
69d650a
slimmed down the matrix for CI
khowe Nov 12, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
104 changes: 104 additions & 0 deletions .github/workflows/adviso-compare-ci.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,104 @@
name: adviso-compare CI

on:
pull_request:
branches: [main]
push:
branches: [main]
schedule:
- cron: '23 4 * * 2'
workflow_dispatch:

permissions:
contents: read

concurrency:
group: ${{ github.workflow }}-${{ github.event_name }}-${{ github.event.pull_request.number || github.ref }}
cancel-in-progress: ${{ github.event_name == 'pull_request' }}

jobs:
test:
name: adviso-compare / ${{ matrix.os }} / Python ${{ matrix.python }}
runs-on: ${{ matrix.os }}
timeout-minutes: 25
strategy:
fail-fast: false
matrix:
os: [ubuntu-24.04, macos-15, windows-2025]
python: ['3.11', '3.12', '3.13', '3.14', '3.15']
# Linux is the primary platform; other platforms cover the endpoints.
exclude:
- os: macos-15
python: '3.12'
- os: macos-15
python: '3.13'
- os: macos-15
python: '3.14'
- os: windows-2025
python: '3.12'
- os: windows-2025
python: '3.13'
- os: windows-2025
python: '3.14'
defaults:
run:
shell: bash
env:
PIP_DISABLE_PIP_VERSION_CHECK: '1'
steps:
- name: Check out source and version history
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
fetch-depth: 0
persist-credentials: false

- name: Select Python
uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
with:
python-version: ${{ matrix.python }}

- name: Install package and development dependencies
run: |
python -m pip install --upgrade pip
python -m pip install './packages/adviso-compare[dev]'
python -m pip check

- name: Record verification environment
run: |
mkdir -p ci-output
python --version > ci-output/python.txt
python -c "import platform; print(platform.platform()); print(platform.machine())" > ci-output/platform.txt
git rev-parse HEAD > ci-output/commit.txt
python -m pip list --format=freeze > ci-output/test-dependencies.txt

- name: Run suite, builds, and clean installation scenarios
run: >-
python -m pytest packages/adviso-compare/tests -q
--junitxml=ci-output/tests.xml
--basetemp=ci-output/tmp

- name: Retain test reports, distributions, and dependency records
if: always()
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: adviso-compare-${{ matrix.os }}-python-${{ matrix.python }}
retention-days: 30
if-no-files-found: warn
path: |
ci-output/*.txt
ci-output/tests.xml
ci-output/tmp/distributions/*

ci:
name: adviso-compare CI passed
needs: test
if: always()
runs-on: ubuntu-24.04
defaults:
run:
shell: bash
steps:
- name: Require every matrix job to succeed
env:
MATRIX_RESULT: ${{ needs.test.result }}
run: test "$MATRIX_RESULT" = success
36 changes: 0 additions & 36 deletions .github/workflows/ci.yml

This file was deleted.

11 changes: 5 additions & 6 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# artefacts
.DS_Store

# dynamic version
version.py
# dynamic versions
**/_version.py

## dev/env
.venv
Expand Down Expand Up @@ -79,7 +79,7 @@ instance/
.scrapy

# Sphinx documentation
docs/_build/
**/docs/_build/

# PyBuilder
.pybuilder/
Expand Down Expand Up @@ -146,6 +146,5 @@ dmypy.json

# Cython debug symbols
cython_debug/

# file generated by setuptools_scm
version.py
# Local CI reports and temporary build/install environments
/ci-output/
121 changes: 121 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,121 @@
# Agent guidance for the AdvISO validation toolkit

## Purpose of this file

This file governs how agents work in this monorepo. It does not define product behaviour. Product requirements belong in the applicable package specification and normative schemas; do not duplicate them here.

## Sources of truth

For `adviso-compare`, use this order of authority:

1. `packages/adviso-compare/docs/SPECIFICATION.md` — normative behaviour.
2. `packages/adviso-compare/src/adviso_compare/schemas/comparison-configuration-v1.0.schema.json` — normative comparison-configuration structure.
3. `packages/adviso-compare/src/adviso_compare/schemas/comparison-results-v1.0.schema.json` — normative canonical-results structure.
4. Version 1 tests and controlled fixtures — executable verification of the normative sources.
5. User documentation — explanatory material that must agree with the sources above.

If these sources appear inconsistent, stop and report the exact conflict and its consequences. Do not silently choose an interpretation, weaken a requirement, or invent behaviour.

## Repository layout

- Keep each independently installable tool under `packages/<distribution-name>/`.
- Give each tool its own `pyproject.toml`, README, `docs/`, `src/`, and `tests/`.
- For `adviso-compare`, put production code and runtime resources under
`packages/adviso-compare/src/adviso_compare/`, tests under
`packages/adviso-compare/tests/`, and maintained product documentation under
`packages/adviso-compare/docs/`.
- Keep repository-wide guidance at the repository root. Do not place
product-specific requirements there.
- Treat generated version files, build outputs, caches, coverage output, and virtual environments as generated artefacts rather than source.

Do not create a package for a proposed tool until its scope and implementation work have been approved. Do not create new top-level directories or reorganize established modules without a concrete need in an approved plan.

## Working method

Before changing behaviour:

1. Read the relevant specification sections in full, including referenced requirements elsewhere in the document.
2. Read the relevant schema definitions.
3. Identify the specified behaviours affected by the work.
4. Add or update the smallest coherent set of tests that verifies those behaviours.
5. Implement until those tests pass.
6. Run proportionate wider tests, static checks, schema checks, and packaging checks.
7. Update affected documentation and controlled fixtures.

Use test-driven development for the version 1 implementation. A failing test is useful only when it represents current specified behaviour. Do not create tests for discarded ideas, historical decisions that never entered version 1, or renamed and removed properties.

## Change control

- Do not change a package specification, its normative schemas, or established requirement semantics unless the task explicitly authorizes a specification change.
- Preserve schema version identifiers and canonical `$id` values unless a deliberate version change has been approved.
- When behaviour changes are authorized, update all affected normative text, schemas, tests, fixtures, and user documentation together.
- Do not add speculative features, extension points, compatibility layers, dependencies, or abstractions.
- Keep patches narrowly scoped. Do not mix behavioural work with unrelated restructuring or formatting.
- Preserve unrelated work already present in the worktree.

When a requirement is ambiguous, contradictory, or not implementable as written, ask for a decision rather than encoding an undocumented assumption.

## Code quality

- Follow PEP 8 and write idiomatic Python compatible with the project's supported Python versions.
- Follow PEP 257 for public-module, class, function, and method docstrings; document intent and constraints rather than restating the code.
- Where configured automated formatting, linting, or type-checking rules differ from general style guidance, the project configuration is authoritative.
- Avoid unrelated formatting changes that obscure the substantive content of a patch.
- Keep the command-line layer thin and keep domain logic independently testable.
- Separate I/O, domain logic, validation, and presentation responsibilities.
- Prefer small explicit interfaces and ordinary modules over framework-like abstraction.
- Use type annotations for production interfaces and non-trivial internal functions.
- Prefer explicit domain types and immutable value objects where they prevent invalid states.
- Keep functions focused and transformation stages testable in isolation.
- Avoid mutable global state and import-time side effects.
- Use domain-specific exceptions or result types at architectural boundaries.
- Do not use broad exception handling to conceal defects.
- Keep dependencies minimal and justified, with runtime and development dependencies separated.
- Write deterministic code; do not depend accidentally on unordered collections, filesystem order, locale, or hash iteration.

Do not introduce or replace a formatter, linter, type checker, build backend, test framework, dependency manager, or supported-Python policy as an incidental edit. Project-wide tooling choices require deliberate configuration and approval.

## Testing practice

- Give tests descriptive behavioural names that remain meaningful without the specification.
- Do not embed specification requirement identifiers or acceptance-scenario identifiers in code, tests, fixtures, snapshots, or package metadata. Development traceability belongs in the specification and review records, and must remain a one-way reference from those records to the software artefacts.
- Prefer parameterization when it expresses one rule table clearly; do not merge unrelated behaviours merely to reduce test count.
- Test public behaviour and stable internal contracts rather than private implementation details.
- Use controlled, synthetic, non-sensitive fixtures.
- Keep fixtures small enough for meaningful review unless scale is the subject of the test.
- Document generated fixtures and make their regeneration deterministic.
- Test both directions where the specification requires symmetry.
- Exercise boundary values, malformed inputs, and failure paths, not only successful examples.
- Validate representative configuration and result documents against their packaged schemas.
- Include installed-entry-point and built-distribution tests where required by the specification.
- Do not update expected outputs blindly; review semantic changes field by field.

Not every implementation, documentation, release-process, or quality requirement needs a direct automated test. Add automated coverage where it provides a reliable and maintainable verification of observable behaviour.

## Sensitive data and repository safety

- Never place real patient data, clinical identifiers, credentials, secrets, or identifying local paths in source, tests, fixtures, snapshots, logs, examples, or documentation.
- Do not use destructive repository or filesystem operations unless the user has explicitly authorized them and the exact target has been verified.
- Never overwrite unrelated user changes to make a check pass.

Refer to the specification for the software's normative security and data-governance behaviour.

## Documentation

- Keep the README and user documentation accurate for the implemented version.
- Do not document planned behaviour as already available.
- Ensure complete examples validate against the corresponding packaged schema.
- Link to normative material instead of copying substantial requirements into explanatory documentation.

## Before declaring work complete

Report:

- the specified behaviours affected;
- tests added or updated and why they are sufficient;
- commands run and their results;
- schema, static, packaging, and documentation checks performed;
- checks not run and the reason;
- remaining assumptions, limitations, or follow-up work.

Do not claim completion while relevant tests, schemas, documentation, or packaging metadata are knowingly inconsistent with the implementation.
54 changes: 54 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
# Contributing to the AdvISO validation toolkit

This repository contains independently installable tools. Start by selecting
the package you intend to change under `packages/` and reading its README.
Each tool owns its dependencies, development setup, tests, documentation, and
release process. Use that tool's documented commands and runtime requirements.

The first tool is [`adviso-compare`](packages/adviso-compare/README.md).
Its [development instructions](packages/adviso-compare/CONTRIBUTING.md)
cover editable installation, testing, and building distributions.

## Where guidance belongs

| Location | Purpose |
| --- | --- |
| Repository README | Tool catalogue and repository overview. |
| This guide | Contribution workflow shared across tools. |
| `AGENTS.md` files | Applicable agent instructions and code-quality guidance. |
| Package README | Tool status, entry points, and links to developer guidance. |
| Package contribution guide, where provided | Tool-specific setup, tests, builds, and change workflow. |
| Package `docs/` | User documentation, architecture guidance, and applicable product/development records. |
| Package `tests/` | Executable verification and controlled synthetic fixtures. |

Keep tool-specific implementation and dependencies within the relevant package.
A future tool can have a different dependency set or release schedule. Shared
code or tooling should follow a concrete need agreed for the affected packages.

## Working on a change

1. Read the applicable `AGENTS.md` instructions and the selected package's
documentation, including its behaviour specification and schemas where
provided.
2. Run the relevant existing tests to establish a baseline.
3. For an approved behavioural change or defect fix, adapt existing tests where
possible and add focused regression cases for uncovered behaviour. Confirm
that a new regression fails for the expected reason before implementing it.
4. Keep the implementation scoped to the selected package. Run focused checks
during development, then its wider tests and applicable packaging checks.
5. Update affected documentation and examples, and check their links and
commands. The user guide describes the tool; developer setup belongs in
developer-facing documentation.
6. Report what changed, how it was verified, and any checks or platforms that
remain unverified. When changing shared guidance or another package, include
the checks relevant to each affected tool.

Use synthetic, non-sensitive examples and fixtures. Detailed code-quality,
change-control, and testing guidance is in [AGENTS.md](AGENTS.md).

## Releases

Release decisions belong to each tool. Consult its current verification records
and declared support policy. A passing local suite is evidence for that
environment; report separately any outstanding platform, dependency-installation,
or independent-review checks.
Loading
Loading