diff --git a/.github/workflows/adviso-compare-ci.yml b/.github/workflows/adviso-compare-ci.yml new file mode 100644 index 0000000..d69b774 --- /dev/null +++ b/.github/workflows/adviso-compare-ci.yml @@ -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 diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml deleted file mode 100644 index 44746e4..0000000 --- a/.github/workflows/ci.yml +++ /dev/null @@ -1,36 +0,0 @@ -name: Run PyTest on Push - -on: - push: - branches: [ "*" ] - -jobs: - build: - runs-on: ubuntu-latest - - steps: - - name: Checkout code - uses: actions/checkout@v4 - - - name: Set up Python 3.12 - uses: actions/setup-python@v5 - with: - python-version: '3.12' - - - name: Install dependencies - run: | - python -m pip install --upgrade pip - pip install pytest flake8 importlib-resources pyyaml - - - name: Run linting - shell: bash -l {0} - run: | - # stop the build if there are Python syntax errors or undefined names - # exit-zero treats all errors as warnings. - flake8 . --count --select=E9,F63,F7 --show-source --statistics --exit-zero - # Check function comlexity and line length. The GitHub editor is 127 chars wide - # exit-zero treats all errors as warnings. - flake8 . --count --max-complexity=10 --max-line-length=127 --statistics --exit-zero - - - name: Run pytest - run: pytest -v \ No newline at end of file diff --git a/.gitignore b/.gitignore index 9c14cd4..861df06 100644 --- a/.gitignore +++ b/.gitignore @@ -1,8 +1,8 @@ # artefacts .DS_Store -# dynamic version -version.py +# dynamic versions +**/_version.py ## dev/env .venv @@ -79,7 +79,7 @@ instance/ .scrapy # Sphinx documentation -docs/_build/ +**/docs/_build/ # PyBuilder .pybuilder/ @@ -146,6 +146,5 @@ dmypy.json # Cython debug symbols cython_debug/ - -# file generated by setuptools_scm -version.py \ No newline at end of file +# Local CI reports and temporary build/install environments +/ci-output/ diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..a207efd --- /dev/null +++ b/AGENTS.md @@ -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//`. +- 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. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..215e645 --- /dev/null +++ b/CONTRIBUTING.md @@ -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. diff --git a/README.md b/README.md index 4ecdfe4..3b8a6bd 100644 --- a/README.md +++ b/README.md @@ -1,140 +1,22 @@ -# Validation Toolkit +# AdvISO validation toolkit -A Python package to compare tabular datasets and record discrepancies. +This repository is a monorepo for independently installable AdvISO tools that +support bioinformatics validation and verification work. Repository membership +groups related software; it does not imply a shared executable, Python package, +dependency set, version, or release lifecycle. -# Install +## Tools -From source +| Tool | Purpose | Status | +| --- | --- | --- | +| [`adviso-compare`](packages/adviso-compare/README.md) | Translate and compare structured reference and query datasets | Implemented; unreleased | -```bash -git clone path/to/repo -cd path/to/repo -pip install . -``` +Each tool lives under `packages/` with its own packaging metadata, source, +tests, documentation, normative artefacts, and release version. `adviso-compare` +is the first tool. Additional tools will be added as peer packages as their +scope and implementation are agreed. -With pip - -```bash -pip install validation_toolkit@git+path/to/repo -``` - -# Usage -Using this package, you can compare a known "reference" table to a new "query" table. When verifying that a change in your data pipeline did not change the output table, the older iteration of the table is the reference and the new one generated after your change is the query; when comparing the outputs of your pipeline to those of another existing one, the outputs of the existing pipeline can be considered the reference. Depending on your use case, you may want to compare two tables that have identical schemas; or compare two such tables but only on a subset of columns; or else compare two tables that have entirely different schemas -- the CLI for each case is shown below. - -To compare two tables that have the same column names and data vocabularies: - -```bash -validation_toolkit compare \ - -r path/to/reference/data_table \ - -q path/to/query/data_table \ - -rs sample_id_colname \ - -o path/to/output/file \ - -f output_file_format -``` - -To compare **a subset of columns** from two tables that have the same column names and data vocabularies: -```bash -validation_toolkit compare \ - -r path/to/reference/data_table \ - -q path/to/query/data_table \ - -m compare_subset \ - -l col_name_1,col_name_2,col_name3 \ - -rs sample_id_colname \ - -o path/to/output/file \ - -f output_file_format -``` - -To compare two tables that have **different** column names and/or data vocabularies: -```bash -validation_toolkit compare \ - -r path/to/reference/data_table \ - -q path/to/query/data_table \ - -l col_name_1,col_name_2,col_name3 \ - -rs sample_id_colname_in_ref \ - -qs sample_id_colname_in_query \ - -c path/to/custom_config.yaml \ - -o path/to/output/file \ - -f output_file_format -``` - -# Using Custom Configs - -If comparing tabular data that may have been produced by different data pipelines, a custom configuration file in YAML format can be provided using the `-c` flag as shown above. When such a config file is used, the internal representation of the **reference** table is mapped to the provided mappings in the config, and the data in the query table is represented as-is. - -The custom config file has the following structure: - -```yaml -col_1_ref: - col_name: col_1_query - value_map: null -col_2_ref: - col_name: col_2_query - value_map: - true: 1 - false: 0 - unknown: null -col_3_ref: - col_name: col_3_query - value_map: - resistant: 1 - sensitive: 0 - unknown: 2 -``` - -The example config above says: the column `col_1_ref` in the reference table maps to the column called `col_1_query` in the query dataset. In terms of data vocabularies, however, this first column is the same across both datasets. - -This is not true for the column `col_2_ref` in the reference table: this column has a different name in the query table (`col_2_query`) but also, a `boolean true` in the reference table is represented as a `int 1` in the query, and so on. - -# Output Files -This progam can produce outputs in either JSON or CSV formats. If using JSON, the output file will contain the following data: - -```json -{ - "metadata": { - "prog": "validation_toolkit", - "prog_version": "0.0.1dev", - "datetime": "2025-03-25 15:52:19", - "cli": "path/to/validation_toolkit compare -r tests/test_data/data_map_test_left.csv -q tests/test_data/data_map_test_right.csv -rs col_left_1 -qs col_right_1 -c tests/test_data/sample_config.yaml -m compare_subset -l col_right_2,col_right_3 -o test_out.json -f json", - "ref": "path/to/ref_table.csv", - "query": "path/to/query_table.csv" - }, - "schema_check": { - "sample1": { - "sample_id": "sample1", - "col_right_1": "SchemaMatch", - "col_right_2": "SchemaMatch", - "col_right_3": "SchemaMatch" - }, - ... - }, - "value_check": { - "sample1": { - "sample_id": "sample1", - "col_right_1": "Field not checked", - "col_right_2": "ValueMatch", - "col_right_3": "ValueMatch" - }, - ... - } -} -``` -The three pieces of data in this JSON are the `metadata`, which stores information on the features of the comparison run you just executed; the `schema_check`, which stores information on whether the structure of the two tables (after applying config-based mapping if this is applicable) matches or not; and the `value_check`, which stores information on whether the corresponiding values across the tables match or not. - -Alternatively, the user can output this information in CSV format, whereby two files are written (assuming the output file provided by the user is `output_basename.csv`): -- `{output_basename}_schema_check.csv` contains `schema_check` data -- `{output_basename}_value_check.csv` contains `value_check` data - -Metadata lines are formatted as comments starting with two hashes; these are written to the top of both of the above CSV files. - -# List of Options -- `-h`, `--help`: show this help message and exit -- `-r`, `--ref_table`: Reference tabular dataset. -- `-q`, `--query_table`: Subject tabular dataset to compare. -- `-rs`, `--ref_sampleid_key`: The column/field name that contains sample IDs in the reference table. -- `-qs`, `--query_sampleid_key`: The column/field name that contains sample IDs in the query table. -- `-e`, `--strict`: Whether to raise warnings as exceptions or not. **NB** Using this option will cause the program to quit upon encountering differences in the datasets and consequenctly, no output files will be generated. Ordinarily, this flag should never be used. -- `-m`, `--mode`: How to execute comparison. [quick_compare, compare_subset] -- `-l`, `--field_list`: Comma-separated list of column names/fields to compare, required and used ONLY if using mode 'compare_subset'. -- `-c`, `--custom_config`: Custom config file containing col_name and value mappings in .yaml format. -- `-o`, `--output_filename`: Path to output file to be written. -- `-f`, `--write_format`: File format to write comparison output to ['json', 'csv']. +For development, start with the [contribution guide](CONTRIBUTING.md), then +follow the selected tool's developer guidance, linked from its README. +Repository-wide agent and code-quality guidance is in [`AGENTS.md`](AGENTS.md). +Product behaviour is defined within each tool's own specification and schemas. diff --git a/packages/adviso-compare/CONTRIBUTING.md b/packages/adviso-compare/CONTRIBUTING.md new file mode 100644 index 0000000..a60044d --- /dev/null +++ b/packages/adviso-compare/CONTRIBUTING.md @@ -0,0 +1,195 @@ +# Contributing to `adviso-compare` + +Read the repository [contribution guide](../../CONTRIBUTING.md) and applicable +[agent guidance](../../AGENTS.md). The +[architecture guide](docs/ARCHITECTURE.md) explains the implementation and +points to the code and tests for each responsibility. The commands below run +from the repository root and apply to this package. Other tools have their own +development setup. + +## Environment and editable installation + +Use a supported CPython version: 3.11, 3.12, 3.13, 3.14, or 3.15, with its +latest available patch release. Python 3.11 is the installation minimum; +future Python minor versions need verification before joining the support +matrix. Activate an existing development environment, or create one with: + +```console +python -m venv .venv +. .venv/bin/activate +``` + +On Windows Command Prompt, activate it with `.venv\Scripts\activate`; in +PowerShell, use `.venv\Scripts\Activate.ps1`. + +Install the package and its development dependencies into that environment: + +```console +python -m pip install -e "packages/adviso-compare[dev]" +``` + +The editable installation makes source changes available to the installed +`adviso-compare` command. Versions come from Git through `setuptools-scm`; +`src/adviso_compare/_version.py` is generated and is not maintained by hand. + +## Tests and checks + +Run the complete package suite with: + +```console +python -m pytest packages/adviso-compare/tests -q +``` + +For a focused run, select a relevant test module, for example: + +```console +python -m pytest packages/adviso-compare/tests/test_inputs.py -q +``` + +The suite includes configuration and results schema validation, CLI behaviour, +documentation examples, and distribution builds and installation. The +[test conventions](tests/README.md) describe shared fixtures and schema helpers. + +Additional local checks are: + +```console +python -m pip check +python -m compileall -q packages/adviso-compare/src packages/adviso-compare/tests +git diff --check +``` + +No formatter, linter, or type checker is currently configured. The +[CI workflow](../../.github/workflows/adviso-compare-ci.yml) runs the existing +test, schema, example, build, and installed-product checks. + +## Build distributions + +With the development dependencies installed, build a wheel and source archive: + +```console +python -m build --no-isolation --outdir packages/adviso-compare/dist packages/adviso-compare +``` + +The output directory is generated content. The distribution test builds both +archives once, then installs each into a separate fresh virtual environment. +It resolves declared dependencies without borrowing development site-packages; +source-archive installation also uses isolated build dependencies. These tests +may need network access to a package index. + +Both installations run outside the checkout, check dependency consistency and +installed resources, and exercise the same automatic, custom, repeated-run, and +error scenarios. Evidence is also validated using each installed package. The +archives and resolved dependency records remain in the pytest base temporary +directory for the run. + +## Documentation and examples + +The [user guide](docs/USER_GUIDE.md) and `docs/examples/` are installed with the +distribution. Check their runnable examples and installed copies with: + +```console +python -m pytest packages/adviso-compare/tests/test_documentation.py packages/adviso-compare/tests/test_distribution.py -q +``` + +An editable installation does not keep installed documentation copies in sync +with edits to their source files. Use the maintained source guide during +development; the distribution test checks the guide installed from a fresh +wheel against that source. + +The [specification](docs/SPECIFICATION.md) and packaged schemas define the +current behavioural contract. The original `IMPLEMENTATION_PLAN.md` describes +the initial delivery sequence, and `VERIFICATION_REPORT.md` contains dated +verification records. Consult their dates and scope when assessing evidence +for the current source revision. + +Release verification still requires successful runs across the supported +Python/OS matrix, CI enforcement, and applicable release review. A configured +workflow or passing local suite alone does not establish those checks. + +## Continuous integration + +The workflow runs on pull requests targeting `main` (including updates to those +pull requests), pushes to `main`, Tuesdays at 04:23 UTC, and manual requests. +Pushes to development branches without an open pull request do not trigger it. +It does not publish releases. + +Each run tests nine combinations. Linux is the primary platform and exercises +every supported Python minor version. Windows and macOS exercise the minimum +and newest supported versions on these standard GitHub-hosted runners: + +| Runner | Architecture | CPython versions | +| --- | --- | --- | +| `ubuntu-24.04` | x86-64 | 3.11, 3.12, 3.13, 3.14, 3.15 | +| `macos-15` | ARM64 | 3.11, 3.15 | +| `windows-2025` | x86-64 | 3.11, 3.15 | + +The same matrix applies to pull requests, `main`, scheduled runs, and manual +runs. Intermediate Python versions on Windows and macOS remain supported but +are not exercised by routine CI. Review this coverage when preparing a release +or updating the support policy. + +These identify the environments exercised by CI, rather than every supported +OS release or architecture. Runner images and Python patch releases can change; +each job records the platform, architecture, Python version, checked-out commit, +and resolved test dependencies. The distribution tests also record dependencies +for each clean installation. Every job installs the package normally, rather +than relying on an editable source installation, before running the full suite. +The scheduled run resolves dependencies afresh, just as pull-request runs do. + +The workflow retains JUnit test results, built wheel/source archives, and +version/dependency records for 30 days, including available reports on failure. +It does not upload the temporary comparison datasets or evidence packages. +Development CI artefacts are temporary verification records; release evidence +needs separate retention. Superseded pull-request runs are cancelled. Other +matrix jobs continue after a failure to show the full set of outcomes. + +To reproduce the test command locally, use a supported Python environment with +the development dependencies installed: + +```console +python -c "from pathlib import Path; Path('ci-output').mkdir(exist_ok=True)" +python -m pytest packages/adviso-compare/tests -q --junitxml=ci-output/tests.xml --basetemp=ci-output/tmp +``` + +`ci-output/` is ignored generated content. Pytest clears the selected base +temporary directory before a run; use this command only with that disposable +path. The normal test command above lets pytest manage its own temporary path. + +### GitHub merge settings + +After the workflow has run on GitHub, configure branch protection or a ruleset +for `main` to require a pull request and the **`adviso-compare CI passed`** status +check from GitHub Actions. This final job succeeds only when every matrix job +succeeds. Enable the requirement for the branch to be up to date before merging +so checks cover the current base branch. Another person's review approval is +not required by this project's chosen merge policy. + +These settings are configured in GitHub, separately from the workflow file; +committing the workflow does not enable them. Workflow changes themselves are +part of the proposed change and deserve scrutiny, since a pull request runs the +workflow from its temporary merged state. Keep action commit pins and runner +labels current through deliberate updates and rerun CI when changing them. + +## Making a change + +Start with the [specification](docs/SPECIFICATION.md) and the relevant packaged +[schema definitions](src/adviso_compare/schemas/). Resolve any disagreement +between those sources before changing behaviour. The architecture guide's +[change map](docs/ARCHITECTURE.md#where-to-make-a-change) helps locate the +implementation and existing tests. + +For a behaviour change, review the existing tests first: adapt or remove cases +whose expectations are no longer specified, and add cases for uncovered rules. +Run the affected tests to confirm the expected failure, implement the change, +then run the complete suite and relevant schema and distribution checks. +For documentation-only work, check links and examples; run the documentation +and distribution tests when changing published instructions or installed files. + +Keep the specification, schemas, controlled examples, and user guide aligned +with the implemented behaviour. Update the architecture guide when module +responsibilities or data flow change. These developer guides explain how to +maintain the software; they do not add product requirements. + +When submitting a change, describe its effect, tests and commands run, and any +remaining verification limits. Distinguish a passing local suite from checks +performed across the supported environments. diff --git a/packages/adviso-compare/README.md b/packages/adviso-compare/README.md new file mode 100644 index 0000000..e6e9ec7 --- /dev/null +++ b/packages/adviso-compare/README.md @@ -0,0 +1,55 @@ +# `adviso-compare` + +`adviso-compare` is a command-line tool for comparing a reference dataset with a query dataset. It uses explicit configuration rules to translate different source representations into a common canonical representation, then reports post-translation differences separately from issues that prevented assessment. + +The project is intended to support bioinformatics validation and verification activities associated with ISO 15189 accreditation. It produces comparison evidence; it does not determine whether a pipeline is valid, acceptable, or compliant. + +## Project status + +The tool is implemented and unreleased. Release verification is ongoing. +The supported runtime matrix is CPython 3.11–3.15 on Linux, macOS, and Windows; +Python 3.11 is the installation minimum. +It supports automatic strict-exact comparisons +and custom YAML comparison configurations across CSV, TSV, and JSON inputs. A +non-error run produces canonical JSON results, the complete effective +configuration as JSON, and a self-contained HTML report. + +For installation, commands, configuration rules, output fields, examples, and +troubleshooting, read the [user guide](docs/USER_GUIDE.md). + +The basic command is: + +```text +adviso-compare \ + --reference REFERENCE \ + --query QUERY \ + --output OUTPUT \ + [--configuration CONFIGURATION] +``` + +`--output` selects a parent directory. Each complete or incomplete run creates +its own child named `YYYYMMDDTHHMMSSZ-`, containing exactly +`comparison-results.json`, `comparison-configuration.json`, and +`comparison-report.html`. Results record the SHA-256 digest of the exact saved +configuration bytes. Repeated runs preserve existing evidence. The completion +summary identifies the published run directory. + +Both JSON formats use their own root `schema_version` and are independently +versioned. Version 1 supports results schema `1.0` with configuration schema +`1.0`. Keep the three files together; see the user guide's +[package-validation procedure](docs/USER_GUIDE.md#73-structural-and-semantic-validation). + +The current normative artefacts are: + +- [Behaviour specification](docs/SPECIFICATION.md) +- [Comparison-configuration schema](src/adviso_compare/schemas/comparison-configuration-v1.0.schema.json) +- [Canonical-results schema](src/adviso_compare/schemas/comparison-results-v1.0.schema.json) + +The distribution and executable are named `adviso-compare`; the Python import +package is `adviso_compare`. + +## Development + +See the [package contribution guide](CONTRIBUTING.md) for environment setup, +tests, builds, and the change workflow. The [architecture guide](docs/ARCHITECTURE.md) +explains the implementation, data flow, and validation boundaries. diff --git a/packages/adviso-compare/docs/ARCHITECTURE.md b/packages/adviso-compare/docs/ARCHITECTURE.md new file mode 100644 index 0000000..2830293 --- /dev/null +++ b/packages/adviso-compare/docs/ARCHITECTURE.md @@ -0,0 +1,245 @@ +# Architecture of `adviso-compare` + +This guide describes the current implementation for developers maintaining the +tool. It explains responsibilities and boundaries rather than defining product +behaviour. The [specification](SPECIFICATION.md) and packaged +[schemas](../src/adviso_compare/schemas/) remain the normative sources; the +[user guide](USER_GUIDE.md) explains the comparison concepts and terminology. +For setup, commands, and the development workflow, see +[Contributing](../CONTRIBUTING.md). + +## Contents + +- [Execution flow](#execution-flow) +- [Module responsibilities](#module-responsibilities) +- [Data representations](#data-representations) +- [Validation boundaries](#validation-boundaries) +- [Evidence assembly and publication](#evidence-assembly-and-publication) +- [Errors and determinism](#errors-and-determinism) +- [Packaging](#packaging) +- [Where to make a change](#where-to-make-a-change) + +## Execution flow + +The installed command enters `cli.main`. The CLI parses arguments, constructs a +`ComparisonInvocation`, calls the application, and translates its outcome or +exception into console output and an exit code. Comparison logic lives outside +the CLI. + +The following diagram shows execution order, rather than module imports: + +```mermaid +flowchart TD + CLI[CLI: parse invocation] --> Prepare[Prepare configuration, inputs, and record keys] + Prepare --> Contract[Contract: assess field values and scope] + Contract --> Records[Records: align canonical keys] + Records --> Values[Values: compare aligned non-key fields] + Values --> Evidence[Assemble and validate JSON evidence] + Evidence --> Publish[Render HTML and publish package] + Publish --> Outcome[CLI: summarize outcome] +``` + +[`application.py`](../src/adviso_compare/application.py) coordinates this flow +through `prepare_comparison` and `execute_comparison`: + +1. A supplied configuration is loaded and validated before either dataset is + opened. Without one, both datasets are parsed before automatic configuration + is generated. +2. Each dataset becomes a `RecordModel`. Key fields are translated and checked + here, before the three comparison phases. An unusable or duplicate canonical + key prevents safe alignment and raises an error. +3. Contract assessment translates in-scope fields on both sides, including + records that will have no counterpart. It records assessment issues and + exclusions, retaining translated values for subsequent comparison. +4. Record alignment matches canonical keys and records missing and extra + records. +5. Value comparison considers in-scope non-key fields in matched records. It + reuses contract assessments, classifying opportunities as matched, + mismatched, or not assessable. +6. Evidence assembly combines these outcomes, validates the JSON pair against + the original comparison context, and supplies immutable bytes to publication. + +An incomplete comparison is a reportable outcome. Invalid configuration, +unreadable input, or unsafe record keys instead stop execution with an error. +The user guide explains the distinction between completion and agreement. + +## Module responsibilities + +All paths below are within `src/adviso_compare/`. + +| Module | Responsibility | +| --- | --- | +| [`cli.py`](../src/adviso_compare/cli.py), [`invocation.py`](../src/adviso_compare/invocation.py) | Command parsing, invocation/outcome types, diagnostics, and exit codes. | +| [`application.py`](../src/adviso_compare/application.py) | Coordinates preparation, comparison phases, assembly, and publication. | +| [`inputs.py`](../src/adviso_compare/inputs.py) | Reads source bytes, captures provenance, parses CSV/TSV/JSON, and preserves native value categories and locations. | +| [`configuration.py`](../src/adviso_compare/configuration.py) | Loads restricted YAML, validates configuration, resolves defaults into domain objects, and validates saved configuration JSON. | +| [`processing.py`](../src/adviso_compare/processing.py) | Shared operation definitions and compatibility rules used by configuration validation and translation. | +| [`records.py`](../src/adviso_compare/records.py) | Generates automatic configuration and builds indexed records with validated canonical keys. | +| [`translation.py`](../src/adviso_compare/translation.py) | Applies source processing, null handling, mappings, type parsing, collection processing, and typed normalisation. | +| [`contract.py`](../src/adviso_compare/contract.py) | Assesses fields and scope, records causal issues and exclusions, and indexes assessments. | +| [`alignment.py`](../src/adviso_compare/alignment.py) | Aligns canonical record keys and identifies missing/extra records. | +| [`comparators.py`](../src/adviso_compare/comparators.py), [`values.py`](../src/adviso_compare/values.py) | Compare translated values and account for aligned value opportunities. | +| [`results.py`](../src/adviso_compare/results.py) | Constructs findings and summaries, orders and serializes JSON, validates evidence semantics, and owns `ComparisonEvidence`. | +| [`reporting.py`](../src/adviso_compare/reporting.py) | Renders HTML, publishes evidence safely, and inspects saved packages. | +| [`schemas/__init__.py`](../src/adviso_compare/schemas/__init__.py) | Loads explicitly supported schema resources from the installed package. | + +These are ordinary modules with explicit function calls. Translation is shared +by key preparation and contract assessment. Results assembly consumes domain +outcomes; reporting consumes the validated evidence pair. `results.py` refers +to `PreparedComparison` through a type-checking import, avoiding a runtime +import cycle with the application coordinator. + +Some responsibilities share a module: JSON assembly and semantic validation +are both in `results.py`; HTML, publication, and package inspection are all in +`reporting.py`. Their functions provide separate entry points for focused tests. + +## Data representations + +The implementation keeps source, canonical, and serialized representations +distinct so that comparison can use translated values while evidence retains +the relevant source facts. + +| Representation | Purpose | +| --- | --- | +| `ParsedDataset`, `ParsedRecord`, `NativeValue` | Preserve parsed source values, native categories, numeric lexical forms, source locations, and input provenance. | +| `EffectiveConfiguration`, `FieldDefinition` | Supply resolved rules to comparison code. `EffectiveConfiguration.document` returns a copy of the selected configuration document. | +| `RecordModel`, `KeyedRecord`, `CanonicalKeyComponent` | Associate source records with typed canonical keys and provide a read-only key index. | +| `TranslatedValue`, `CanonicalValue`, `TranslationIssue` | Represent a field's source-to-canonical outcome and any attributable failure. Untyped preserved values retain their native representation. | +| `ContractResult`, `RecordsResult`, `ValuesResult` | Carry phase outcomes independently of JSON field layout and HTML presentation. | +| `ComparisonEvidence` | Holds the exact validated results and configuration byte streams. Parsed document access returns fresh mutable views. | +| `ComparisonOutcome` | Gives the CLI completion status, published directory, and finding counts. | + +Most domain objects are frozen dataclasses, with tuples and read-only mappings +where appropriate. JSON dictionaries are used at document boundaries. + +The configuration has two complementary representations. Domain fields have +defaults resolved for execution, while the saved document preserves the +selected configuration, including omitted optional properties. Saving does not +expand all defaults into JSON. This distinction matters when changing default +resolution or serialization: the document and executable interpretation must +continue to agree. + +## Validation boundaries + +Validation is layered because JSON Schema cannot express every comparison or +cross-file invariant. + +| Boundary | Checks and available context | +| --- | --- | +| Configuration loading | Restricted YAML syntax, supported schema version, packaged configuration schema, and semantic rules such as field references and operation compatibility. | +| Input parsing and key preparation | Source format, encoding, native values, record shape, and usable unique canonical keys. | +| Contract assessment and value comparison | Per-field validity and comparability; attributable failures become assessment issues rather than generic parser errors. | +| `results.validate_result` | Results schema, exact configuration digest, saved configuration validity, supported schema combination, and cross-document semantics. Comparison context, when supplied, enables additional checks against inputs and phase outcomes. | +| `reporting.validate_evidence_package` | Fixed package membership, regular files, strict JSON parsing, and the validations available from the saved JSON pair. | + +The dataset JSON decoder preserves native categories and numeric lexical +information for comparison. The separate `results.parse_evidence_json` decoder +reads evidence documents as JSON objects and rejects duplicate members, +non-finite numbers, and invalid encoding. Use the decoder appropriate to the +boundary rather than substituting a permissive `json.loads` call. + +Both JSON documents declare their own `schema_version`. Schema resources are +selected locally by family and version; validation does not fetch schema IDs +from the network. The results schema does not embed the configuration schema. +`results.SUPPORTED_SCHEMA_COMBINATIONS` explicitly declares supported pairs, +and semantic validation checks their relationship. + +Saved-package validation cannot reproduce the comparison without source +inputs. It also does not authenticate HTML content: the report is checked as a +required regular member, while the JSON pair supplies the validated evidence. + +## Evidence assembly and publication + +`results.assemble_result` converts domain outcomes into ordered findings, +counts, provenance, and run metadata. It serializes the configuration once and +records the SHA-256 digest of those exact bytes in the results document. The +pair is validated with comparison context before `ComparisonEvidence` is +created. Reserializing configuration later would risk breaking that byte link. + +`reporting.render_html_report` renders the results and configuration documents +from that validated pair. It does not reread the original YAML or source +datasets. Presentation choices remain in the renderer; the JSON evidence +defines the facts displayed. + +`reporting.publish_evidence_package` renders HTML before preparing output, +writes all three members into a private staging directory inside the output +parent, and publishes the completed directory through an exclusive rename. +The final name comes from the run timestamp and identifier. Publication refuses +an existing destination and cleans up its own staging area on failure. + +The exclusive rename uses platform-specific filesystem operations. Unsupported +safe publication produces an output error rather than a replacement-based +fallback. POSIX directory and file modes restrict access to newly created +evidence. These details belong in publication code, not comparison phases. + +## Errors and determinism + +Boundary exceptions carry structured diagnostics: `ConfigurationError`, +`InputError`, `RecordKeyError`, and `OutputError`. `ResultValidationError` +reports invalid assembled or saved evidence. Translation failures attributable +to a field use `TranslationIssue` within a result object. + +Exception objects remain mutable so Python can attach traceback and chaining +information, including during context-manager cleanup. Frozen domain data and +mutable exceptions serve different purposes. + +The CLI maps expected input/configuration/output errors to exit code 2 and +unexpected errors to a generic diagnostic with exit code 3. A complete run +returns 0; an incomplete run returns 1. It does not expose an unexpected +traceback through normal command output. + +Explicit sorting controls record, field, finding, and document order. Numeric +and datetime processing preserve the precision needed for comparison rather +than relying on binary floating-point approximations. Input hashes refer to +original bytes, and recorded input provenance uses basenames rather than +absolute paths. Findings can still contain sensitive source values; output +protection remains relevant. + +Deterministic comparison does not mean identical bytes for repeated runs: +run identifiers and completion timestamps intentionally vary. Assembly accepts +controlled run metadata for repeatable tests. + +## Packaging + +[`pyproject.toml`](../pyproject.toml) defines a single installable distribution +with a `src/` layout and the `adviso-compare` console entry point. Runtime +dependencies are PyYAML and jsonschema with its configured format support; +development/build dependencies are declared separately. + +Schemas are package resources loaded through `importlib.resources`. The user +guide and runnable examples are installed under `share/doc/adviso-compare`. +Developer guides are maintained in the repository. Git-derived version +information is generated by `setuptools-scm`; `_version.py` is generated output. + +The [distribution test](../tests/test_distribution.py) builds both archives +and runs the same installed-command scenarios after fresh wheel and +source-archive installations. Each installation resolves its own dependencies +and runs outside the checkout. The +[CI workflow](../../../.github/workflows/adviso-compare-ci.yml) exercises the +routine Python/OS matrix; its scope and merge settings are explained in the +[contribution guide](../CONTRIBUTING.md#continuous-integration). + +## Where to make a change + +Start by checking the relevant normative text and existing tests. This table +locates responsibilities; it does not authorize a behavioural or schema change. + +| Change | Implementation and existing tests | +| --- | --- | +| Input decoding, native categories, or source locations | `inputs.py`; [input tests](../tests/test_inputs.py). | +| Configuration syntax, defaults, or compatibility rules | Configuration schema, `configuration.py`, `processing.py`; [configuration](../tests/test_configuration.py) and [schema tests](../tests/test_schemas.py). | +| Automatic configuration or canonical keys | `records.py`, shared translation; [record tests](../tests/test_records.py). | +| Translation operations or logical types | `processing.py`, `translation.py`, configuration validation; [translation](../tests/test_translation.py) and configuration tests. | +| Contract assessment or exclusions | `contract.py`; [contract tests](../tests/test_contract.py). | +| Record matching | `alignment.py`; [alignment tests](../tests/test_alignment.py). | +| Equality, tolerance, collections, or opportunity counts | `comparators.py`, `values.py`; [value tests](../tests/test_values.py). | +| Finding content, JSON layout, or evidence linkage | `results.py`, relevant schemas; [results](../tests/test_results.py) and schema tests. | +| HTML presentation, saved-package inspection, or publication | Separate functions in `reporting.py`; [reporting tests](../tests/test_reporting.py). | +| Command behaviour or boundary errors | `cli.py`, `invocation.py`, `application.py`; [CLI tests](../tests/test_cli.py). | +| Installed resources or packaging | `pyproject.toml`; distribution tests. | +| Published examples and user instructions | `docs/USER_GUIDE.md`, `docs/examples/`; [documentation tests](../tests/test_documentation.py) and distribution tests. | + +Cross-cutting changes often need tests at more than one boundary. For example, +a new configuration operation affects schema validation, resolved rules, +translation, and recorded evidence. Existing tests and the +[test conventions](../tests/README.md) provide the starting point. diff --git a/packages/adviso-compare/docs/IMPLEMENTATION_PLAN.md b/packages/adviso-compare/docs/IMPLEMENTATION_PLAN.md new file mode 100644 index 0000000..75eed9f --- /dev/null +++ b/packages/adviso-compare/docs/IMPLEMENTATION_PLAN.md @@ -0,0 +1,419 @@ +# `adviso-compare` version 1 implementation plan + +## 1. Purpose + +This document divides the version 1 implementation of `adviso-compare` into +reviewable, test-driven increments. Each increment ends in a coherent and +demonstrable result. Work on the next increment starts only after the completed +increment has been reviewed and approved. + +The behaviour specification and the two normative schemas remain the sources of +truth. This plan sequences their implementation; it does not add, remove, or +reinterpret product requirements. + +The plan covers only `adviso-compare`. Dataset acquisition, dataset subsetting, +pipeline execution, validation-dataset curation, and the proposed +`adviso-datasets` product remain outside its scope. The implementation also does +not add a laboratory acceptance verdict: its output is comparison evidence for +the validation process. + +## 2. Delivery method + +Each implementation step follows the same cycle: + +1. Re-read the relevant specification sections and schemas. +2. Identify the specified behaviours and validation scenarios in scope. +3. Add the smallest coherent set of tests and controlled fixtures for that + behaviour. Confirm that new behavioural tests fail for the expected reason. +4. Implement only enough production code to satisfy the step. +5. Run the new tests and all previously passing tests. +6. Run the proportionate schema, packaging, static, and documentation checks + that are already configured for the project. +7. Present the increment for review and approval. + +Tests will use descriptive behavioural names and remain understandable without +the development specification. Parameterization will be used for genuine rule +tables, without merging unrelated behaviours merely to reduce the test count. +Fixtures will be synthetic, small, non-sensitive, and deterministically +reproducible. + +No implementation difficulty will be resolved by silently changing the +specification or a schema. Any conflict, ambiguity, or impracticable requirement +will stop the affected step and be presented as a decision before implementation +continues. + +### Approval packet for every step + +The review at the end of each step will include: + +- the implemented capability and its architectural boundaries; +- the specified behaviours and validation scenarios addressed; +- tests and fixtures added or changed; +- commands run and their results; +- any schema, packaging, static, or documentation checks performed; +- a focused demonstration using representative inputs; +- known limitations and behaviour intentionally deferred to later steps; and +- any questions or proposed deviations requiring a decision. + +Approval means that the increment becomes the baseline for subsequent work. A +review may instead request corrections within the same step; those corrections +are completed and re-presented before the next step begins. + +## 3. Implementation sequence + +### Step 0 — Establish the verified baseline and test architecture + +**Goal:** create a trustworthy starting point without implementing comparison +behaviour. + +Work in this step: + +- verify that the existing specification and both JSON Schemas can be loaded; +- verify their canonical `$id` values and internal schema references; +- define the test layout, behavioural naming convention, shared fixture builders, + and deterministic fixture-generation approach; +- add schema-validation helpers that use Draft 2020-12 with format assertion; +- establish tests for loading packaged schemas through the package-resource API; +- build the source distribution and wheel and inspect their contents; and +- record any source/schema conflict as a blocker rather than choosing an + interpretation. + +This step does not create a comparison engine or claim that the executable is +usable. + +**Approval demonstration:** the schemas validate themselves and representative +schema fixtures, packaged schema resources can be loaded, and both distribution +formats build reproducibly enough for inspection. + +### Step 1 — Define package boundaries, domain vocabulary, and CLI invocation + +**Goal:** establish stable outer interfaces before domain behaviour is added. + +Work in this step: + +- create the intended package/module boundaries for input, configuration, + translation, comparison, results, reporting, and CLI orchestration; +- define narrowly scoped domain value types and exception categories at those + boundaries, without speculative framework abstractions; +- implement parsing of the direct `adviso-compare` command form into an + invocation value object; +- implement required arguments, `--configuration`, `--overwrite`, help, and + invalid-invocation handling that does not access inputs; and +- keep orchestration injectable so CLI tests need not depend on private kernel + details. + +The executable will not be presented as end-to-end complete in this increment. +The installed entry point and complete diagnostic behaviour are closed in Step +11. + +**Approval demonstration:** accepted arguments produce the expected invocation +object, invalid combinations fail before file access, subcommands are rejected, +and help accurately describes the version 1 interface. + +### Step 2 — Implement deterministic input discovery and parsing + +**Goal:** turn reference and query files into lossless parser-native datasets +with provenance, without yet interpreting configured field types. + +Work in this step: + +- determine CSV, TSV, and JSON formats independently from filename extensions; +- read exact input bytes, calculate SHA-256 digests, and retain basenames; +- enforce UTF-8 and the fixed tabular dialects; +- parse tabular headers and records while retaining record and physical-line + locations; +- parse JSON arrays of objects while rejecting duplicate member names, + non-object records, non-finite numbers, and invalid root structures; +- preserve parser-native categories, exact decimal values, numerical lexical + evidence, presence state, and JSON Pointer locations; +- distinguish valid empty datasets from invalid zero-byte inputs; and +- implement the applicable input-error taxonomy without logging sensitive + record content. + +**Approval demonstration:** a table-driven parser suite shows accepted edge +cases and precise rejection of malformed inputs across all three formats, with +exact categories and source locations visible through the domain API. + +### Step 3 — Load, validate, and resolve custom comparison configurations + +**Goal:** convert a custom YAML document into one validated, immutable effective +configuration before either dataset is read. + +Work in this step: + +- load YAML safely using the required scalar resolution and duplicate-key + handling; +- validate structure with the packaged configuration schema; +- implement every cross-property semantic validation rule that JSON Schema + cannot express; +- report precise configuration paths and stable configuration error categories; +- expand only the documented defaults and omitted empty structures; +- validate field definitions, source-field correspondence, in-scope fields, + record keys, logical types, collection representations, mappings, + normalisations, comparators, and review priorities; and +- serialize the resolved configuration into its schema-valid embedded form. + +**Approval demonstration:** representative valid configurations resolve to the +expected effective model, while a parameterized semantic-error suite produces +precise paths and reasons. A test proves that custom configuration failure +precedes dataset access. + +### Step 4 — Implement the source-to-canonical translation pipeline + +**Goal:** translate an individual declared field value from either dataset into +canonical typed evidence using the exact configured sequence of operations. + +Work in this step: + +- implement presence and null-policy handling; +- implement closed value mappings with typed source descriptors; +- implement source-text and typed-value normalisation registries; +- implement declared scalar parsing for string, integer, decimal, boolean, + date, and datetime values using exact arithmetic where required; +- implement list, set, and multiset source representations, element processing, + duplicate semantics, and deterministic canonical ordering; +- retain source and canonical evidence needed by later findings; and +- distinguish valid values, invalid attributable values, prohibited nulls, and + deliberately out-of-scope content without yet deciding whole-run status. + +**Approval demonstration:** table-driven unit tests trace representative scalar +and collection values through every configured operation, including failure +states, with no implicit coercion or inference. + +### Step 5 — Resolve record identity and automatic strict-exact mode + +**Goal:** obtain an unambiguous ordered record key for each dataset in custom and +configuration-free operation. + +Work in this step: + +- process configured single and composite record keys through the same explicit + translation rules that apply to their declared fields; +- detect missing, null, invalid, and duplicate keys as execution errors without + overwriting records; +- generate the automatic strict-exact effective configuration after parsing and + dataset-wide field discovery; +- apply the specified `record_id` preference and conservative single-field key + discovery algorithm, including its no-fallback rule; +- generate same-name non-key field definitions without type inference, + mapping, normalisation, or coercion, while leaving one-sided fields undefined + so that the contract phase can produce their exclusion summaries; and +- validate the generated configuration before comparison. + +**Approval demonstration:** custom aliases and composite keys work; duplicate or +invalid keys fail with attributable locations; and automatic-mode fixtures show +deterministic success, zero-candidate failure, ambiguous-candidate failure, and +the special handling of shared `record_id`. + +### Step 6 — Implement the contract phase + +**Goal:** assess whether the declared correspondence can be applied to every +record while allowing unaffected content to proceed. + +Work in this step: + +- discover dataset-wide structure from tabular headers and the union of JSON + members; +- apply required/optional field rules independently on each side; +- classify invalid, missing, null, prohibited, and type-incompatible configured + values; +- create side-specific contract findings and causal not-assessable states; +- consolidate defined-but-out-of-scope and undeclared-source-field exclusions; +- attach resolved review priority where applicable; and +- mark the contract phase complete when it was fully performed, even when it + contains findings. + +**Approval demonstration:** a mixed dataset produces all expected contract +findings, exclusions, and blocked opportunities while still exposing unaffected +records and values to later phases. + +### Step 7 — Implement the records phase + +**Goal:** align records by canonical identity and report the complete set of +reference-only and query-only records. + +Work in this step: + +- construct collision-safe indexes for ordered single and composite keys; +- match record identities independently of input order; +- emit every missing-record and extra-record difference; +- retain the reference and query source identities required for readable + evidence; and +- reconcile zero-record, one-sided-empty, and mixed missing/extra cases. + +**Approval demonstration:** reordered datasets match identically, composite keys +preserve multiple records for a sample, and simultaneous missing and extra +records are all reported deterministically. + +### Step 8 — Implement comparators and the values phase + +**Goal:** compare every assessable in-scope non-key value and distinguish true +post-translation differences from assessment issues. + +Work in this step: + +- implement the fixed comparator registry and legal type/comparator + combinations; +- implement preserved, typed, normalized-string, numeric, date, datetime, list, + set, and multiset equality semantics; +- implement absolute or reference-directed relative numeric tolerance with exact + decimal arithmetic and inclusive boundaries; +- classify every value opportunity as matched, mismatched, not assessable, or + deliberately not assessed as specified; +- collect all assessable differences rather than stopping at the first; and +- preserve the independence of finding classification, phase, and review + priority. + +**Approval demonstration:** a matrix covering representative semantics for +every comparator, together with focused numeric-tolerance boundary cases, +produces the expected canonical outcomes. One mixed custom comparison accounts +for every configured value opportunity, and an automatic-mode comparison +demonstrates that generated configuration flows through the values phase. + +### Step 9 — Assemble and validate canonical results + +**Goal:** construct the complete canonical result document deterministically and +prove that it satisfies both structural and semantic invariants. + +Work in this step: + +- finalize the finding registry, fixed classifications, structured fields, + deterministic messages, coalescence, total order, and report-local IDs; +- derive phase completion and overall `complete` or `incomplete` status; +- build fixed-shape, zero-inclusive summaries and exclusion summaries; +- render record identities, values, locations, software/runtime identity, + dialect metadata, UUID, and completion timestamp in their prescribed forms; +- embed the effective configuration and exact input provenance; +- serialize canonical JSON using the required member order, Unicode handling, + indentation, line endings, and final newline; +- validate the generated result against the packaged results schema with format + assertion; and +- implement additional semantic self-validation and treat self-validation + failure as an internal error. + +**Approval demonstration:** representative complete and incomplete documents +validate structurally and semantically, summaries reconcile with findings and +opportunities, and repeated/order-varied runs differ only in the explicitly +permitted runtime metadata, byte provenance, source locations, +location-dependent messages, and report-local finding IDs. + +### Step 10 — Produce the evidence package and HTML report + +**Goal:** publish a safe, atomic, human-readable two-file evidence package whose +canonical source is the validated JSON result. + +Work in this step: + +- generate `comparison-report.html` solely from canonical JSON; +- present completeness, comparison differences, assessment issues, phase + traceability, exclusions, provenance, and sensitive-content warnings without + an acceptance verdict; +- provide accessible priority presentation that does not rely on colour alone; +- implement exact destination and overwrite rules, including rejection of + symlinks, special objects, partial packages, and directories with extra + entries; +- stage and replace output atomically while preserving an existing package after + failed replacement; +- apply restrictive temporary-file handling and cleanup; and +- keep operation wholly offline and avoid exposing identifiers or values in + routine terminal output. + +**Approval demonstration:** complete and incomplete sample packages contain +exactly the two required files; the HTML can be regenerated from JSON alone; and +fault-injection tests demonstrate safe creation, refusal, overwrite, rollback, +permissions, and cleanup. + +### Step 11 — Integrate the installed CLI and execution-error boundary + +**Goal:** deliver the complete product path from installed executable to +evidence package, with stable exit and diagnostic behaviour. + +Work in this step: + +- connect the CLI invocation, parsers, configuration resolution, comparison + kernel, result construction, and evidence writer; +- implement the normal standard-output summary without adding a version 1 + progress interface or contaminating machine-readable evidence; +- map every expected invocation, configuration, input, resource, and output + failure to its specified diagnostic and exit code; +- isolate unexpected internal failures, omit ordinary-use tracebacks, and + publish no partial report for execution errors; +- confirm that comparison findings still produce exit code 0 when assessment is + complete, and that not-assessable content produces the documented incomplete + result and exit code; +- build and install the wheel in an isolated environment; and +- run representative custom and automatic comparisons through the installed + `adviso-compare` executable without network access. + +**Approval demonstration:** an installed wheel completes end-to-end successful, +difference-containing, incomplete, and expected-error runs with the precise +files, diagnostics, and exit codes required by the specification. + +### Step 12 — Complete user documentation and release-candidate verification + +**Goal:** make the implemented version understandable, reproducible, and ready +for a release decision. + +Work in this step: + +- write the user guide, available offline after installation, covering + installation, supported inputs, custom and automatic operation, the complete + configuration model, canonical result + fields, HTML interpretation, exit behaviour, security cautions, and worked + examples; +- validate every complete configuration and result example against its packaged + schema; +- verify every documented command against the installed interface; +- document deterministic fixture regeneration; +- run the complete behavioural acceptance suite; +- run all configured schema, packaging, static, and documentation checks across + the supported environments available to the project; and +- produce a final verification report that distinguishes automated, + inspection-based, process, and release-time evidence. + +This step does not silently introduce a formatter, linter, type checker, +dependency manager, CI system, or release policy. Any new project-wide tooling +or policy identified as desirable is proposed separately for approval. + +**Approval demonstration:** a fresh user can install the built artefact and its +declared dependencies using the documented process, follow the packaged guide, +run both documented modes without any runtime network service, validate the +resulting canonical JSON, interpret the HTML, and reproduce the controlled +fixtures. The final review identifies any requirements that remain dependent on +manual or release-process evidence. + +## 4. Recommended review boundaries + +The steps are intentionally ordered by dependency. In particular: + +- result and report design is not allowed to drive undocumented changes to the + comparison model; +- automatic mode is built on the same validated effective-configuration model as + custom mode; +- the HTML report is built from canonical JSON rather than from private engine + state; and +- installed-product testing follows component integration, but packaging and + schema-resource checks begin at the baseline so problems are not deferred. + +If a step proves too large for effective review, it may be divided into smaller +approval checkpoints without changing its scope or starting work assigned to a +later step. Conversely, steps should not be merged merely for speed: the purpose +of the sequence is to make behavioural and architectural corrections inexpensive +before later components depend on them. + +## 5. Definition of version 1 implementation complete + +Implementation is complete only when: + +- the baseline step and all twelve implementation steps have been approved; +- the installed executable satisfies the normative specification and schemas; +- every acceptance-catalogue scenario passes in its intended test environment; +- tests and fixtures remain understandable without the development specification; +- generated configuration and result documents pass structural and semantic + validation; +- the built distributions contain all required code, schemas, and offline + documentation; +- no known inconsistency remains between implementation, tests, schemas, and + documentation; and +- specified behaviours not directly automated are explicitly accounted for by + inspection, packaging, environment, or release-process evidence. diff --git a/packages/adviso-compare/docs/SPECIFICATION.md b/packages/adviso-compare/docs/SPECIFICATION.md new file mode 100644 index 0000000..d4d80a9 --- /dev/null +++ b/packages/adviso-compare/docs/SPECIFICATION.md @@ -0,0 +1,1836 @@ +# `adviso-compare` Behaviour Specification + +**Document status:** Draft for review +**Specification version:** 0.1.0-draft +**Applies to:** The `adviso-compare` command and its supporting comparison engine
+**Normative language:** The terms **MUST**, **MUST NOT**, **SHOULD**, **SHOULD NOT**, and **MAY** indicate requirement strength. + +## 1. Purpose + +This document defines a specification for version 1.0 of `adviso-compare`, a command-line tool that supports bioinformatics validation and verification activities associated with ISO 15189 accreditation. + +`adviso-compare` is designed for two datasets that describe the same kinds of samples or observations but may express their fields and values using different names, types, vocabularies, or other source dialects. The declared comparison configuration translates those representations into a common canonical representation, after which the tool compares the canonical records and values. It produces deterministic, machine-readable findings and a human-readable summary suitable for review and retention as one component of a bioinformatics pipeline validation or verification record. + +The tool distinguishes differences that remain after successful translation from issues that prevented some intended translation or assessment. It is intended to answer these questions: + +> Given these identified inputs and declared translation and comparison rules, which expected and observed records and values are equivalent, different, missing, or extra after translation? Which input or configuration-related issues prevented an intended assessment? + +Given this narrow and precisely defined scope, the tool cannot be used _alone_ to assert that: + +- a pipeline is clinically or analytically valid +- a pipeline conforms with ISO 15189 or any other standard +- a pipeline is fit for an unspecified intended use +- a reference or query dataset is intrinsically correct + +Responsibility for the provenance and suitability of reference material, the comparison rules, acceptance criteria, review, approval, and resulting validation decision remains with the laboratory. + +## 2. Product structure and scope + +### 2.1 Product structure + +The product identities and their roles are: + +| Concept | Name | Role | +| --- | --- | --- | +| Product | **`adviso-compare`** | User-facing comparison tool | +| Distribution | `adviso-compare` | Installable Python distribution | +| Executable | `adviso-compare` | Direct command-line interface | +| Import package | `adviso_compare` | Python implementation package | +| Comparison engine | Internal component | Implements the comparison behaviour | + +The distribution contains the `adviso_compare` import package and installs the +`adviso-compare` executable. The executable delegates to a thin command-line +layer in that package. The comparison engine and supporting configuration, +provenance, findings, and reporting components are internal modules rather than +separate products. + +**REQ-PRD-001.** **`adviso-compare`** is the user-facing product. The installable distribution package MUST be named **`adviso-compare`**. The command-line executable MUST be named **`adviso-compare`**. The other components, including the **comparison engine**, are internal reusable software components and are not separate products. + +**REQ-PRD-002.** The command-line form MUST be: + +```text +adviso-compare ... +``` + +**REQ-PRD-003.** The Python import package MUST be named `adviso_compare`. + +**REQ-PRD-004.** The repository name MAY differ from the distribution and import-package names. Any difference between these names MUST be documented clearly. + +**REQ-PRD-005.** Once released, changes to the distribution name MUST follow the documented compatibility policy. Changes to the executable name MUST follow that policy. Changes to the import-package name MUST follow that policy. + +**REQ-PRD-006.** The executable MUST perform its comparison operation directly and MUST NOT expose a subcommand hierarchy. + +**REQ-PRD-007.** Any future proposal to expand this executable to multiple comparison operations MUST define and justify a cohesive revised command-line interface rather than reserve speculative subcommands in version 1. + +**REQ-PRD-008.** The command-line layer MUST remain thin. It MUST NOT create speculative shared abstractions. + +**REQ-PRD-009.** The initial implementation SHOULD use ordinary modules and a small comparator registry rather than a general plugin framework. + +**REQ-PRD-010.** Capabilities with materially different purposes, dependencies, governance, or release lifecycles SHOULD be separate AdvISO packages. + +### 2.2 Scope of `adviso-compare` + +The first-release scope of `adviso-compare` is: + +- comparison of structured records represented in CSV, TSV or JSON; +- configuration-defined record keys and conservative single-field key selection in automatic mode; +- detection of matching, differing, missing, and extra records and fields; +- field-specific comparison rules; +- controlled column-name and value mappings; +- explicit treatment of types, nulls, and missing values; +- complete discrepancy collection rather than stopping at the first difference; +- structured JSON results, human-readable reports, and automation-friendly exit codes; +- provenance sufficient to reproduce and review a comparison; +- safe handling of data that may contain sensitive clinical information. + +### 2.3 Out of scope + +`adviso-compare` does not: + +- establish analytical sensitivity, analytical specificity, precision, limit of detection, reportable range, clinical validity, or clinical utility; +- generate or adjudicate truth data; +- determine whether a reference dataset is representative or fit for purpose; +- replace laboratory review or approval; +- compare unstructured prose, images, binary files, or specialist bioinformatics formats (e.g. SAM, VCF, FASTQ); +- infer biological equivalence of variants, transcripts, genomic intervals, taxonomic calls, or other domain objects; +- provide automated redaction, identifier pseudonymisation, keyed hashing, or field-level sensitivity policies; +- provide an electronic-signature or laboratory document-management system. + +## 3. Design principles + +The following principles govern all requirements: + +1. **REQ-PRN-001.** **Explicit over inferred:** A custom comparison configuration MUST declare comparison behaviour rather than relying on observed-data inference. The automatic strict-exact mode defined in Section 6.9 is the sole version 1 exception: it MAY infer same-name field correspondence and a single record key only by the fixed rules in that section, and MUST NOT infer types, conversions, mappings, normalisation, tolerance, or biological equivalence. +2. **REQ-PRN-002.** **No silent data loss:** Input records, duplicate keys, unmapped values, and unsupported structures MUST NOT be silently discarded or overwritten. +3. **REQ-PRN-003.** **Symmetry:** Missing and extra content MUST be assessed in both directions. +4. **REQ-PRN-009.** **Separation of concerns:** Run status, comparison evidence, and the laboratory's acceptance decision MUST remain distinct concepts. +5. **REQ-PRN-004.** **Complete evidence:** A normal comparison mismatch MUST still produce a complete report. +6. **REQ-PRN-005.** **Determinism:** The same exact input bytes, input basenames, configuration selection, software version, and runtime identity MUST produce identical result content except for the explicitly variable run identifier and completion time. Configuration selection includes omission of `--configuration`, in which case automatic construction MUST itself be deterministic. Comparison outcomes MUST additionally satisfy the invariance rules in Section 9.1. +7. **REQ-PRN-006.** **Traceability:** Findings MUST identify the rule, record, and field that produced them. +8. **REQ-PRN-007.** **Data minimisation:** Reports MUST include only the source identifiers and values necessary to explain and review the comparison. Routine logs, progress output, terminal diagnostics, and execution-error diagnostics MUST NOT reproduce them. +9. **REQ-PRN-008.** **Fail clearly:** Invalid or ambiguous input MUST produce an explicit error rather than an assumed interpretation. + +## 4. Terminology + +- **Reference dataset:** The dataset containing the approved expected or comparator records. “Reference” does not imply intrinsic truth. +- **Query dataset:** The dataset being evaluated against the reference. +- **Custom comparison configuration:** A versioned YAML document supplied by the user to declare the data contract, normalisation, and comparison behaviour. +- **Effective comparison configuration:** The schema-valid configuration used for a run: either the validated custom configuration or the deterministic configuration generated by automatic strict-exact mode. +- **Automatic strict-exact mode:** The configuration-free mode used when `--configuration` is omitted. It constructs an effective comparison configuration from the inputs using only the rules in Section 6.9. +- **Not assessed:** Outside the canonical fields selected by `fields.in_scope`. +- **Not assessable:** Included in the configured comparison, but unable to be compared safely because a prerequisite was not satisfied. +- **Contract comparison:** Assessment of whether inputs satisfy the declared data contract, including fields, logical types, key definitions, nullability, mappings, and configured constraints. +- **Records comparison:** Alignment and assessment of valid record identities, including matching, missing, and extra records. Invalid, missing, null, or duplicate record keys are execution errors rather than record-comparison findings. +- **Value comparison:** Application of declared comparators to values in records that can be aligned meaningfully. +- **Record:** One logical unit of comparison. +- **Record key:** One field or an ordered combination of fields that uniquely identifies a record within a dataset. +- **Field:** A named value within a record. +- **Finding:** A structured observation generated by applying one comparison rule to a record, field, dataset, or run. +- **Run status:** Whether the requested comparison is `complete`, `incomplete`, or ended in `error`. +- **Output parent:** The directory selected by `--output`, under which individual run directories are published. +- **Saved comparison configuration:** The complete effective comparison configuration serialized as `comparison-configuration.json` in the evidence package. +- **Configuration digest:** The SHA-256 digest of the exact saved comparison-configuration bytes. +- **Evidence package:** One run's directory containing its canonical JSON result, saved comparison configuration, and HTML report. +- **Package validation:** Independent structural validation of the two JSON documents, verification of their byte-digest linkage and supported schema combination, and semantic consistency checks within and between them. +- **Laboratory decision:** The externally reviewed conclusion about validation or verification. The tool does not make this decision. +- **Missing:** Expected in the reference but absent from the query. +- **Extra:** Present in the query but absent from the reference. +- **Null:** A present field with an explicitly empty/no-value representation defined by the input format or comparison configuration. +- **Absent:** A field or record that is not present at all. +- **Normalisation:** A declared, non-lossy or intentionally controlled transformation performed before comparison. +- **Mapping:** A declared translation of field names or values from one representation to another. + +## 5. Inputs + +### 5.1 Required inputs + +**REQ-INP-001.** A comparison run MUST receive: + +- **REQ-INP-060.** one reference dataset; +- **REQ-INP-061.** one query dataset; +- **REQ-INP-062.** an output destination. + +**REQ-INP-002.** A custom comparison configuration MAY be supplied. + +**REQ-INP-003.** If a custom comparison configuration is omitted, the tool MUST use the automatic strict-exact mode defined in Section 6.9. + +### 5.2 Supported formats + +**REQ-INP-004.** The initial implementation MUST support: + +- **REQ-INP-063.** CSV using the fixed version 1 parsing rules in Section 5.4; +- **REQ-INP-064.** TSV using the fixed version 1 parsing rules in Section 5.4; +- **REQ-INP-065.** JSON using a documented record-oriented structure. + +For each input: + +- **REQ-INP-005.** its format MUST be determined from its case-insensitive filename extension: `.csv`, `.tsv` or `.json`; +- **REQ-INP-006.** the detected format MUST be recorded; +- **REQ-INP-007.** a missing, unknown, or ambiguous extension, including `.txt`, MUST cause an input error; +- **REQ-INP-008.** its content MUST be validated against the format indicated by the extension; +- **REQ-INP-009.** content that does not conform to the indicated format MUST cause an input error. + +### 5.3 Character encoding and text handling + +- **REQ-INP-010.** UTF-8 MUST be the only supported input encoding in version 1. +- **REQ-INP-011.** Invalid UTF-8 byte sequences MUST cause an input error. +- **REQ-INP-012.** Invalid UTF-8 byte sequences MUST NOT be replaced silently. +- **REQ-INP-013.** Field names and string values MUST be preserved exactly before declared normalisation. +- **REQ-INP-014.** Changing only accepted LF and CRLF line endings MUST NOT affect the comparison outcome defined in Section 9.1. Exact-byte size and digest evidence MAY differ. + +### 5.4 Tabular parsing + +For CSV and TSV: + +- **REQ-INP-015.** CSV MUST use comma as its delimiter. +- **REQ-INP-016.** TSV MUST use tab as its delimiter. +- **REQ-INP-017.** CSV and TSV MUST use double quote as the quote character. +- **REQ-INP-018.** A double quote within a quoted field MUST be escaped by doubling it. +- **REQ-INP-019.** CRLF and LF record endings MUST be accepted. +- **REQ-INP-020.** Embedded delimiters and line breaks MUST be accepted only within quoted fields. +- No separate backslash or alternative escape mechanism is supported in version 1. +- **REQ-INP-021.** a header row MUST be required; +- **REQ-INP-022.** duplicate or empty column names MUST cause an input error; +- **REQ-INP-023.** delimiters, quoting, escaping, and embedded newlines MUST be handled by a standards-compliant parser; +- **REQ-INP-024.** rows with too many or too few columns MUST be input errors; +- **REQ-INP-025.** all physical input rows MUST be accounted for; +- **REQ-INP-026.** the one-based data-record number and one-based starting physical line number of every record MUST be retained for traceability; the header is not a data record; +- **REQ-INP-027.** Input values MUST initially remain strings unless a custom configuration declares a null representation or type conversion. +- **REQ-INP-028.** CSV and TSV cells, including empty cells, MUST initially remain strings before any configured field processing. + +### 5.5 JSON parsing + +- **REQ-INP-029.** A JSON input MUST contain one root-level array of record objects. A dataset containing one record MUST use a one-element array; a root-level record object is not supported: + +```json +[ + {"sample_id": "S1", "gene": "BRAF", "result": "detected"}, + {"sample_id": "S2", "gene": "KRAS", "result": "not_detected"} +] +``` + +- **REQ-INP-030.** Values such as `yes`, `no`, `on`, `off`, uppercase boolean-like values, and timestamp-like strings MUST remain strings unless a custom configuration explicitly maps or parses them. +- **REQ-INP-031.** JSON decimal numbers - i.e. numbers containing a fractional or exponent component - MUST be parsed using exact decimal arithmetic. +- **REQ-INP-032.** JSON decimal numbers MUST NOT first be converted to binary floating-point values. +- **REQ-INP-033.** The tool MUST retain the original text of each JSON number — for example, distinguishing the representations `0.100`, `0.1`, and `1e-1` — for inclusion in evidence when required. +- **REQ-INP-034.** A root-level JSON value that is not an array MUST cause an input error, including a root-level object that could otherwise represent one record. +- **REQ-INP-035.** A root-level scalar MUST cause an input error. +- **REQ-INP-036.** A root-level array containing any item that is not an object MUST cause an input error. +- **REQ-INP-037.** An invalid-root error MUST identify the invalid root value or array item. +- **REQ-INP-038.** An invalid-root error MUST explain the required structure. +- **REQ-INP-070.** Duplicate member names in any JSON object MUST cause an input error, including duplicates in record objects and nested object-valued fields. A parser MUST detect duplicates before constructing a mapping that could overwrite an earlier member. +- **REQ-INP-072.** A top-level JSON record object MUST NOT contain an empty + member name, because record member names participate in dataset-wide field + discovery and configuration. An empty member name in a nested object-valued + field remains valid data content. An empty record member name MUST produce an + `input.invalid_structure` execution error. + +### 5.6 Parser-native value model + +- **REQ-INP-039.** When an input file is read, and before any configured type conversion, mapping, or normalisation is applied, each input value MUST be represented internally using one of the following parser-native value categories: `string`, `integer`, `decimal`, `boolean`, `null`, `array`, and `object`. +- **REQ-INP-040.** CSV and TSV cells MUST be strings, including empty strings, unless a custom configuration declares further processing. +- **REQ-INP-041.** JSON numbers without a fractional or exponent component MUST be integers. +- **REQ-INP-042.** Other finite JSON numbers MUST be exact decimals. +- **REQ-INP-043.** JSON arrays used as field values MUST be represented internally as `array` values. +- **REQ-INP-044.** JSON objects used as field values MUST be represented internally as `object` values. +- Parser-native values are equal only when they have the same category and recursively equal content. For array-valued fields, element order is significant; for object-valued fields, member names and values must match but member order is not significant. Top-level records are aligned by their declared record keys, and their input order does not affect comparison. +- **REQ-INP-045.** Numerical values MUST be retained exactly as they appeared in the input for reporting and traceability. +- **REQ-INP-046.** Two values in the same numerical category MUST compare as equal when they represent the same number; for example, decimal `1.0` and decimal `1.00` are equal. +- `NaN`, positive infinity, and negative infinity are not valid JSON numerical values or valid declared decimals. +- **REQ-INP-047.** An unquoted non-finite token such as `NaN`, `Infinity`, or `-Infinity` in a JSON input MUST cause an input error because the document is not valid JSON, irrespective of the field in which it occurs. +- **REQ-INP-048.** A quoted representation such as `"NaN"` in JSON, CSV, or TSV MUST initially remain a parser-native string. +- **REQ-INP-049.** If such a string is parsed as a declared decimal in an attributable non-key field, it MUST produce an `invalid_field_value` finding, make that value opportunity `not_assessable`, and allow other assessable content to continue. +- **REQ-INP-050.** If such a string is parsed as a declared decimal record-key field, the invalid key MUST produce an execution error. +- **REQ-INP-051.** The JSON parser MUST reject non-standard non-finite tokens rather than enabling a permissive extension. Every accepted parser-native JSON number is therefore a finite exact integer or decimal. + +### 5.7 Empty inputs + +- **REQ-INP-052.** Zero-byte files and datasets with zero records MUST be recognised explicitly and distinguished. A valid zero-record JSON dataset is `[]`; a valid zero-record CSV or TSV dataset contains a valid header and no data records. A zero-byte JSON file is malformed JSON, and a zero-byte CSV or TSV file is an input error because it lacks the required header. +- **REQ-INP-053.** If both datasets are syntactically valid, contain no records, and provide or permit construction of a valid effective comparison configuration and record key, the records phase MUST report no missing records. +- **REQ-INP-054.** Under the conditions in `REQ-INP-053`, the records phase MUST report no extra records. +- **REQ-INP-055.** Under the conditions in `REQ-INP-053`, the values phase MUST perform no comparisons. +- **REQ-INP-056.** Contract requirements that can be evaluated without records MUST still be checked. +- **REQ-INP-057.** The tool MUST NOT infer that an empty dataset is unsuitable merely because it is empty. +- **REQ-INP-066.** Per-record requirements have no applicable opportunities in a zero-record dataset and MUST NOT produce findings or not-assessable classifications merely because no records exist. +- **REQ-INP-067.** Available dataset-level structure MUST still be assessed. A zero-record CSV or TSV header MAY establish configured, missing, or otherwise excluded source columns. A JSON empty array exposes no field structure, so field presence or absence MUST NOT be inferred from it. +- **REQ-INP-068.** When the conditions in `REQ-INP-053` are satisfied, two valid zero-record datasets MUST have complete records and values phases, zero matched, missing, and extra records, and zero value opportunities. Header-derived contract findings do not alter those phase statuses. +- **REQ-INP-069.** When exactly one dataset has records and a valid effective comparison configuration and record key are available, every record on that side MUST be reported as missing or extra as applicable; because there are no aligned records, there are zero value opportunities and the records and values phases remain complete. +- **REQ-INP-071.** In automatic strict-exact mode, two empty JSON arrays do not expose a field from which a record key can be selected and MUST produce an `input.invalid_record_key` execution error. A valid custom configuration can compare the same inputs. +- Any minimum-size acceptance criterion belongs to the external laboratory decision process. +- **REQ-INP-058.** When a valid effective comparison configuration and record key are available, a non-empty reference and empty query MUST report every expected record as missing. +- **REQ-INP-059.** When a valid effective comparison configuration and record key are available, an empty reference and non-empty query MUST report every observed record as extra. + +## 6. Comparison configurations + +### 6.1 General requirements + +**REQ-CFG-001.** Every comparison uses an effective comparison configuration. A custom configuration MUST: + +- **REQ-CFG-095.** use a published, independently versioned comparison-configuration schema supported by the installed software release; +- **REQ-CFG-096.** declare its schema version and a stable configuration identifier and revision; +- **REQ-CFG-097.** be validated fully before either dataset is compared; +- **REQ-CFG-098.** reject unknown configuration keys by default; +- **REQ-CFG-099.** provide actionable validation errors with configuration locations; +- **REQ-CFG-100.** be saved in full as `comparison-configuration.json` in the evidence package. + +An automatically generated effective configuration is constructed only after both datasets have been parsed and their dataset-wide field names have been discovered. It MUST satisfy the comparison-configuration schema and semantic rules before any contract, record, or value comparison is performed, and it MUST be saved in full as `comparison-configuration.json` in the evidence package. + +**REQ-CFG-002.** A valid comparison configuration MUST declare at least: + +- **REQ-CFG-101.** record key fields; +- **REQ-CFG-102.** field definitions and an explicit list of fields in scope for comparison; +- **REQ-CFG-103.** comparison rules. + +### 6.2 Custom comparison-configuration YAML format + +**REQ-CFG-003.** Custom comparison configurations MUST be YAML documents conforming to the format defined in this section. YAML is used only for the comparison configuration; it is not a supported dataset format. + +**REQ-CFG-004.** A configuration file SHOULD use the `.yaml` or `.yml` extension. + +#### 6.2.1 YAML parsing and validation + +- **REQ-CFG-005.** The document MUST be UTF-8 encoded and contain exactly one YAML mapping at its root. +- **REQ-CFG-006.** The configuration MUST be parsed according to the YAML 1.2 rules for interpreting unquoted scalar values. +- **REQ-CFG-007.** The parser MUST use a safe loading mode that cannot construct arbitrary application objects or execute code. +- **REQ-CFG-008.** Duplicate mapping keys, merge keys, aliases, anchors, explicit tags, and executable or implementation-specific object constructors MUST be rejected as configuration errors. +- **REQ-CFG-009.** Unknown keys MUST be rejected as configuration errors. +- **REQ-CFG-010.** Required keys MUST NOT be supplied as YAML null values. +- **REQ-CFG-011.** `schema_version`, `id`, `revision`, field names, operation names, comparator names, enumerated values, decimal lexical values, dates, and datetimes SHOULD be quoted to prevent unintended YAML scalar conversion. +- **REQ-CFG-012.** The complete document MUST be validated against the published schema identified by `schema_version` before either dataset is read. +- **REQ-CFG-013.** Validation errors MUST identify the YAML path and the violated requirement. + +#### 6.2.2 Complete structural template + +**REQ-CFG-014.** The following template defines the complete first-release structure. Keys marked “optional” in comments MAY be omitted; other displayed keys are required when their parent construct is used, except where a conditional omission is explicitly permitted below. Optional processing properties are omitted rather than represented by empty lists. + +```yaml +schema_version: "1.0" + +metadata: + id: "org.example.pipeline-output-comparison" + revision: "1.0.0" + title: "Example pipeline-output comparison" # optional + description: "Approved comparison rules" # optional + +fields: + record_key: + - "record_id" + in_scope: + - "record_id" + - "field_example_1" + - "field_example_2" + - "field_example_3" + definitions: + record_id: + source_fields: + reference: "sample_id" + query: "specimen_id" + required: + reference: true + query: true + logical_type: "string" + null_policy: + allowed: false + nulls_equal: false + comparator: + name: "typed_exact" + field_example_1: + source_fields: + reference: "expected_result" + query: "reported_result" + required: + reference: true + query: true + logical_type: "decimal" + null_policy: + allowed: false + nulls_equal: false + typed_normalisation: + - operation: "decimal_quantise" + parameters: + places: 3 + rounding: "half_even" + comparator: + name: "numeric_tolerance" + parameters: + absolute_tolerance: "0.01" + review_priority: "high" # optional; default: normal + field_example_2: + source_fields: + reference: "expected_interpretation" + query: "reported_interpretation" + required: + reference: true + query: true + logical_type: "string" + null_policy: + allowed: true + nulls_equal: true + missing_tokens: + reference: + - category: "string" + value: "na" + query: + - category: "string" + value: "." + source_normalisation: + reference: + - operation: "trim" + parameters: + side: "both" + - operation: "case_fold" + query: + - operation: "trim" + parameters: + side: "both" + value_mapping: + reference: + - from: + category: "string" + value: "detected" + to: + category: "string" + value: "detected" + - from: + category: "string" + value: "not detected" + to: + category: "string" + value: "not_detected" + query: + - from: + category: "string" + value: "pos" + to: + category: "string" + value: "detected" + - from: + category: "string" + value: "neg" + to: + category: "string" + value: "not_detected" + comparator: + name: "typed_exact" + review_priority: "low" # optional; default: normal + field_example_3: + source_fields: + reference: "expected_markers" + query: "reported_markers" + required: + reference: true + query: true + logical_type: + collection_type: "set" + element_type: "string" + element_comparator: + name: "typed_exact" + null_policy: + allowed: false + nulls_equal: false + collection_representation: + query: + format: "delimited_text" + delimiter: "/" + element_normalisation: + - operation: "trim" + parameters: + side: "both" + - operation: "case_fold" + element_mapping: + - from: + category: "string" + value: "wild_type" + to: + category: "string" + value: "WT" + - from: + category: "string" + value: "mutant" + to: + category: "string" + value: "MUT" + comparator: + name: "set_exact" + +``` + +The template is illustrative rather than a recommendation to use these particular rules. + +**REQ-CFG-016.** The published machine-readable schema MUST encode the complete version 1 comparison-configuration structure and constraints. + +The four field definitions illustrate different configuration roles: `record_id` is a renamed exact key; `field_example_1` is parsed as an exact decimal and quantised before tolerance comparison; `field_example_2` demonstrates source-text normalisation, side-specific missing tokens, and mapping different source vocabularies to common canonical string values; and `field_example_3` compares a reference JSON array with a slash-delimited query string after element-level normalisation and mapping. The deliberately generic names make clear that these are user-defined canonical field names rather than reserved configuration keywords. These example rules are not domain recommendations. + +#### 6.2.3 Top-level keys and identity + +The only permitted top-level keys are `schema_version`, `metadata`, and `fields`. + +- **REQ-CFG-017.** `schema_version` MUST be a quoted string identifying a supported comparison-configuration schema version. +- **REQ-CFG-018.** `metadata.id` MUST be a stable, non-empty identifier for the comparison configuration. +- **REQ-CFG-020.** `metadata.revision` MUST be a non-empty string. +- `metadata.title` and `metadata.description` are optional human-readable strings. +- **REQ-CFG-022.** The `metadata` properties MUST NOT directly alter comparison behaviour. +- **REQ-CFG-023.** The `metadata` properties MUST be preserved in the saved comparison configuration. + +#### 6.2.4 Record-key selection + +- **REQ-CFG-024.** `fields.record_key` MUST be a non-empty ordered list of canonical field names present in `fields.definitions`. The list defines one logical record key, and list order defines the component order of a composite key. +- **REQ-CFG-025.** Every key field MUST be required on both sides. +- **REQ-CFG-026.** Every key field MUST be non-nullable. +- **REQ-CFG-027.** Every key field MUST be declared with a scalar logical type. +- **REQ-CFG-028.** A key field MAY use explicitly declared source normalisation or value mapping. +- **REQ-CFG-029.** Every key field MUST use `typed_exact` after transformation. + +#### 6.2.5 Field selection, declaration, and source names + +- `fields.definitions` declares canonical fields and their reference-to-query correspondence. Declaration alone does not select a field for assessment. +- **REQ-CFG-030.** `fields.in_scope` is required and MUST be a non-empty list of unique canonical field names. Every listed name MUST exist in `fields.definitions`. +- **REQ-CFG-031.** The order of names in `fields.in_scope` MUST NOT affect the comparison outcome or the ordering of findings and exclusions. The saved comparison configuration MUST preserve the effective list order as provenance. +- **REQ-CFG-116.** Source-field names MUST be discovered dataset-wide. For CSV and TSV, the header defines the observed names even when there are no records. For JSON, the observed names are the union of member names across all record objects. +- **REQ-CFG-117.** A field present in `fields.definitions` but absent from `fields.in_scope` is deliberately excluded from assessment. It MUST produce exactly one `configured_field_excluded` entry naming its canonical field, regardless of whether either source field is observed in the inputs. +- **REQ-CFG-118.** A source field observed on a dataset side but not named by any field definition for that side is outside scope. It MUST produce one `undeclared_field_excluded` entry for that dataset side and source field. +- **REQ-CFG-119.** Excluded fields MUST NOT be compared, create findings, create value opportunities, or affect run or phase status. +- **REQ-CFG-120.** Exclusions MUST be summarised rather than repeated for individual records and MUST use the exact forms and deterministic ordering defined in Section 9.1.3. +- **REQ-CFG-121.** An `undeclared_field_excluded` entry MUST record the number of records on that dataset side that contain the source field. A field known only from a zero-record CSV or TSV header has a record count of zero. +- **REQ-CFG-032.** Fields with different names MUST be declared explicitly under a common canonical field definition if they are intended to correspond. +- **REQ-CFG-033.** `fields.definitions` MUST be a mapping keyed by unique canonical field name. +- **REQ-CFG-034.** `fields.definitions` MUST contain a definition for every field referenced by `fields.record_key`, and every record-key field MUST also occur in `fields.in_scope`. +- **REQ-CFG-035.** `source_fields.reference` and `source_fields.query` MUST each contain a non-empty source field name. A declared field always defines correspondence between one reference field and one query field, regardless of whether either field is required to be present in every record. +- **REQ-CFG-036.** `required.reference` and `required.query` MUST be booleans. +- **REQ-CFG-037.** Absence of a field required on a particular side MUST create a contract finding. +- **REQ-CFG-038.** Absence of an optional field MUST NOT create a missing-field finding. +- **REQ-CFG-039.** A source field observed in an input but not represented by a field definition for that dataset side MUST be excluded as specified by `REQ-CFG-118`. It MUST NOT be aligned or compared implicitly, even when the same source-field name occurs on both sides. +- **REQ-CFG-040.** `review_priority`, when present, MUST be `low`, `normal`, or `high`. When omitted, it defaults to `normal` in the effective configuration. +- **REQ-CFG-041.** A declared field's resolved `review_priority` MUST be attached to every finding attributable to that canonical field, including missing-field, null-policy, type, parsing, mapping, and value-mismatch findings. +- **REQ-CFG-042.** Review priority MUST NOT be inherited by findings that cannot be attributed to a declared field, such as missing or extra records. +- **REQ-CFG-043.** Review priority is presentation and review-workflow metadata only. It MUST NOT change comparison behaviour, determine whether a finding is emitted, alter counts, affect run or phase status, affect exit codes, or constitute a laboratory acceptance decision. +- **REQ-CFG-044.** Human-readable reports MAY use review priority for grouping, ordering, filtering, icons, or colour coding. +- **REQ-CFG-045.** Colour MUST NOT be the only means of communicating review priority. +- **REQ-CFG-046.** Reports and documentation MUST NOT describe review priority as clinical significance. +- **REQ-CFG-047.** Reports and documentation MUST NOT describe review priority as an execution-error classification. + +#### 6.2.6 Logical types and null policy + +**REQ-CFG-048.** For a scalar field, `logical_type` MUST be one of `string`, `integer`, `decimal`, `boolean`, `date`, or `datetime`. + +**REQ-CFG-049.** `logical_type` MUST be omitted when, and only when, the comparator is `preserved_exact`. A `preserved_exact` field MUST also omit `source_normalisation`, `collection_representation`, `value_mapping`, `typed_normalisation`, and `null_policy.missing_tokens`. Its requiredness and null policy still apply, and parser-native JSON null remains governed by that null policy, but no additional source representation is transformed or interpreted as null. + +**REQ-CFG-050.** For a collection field, `logical_type` MUST use this form: + +```yaml +logical_type: + collection_type: "list" # list, set, or multiset + element_type: "string" # scalar logical type + element_comparator: + name: "typed_exact" +``` + +**REQ-CFG-051.** Nested collection types MUST be rejected. + +**REQ-CFG-052.** The comparator named for the field itself MUST correspond to the collection kind: `list_exact`, `set_exact`, or `multiset_exact`. + +**REQ-CFG-124.** A `set` or `multiset` element comparator MUST be `typed_exact`. + +**REQ-CFG-125.** A `list` element comparator MUST be `typed_exact` or `numeric_tolerance`. `numeric_tolerance` MUST be permitted only when `element_type` is `integer` or `decimal` and MUST use the same parameter rules as a field-level numeric-tolerance comparator. + +**REQ-CFG-126.** `preserved_exact`, `normalised_string`, `numeric_exact`, `date_exact`, `datetime_exact`, and the collection comparators MUST NOT be used as element comparators in version 1. Exact comparison of any declared scalar element type uses `typed_exact`. + +**REQ-CFG-053.** Every declared field MUST contain a `null_policy` mapping: + +- **REQ-CFG-054.** `allowed` and `nulls_equal` MUST be booleans. +- **REQ-CFG-055.** `nulls_equal` MUST be `false` when `allowed` is `false`. +- **REQ-CFG-056.** `missing_tokens` MAY be omitted; omission means that no additional source values are interpreted as null. Parser-native JSON null remains null independently of this property. +- **REQ-CFG-057.** When `missing_tokens` is present, it MUST contain `reference`, `query`, or both. Each present side MUST be a non-empty list of non-null source-value descriptors. An omitted side has no configured missing tokens. A matched token is converted to null at processing step 3 in Section 6.8. + +A source-value descriptor has one of these forms: + +```yaml +category: "string" +value: "NA" +``` + +```yaml +category: "decimal" +value: "1.00" +``` + +```yaml +category: "null" +``` + +**REQ-CFG-058.** `category` MUST be `string`, `integer`, `decimal`, `boolean`, or `null`. + +**REQ-CFG-059.** `value` MUST be present for every category except `null`. It MUST be a quoted lexical string for `string`, `integer`, and `decimal`. It MUST be `true` or `false` for `boolean`. The lexical value MUST be valid for its stated category. + +**REQ-CFG-122.** A descriptor with `category: null` MUST be permitted only as the `to` destination of a value-mapping entry. It MUST NOT be permitted as a missing token or as a mapping `from` value, because parser-native null is recognised without configuration and null values bypass mapping. + +Descriptors are matched using parser-native category and value equality under Section 5.6. The retained lexical form remains evidence but does not create a distinct numerical value. This explicit representation prevents YAML scalar resolution from changing mapping keys or missing tokens. + +#### 6.2.7 Normalisation, collection representation, and value mapping + +**REQ-CFG-060.** `source_normalisation` MAY be omitted. Omission means that no source-text normalisation is applied. + +**REQ-CFG-061.** When present, `source_normalisation` MUST contain `reference`, `query`, or both. Each present side MUST be a non-empty ordered list of operations applied only to values from that dataset. An omitted side has no source-text operations. + +**REQ-CFG-062.** `typed_normalisation` MAY be omitted. Omission means that no typed-value normalisation is applied. + +**REQ-CFG-063.** When present, `typed_normalisation` MUST be a non-empty ordered list applied to the canonical typed values on both sides. Each operation entry has this form: + +```yaml +- operation: "decimal_quantise" + parameters: + places: 3 + rounding: "half_even" +``` + +**REQ-CFG-064.** `parameters` MAY be omitted only when the registered operation has no parameters. + +**REQ-CFG-065.** `operation` MUST name an operation defined by the applicable schema version. Its parameters MUST validate against that operation’s published parameter schema. An unknown operation MUST invalidate the comparison configuration. An unknown parameter MUST invalidate the comparison configuration. + +List order is execution order. The permitted processing stages and their overall order are fixed by Section 6.8. + +The first-release source-text operation identifiers are: + +- `unicode_normalise`, requiring `form` with one of `NFC`, `NFD`, `NFKC`, or `NFKD`; +- `trim`, requiring `side` with one of `leading`, `trailing`, or `both`; here `side` identifies which end or ends of the text are trimmed, not the reference or query dataset; and +- `case_fold`, which takes no parameters. + +The first-release typed-value operation identifiers are: + +- `decimal_quantise`, requiring a non-negative integer `places` and `rounding` with one of `half_even`, `half_up`, or `down`; and +- `datetime_truncate`, requiring `precision` with one of `second`, `millisecond`, or `microsecond`. + +**REQ-CFG-146.** For `decimal_quantise`, `places` is the number of +digits after the decimal point to which the value is quantised. `half_even` +MUST round to the nearest value, with an exact tie resolved to the value whose +final retained digit is even. `half_up` MUST round to the nearest value, with +an exact tie resolved away from zero. `down` MUST discard excess fractional +digits towards zero. + +**REQ-CFG-147.** The `trim` operation MUST recognise exactly the characters +with the Unicode `White_Space` property in the Unicode version recorded in the +results. It MUST remove the maximal sequence of those characters from the +configured leading end, trailing end, or both ends. It MUST NOT remove other +characters merely because the implementation language treats them as +whitespace. + +**REQ-CFG-148.** `datetime_truncate` MUST operate on the canonical UTC instant +after offset normalisation. `second` MUST discard the complete fractional-second +component, `millisecond` MUST retain at most three fractional digits, and +`microsecond` MUST retain at most six fractional digits. Discarded digits MUST +be removed without rounding. + +**REQ-CFG-149.** `case_fold` MUST apply locale-independent Unicode Default Case +Folding using the Unicode version recorded in the results. It MUST use full +case folding, including mappings that expand one character into multiple +characters. It MUST NOT apply Unicode normalisation implicitly; normalisation +occurs only through a separately configured `unicode_normalise` operation. + +**REQ-CFG-066.** A source-text operation MUST appear only in `source_normalisation.reference`, `source_normalisation.query`, or a side's `collection_representation..element_normalisation`. It applies only to values or decoded elements, respectively, from the corresponding dataset side. + +**REQ-CFG-123.** A source-text operation MUST apply only when the current parser-native value is a string. A non-string value MUST pass through the source-normalisation stage unchanged; it MUST NOT be stringified, transformed, or rejected merely because a source-text operation is configured. + +**REQ-CFG-067.** A typed-value operation MUST appear only in `typed_normalisation`. It applies identically to both datasets. + +**REQ-CFG-068.** Operation semantics MUST be published with the schema and recorded sufficiently for reproducibility. This information MUST include the Unicode-data version used by Unicode operations. + +**REQ-CFG-137.** `collection_representation` MAY be present only for a collection logical type. It MAY contain `reference`, `query`, or both; each present side declares how that dataset side represents the collection and MAY declare element-level source processing. An omitted side uses `json_array` with no element normalisation or element mapping. + +**REQ-CFG-138.** Each present side of `collection_representation` MUST contain `format`, which MUST be `json_array` or `delimited_text`. + +- `json_array` means a parser-native array in JSON or a parser-native string containing one valid JSON array in CSV or TSV. +- `delimited_text` means a parser-native string split using an explicitly configured delimiter. It does not mean a CSV or TSV row-level dialect. + +**REQ-CFG-139.** A `delimited_text` declaration MUST contain a non-empty string `delimiter`. A `json_array` declaration MUST omit `delimiter`. + +**REQ-CFG-140.** `element_normalisation`, when present, MUST be a non-empty ordered list of the source-text operations defined in this section. The operations apply only to string elements from the declared dataset side. Non-string elements pass through unchanged. + +**REQ-CFG-141.** `element_mapping`, when present, MUST be a non-empty ordered list using the same `from` and `to` structure as `value_mapping`. Both descriptors MUST be non-null. Each `from` value MUST occur at most once within one side's element mapping; conflicting or unreachable entries MUST invalidate the comparison configuration. Many-to-one element mappings are permitted when declared explicitly. + +**REQ-CFG-142.** When an element mapping is present, an element with no matching entry MUST produce a `mapping_failure` contract finding, prevent construction of that field's canonical collection value, and make that value opportunity `not_assessable`. Unmapped elements MUST NOT pass through implicitly. + +**REQ-CFG-143.** An empty optional `collection_representation`, `element_normalisation`, or `element_mapping` mapping or list MUST be rejected. Absence MUST be represented by omission. + +**REQ-CFG-145.** A collection field MUST omit field-level `source_normalisation`, `value_mapping`, and `typed_normalisation`. Source processing of collection elements MUST be declared through the applicable side of `collection_representation`. The field-level null policy and missing-token recognition continue to apply to the collection value as a whole before representation decoding. + +**REQ-CFG-069.** `value_mapping` MAY be omitted. Omission means that no value mapping is applied. + +**REQ-CFG-070.** When present, `value_mapping` MUST contain `reference`, `query`, or both. Each present side MUST be a non-empty ordered list of entries with the following form. An omitted side has no value mapping: + +```yaml +- from: + category: "string" + value: "resistant" + to: + category: "string" + value: "R" +``` + +- **REQ-CFG-071.** `from` MUST be a non-null source-value descriptor and `to` MUST be a source-value descriptor as defined in Section 6.2.6. +- A `from` descriptor is matched against the source value after the applicable `source_normalisation` operations and missing-token recognition have been performed, in accordance with the processing order in Section 6.8. +- A `to` descriptor with `category: "null"` explicitly maps a non-null source value to null and is distinct from absence of a mapping entry. The null policy is then applied and typed parsing is bypassed. +- **REQ-CFG-072.** Each `from` value MUST occur at most once within one side’s mapping. +- **REQ-CFG-073.** Conflicting entries MUST invalidate the comparison configuration. +- **REQ-CFG-074.** Unreachable entries MUST invalidate the comparison configuration. +- A field-level `value_mapping` requires a scalar `logical_type`; whole-collection value mapping is not supported in the first release. Collection elements may instead use `collection_representation..element_mapping`. A field-level mapping's `to` values are parsed as the destination type after mapping. +- When a side has a value mapping, a source value with no mapping entry creates a contract finding. Pass-through of unmapped values is not supported in the first release. + +**REQ-CFG-075.** Before comparison, the tool MAY expand omitted optional processing properties and omitted dataset sides into explicit empty internal structures for internal use. + +**REQ-CFG-076.** Such expansion is implementation state. It MUST NOT replace the validated configuration document selected for the run and saved in the evidence package. It MUST NOT alter that document. Omission changes no behaviour beyond declaring that the corresponding processing step is absent. + +#### 6.2.8 Comparator declarations + +**REQ-CFG-077.** Every field definition MUST contain `comparator.name`. + +**REQ-CFG-078.** `name` MUST be one of the comparator identifiers in Section 7.4. + +**REQ-CFG-079.** A `parameters` mapping MUST be present only when the selected comparator requires parameters. It MUST contain only parameters valid for that comparator. + +- **REQ-CFG-080.** `preserved_exact`, `typed_exact`, `normalised_string`, `numeric_exact`, `date_exact`, `datetime_exact`, `list_exact`, `set_exact`, and `multiset_exact` take no field-level parameters in the first release; `parameters` MUST be omitted for these comparators. +- **REQ-CFG-081.** `numeric_tolerance` MUST contain a `parameters` mapping with exactly one of `absolute_tolerance` or `relative_tolerance`. +- **REQ-CFG-082.** Supplying neither tolerance MUST invalidate the comparison configuration. +- **REQ-CFG-083.** Supplying both tolerances MUST invalidate the comparison configuration. +- **REQ-CFG-084.** The supplied tolerance MUST be a quoted, non-negative finite decimal string. +- **REQ-CFG-085.** The comparator MUST be compatible with `logical_type`: string comparators with `string`, numeric comparators with `integer` or `decimal`, date comparators with their corresponding temporal type, and collection comparators with their corresponding collection type. +- `normalised_string` requires at least one operation in `source_normalisation.reference`, `source_normalisation.query`, or `typed_normalisation` that is applicable to strings. + +#### 6.2.9 Normative machine-readable schema and semantic validation + +The normative JSON Schema Draft 2020-12 definition of comparison-configuration schema version `1.0` is [`src/adviso_compare/schemas/comparison-configuration-v1.0.schema.json`](../src/adviso_compare/schemas/comparison-configuration-v1.0.schema.json). + +**REQ-CFG-128.** The schema MUST use `https://adviso-project.github.io/validation_toolkit/schemas/comparison-configuration-v1.0.schema.json` as its canonical `$id`. + +**REQ-CFG-086.** A YAML configuration MUST first be loaded using Section 6.2.1. The resulting JSON-compatible data structure MUST then validate against that schema before either input dataset is read. + +The standalone schema file is the authoritative machine-readable definition. + +**REQ-CFG-087.** It MUST be version controlled in the source repository. It MUST be included as package data in the installed `adviso_compare.schemas` package. It MUST be loaded at runtime through the package-resource API rather than through a path relative to the working directory. + +**REQ-CFG-088.** CI MUST verify the schema's presence in built distributions. CI MUST validate every documented example against it. CI MUST validate every controlled configuration fixture against it. + +**REQ-CFG-090.** JSON Schema cannot reliably express every relationship involving user-defined mapping keys, uniqueness across separate arrays, or references between distant parts of a document. After schema validation, the implementation MUST therefore apply the following semantic checks before reading either dataset: + +- **REQ-CFG-104.** every name in `fields.record_key` exists in `fields.definitions`; +- **REQ-CFG-129.** every name in `fields.in_scope` exists in `fields.definitions`, and every name in `fields.record_key` also occurs in `fields.in_scope`; +- **REQ-CFG-105.** every key field is required on both sides, non-nullable, scalar, and uses `typed_exact`; +- **REQ-CFG-106.** a field without `logical_type` uses `preserved_exact` and has no source normalisation, collection representation, value mapping, typed normalisation, or configured missing tokens; conversely, a field using `preserved_exact` omits `logical_type` and all of those processing properties; +- **REQ-CFG-107.** each comparator and normalisation operation is compatible with the field’s logical type and processing stage; +- **REQ-CFG-108.** source-value descriptors contain lexically valid values for their declared categories, and each side’s value mapping has unique `from` values; +- **REQ-CFG-144.** each `collection_representation` is used only with a collection logical type, and each side's element mapping has unique `from` values and contains no conflicting or unreachable entries; +- **REQ-CFG-127.** the `source_fields.reference` names are unique across canonical field definitions, and the `source_fields.query` names are independently unique across canonical field definitions; +- **REQ-CFG-136.** a custom configuration does not use the reserved automatic-mode identifier `adviso-compare:automatic-strict-exact`; + +**REQ-CFG-091.** A failure of any semantic check MUST be reported as an invalid comparison configuration with the relevant configuration path and violated rule. + +### 6.3 Record keys + +- **REQ-REC-001.** A record key MUST contain one or more named fields. +- **REQ-REC-002.** Composite-key field order MUST be stable and recorded. +- **REQ-REC-003.** Key fields MUST be present, valid under their declared field definitions, and non-null. +- **REQ-REC-004.** Key values MUST NOT undergo implicit numeric or boolean conversion. +- **REQ-REC-005.** Normalisation of key values MUST be explicitly configured. +- **REQ-REC-006.** Composite keys MUST be declared in a custom configuration. A non-`record_id` single-field key MAY be selected without a custom configuration only by the automatic discovery rules in Section 6.9. +- **REQ-REC-007.** Key names MUST NOT be inferred except by the automatic strict-exact mode defined in Section 6.9. +- **REQ-REC-008.** Command-line key overrides MUST NOT be supported in the first release. +- **REQ-REC-009.** The normalised key MUST uniquely identify one record within its dataset. +- **REQ-REC-010.** A missing, null, invalid, duplicate, undiscoverable, or ambiguous record key prevents construction of an unambiguous record model and MUST be an input error in every comparison. +- **REQ-REC-011.** The resulting execution error MUST identify the affected dataset when the defect is attributable to one side. An automatic discovery failure or ambiguity MUST state that both inputs were considered. +- **REQ-REC-012.** The resulting execution error MUST identify the selected key or candidate field names where they exist. A no-candidate error MUST state that no field satisfied the automatic key criteria. +- **REQ-REC-013.** Where available, the resulting execution error MUST identify the relevant source-record locations. +- **REQ-REC-014.** Duplicate records MUST never overwrite one another silently. +- **REQ-REC-015.** Findings and reports MUST retain enough information to distinguish every source record. + +### 6.4 Field declarations and preserved values + +**REQ-VAL-001.** The comparison engine MUST support preserved, untyped values. It MUST also support explicitly declared logical types. + +A type declaration is required for a field that uses typed parsing, normalisation, mapping, or a type-specific comparator. + +**REQ-VAL-002.** Every custom configuration MUST explicitly list the canonical fields selected for assessment in `fields.in_scope`. Defined fields omitted from that list and observed source fields not represented by a definition are outside scope and MUST be represented as exclusions in accordance with Section 7.5. + +**REQ-VAL-003.** Every declared field MUST define its canonical name, reference source name, query source name, required status on each side, null policy, and comparator. + +**REQ-VAL-004.** Every declared field MUST declare a logical type except where Section 6.2.6 permits omission for `preserved_exact`. + +Normalisation, value mapping, and review priority are optional. An omitted review priority resolves to `normal` in the effective configuration. The authoritative YAML representation and validation rules are defined in Section 6.2. + +### 6.5 Logical types and typed parsing + +**REQ-VAL-005.** The comparison engine MUST support custom configurations declaring scalar logical types `string`, `integer`, `decimal`, `boolean`, `date`, and `datetime`. + +**REQ-VAL-006.** The comparison engine MUST support typed `list`, `set`, and `multiset` collections. Collection fields MUST declare their element type. Null is a distinct value state governed by field policy, not a logical type. + +**REQ-VAL-007.** Type parsing MUST be field-specific and declared. + +**REQ-VAL-008.** The tool MUST NOT infer a logical type from observed text. + +**REQ-VAL-009.** Values of different logical types MUST NOT be implicitly equal. + +Intended equivalence between differing source representations requires both sides to be parsed as the same declared destination logical type, with an explicit value mapping where the source representation cannot be parsed directly. + +The accepted parser-native inputs for each declared logical type are fixed as follows: + +- **REQ-VAL-076.** A `string` field MUST accept only a parser-native string. No other parser-native category is converted to text implicitly. +- **REQ-VAL-077.** An `integer` field MUST accept a parser-native integer or a parser-native string satisfying the textual integer grammar in Section 6.5.2. A parser-native decimal MUST be rejected even when it represents a mathematically integral value. +- **REQ-VAL-078.** A `decimal` field MUST accept a parser-native integer, parser-native decimal, or parser-native string matching `[+-]?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?`. Conversion of a parser-native integer to a decimal is exact. Text such as `.5` and `1.` MUST be rejected. +- **REQ-VAL-079.** A `boolean` field MUST accept a parser-native boolean or a parser-native string accepted by Section 6.5.4. +- **REQ-VAL-080.** A `date` or `datetime` field MUST accept only a parser-native string, which MUST then satisfy the applicable grammar in Sections 6.5.5 and 6.5.6. +- **REQ-VAL-081.** A collection side using the default or explicitly declared `json_array` representation MUST accept a parser-native array from JSON or a parser-native string containing one valid JSON array from CSV or TSV. No other parser-native category is accepted for that representation. +- **REQ-VAL-082.** After a collection has been decoded and any configured element processing has been applied, each element MUST be parsed independently according to the declared scalar element type and the same source-category rules. +- **REQ-VAL-083.** A parser-native object MUST be invalid for every declared version 1 logical type. An untyped field using `preserved_exact` MAY still preserve and compare a parser-native object. +- **REQ-VAL-084.** A source representation not accepted directly by this matrix MUST require an explicit value mapping to an accepted representation. The implementation MUST NOT introduce any additional implicit conversion. +- **REQ-VAL-085.** Null recognition and null-policy handling MUST occur before typed parsing. Null is therefore not an accepted typed-parser input category. + +**REQ-VAL-010.** The original source value or lexical representation MUST remain available to the comparison engine. It MAY be included in evidence when required to explain a finding. + +**REQ-VAL-011.** An invalid typed value in a non-key field that remains attributable to an unambiguous record MUST be a contract finding. It MUST make that value `not_assessable`. It MUST NOT be an execution error. + +#### 6.5.1 String + +- **REQ-VAL-012.** A string MUST preserve its Unicode code points exactly by default. +- **REQ-VAL-013.** `typed_exact` equality MUST be code-point-for-code-point equality. +- **REQ-VAL-014.** Empty strings, whitespace-only strings, nulls, and absent fields MUST remain distinct. + +#### 6.5.2 Integer + +- **REQ-VAL-015.** Textual integers MUST use signed base-10 notation consisting of an optional `+` or `-` followed by one or more ASCII digits. +- **REQ-VAL-016.** Decimal points, exponent notation, booleans, and other characters MUST be invalid after source-text normalisation and mapping. +- **REQ-VAL-017.** Leading zeros MUST be accepted and have no numerical significance. Identifiers for which leading zeros are significant MUST be declared as strings. +- **REQ-VAL-018.** Integer representation MUST support arbitrary precision within documented resource limits. + +#### 6.5.3 Decimal + +- **REQ-VAL-019.** Decimals MUST be parsed and represented using decimal arithmetic without an intermediate binary floating-point conversion. +- **REQ-VAL-020.** Plain and scientific decimal notation MUST be accepted. +- **REQ-VAL-021.** Numerically equivalent finite representations such as `1.0`, `1.00`, and `1e0` MUST have the same canonical value. +- **REQ-VAL-022.** Parsing MUST preserve all supplied numerical precision. +- **REQ-VAL-023.** `NaN`, positive infinity, and negative infinity MUST be invalid. + +#### 6.5.4 Boolean + +- **REQ-VAL-024.** Native JSON booleans MUST be accepted. +- **REQ-VAL-025.** Textual boolean parsing MUST accept only lowercase `true` and `false`. +- **REQ-VAL-026.** Integers, uppercase boolean-like values, `yes`, `no`, `on`, `off`, and other representations MUST require an explicit value mapping. +- **REQ-VAL-027.** Booleans MUST NOT be treated as integers. + +#### 6.5.5 Date + +- **REQ-VAL-028.** Dates MUST use the ISO 8601 full-date form `YYYY-MM-DD`. +- **REQ-VAL-029.** Values MUST represent valid Gregorian calendar dates. +- **REQ-VAL-030.** Partial dates and locale-dependent forms MUST be invalid. +- **REQ-VAL-031.** The canonical value MUST be the represented calendar date. + +#### 6.5.6 Datetime + +- **REQ-VAL-032.** Datetimes MUST use an RFC 3339-compatible representation containing a full date, time, and `Z` or numeric UTC offset. +- **REQ-VAL-033.** Local datetimes without an offset MUST be invalid. +- **REQ-VAL-034.** Equivalent instants expressed with different offsets MUST have the same canonical value. +- **REQ-VAL-035.** Supplied fractional-second precision MUST remain available in the source lexical evidence. The canonical datetime representation MUST remove unnecessary trailing fractional-second zeros and omit a zero-valued fractional component. Any reduction that changes the represented instant, rather than only its redundant lexical form, MUST require explicit precision normalisation. +- **REQ-VAL-036.** Leap-second representations MUST be invalid in the first release. +- **REQ-VAL-092.** Datetime input MUST accept uppercase or lowercase `T` and + `Z`, but MUST NOT accept a space in place of `T`. Numeric offsets from + `+00:00` through `+23:59` and from `-00:01` through `-23:59` MUST be + accepted. `-00:00` MUST be invalid because it denotes an unknown local + offset rather than a known UTC instant. Canonical output continues to use + uppercase `T` and `Z`. + +#### 6.5.7 Collections + +- **REQ-VAL-037.** Every collection MUST declare its element logical type and element comparator. +- **REQ-VAL-038.** A `list` MUST preserve order and duplicates. +- **REQ-VAL-039.** A `set` MUST be unordered. +- **REQ-VAL-040.** A `set` MUST reject duplicate elements after typed parsing, using typed-exact canonical equality, rather than silently collapse them. Distinct source representations that parse to the same canonical value, such as textual integers `"01"` and `"1"`, are duplicates. +- **REQ-VAL-041.** A `multiset` MUST be unordered. +- **REQ-VAL-042.** A `multiset` MUST preserve element occurrence counts. +- **REQ-VAL-043.** A JSON collection using `json_array` representation MUST be a parser-native array. +- **REQ-VAL-044.** A CSV or TSV collection cell using `json_array` representation MUST use valid JSON-array syntax. +- **REQ-VAL-045.** Ordinary delimited text MUST NOT be inferred to be a collection. It is accepted only for a dataset side explicitly configured with `format: "delimited_text"`. +- **REQ-VAL-046.** Collection elements MUST be non-null in version 1. A parser-native null element MUST produce an `invalid_field_value` finding, prevent construction of a canonical collection value, and make that field comparison `not_assessable`. +- **REQ-VAL-087.** A `delimited_text` representation MUST accept only a parser-native string. The configured delimiter MUST be matched literally, not as a regular expression, and splitting MUST proceed deterministically from left to right using non-overlapping occurrences. +- **REQ-VAL-088.** CSV or TSV quoting and escaping MUST be resolved by the dataset parser before collection splitting. Delimited collection text has no additional quoting or escaping syntax in version 1; delimiter text within an element cannot be represented by that encoding. +- **REQ-VAL-089.** An empty delimited string MUST decode to an empty collection. Otherwise, leading, trailing, or consecutive delimiters MUST produce empty-string elements, which then undergo the configured element processing and typed parsing normally. Whitespace MUST NOT be trimmed implicitly. +- **REQ-VAL-090.** For each decoded collection element, configured `element_normalisation` operations MUST run in declared order before configured `element_mapping`; the resulting non-null value MUST then undergo scalar element-type parsing. No whole-field missing-token or null-policy rule is reapplied to individual elements. +- **REQ-VAL-091.** Element mappings MUST use parser-native category and value equality after element normalisation. A configured element mapping is closed: every non-null element must match an entry. Applied element mappings MUST remain identifiable through the saved comparison configuration and the source and canonical evidence required for a finding. +- Nested collections are outside the first-release scope. + +### 6.6 Null, blank, and absent values + +**REQ-VAL-047.** The comparison configuration MUST distinguish absent fields, explicit nulls, empty strings, whitespace-only strings, and configured missing tokens such as `NA`, `.`, or `null`. No two states are equivalent unless a field-specific policy declares them equivalent. Applied equivalence rules MUST be recorded. + +- **REQ-VAL-048.** Two explicit nulls MUST match only when the field permits null and its policy declares them equivalent. +- **REQ-VAL-049.** Null MUST NOT implicitly equal empty string, absent field, zero, boolean false, or a missing token. +- **REQ-VAL-050.** A missing token MUST become null only through an explicit field policy. +- **REQ-VAL-051.** Two absent required fields MUST produce contract findings. +- **REQ-VAL-052.** Two absent required fields MUST NOT constitute a value match. +- **REQ-VAL-053.** A null and non-null pair MUST be a value mismatch when both states are valid and comparable. +- **REQ-VAL-054.** A prohibited null MUST be a contract finding. +- **REQ-VAL-055.** A prohibited null MUST make the affected value `not_assessable` unless another treatment is explicitly configured. + +For a nullable configured field, null matches only null when `nulls_equal` is true and remains distinct from an absent field, an empty string, and every non-null value. + +The field-level null policy governs the collection value as a whole and does not permit null collection elements. Version 1 has no separate element-null policy. + +### 6.7 Mappings + +#### 6.7.1 Column mappings + +- **REQ-VAL-056.** Reference and query fields MAY map to a canonical field name. +- **REQ-VAL-057.** Column-name mappings MUST be one-to-one in version 1. One source field MUST NOT feed multiple canonical fields, and one canonical field MUST NOT receive multiple source fields from the same dataset side. +- **REQ-VAL-058.** Reuse of a source name by more than one canonical field on the same dataset side MUST invalidate the comparison configuration before either dataset is read. Reference and query namespaces are independent, so the same source name MAY occur once on each side. +- **REQ-VAL-059.** Unknown source fields MUST be excluded from assessment and summarised in the canonical result. They MUST NOT be inferred, mapped, or compared implicitly. +- **REQ-VAL-060.** Required mapped fields that are absent MUST be reported. +- **REQ-VAL-061.** All applied mappings MUST be identifiable in the evidence. + +#### 6.7.2 Value mappings + +Requirements in this subsection describe field-level `value_mapping` unless they explicitly mention element mapping. Collection-element mapping has the additional constraints and processing order in Sections 6.2.7 and 6.5.7. + +- **REQ-VAL-062.** A value mapping MUST operate on a preserved source value before typed parsing. +- **REQ-VAL-063.** The mapping output MUST be parsed as the declared destination logical type. +- **REQ-VAL-064.** A map MUST declare its source representation and destination logical type. +- **REQ-VAL-065.** Unknown source values MUST default to a contract finding, not pass through silently. +- **REQ-VAL-066.** Many-to-one mappings MUST be allowed only when intentionally declared. +- **REQ-VAL-067.** Mapping to null MUST be distinguished from a missing map entry. +- **REQ-VAL-068.** Values used in mappings MUST be represented using the typed source-value descriptor. The parser MUST NOT infer their intended category from YAML scalar syntax. +- **REQ-VAL-069.** Applied mappings MUST be identifiable in the evidence. + +**REQ-VAL-086.** Parser-native null and values converted to null by missing-token recognition MUST bypass value mapping and typed parsing. A non-null value explicitly mapped to null MUST bypass typed parsing after the null policy has been applied. Mapping from null is not supported. + +### 6.8 Normalisation and processing order + +**REQ-VAL-070.** Normalisation MUST be opt-in, field-specific, ordered deterministically, and recorded. Source-text normalisation is distinct from typed-value normalisation. + +**REQ-VAL-071.** Source-text normalisation MAY include Unicode normalisation, leading or trailing whitespace trimming, and case folding. Typed-value normalisation MAY include datetime offset normalisation and declared precision reduction. Deterministic serialization order for sets and multisets is canonical output handling, not a configured typed-normalisation operation. + +**REQ-VAL-072.** Typed processing MUST occur in this order: + +1. preserve the source value and representation; +2. if the current value is a parser-native string, apply the source-text normalisation declared for the applicable dataset side; otherwise pass it through unchanged; +3. recognise parser-native null or a configured non-null missing token; +4. if the value is null, apply the null policy and bypass value mapping and typed parsing; +5. for a non-null value, apply a declared source-value mapping and produce a `mapping_failure` finding if a configured mapping has no matching entry; +6. if the mapping output is null, apply the null policy and bypass typed parsing; +7. otherwise parse the declared logical type; for a collection, first decode the side's declared or default collection representation, then apply element normalisation, element mapping, and scalar element-type parsing to each element in that order; +8. apply declared typed-value normalisation; +9. compare canonical values. + +**REQ-VAL-073.** Column-name mapping MUST occur before field-value processing. + +**REQ-VAL-074.** A failure at any stage MUST identify the stage and attributable record and field. + +**REQ-VAL-075.** The source value MUST be included in the evidence package only when required to explain the failure. It MUST NOT be reproduced in routine logs, progress output, terminal diagnostics, or execution-error diagnostics. + +### 6.9 Automatic strict-exact mode + +**REQ-CFG-092.** If `--configuration` is omitted, the tool MUST construct an effective comparison configuration deterministically from the parsed inputs using this section. Supplying `--configuration` MUST disable automatic construction and select only the named custom configuration. + +**REQ-CFG-093.** Automatic strict-exact mode MUST discover source-field names dataset-wide using `REQ-CFG-116`. Field-name matching MUST be exact and case-sensitive. It MUST NOT apply aliases, approximate matching, or Unicode, case, or whitespace normalisation to field names. + +#### 6.9.1 Automatic record-key selection + +- **REQ-CFG-109.** If the exact field name `record_id` is observed on both dataset sides, it MUST be selected as the single-field record key. +- **REQ-CFG-110.** An automatically selected `record_id` MUST be present in every record, non-null, parser-native string-valued, and unique within each dataset. It MAY be selected from matching CSV or TSV headers when both datasets contain zero records. +- **REQ-CFG-111.** If an automatically selected `record_id` fails any key requirement, the run MUST produce an `input.invalid_record_key` execution error. The tool MUST NOT fall back to another candidate key. +- **REQ-CFG-112.** If `record_id` is not observed on both sides, an automatic key candidate MUST satisfy all of the following conditions: + 1. the exact same field name is observed on both sides; + 2. the field is present in every record on both sides; + 3. every value is a non-null parser-native string; + 4. values are unique within each dataset; and + 5. the reference and query value sets have at least one exactly equal value in common. +- **REQ-CFG-113.** Candidate assessment MUST use preserved source strings without conversion or normalisation. It MUST NOT rank candidates by column position, name patterns, preferred-name lists, value-set overlap, or any other heuristic. +- **REQ-CFG-114.** If exactly one field satisfies `REQ-CFG-112`, it MUST be selected as the single-field record key. If none qualifies, the run MUST produce an `input.invalid_record_key` execution error explaining that no automatic key could be established. If more than one qualifies, the same error code MUST identify the candidate field names and explain that key selection is ambiguous. Source key values MUST NOT be reproduced in the diagnostic. +- **REQ-CFG-115.** Automatic mode MUST NOT construct a composite key. A composite key requires a custom comparison configuration. + +#### 6.9.2 Generated field definitions + +- **REQ-CFG-130.** The generated effective configuration MUST use `schema_version: "1.0"`, `metadata.id: "adviso-compare:automatic-strict-exact"`, and `metadata.revision: "1.0"`. The identifier is reserved for tool-generated automatic configurations so that result consumers can identify the configuration's origin without an additional results property. +- **REQ-CFG-131.** The selected key field's canonical, reference source, and query source names MUST be identical. It MUST be declared as required and non-nullable on both sides, with logical type `string` and comparator `typed_exact`. +- **REQ-CFG-132.** Every non-key source-field name observed on both sides MUST become one generated canonical field whose canonical, reference source, and query source names are identical. It MUST be included in `fields.in_scope`, be optional on both sides, permit null with null equal to null, use `preserved_exact`, and have no logical type, missing tokens, mapping, normalisation, coercion, or tolerance. +- **REQ-CFG-133.** A source field observed on only one side MUST remain undefined in the generated configuration and MUST be represented by an `undeclared_field_excluded` entry under Section 9.1.3. It MUST NOT produce a finding or value opportunity. +- **REQ-CFG-134.** The generated `fields.record_key` MUST contain only the selected key. `fields.in_scope` and `fields.definitions` MUST contain the selected key and every same-name field observed on both sides, ordered by Unicode code point with the key first. +- **REQ-CFG-135.** The generated document MUST validate against the comparison-configuration schema and all applicable semantic configuration rules before the contract phase begins. It MUST be saved unchanged as `comparison-configuration.json` in the evidence package. + +**REQ-CFG-094.** Automatic mode MUST perform no type inference, implicit coercion, value mapping, normalisation, or tolerance. Non-key values compare according to `preserved_exact`, so lexically or scientifically equivalent representations can differ, particularly across input formats. The HTML report MUST identify automatic mode prominently, explain that only identically named fields observed on both sides were compared, and direct the user to review exclusions before interpreting the findings. A custom configuration is required whenever record identity, field correspondence, or value equivalence requires domain knowledge. + +## 7. Comparison behaviour + +### 7.1 Comparison phases + +**REQ-CMP-001.** Every comparison MUST perform all three phases in this order: + +1. **Contract:** assess fields, logical types, key definitions, nullability, mappings, and declared data-contract constraints. +2. **Records:** align valid record identities and assess matching, missing, and extra records. +3. **Values:** compare corresponding values using declared comparators. + +**REQ-CMP-002.** A finding or `not_assessable` item in an earlier phase MUST NOT automatically prevent later assessment. + +**REQ-CMP-003.** Later comparison MUST continue wherever its prerequisites remain satisfied. + +**REQ-CMP-004.** In-scope content that cannot be compared safely MUST be `not_assessable`. Content outside `fields.in_scope` MUST be `not_assessed`. + +**REQ-CMP-005.** A run MUST conceptually: + +1. validate a supplied custom comparison configuration, if any; +2. identify and hash inputs; +3. parse inputs without silent loss; +4. when no custom configuration was supplied, construct and validate the automatic effective comparison configuration; +5. perform the contract phase; +6. align and compare records; +7. compare values for safely aligned records; +8. determine whether every configured assessment was completed; +9. write results and provenance atomically. + +### 7.2 Contract comparison + +**REQ-CMP-006.** The contract phase MUST assess declared and observed fields from both directions for every record. It MUST distinguish: + +- **REQ-CMP-034.** field present and valid; +- **REQ-CMP-035.** required field missing from the reference or query; +- **REQ-CMP-036.** configured in-scope field or content excluded from assessment; +- **REQ-CMP-037.** invalid logical type, null state, mapping, or controlled value; +- **REQ-CMP-038.** field deliberately `not_assessed`; +- **REQ-CMP-039.** field `not_assessable` because a prerequisite failed. + +**REQ-CMP-007.** One record’s observed field set MUST NOT be assumed to represent every other record. + +**REQ-CMP-008.** Key presence, validity, and uniqueness MUST always be assessed because later interpretation depends on an unambiguous record model. + +**REQ-CMP-009.** For a zero-record dataset, contract requirements that can be evaluated from available structural information, such as CSV or TSV headers, MUST still be assessed. + +**REQ-CMP-010.** A per-record requirement with no applicable record opportunity MUST be treated as not applicable, not as satisfied, violated, `not_assessed`, or `not_assessable`. It MUST contribute no finding or value count. This rule does not suppress contract checks supported by available dataset-level structure. + +### 7.3 Records comparison + +**REQ-CMP-011.** For the union of normalised valid record keys, the records phase MUST classify each key as matching, missing from the query, or extra in the query. Duplicate or otherwise invalid keys are execution errors under Section 8.3, not ordinary record findings. + +**REQ-CMP-012.** Missing records MUST be reported individually. Extra records MUST be reported individually. Query-only records MUST NOT be ignored. Missing or extra records MUST NOT prevent value comparison of the safely aligned intersection. + +### 7.4 Values comparison and comparators + +**REQ-CMP-013.** The values phase MUST compare every valid non-key field listed in `fields.in_scope` in safely aligned records. + +**REQ-CMP-014.** A value whose contract or alignment prerequisite failed MUST be `not_assessable`. Other values MUST continue to be compared. + +**REQ-CMP-015.** The first release MUST support the following deterministic comparators with stable identifiers. + +#### 7.4.1 `preserved_exact` + +Values match according to the parser-native value model and equality rules in Section 5.6. No logical type, additional missing-token recognition, inference, coercion, mapping, normalisation, or tolerance is applied. Textual `"1"`, integer `1`, decimal `1.0`, and boolean `true` are distinct. + +#### 7.4.2 `typed_exact` + +Values match only when both are present, valid under their field policies, have the same declared logical type, and have equal canonical values. Null handling follows Section 6.6. Cross-type equality is not implicit. + +#### 7.4.3 `normalised_string` + +**REQ-CMP-016.** Only configured string normalisations are applied in their declared order. Equality is exact code-point equality after transformation. Applied transformations MUST be identifiable in the evidence. + +#### 7.4.4 `numeric_exact` + +**REQ-CMP-017.** Integer or decimal comparison MUST use canonical arbitrary-precision values. Integer and decimal remain different logical types. Differing source representations are comparable only when both are explicitly parsed as the same declared logical type, using a mapping where required. + +#### 7.4.5 `numeric_tolerance` + +```text +difference = abs(reference - query) +``` + +- **REQ-CMP-018.** Exactly one of `absolute_tolerance` or `relative_tolerance` MUST be specified. +- With `absolute_tolerance`, values match when `difference <= absolute_tolerance`. +- With `relative_tolerance`, values match when `difference <= relative_tolerance * abs(reference)`. A relative tolerance is expressed as a fraction; for example, `"0.05"` means five percent. +- **REQ-CMP-019.** Tolerances MUST be non-negative finite decimals. +- **REQ-CMP-020.** The boundary MUST be inclusive. +- **REQ-CMP-021.** Relative tolerance MUST be calculated using the magnitude of the reference value: `relative_tolerance × abs(reference)`. The reference and query therefore have distinct roles in this calculation. The same tolerance applies to query values above and below the reference. +- **REQ-CMP-022.** When the reference value is zero, a relative tolerance permits only an exactly equal query value. An absolute tolerance MUST be used when non-zero differences around a zero reference are intended to match. +- **REQ-CMP-023.** Rounding or significant-figure normalisation MUST occur explicitly before comparison. + +#### 7.4.6 `date_exact` and `datetime_exact` + +**REQ-CMP-024.** Dates match when their canonical calendar dates are equal. Datetimes match when they represent the same instant after UTC-offset normalisation. Any precision reduction MUST be explicitly configured before comparison. + +#### 7.4.7 `list_exact`, `set_exact`, and `multiset_exact` + +- **REQ-CMP-025.** Lists use ordered element-by-element comparison and their lengths MUST match. +- Sets use order-independent comparison of unique elements; duplicate source elements are invalid under Section 6.5.7. +- Multisets use order-independent comparison that preserves occurrence counts. +- **REQ-CMP-040.** List elements use their declared element comparator positionally: element `n` in the reference is compared only with element `n` in the query. Numeric tolerance is therefore unambiguous for lists. +- **REQ-CMP-041.** Set and multiset elements use typed-exact equality. Version 1 MUST NOT perform tolerance-based or other fuzzy matching within an unordered collection. + +### 7.5 Completeness, subsets, and determinism + +- **REQ-CMP-026.** Findings MUST NOT terminate a normal run. +- **REQ-CMP-027.** All assessable differences MUST be collected. +- **REQ-CMP-028.** A malformed record that prevents a complete and unambiguous record model MUST be an input error. +- **REQ-CMP-029.** A malformed record MUST NOT disappear silently. +- **REQ-CMP-030.** Key fields MUST always be processed. +- **REQ-CMP-031.** Out-of-scope content MUST be represented by exclusion summaries rather than individual findings or per-record exclusions. The canonical report MUST distinguish fields deliberately omitted from `fields.in_scope` from observed source fields not represented in `fields.definitions`. +- **REQ-CMP-032.** Record order MUST NOT affect the comparison outcome defined in Section 9.1. Input digests, source locations, messages containing those locations, and report-local finding IDs MAY differ as permitted by the provenance and ordering rules. +- **REQ-CMP-033.** Output ordering MUST be deterministic and independent of hash-map ordering and locale. + +## 8. Findings and run status + +### 8.1 Finding structure + +**REQ-FND-001.** Every finding MUST follow the structured representation in Section 9.1.2 and the normative results schema. + +**REQ-FND-002.** Every finding MUST contain a stable finding code, finding classification, deterministic report-local ID, phase, affected side, and human-readable message. + +**REQ-FND-003.** Record identity, source locations, canonical or source field name, review priority, and value evidence MUST be present exactly where required by the finding code and data-minimisation rules. + +**REQ-FND-004.** Human-readable messages MUST NOT be the sole machine-readable representation of a finding. + +**REQ-FND-005.** Successful field matches MUST be represented in summary counts. Successful record matches MUST be represented in summary counts. Successful matches MUST NOT produce individual findings. + +### 8.2 Finding codes and classifications + +**REQ-FND-006.** Stable finding codes MUST exist for at least: + +- **REQ-FND-008.** missing record; +- **REQ-FND-009.** extra record; +- **REQ-FND-010.** missing required field; +- **REQ-FND-012.** type mismatch: the parser-native category of a non-null source value is not accepted by the field's declared logical type under the matrix in Section 6.5; +- **REQ-FND-013.** invalid field value: the parser-native category is accepted by the declared logical type, but the value fails its lexical, domain, collection-content, or other field-level validity rule; +- **REQ-FND-014.** null-policy violation; +- **REQ-FND-015.** mapping failure; +- **REQ-FND-016.** value mismatch: both values are valid and assessable, but the selected comparator determines that they differ; + +**REQ-FND-023.** Every finding MUST have exactly one of two classifications. Classification expresses the meaning of a finding, while phase records where in processing it was detected; neither replaces the other. + +- **REQ-FND-024.** `comparison_difference` means that translation succeeded sufficiently to compare the relevant records or values and a difference remained. `missing_record`, `extra_record`, and `value_mismatch` MUST have this classification. +- **REQ-FND-025.** `assessment_issue` means that the declared translation or assessment could not be applied cleanly to some input content. `missing_required_field`, `type_mismatch`, `invalid_field_value`, `null_policy_violation`, and `mapping_failure` MUST have this classification. + +Finding classification does not assert scientific or clinical significance. In particular, an assessment issue such as an unrecognised mapped value may be important to investigate, but the tool cannot report it as a post-translation difference because translation did not succeed. + +**REQ-FND-018.** `type_mismatch`, `invalid_field_value`, and `value_mismatch` are mutually exclusive for one affected value or value opportunity. A parser-native category difference under `preserved_exact` MUST be a `value_mismatch`, not a `type_mismatch`, because no logical type contract has been declared. + +**REQ-FND-019.** A record-specific missing-required-field, type-mismatch, invalid-field-value, null-policy-violation, or mapping-failure finding MUST describe one record, one canonical field, and one affected dataset side. If reference and query independently violate the same field rule, the tool MUST emit two findings, one with `affected_side: reference` and one with `affected_side: query`. It MUST NOT combine the independent violations into one `both` finding. The dataset-level zero-record missing-field case is the explicit exception defined by `REQ-FND-022`. + +**REQ-FND-020.** A value-mismatch finding MUST describe one comparison between two individually valid, assessable values and MUST use `affected_side: both`. Missing-record and extra-record findings remain one finding per affected record key. + +**REQ-FND-022.** If a zero-record CSV or TSV header omits a declared source column that is required on that dataset side, the tool MUST emit one dataset-level `missing_required_field` finding for that canonical field and side. It contains the canonical field and review priority but no record identity, source location, or value evidence. An empty JSON array cannot produce this finding because it exposes no field structure. + +**REQ-FND-017.** `not_assessable` MUST be a value-opportunity classification, not a finding code. Every not-assessable opportunity MUST be explained by its applicable causal finding, such as `missing_required_field`, `type_mismatch`, `invalid_field_value`, `null_policy_violation`, or `mapping_failure`. The tool MUST NOT emit an additional finding merely to repeat that the affected opportunity is not assessable. + +**REQ-FND-007.** Execution errors MUST NOT be represented as findings or assigned finding codes. In particular, invalid invocation or configuration, malformed input structure, invalid record keys, resource failure, I/O failure, and internal failure are execution errors governed by Section 8.3. + +### 8.3 Run status + +**REQ-RUN-001.** Run status MUST be one of: + +- **REQ-RUN-015.** `complete`: every configured assessment was performed wherever the configuration and inputs made it applicable; +- **REQ-RUN-016.** `incomplete`: the inputs and record model remain sufficiently trustworthy for a useful comparison, but one or more configured assessments could not be completed safely because a comparison prerequisite was not satisfied; +- **REQ-RUN-017.** `error`: no trustworthy comparison result could be produced because of an invalid invocation or comparison configuration, malformed or unreadable input syntax or structure, a missing, null, invalid, or duplicate record key, an incomplete or ambiguous record model, an enforced resource limit, resource exhaustion, an input/output failure, or an unexpected internal failure. + +**REQ-RUN-002.** Findings, whether classified as `comparison_difference` or `assessment_issue`, MUST NOT by themselves change a run from `complete` to `incomplete` or `error`. A finding may identify a not-assessable opportunity that independently makes the run incomplete under `REQ-RUN-003`. Run status describes completeness and operational validity, not acceptability. + +**REQ-RUN-003.** Any configured content classified as `not_assessable` MUST make the run `incomplete`. + +**REQ-RUN-004.** Deliberately `not_assessed` content MUST NOT make the run `incomplete`. + +**REQ-RUN-005.** An incomplete report MUST identify the affected content. It MUST identify why the comparison prerequisite was not satisfied. + +**REQ-RUN-006.** Content that is parseable and attributable to an unambiguous record but violates the declared data contract MUST be recorded as an `assessment_issue` finding rather than an execution error. + +**REQ-RUN-007.** Comparisons that remain assessable MUST continue. + +**REQ-RUN-008.** An errored run MUST write a concise diagnostic to standard error and MUST NOT publish a new evidence package or filesystem report. Existing output-parent contents MUST remain intact. An empty output parent created during publication preparation MAY remain after an error, subject to Section 9.3. + +**REQ-RUN-009.** The diagnostic MUST contain a stable execution-error code and category, a concise actionable message, and sufficient non-sensitive context to locate the cause. + +**REQ-RUN-010.** The diagnostic MUST NOT contain findings, finding codes, comparison summary metrics, phase statuses, record identifiers, or source values. + +**REQ-RUN-024.** Version 1 execution errors MUST use exactly one of the following category and code combinations: + +| Category | Code | Meaning | +| --- | --- | --- | +| `invocation` | `invalid_arguments` | Command-line arguments are missing, invalid, or mutually incompatible | +| `configuration` | `unreadable` | The selected comparison configuration cannot be read | +| `configuration` | `invalid_syntax` | The comparison configuration is not permitted YAML syntax | +| `configuration` | `schema_violation` | The parsed comparison configuration does not satisfy its JSON Schema | +| `configuration` | `semantic_violation` | The configuration is schema-valid but violates a semantic configuration rule | +| `configuration` | `unsupported_version` | The configuration names an unsupported schema version | +| `input` | `unreadable` | A reference or query input cannot be read | +| `input` | `unsupported_format` | An input has a missing, unknown, or ambiguous filename extension | +| `input` | `invalid_encoding` | An input is not valid UTF-8 | +| `input` | `invalid_syntax` | Input text is malformed for the format selected by its extension | +| `input` | `invalid_structure` | Parsed input does not satisfy the required dataset or record structure | +| `input` | `invalid_record_key` | A record key is missing, null, invalid, duplicated, undiscoverable, ambiguous, or otherwise unable to form an unambiguous record model | +| `resource` | `limit_exceeded` | A documented implementation safeguard stops assessment | +| `resource` | `exhausted` | An unplanned resource exhaustion prevents completion | +| `output` | `invalid_destination` | The selected output parent is ineligible or the run-directory path is already occupied | +| `output` | `write_failed` | The evidence package cannot be written or published | +| `internal` | `unexpected` | An unexpected implementation failure occurs, including generated-result self-validation failure | + +**REQ-RUN-025.** The execution-error code MUST be the dotted combination `.`. The first diagnostic line MUST have the exact form `ERROR [.]: `. The message MUST be non-empty and MUST NOT contain a line break. Additional non-sensitive context MAY follow on subsequent lines. + +**REQ-RUN-026.** Every execution-error code except `internal.unexpected` MUST return exit code 2. `internal.unexpected` MUST return exit code 3. + +**REQ-RUN-011.** Findings accumulated internally before the error occurred MUST NOT be published as a partial comparison result. + +**REQ-RUN-012.** Each phase MUST record whether it was `complete` or `incomplete`. + +Overall status is `complete` only when all three phases are complete. + +**REQ-RUN-018.** The contract phase MUST be `complete` when every applicable contract check was performed. Contract findings, including missing-field, type, invalid-value, null-policy, and mapping findings, MUST NOT by themselves make the contract phase incomplete. + +**REQ-RUN-019.** The records phase MUST be `complete` when valid record keys were constructed and every record was aligned and classified. Missing-record and extra-record findings MUST NOT make the records phase incomplete. A key or record-model failure that prevents this assessment is an execution error and produces no comparison phase statuses. + +**REQ-RUN-020.** The values phase MUST be `complete` when every applicable in-scope value opportunity was compared. It MUST be `incomplete` when at least one such opportunity is `not_assessable`. + +**REQ-RUN-021.** A finding MUST NOT by itself make a phase incomplete. A phase is incomplete only when an intended assessment within that phase could not be performed safely. + +**REQ-RUN-022.** Content classified as `not_assessed` because it is outside `fields.in_scope` MUST NOT make any phase incomplete. + +**REQ-RUN-023.** Overall run status MUST be `complete` if and only if the contract, records, and values phases are all `complete`; otherwise a non-error comparison run MUST be `incomplete`. + +**REQ-RUN-013.** The tool MUST report raw findings and metrics without applying acceptance thresholds. It MUST NOT produce a pass/fail verdict. + +### 8.4 Laboratory decision + +The run status and reported differences do not constitute a laboratory validation, approval, or acceptance decision. Any acceptance criteria and their application belong to a separately governed process outside the tool. + +**REQ-RUN-014.** Reports MUST label these concepts separately. Reports MUST NOT describe the output as “ISO 15189 compliant”, “clinically validated”, or equivalent. + +## 9. Output and evidence + +**REQ-OUT-001.** A non-error comparison, whether `complete` or `incomplete`, MUST publish one new evidence-package directory as an immediate child of the output parent selected by `--output`. + +**REQ-OUT-002.** The evidence package MUST contain exactly three regular files: the canonical JSON result, the saved comparison configuration, and the HTML report. Version 1 MUST NOT produce any additional report or findings-export format. + +**REQ-OUT-115.** The canonical JSON result MUST be named `comparison-results.json`, the saved comparison configuration MUST be named `comparison-configuration.json`, and the HTML report MUST be named `comparison-report.html`. These are fixed sibling basenames within the run directory. + +No separate package manifest is required in version 1; `comparison-results.json` contains the comparison and provenance metadata and the byte-digest link to the saved configuration. + +**REQ-OUT-003.** Package member names MUST be stable and documented. Package layout MUST be stable and documented. + +**REQ-OUT-129.** The run-directory name MUST be `YYYYMMDDTHHMMSSZ-`. The timestamp MUST be derived from the validated result's `run.completed_at` by removing its date and time separators, retaining UTC `T` and `Z` and whole-second precision. `` MUST be the complete canonical lowercase hyphenated UUID from that result's `run.id`. Naming MUST NOT use a separate clock reading or identifier. + +The evidence-package layout is: + +```text +OUTPUT/ +└── YYYYMMDDTHHMMSSZ-/ + ├── comparison-results.json + ├── comparison-configuration.json + └── comparison-report.html +``` + +### 9.1 Machine-readable output + +**REQ-OUT-004.** JSON MUST be the canonical output format. Its normative JSON Schema Draft 2020-12 definition is [`src/adviso_compare/schemas/comparison-results-v1.0.schema.json`](../src/adviso_compare/schemas/comparison-results-v1.0.schema.json). + +**REQ-OUT-125.** `comparison-results.json` MUST be serialized as RFC 8259 JSON encoded as UTF-8 without a byte-order mark, using two-space indentation, LF line endings, and exactly one final newline. Non-ASCII characters MUST be emitted directly rather than escaped unless escaping is required by JSON syntax. Members of fixed-schema objects MUST be emitted in their documented schema order; members of dynamically named objects MUST be emitted in Unicode code-point order. + +**REQ-OUT-133.** `comparison-configuration.json` MUST use the same encoding, indentation, line endings, final newline, and direct non-ASCII rendering as `REQ-OUT-125`. Fixed-schema objects MUST use the corresponding comparison-configuration schema's property declaration order; dynamically named members MUST use Unicode code-point order. Lists MUST preserve their effective document order. Every permitted property MUST be preserved without adding omitted defaults. Identical effective configuration documents MUST produce identical saved bytes. Run identifiers and completion times MUST NOT be added to the saved configuration. + +**REQ-OUT-112.** The results schema MUST use `https://adviso-project.github.io/validation_toolkit/schemas/comparison-results-v1.0.schema.json` as its canonical `$id`. + +**REQ-OUT-005.** The standalone results-schema file MUST be version controlled and included as package data in `adviso_compare.schemas`. It MUST support structural validation without loading or registering the comparison-configuration schema and MUST NOT reference that schema. + +The result-schema version and comparison-configuration-schema version are independent. + +**REQ-OUT-006.** The canonical result MUST contain exactly these top-level properties: + +- **REQ-OUT-050.** `schema_version`, the string `"1.0"` identifying the results format; +- **REQ-OUT-051.** `run`; +- **REQ-OUT-052.** `phases`; +- **REQ-OUT-053.** `software`; +- **REQ-OUT-054.** `runtime`; +- **REQ-OUT-055.** `inputs`; +- **REQ-OUT-056.** `record_key_fields`; +- **REQ-OUT-057.** `comparison_configuration_digest`; +- **REQ-OUT-058.** `summary`; +- **REQ-OUT-059.** `exclusions`; +- **REQ-OUT-060.** `findings`. + +Every property is required, including empty `exclusions` and `findings` arrays. + +**REQ-OUT-007.** Unknown properties MUST be rejected at every defined object level. + +**REQ-OUT-008.** The schema accepts only non-error results with run status `complete` or `incomplete`. An execution-error diagnostic under Section 8.3 is not a canonical comparison result and MUST NOT validate against this schema. + +**REQ-OUT-009.** The `run` object MUST contain `id`, `status`, and `completed_at`. `id` MUST be a randomly generated UUID version 4 in canonical lowercase hyphenated form. + +**REQ-OUT-010.** `completed_at` MUST be an RFC 3339 UTC timestamp using `Z` and whole-second precision, in the exact form `YYYY-MM-DDTHH:MM:SSZ`. + +**REQ-OUT-011.** Start time MUST NOT be included. Elapsed duration MUST NOT be included. + +**REQ-OUT-012.** Run ID and completion time are deliberately variable metadata and MUST be excluded from repeat-determinism comparisons. + +**REQ-OUT-095.** For determinism requirements, the comparison outcome consists of run and phase statuses; summary counts; exclusions considered without input occurrence order; and each finding's classification, code, phase, affected side, record identity, canonical or source field identity, review priority, and value evidence. It excludes run ID, completion time, software-runtime provenance, input byte provenance, source locations, human-readable messages that reproduce variable locations, and report-local finding IDs. + +**REQ-OUT-096.** Given the same exact input bytes, input basenames, configuration selection, software version, and runtime identity, all canonical result content other than `run.id` and `run.completed_at` MUST be identical. Repeated automatic-mode runs therefore MUST generate byte-identical effective configuration documents. + +**REQ-OUT-097.** Changing only input record order or accepted LF/CRLF line endings MUST leave the comparison outcome unchanged. Exact-byte input size and digest, source locations, location-dependent messages, and report-local finding IDs MAY change. The result for each particular ordered byte input MUST still satisfy all deterministic ordering rules. + +**REQ-OUT-098.** Across supported Python versions and operating systems, the comparison outcome MUST remain invariant for identical inputs and configuration selection. Recorded runtime provenance MAY differ. Release testing MUST verify that Unicode-data differences do not silently change comparison outcomes across the supported matrix. + +**REQ-OUT-013.** The `phases` object MUST contain `contract`, `records`, and `values`, each with status `complete` or `incomplete`. + +**REQ-OUT-014.** Overall run status MUST be `complete` if and only if all three phases are complete. + +**REQ-OUT-015.** The `software` object MUST identify `adviso-compare` and its version. A build identifier MAY be included when available. + +**REQ-OUT-016.** The `runtime` object MUST record Python version, a normalized non-identifying platform identifier, and the Unicode-data version. + +**REQ-OUT-121.** `runtime.python` MUST have the form `-..`, using a lowercase implementation name and the full runtime version, for example `cpython-3.12.7`. A prerelease suffix MAY follow the micro version when applicable. + +**REQ-OUT-122.** `runtime.platform` MUST have the form `-` using lowercase normalized names, for example `linux-x86_64`, `linux-aarch64`, `windows-x86_64`, or `macos-aarch64`. `amd64` MUST be normalized to `x86_64`, and `arm64` MUST be normalized to `aarch64`. The supported release matrix determines the permitted combinations. + +**REQ-OUT-123.** `runtime.platform` MUST NOT include a distribution name, distribution version, kernel version, hostname, or other host-specific detail. + +**REQ-OUT-124.** `runtime.unicode_version` MUST be the exact runtime Unicode database version in `..` form. + +**REQ-OUT-017.** Hostname, username, environment variables, working directory, absolute paths, raw command line, and a full dependency inventory MUST NOT be included. + +**REQ-OUT-018.** Each input object MUST contain its automatically captured basename, selected format, UTF-8 encoding, byte size, and SHA-256 digest of the exact input bytes. + +**REQ-OUT-019.** Absolute paths MUST NOT be included. + +Basenames form part of the potentially sensitive evidence covered by Section 11. + +**REQ-OUT-020.** V1 MUST use one fixed documented interpretation for CSV. It MUST use one fixed documented interpretation for TSV. Because format uniquely determines that interpretation, no dialect identifier appears in the result. + +**REQ-OUT-021.** `record_key_fields` MUST declare the ordered source key-field names for the reference and query and the ordered canonical key-field names. Findings identify records through corresponding ordered arrays of source lexical values and canonical textual values. Canonical key components MUST use the scalar rendering rules in `REQ-OUT-029`. A single-field key is represented by a one-element array. Each identity array MUST have the same length as its corresponding field-name array. The reference or query identity is JSON null when that record is absent on that side; the canonical identity is always present. + +**REQ-OUT-022.** `comparison_configuration_digest` MUST be an object containing exactly `algorithm` and `value`, in that canonical order. `algorithm` MUST be `"sha256"`; `value` MUST be 64 lowercase hexadecimal characters representing the SHA-256 digest of the exact published `comparison-configuration.json` bytes, including the final newline. The tool MUST compute the digest from the same byte sequence it publishes, not from source YAML bytes or a later reserialization. + +**REQ-OUT-023.** `comparison-configuration.json` MUST contain the complete validated JSON-compatible effective comparison configuration, including its metadata and explicit declarations, with omitted optional properties left absent. It MUST NOT contain expanded internal defaults. In automatic mode, it MUST contain the generated document defined in Section 6.9. It MUST validate independently against the comparison-configuration schema selected by its own root `schema_version` and satisfy the applicable semantic configuration rules. + +**REQ-OUT-113.** Both JSON documents MUST use root `schema_version` to identify their own format version. Schema selection MUST use document family and version through a trusted local lookup of packaged schemas. The fixed filenames identify the document families. Version 1 supports results schema `1.0` and comparison-configuration schema `1.0`. The results schema MUST NOT constrain the configuration schema version. Supporting a configuration schema version MUST NOT by itself require a results-schema revision when the results structure and meaning remain compatible; software MUST still check that it supports the selected combination. + +The results JSON records only the configuration digest; the fixed configuration filename, configuration schema version, configuration identity, and configuration revision MUST NOT be repeated as configuration-reference properties. Consumers obtain configuration metadata from the saved document. No command-invocation object is included in version 1. The digest establishes content linkage, not authenticity or laboratory approval. + +#### 9.1.1 Value evidence + +**REQ-OUT-026.** When a finding includes field evidence, `values.reference` and `values.query` MUST each state whether the field is `present` or `absent`. An absent side has no source or canonical value. An explicit null is present and is represented explicitly rather than as absence. + +**REQ-OUT-027.** Parser-native source values MUST use typed objects. Strings retain their text; integer and decimal values retain their source lexical text; booleans use JSON booleans; null has no `value`; arrays contain recursively typed source values; and objects map member names to recursively typed source values. + +**REQ-OUT-028.** Object member order has no semantic significance. Object members MUST be serialized in Unicode code-point order. + +**REQ-OUT-029.** Canonical scalar values MUST contain their logical type and one uniquely rendered value: + +- **REQ-OUT-089.** A canonical integer MUST use ordinary base-10 text with no leading plus sign or unnecessary leading zeros; zero is `"0"`. +- **REQ-OUT-090.** A canonical decimal zero, including negative zero, MUST be `"0"`. Every non-zero canonical decimal MUST use normalized scientific form with exactly one non-zero digit before the optional decimal point, no trailing fractional zeros, lowercase `e`, no `e0`, no positive exponent sign, and no exponent leading zeros. For example, `1.00`, `1000`, `12.30`, `0.0010`, and `-0.0` become `"1"`, `"1e3"`, `"1.23e1"`, `"1e-3"`, and `"0"` respectively. +- **REQ-OUT-091.** A canonical date MUST use `YYYY-MM-DD`. +- **REQ-OUT-092.** A canonical datetime MUST be converted to UTC, use uppercase `Z`, remove unnecessary trailing fractional-second zeros, and omit a zero-valued fractional component. +- **REQ-OUT-093.** A canonical boolean MUST use a JSON boolean. A canonical string MUST contain its Unicode text after configured processing without any additional transformation. +- **REQ-OUT-094.** Canonical collections MUST contain the collection logical type, scalar element type, and an array of compact canonical element values. Lists preserve order. Sets and multisets MUST be serialized in locale-independent Unicode code-point order of the canonical element strings; multiset duplicates remain adjacent. Null uses the declared logical type with a JSON null value. A `preserved_exact` field has no typed canonical value. + +**REQ-OUT-030.** Values MUST be included only as follows: + +- **REQ-OUT-061.** missing and extra record findings contain no field values; +- **REQ-OUT-062.** record-specific missing-required-field findings contain presence states but do not reproduce the present side's value; the dataset-level zero-record form contains no value evidence; +- **REQ-OUT-064.** type-mismatch findings contain source values for affected sides and canonical values only where parsing succeeded; +- **REQ-OUT-065.** invalid-field-value and mapping-failure findings contain the affected source value and no failed canonical value; +- **REQ-OUT-066.** A null-policy-violation finding contains the affected + parser-native source null. For a field with a declared logical type, it also + contains that type's canonical null representation. A `preserved_exact` + field has no logical type and therefore contains no canonical value. +- **REQ-OUT-067.** value-mismatch findings MUST state the presence state of both sides. Each present side MUST contain its source value and, for a declared typed field, its canonical value. An absent side contains neither value. A mismatch of two present untyped values contains no typed canonical values. +- **REQ-OUT-068.** A causal finding for a not-assessable value opportunity MUST contain only the values permitted for that finding code and necessary to explain the failed prerequisite. It MUST NOT contain separate or duplicated not-assessable evidence. + +**REQ-OUT-031.** Implementations MUST NOT add additional source values merely for convenience. + +#### 9.1.2 Findings + +**REQ-OUT-032.** Every finding MUST contain a deterministic report-local ID, finding classification, finding code, phase, human-readable English message, and affected side. + +**REQ-OUT-033.** A message is presentation text derived deterministically from structured properties. It MUST NOT add facts absent from those properties, and every machine-significant fact in a message MUST also be represented by a structured property or finding code. + +Specification-requirement identifiers are not included in version 1. Finding classification is included explicitly and MUST agree with the finding code according to Section 8.2. + +The closed version 1 finding-code vocabulary is: + +- `missing_record`; +- `extra_record`; +- `missing_required_field`; +- `type_mismatch`; +- `invalid_field_value`; +- `null_policy_violation`; +- `mapping_failure`; +- `value_mismatch`. + +**REQ-OUT-034.** `affected_side` MUST be `reference`, `query`, or `both` as required by the finding code. A finding attributable to a declared canonical field MUST contain that field name and its resolved review priority. Record-specific findings MUST contain record identity and source locations; dataset-level missing-required-field findings omit record identity and source locations. + +**REQ-OUT-117.** For CSV and TSV, every record-specific source location MUST contain the one-based data-record number, excluding the header, and the one-based physical line number on which the record begins. Embedded newlines in a quoted field do not change that record's starting line. A location for a present field MUST also contain its source field name; a record-level location or a location for an absent field MUST omit the field name. + +**REQ-OUT-118.** For JSON, a record-level source location MUST contain the RFC 6901 JSON Pointer to the array element, such as `/3`. A location for a present field MUST contain the full pointer to that member, such as `/3/result`, with `~` and `/` escaped as `~0` and `~1`. A location for an absent field MUST identify its containing record because the absent member has no source location. + +**REQ-OUT-119.** Reference and query locations MUST be represented independently. A location MUST be null when the corresponding record does not exist. If the record exists but the relevant field is absent, the location MUST identify the containing record as specified above. + +**REQ-OUT-035.** Findings MUST be sorted by this complete, locale-independent order: + +1. classification: `comparison_difference`, `assessment_issue`; +2. phase: `contract`, `records`, `values`; +3. dataset-level findings before record-specific findings; +4. canonical record identity, compared component-by-component as Unicode strings; +5. canonical field name, with no field sorting component for record findings; +6. finding code in the fixed vocabulary order listed in Section 9.1.2; +7. affected side: `reference`, `query`, `both`; +8. source locations, comparing reference before query, with a null location before a present location; tabular locations compare by record number, physical line number, and field name, while JSON locations compare by JSON Pointer using Unicode code-point order; and +9. canonical JSON serialization of all remaining structured finding properties except `id` and `message`. + +**REQ-OUT-099.** Two candidate findings identical under the final ordering key represent the same finding and MUST be coalesced rather than emitted twice. IDs `F000001`, `F000002`, and so on MUST be assigned only after coalescence and sorting. IDs are stable within one result but are not persistent identifiers across materially different comparisons. + +**REQ-OUT-036.** Comparator parameters, mappings, and normalisation declarations MUST NOT be repeated in findings. Consumers and the HTML renderer obtain them from the saved comparison configuration using the canonical field name. Source and canonical values show their effect for the affected record. + +#### 9.1.3 Summary and exclusions + +**REQ-OUT-037.** The summary MUST contain complete fixed-shape counts, including zero-valued entries. Record counts comprise reference records, query records, matched records, missing records, and extra records. Value counts comprise matched, mismatched, and not-assessable in-scope non-key value opportunities. Finding counts comprise total findings, both finding classifications, every version 1 finding code, and review priorities `low`, `normal`, `high`, and `unassigned`. + +**REQ-OUT-038.** Record counts MUST reconcile as follows: + +```text +reference = matched + missing +query = matched + extra +``` + +**REQ-OUT-039.** Every in-scope non-key value opportunity MUST be classified exactly once as matched, mismatched, or not assessable. Record-key fields are not compared or counted again in the values phase. For declared non-key fields in aligned records: + +- **REQ-OUT-069.** both valid present values are compared normally; +- **REQ-OUT-070.** two absent optional fields match; +- **REQ-OUT-071.** one absent optional field and one present field mismatch; +- **REQ-OUT-072.** absence on a required side is not assessable; +- **REQ-OUT-073.** an invalid or prohibited value that prevents comparison is not assessable. + +Fields absent from `fields.in_scope`, including observed source fields not represented by any field definition, do not contribute value opportunities. + +**REQ-OUT-040.** `summary.findings.total` MUST equal the number of emitted findings. Counts by classification, by code, and by review priority MUST each sum to the total. Record findings, which are not attributable to a declared non-key field, count as `unassigned` review priority. + +**REQ-OUT-041.** `exclusions` MUST always be an array containing exactly these two forms: + +- one `configured_field_excluded` entry for every canonical field in `fields.definitions` but absent from `fields.in_scope`; each such entry contains only `code` and `canonical_field`; +- one `undeclared_field_excluded` entry for every observed source field not represented by a field definition on that dataset side; each such entry contains `code`, `side`, `source_field`, and the number of records containing the field. + +Configured-field exclusions MUST be ordered first by `canonical_field` using Unicode code-point order. Undeclared-field exclusions follow, ordered first by side (`reference`, then `query`) and then by `source_field` using Unicode code-point order. Exclusions are not findings, do not have review priorities, and do not contribute to value counts. A source field known only from a zero-record CSV or TSV header has record count zero. + +#### 9.1.4 Structural and semantic package validation + +**REQ-OUT-100.** The results schema MUST define each finding form as an exact alternative. For each finding code it MUST require the applicable classification and properties and reject properties that are not permitted for that form, including the record-specific and dataset-level forms of `missing_required_field`. + +**REQ-OUT-101.** Structural validation of either JSON document alone MUST NOT be treated as full package validation. Full validation MUST include independent structural validation of both documents, their digest linkage and supported schema combination, and all applicable semantic configuration and result checks. Configuration-dependent checks MUST NOT be skipped when the configuration is unavailable; the package MUST instead fail validation. + +**REQ-OUT-134.** Package validation MUST: + +1. parse the results as strict UTF-8 JSON, rejecting duplicate object member names and non-standard or non-finite number tokens, and validate it against its independently selected supported results schema with format assertion; +2. require the fixed sibling `comparison-configuration.json` as a readable regular file when inspecting a published package, rejecting a missing file, symbolic link, or other filesystem object without following an alternative path or network reference; +3. obtain the exact configuration byte sequence and verify its SHA-256 digest against `comparison_configuration_digest` before using its contents; +4. parse the configuration as strict UTF-8 JSON, rejecting duplicate object member names and non-standard or non-finite number tokens, and independently validate it against its supported schema selected by document family and root `schema_version`, with format assertion; +5. reject an unsupported schema combination and validate the saved configuration's semantic rules, including effective automatic configurations while retaining the reserved-identifier restriction on custom YAML inputs; and +6. apply the result and cross-document semantic checks using the validated configuration and available comparison context. + +For generation, the exact serialized configuration bytes in memory serve as the configuration byte sequence for these checks. A valid digest establishes content linkage, not authenticity or laboratory approval. Structural, digest, and cross-document checks alone do not reproduce the comparison from its inputs; checks requiring source inputs or comparison context depend on that context being available. + +**REQ-OUT-102.** Semantic result validation MUST verify that overall run status agrees with all phase statuses. + +**REQ-OUT-103.** Semantic result validation MUST verify the record-count reconciliation equations in `REQ-OUT-038`. + +**REQ-OUT-104.** Semantic result validation MUST verify that every finding count agrees with the findings array and that counts by classification, code, and review priority each sum to the total. + +**REQ-OUT-105.** Semantic result validation MUST verify that every record-key field-name array and corresponding record-identity value array has the required common length and component order. + +**REQ-OUT-106.** Semantic result validation MUST verify that findings and exclusions use the required order, including classification-first finding order, that duplicate findings are absent, and that finding IDs are sequential after sorting. + +**REQ-OUT-107.** Semantic result validation MUST verify that each finding's classification, presence states, value evidence, locations, affected side, field identity, and review priority are consistent with its code, form, saved comparison configuration, and causal condition. + +**REQ-OUT-108.** Semantic result validation MUST verify that `record_key_fields`, finding field identities, review priorities, configured-field exclusions, and other configuration-derived metadata agree with the saved comparison configuration. It MUST also verify that undeclared-field exclusions agree with the source fields observed on each dataset side. + +**REQ-OUT-109.** Before publication preparation, the tool MUST perform full package validation on the serialized results and configuration bytes in memory, including their digest linkage and every semantic configuration and result rule. The saved configuration MUST agree with the effective configuration selected for the comparison; results and input provenance MUST agree with the available comparison context. The HTML report MUST then be generated from the validated pair. + +**REQ-OUT-110.** Failure of internally generated configuration, results, or package-linkage validation MUST be treated as an unexpected internal error. The tool MUST NOT publish any package member. Invalid user-supplied configuration remains a configuration error under Section 8.3; filesystem creation, writing, and publication failures remain output errors. + +**REQ-OUT-111.** The user guide MUST distinguish independent structural validation of each JSON document, exact-byte package linkage, and semantic validation. It MUST document the invariants and available-context requirements of each layer and MUST NOT describe a results-schema-only check as full package validation. + +**REQ-OUT-114.** Independent validation against each packaged schema MUST enable JSON Schema Draft 2020-12 format assertion. Invalid values for recognised formats, including UUIDs, dates, and date-times, MUST fail validation. The user guide's package-validation procedure MUST instruct users to enable equivalent format assertion. + +### 9.2 Human-readable output + +**REQ-OUT-042.** The first release MUST produce an HTML human-readable report. The report MUST include: + +- **REQ-OUT-074.** purpose of the run and the three comparison phases performed; +- **REQ-OUT-075.** prominent run status and per-phase completion status; +- **REQ-OUT-076.** identities of reference, query, and comparison configuration; +- **REQ-OUT-077.** summary counts; +- **REQ-OUT-078.** measured counts and findings, without an acceptance verdict; +- **REQ-OUT-079.** grouped discrepancy details; +- **REQ-OUT-080.** limitations, exclusions, and unassessed content; +- **REQ-OUT-081.** provenance and reproduction information; +- **REQ-OUT-082.** space or linkage for review and approval outside the tool. + +**REQ-OUT-127.** The report's headline summary MUST present run completeness, total `comparison_difference` findings, and total `assessment_issue` findings as distinct measures. It MUST NOT describe either finding count as an acceptance or validation verdict. + +**REQ-OUT-128.** Detailed findings MUST be organized primarily by classification, with comparison differences presented before assessment issues. Phase MUST remain visible as secondary traceability information and MAY be used for subgrouping within each classification. + +**REQ-OUT-120.** `comparison-report.html` MUST be generated solely from the validated contents of `comparison-results.json` and `comparison-configuration.json`, with verified digest linkage, and fixed renderer resources. It MUST NOT contain comparison facts, findings, metrics, provenance, or run metadata unavailable in those documents. It MAY display the complete saved configuration for review. Rendering MUST NOT reread the original YAML or obtain comparison facts from external state. Fixed explanatory text and blank or generic external review and approval space MAY be added. + +**REQ-OUT-126.** `comparison-report.html` MUST be self-contained and fully usable offline. Required styling MUST be embedded. The report MUST NOT load external scripts, stylesheets, fonts, images, tracking resources, or any other network resource. Core content and navigation MUST remain usable with scripting disabled. Embedded scripting MAY provide non-essential navigation or filtering enhancements but MUST NOT change or supply comparison content. + +### 9.3 Output parents and safe publication + +- **REQ-OUT-044.** Output files MUST be written atomically where supported. +- **REQ-OUT-045.** The complete evidence-package directory MUST be published atomically where the platform supports it. Publication MUST occur only after the serialized JSON pair has passed full package validation and the HTML report has been generated. All three members MUST be fully generated in private staging before the run directory is published. Temporary staging MUST be private and on the same filesystem as the run directory. +- **REQ-OUT-046.** An existing regular output-parent directory MUST be accepted regardless of its contents, without interpreting or validating those contents. A missing output parent MUST be created with private permissions; its enclosing directory MUST already exist. The selected output-parent path MUST NOT be a symbolic link, regular file, or special filesystem object. An ineligible parent or missing enclosing directory MUST cause `output.invalid_destination`; failure to create an eligible parent or write or publish its package MUST cause `output.write_failed`. This rule applies to the selected parent path and introduces no additional restriction on symbolic links in its ancestors. +- **REQ-OUT-116.** Existing output-parent contents MUST NOT be modified, removed, or replaced during successful or failed publication. This includes existing evidence packages, unrelated files and directories, and their permissions. Cleanup MUST be limited to temporary content owned by the current invocation. +- **REQ-OUT-130.** If any filesystem object already occupies the run-directory path, publication MUST fail with `output.invalid_destination` and preserve that object. The tool MUST NOT reuse the path, select a different name, or change the result's run identity to resolve the collision. +- **REQ-OUT-131.** Output-parent creation MUST occur only during publication preparation, after full package self-validation and HTML generation. Input or configuration errors MUST NOT create an output parent. After a publication failure, a newly created empty output parent MAY remain. +- **REQ-OUT-132.** Successive or concurrent invocations with distinct run identities MUST be able to publish distinct evidence packages under the same eligible output parent, including when that parent is initially absent. Equal completion timestamps MUST NOT by themselves cause a collision. Each invocation MUST preserve the other invocations' packages and temporary content. +- **REQ-OUT-047.** The actual published run directory MUST be reported in the normal completion summary using the label `Evidence package:`. For relative `--output`, the displayed path MUST be the supplied relative parent joined to the run-directory name. For absolute `--output`, it MUST be only the parent's final directory name joined to the run-directory name; when the parent is a filesystem root with no final directory name, only the run-directory name MUST be displayed. The absolute path MUST NOT be reproduced. +- **REQ-OUT-048.** File suffixes MUST be handled structurally, not with character stripping. +- **REQ-OUT-049.** A failed or interrupted write MUST NOT publish a partial run directory as if it were a complete evidence package. Temporary output MUST be identifiable as temporary and cleaned up where possible, without disturbing existing output-parent contents or another invocation's temporary content. + +## 10. Command-line interface + +### 10.1 General behaviour + +- **REQ-CLI-001.** Comparison arguments MUST be accepted directly by the `adviso-compare` executable without a subcommand. +- **REQ-CLI-002.** Invalid argument combinations MUST be rejected before input processing. +- **REQ-CLI-003.** Modes and formats MUST use enumerated choices. +- **REQ-CLI-004.** `--help` and `--version` MUST work without other arguments. +- **REQ-CLI-005.** Errors MUST be concise on standard error and actionable. +- **REQ-CLI-006.** Normal summaries SHOULD be written to standard output. +- **REQ-CLI-007.** Version 1 MUST NOT expose a progress option or emit a + progress stream. During a comparison attempt, its terminal output is limited + to the documented completion summary or execution-error diagnostic. + +### 10.2 Comparison interface + +The conceptual interface is: + +```text +adviso-compare \ + --reference REFERENCE \ + --query QUERY \ + --output OUTPUT \ + [--configuration CONFIGURATION] +``` + +**REQ-CLI-009.** `--configuration` MUST be optional. + +**REQ-CLI-010.** Omission of `--configuration` MUST select automatic strict-exact mode. When `--configuration` is present, its value MUST be treated only as the path to a custom comparison-configuration file. + +**REQ-CLI-011.** `--output` MUST name the output parent described in Section 9. Each non-error run MUST publish its evidence package in a new immediate child of that parent. + +**REQ-CLI-013.** Input formats MUST be determined as specified in Section 5.2. Version 1 provides no command-line format overrides. + +### 10.3 Exit codes + +**REQ-CLI-014.** Exit codes MUST distinguish at least: + +| Code | Meaning | +| ---: | --- | +| 0 | Run status is `complete`, whether or not differences were found | +| 1 | Run status is `incomplete` | +| 2 | Invocation, comparison-configuration, input, resource-limit, resource-exhaustion, or I/O error | +| 3 | Unexpected internal error | + +**REQ-CLI-015.** These exit-code meanings MUST be stable. They MUST be documented. + +**REQ-CLI-016.** A complete comparison that finds differences MUST still exit with code 0. It MUST write the evidence package. + +Error classes represented by exit codes 2 and 3 have run status `error`. The distinct codes allow automation to distinguish expected operational errors from unexpected implementation failures. + +### 10.4 Command hierarchy + +**REQ-CLI-017.** The version 1 executable MUST NOT expose user-facing subcommands. + +## 11. Security and data governance + +- **REQ-SEC-001.** Input datasets and evidence packages MAY contain sensitive patient or laboratory information. Version 1 provides only the data-minimisation and non-disclosure safeguards specified below; it does not de-identify data or replace the laboratory's access-control and information-governance arrangements. +- **REQ-SEC-002.** The tool MUST operate locally. +- **REQ-SEC-003.** The tool MUST NOT transmit input data, comparison configurations, logs, or results over a network. +- **REQ-SEC-004.** Routine logs, progress output, terminal diagnostics, and execution-error diagnostics MUST NOT contain record identifiers or source values. +- **REQ-SEC-005.** Evidence packages MAY contain record identifiers and source values only where required to identify or explain findings. +- **REQ-SEC-006.** Human-readable reports MUST state prominently that the evidence package may contain sensitive information. +- **REQ-SEC-007.** Absolute paths, raw command lines, environment variables, and secrets MUST NOT be included in results, reports, or routine logs. +- **REQ-SEC-008.** Input basenames MUST be treated as potentially sensitive evidence. +- **REQ-SEC-009.** If temporary files are used, they MUST NOT be made more accessible than the intended output. +- **REQ-SEC-010.** Temporary files MUST be removed after successful completion. +- **REQ-SEC-011.** Temporary files SHOULD be removed following an error where this can be done safely. +- **REQ-SEC-012.** Comparison-configuration YAML MUST be parsed using the safe-loader rules in Section 6.2.1. +- **REQ-SEC-014.** The tool SHOULD document filesystem permission expectations. The laboratory is responsible for supplying appropriately pseudonymised input data where required and for controlling access to, retention of, and disposal of inputs and evidence packages. +- **REQ-SEC-015.** The saved comparison configuration MUST receive restrictive file permissions consistent with the canonical results JSON. It is subject to the same evidence-package access, retention, and disposal controls. +- Automated redaction, identifier pseudonymisation, keyed hashing, and field-level sensitivity policies are outside the scope of version 1.0. + +## 12. Deployment, accessibility, and reliability + +The supported runtime matrix is CPython 3.11, 3.12, 3.13, 3.14, and 3.15 on +Linux, macOS, and Windows, using the latest available patch release of each +Python minor version. Python 3.11 is the installation minimum. Support for a +new Python minor version requires an explicit matrix update and verification; +it is not implied by the open-ended installation minimum. + +- **REQ-DEP-001.** Once the software and its dependencies are installed, all core comparison functionality MUST operate fully offline; +- **REQ-DEP-002.** During operation, the tool MUST NOT require a hosted service, account, licence server, telemetry connection, or any other network service; +- **REQ-DEP-003.** Version 1 does not require an offline installation bundle. Installation MAY use a network connection to obtain the `adviso-compare` distribution and its declared dependencies from package indexes. This allowance applies only to installation and MUST NOT weaken the offline-operation requirements in `REQ-SEC-002`, `REQ-SEC-003`, `REQ-DEP-001`, or `REQ-DEP-002`; +- **REQ-DEP-004.** reports MUST use open formats; +- **REQ-DEP-005.** reports MUST NOT require proprietary software; +- **REQ-DEP-006.** errors and documentation SHOULD be usable without specialist Python knowledge; +- **REQ-DEP-007.** documentation and examples SHOULD be available offline; +- **REQ-DEP-008.** localisation SHOULD remain possible without changing result semantics. + +**REQ-DEP-009.** Releases SHOULD state any enforced resource or input-size limits. + +**REQ-DEP-010.** Every valid comparison accepted for processing MUST attempt to assess all configured content. + +**REQ-DEP-011.** Exceeding a documented resource or input-size limit MUST produce an error. Encountering resource exhaustion at any stage MUST produce an error. A resource-limit or resource-exhaustion error MUST NOT produce a partial comparison result. + +**REQ-DEP-012.** Interrupted runs MUST NOT leave apparently complete reports or run directories. Existing output-parent contents MUST remain intact; private temporary content and a newly created empty output parent are governed by Section 9.3. + +**REQ-DEP-013.** Comparison outcomes, as defined by `REQ-OUT-095`, MUST remain invariant across supported Python versions and operating systems. Runtime provenance MAY differ. + +**REQ-DEP-014.** Internal exceptions MUST be converted into the standard-error diagnostic required by Section 8.3. A traceback MUST NOT be shown during ordinary CLI use. + +## 13. Software quality and release requirements + +### 13.1 Testing + +**REQ-TST-001.** The project MUST include: + +- **REQ-TST-009.** unit tests for parsing, typing, mapping, normalisation, and comparators; +- **REQ-TST-010.** behavioural contract tests for result semantics; +- **REQ-TST-011.** end-to-end CLI tests including exit codes; +- **REQ-TST-012.** schema validation tests for comparison configurations and canonical results; +- **REQ-TST-013.** installation tests from wheel and source distribution; +- **REQ-TST-014.** regression tests for every corrected material defect; +- **REQ-TST-015.** tests across all supported Python versions; +- **REQ-TST-016.** deterministic-output tests; +- **REQ-TST-017.** representative malformed and adversarial inputs; +- **REQ-TST-018.** tests for duplicate/composite keys and missing/extra content in both directions; +- **REQ-TST-019.** boundary tests for comparator tolerances. + +**REQ-TST-002.** Property-based testing SHOULD be used for parsing and comparison invariants. + +**REQ-TST-003.** Mutation testing SHOULD be used to assess whether the suite detects deliberately introduced comparison defects. + +### 13.2 Test data + +**REQ-TST-004.** Controlled test cases SHOULD record: + +- **REQ-TST-020.** stable, descriptive test or fixture name independent of the identifiers used in this specification; +- **REQ-TST-021.** behaviour under test, expressed in domain terms that remain meaningful without this specification; +- **REQ-TST-022.** purpose and rationale; +- **REQ-TST-023.** input data and comparison configuration; +- **REQ-TST-024.** expected findings, counts, run status, per-phase statuses, and exit code; +- **REQ-TST-025.** fixture provenance or generation method; +- **REQ-TST-026.** fixture version and digest; +- **REQ-TST-027.** independent review status where used as formal validation evidence. + +**REQ-TST-005.** Generated fixtures MUST be reproducible. + +**REQ-TST-006.** Clinically derived fixtures MUST be appropriately de-identified and governed. + +**REQ-TST-007.** Controlled test fixtures, including test comparison configurations, MUST be maintained by the development team under version control and its documented review process. + +**REQ-TST-035.** Traceability to this specification MUST be one-way. The acceptance-test catalogue and development review records MAY map specified requirements to tests, but production code, test code, test names, markers, fixtures, snapshots, package metadata, and runtime artefacts MUST NOT embed specification requirement identifiers or acceptance-scenario identifiers. Archiving or removing this development specification MUST NOT require changes to those software artefacts. + +In operational use, each laboratory is responsible for creating, approving, maintaining, and retaining its own comparison configurations under its local quality-management arrangements. The AdvISO project does not centrally approve or manage laboratory configurations. + +### 13.3 Continuous integration + +The routine CI matrix covers CPython 3.11–3.15 on Linux and CPython 3.11 and +3.15 on each of Windows and macOS. Linux is the primary deployment platform. +This CI coverage is a subset of the supported runtime combinations in Section +12; intermediate Python versions on Windows and macOS remain supported. + +**REQ-TST-008.** CI MUST: + +- **REQ-TST-028.** run on proposed changes and protected branches; +- **REQ-TST-029.** install the built package, not rely solely on the source checkout; +- **REQ-TST-030.** test the console entry point; +- **REQ-TST-031.** test the supported Python matrix; +- **REQ-TST-032.** fail on enforced lint, type, test, and build errors; +- **REQ-TST-033.** validate that generated schemas and examples are current; +- **REQ-TST-034.** avoid publishing releases when required checks fail. + +### 13.4 User documentation + +**REQ-DOC-001.** Version 1 MUST include a version-controlled user guide or manual. The guide MUST be distributed with the software. It MUST be available offline. It MUST be written for users of the command-line tool and describe: + +- **REQ-DOC-006.** installation and verification of the installed executable; +- **REQ-DOC-007.** the complete command-line interface, including inputs, outputs, defaults, exit codes, output-parent eligibility and creation, run-directory naming and preservation, completion-path reporting, and worked invocations; +- **REQ-DOC-008.** the supported input formats and their parsing, encoding, record, field, and filename-extension requirements; +- **REQ-DOC-009.** how automatic strict-exact mode selects a key, generates its effective configuration, compares shared fields, handles exclusions, and can fail when key selection is impossible or ambiguous, together with how to create, validate, and govern a custom comparison configuration; +- **REQ-DOC-010.** every property in the comparison-configuration schema, including its purpose, permitted values, required or optional status, default or omission semantics, constraints, and interactions with other properties; +- **REQ-DOC-011.** the translation-to-canonical comparison model, field-scope and exclusion behaviour, finding classifications, comparison phases, processing order, comparators, mappings, normalisation operations, null handling, and review priorities; +- **REQ-DOC-012.** the three fixed package members, the saved effective JSON configuration in custom and automatic modes, exact-byte digest linkage, independent schema selection, and full package-validation procedure; +- **REQ-DOC-013.** every property in the canonical results JSON schema, including finding classifications and codes, typed source and canonical values, counts, exclusions, run and phase statuses, and provenance fields; the guide MUST explain that software consuming a result must first identify the results format using its root `schema_version` and must use structured properties, classifications, and finding codes rather than parsing presentation messages; +- **REQ-DOC-014.** execution-error diagnostics and common corrective actions; +- **REQ-DOC-015.** the tool's intended use, non-claims, security and data-governance boundaries, and known limitations; and +- **REQ-DOC-016.** the comparison-configuration-schema and results-schema versions supported by the bundled software. The guide MUST describe that software's behaviour without requiring a separate software-version label. + +**REQ-DOC-002.** The guide MUST include complete, runnable examples covering automatic strict-exact mode, including automatic key discovery, and representative custom configuration features. + +**REQ-DOC-003.** Configuration examples MUST validate against the published comparison-configuration schema. Results examples MUST validate against the published results schema. + +**REQ-DOC-004.** Documentation MUST distinguish machine-enforced schema constraints from explanatory guidance. It MUST accurately describe the behaviour of the documented software version and MUST NOT contradict the machine-readable schemas it supports. Any material inconsistency is a release-blocking documentation defect. + +**REQ-DOC-005.** Command-line `--help` output MUST provide a concise description of every command and option. It MUST direct users to the full guide. + +### 13.5 Releases and change control + +**REQ-REL-001.** Each release SHOULD provide: + +- **REQ-REL-006.** an immutable semantic version; +- **REQ-REL-007.** release notes and known limitations; +- **REQ-REL-008.** compatibility statements for comparison-configuration and results schemas; +- **REQ-REL-009.** documented change-impact assessment; +- **REQ-REL-010.** signed or otherwise attestable source and build artefacts where practical; +- **REQ-REL-011.** a reproducible lockfile or equivalent dependency record; +- **REQ-REL-012.** evidence that required verification tests passed. + +**REQ-REL-002.** Comparison-configuration schemas, results schemas, and software releases MUST each have their own version identifier and MUST NOT be assumed to advance in lockstep or to use matching version numbers. Both JSON document families use root `schema_version`, scoped to their own schema family. Configuration schema support and compatibility MUST be checked by the software, independently of results-schema structural validation, as required by `REQ-OUT-113`. + +**REQ-REL-003.** Each software release MUST document the comparison-configuration schema versions, results schema versions, and combinations it supports. New configuration features requiring changes to results structure or meaning MUST be assessed for a corresponding results-schema revision. + +**REQ-REL-004.** An unsupported schema version MUST be rejected clearly rather than interpreted approximately. + +**REQ-REL-005.** The project MUST publish migration and compatibility rules before changing either schema. It MUST provide a migration path or documented transition period for any incompatible change. + +## 14. Acceptance-test catalogue + +This catalogue summarises minimum executable scenarios for the first release. It verifies, but does not independently define, the normative behaviour above. Every scenario lists the requirements it verifies. The scenario and requirement identifiers are development traceability within this specification; they are not identifiers for use in test or runtime artefacts. + +### 14.1 Input and contract scenarios + +- **AT-CON-001:** Identical typed datasets satisfy their contract. + - Verifies: `REQ-VAL-003`, `REQ-VAL-004`, `REQ-CMP-006`, `REQ-RUN-002` +- **AT-CON-002:** Required missing fields produce side-specific contract findings in both directions and across heterogeneous records; optional missing fields do not. Dataset-wide field discovery uses tabular headers and the union of JSON record members. `fields.in_scope` is required, non-empty, unique, and contains only defined canonical fields; list order does not affect behaviour. Defined fields omitted from it and observed source fields not represented by a definition produce the two exact exclusion forms, never findings or value opportunities. Undeclared exclusions are consolidated by side and source field with accurate record counts. Every declared field supplies non-empty `source_fields.reference` and `source_fields.query` names, including when the field is optional on either side; the `required` flags govern record-level presence rather than whether a correspondence is declared. + - Verifies: `REQ-CFG-030`, `REQ-CFG-031`, `REQ-CFG-037`, `REQ-CFG-038`, `REQ-CFG-039`, `REQ-CFG-116`, `REQ-CFG-117`, `REQ-CFG-118`, `REQ-CFG-119`, `REQ-CFG-120`, `REQ-CFG-121`, `REQ-CMP-006`, `REQ-CMP-007`, `REQ-CMP-034`, `REQ-CMP-035`, `REQ-CMP-036`, `REQ-FND-010`, `REQ-VAL-002`, `REQ-CFG-035`, `REQ-CFG-036`, `REQ-OUT-041` +- **AT-CON-004:** Null, empty string, whitespace-only string, absent field, and configured non-null missing tokens remain distinct according to policy. Parser-native null and recognised missing tokens bypass mapping and typed parsing; mapping to null applies the null policy and bypasses typed parsing; and null is rejected as a missing token or mapping source. + - Verifies: `REQ-CFG-053`, `REQ-CFG-054`, `REQ-CFG-055`, `REQ-CFG-056`, `REQ-CFG-057`, `REQ-CFG-122`, `REQ-VAL-014`, `REQ-VAL-047`, `REQ-VAL-048`, `REQ-VAL-049`, `REQ-VAL-050`, `REQ-VAL-051`, `REQ-VAL-052`, `REQ-VAL-053`, `REQ-VAL-054`, `REQ-VAL-055`, `REQ-VAL-086`, `REQ-INP-028` +- **AT-CON-005:** Unknown, conflicting, and incomplete value mappings fail clearly; mapping to null differs from a missing map entry, and mapping from null is rejected. This consolidated parameterized scenario also covers: Source-value descriptors distinguish strings, numbers, booleans, and null in their permitted positions; mapping to null remains distinct from an absent mapping entry. Parameterized mapping fixtures verify reference/query-to-canonical field mapping, required-field reporting, exclusion of unknown source fields, declared source and destination types, permitted intentional many-to-one value mappings, and rejection of reused source column names or any other non-one-to-one column mapping within either dataset side. + - Verifies: `REQ-CFG-065`, `REQ-CFG-071`, `REQ-CFG-072`, `REQ-CFG-073`, `REQ-CFG-074`, `REQ-CFG-127`, `REQ-VAL-058`, `REQ-VAL-065`, `REQ-VAL-067`, `REQ-CFG-058`, `REQ-CFG-059`, `REQ-VAL-068`, `REQ-VAL-056`, `REQ-VAL-057`, `REQ-VAL-059`, `REQ-VAL-060`, `REQ-VAL-064`, `REQ-VAL-066` +- **AT-CON-006:** Malformed syntax or structure, non-array JSON roots (including a single record object), JSON arrays containing non-object items, duplicate JSON member names at any depth, empty top-level JSON record member names, empty or duplicate tabular column names, and irregular tabular rows receive their specified error classification without silent data loss. Empty member names in nested JSON object values remain valid data content. This consolidated parameterized scenario also covers: A table-driven parser suite verifies the fixed CSV and TSV dialects, UTF-8-only decoding, CRLF/LF equivalence, quoted delimiters, doubled quotes, embedded line breaks, retention of one-based data-record and starting physical line numbers, and initial string preservation. + - Verifies: `REQ-INP-021`, `REQ-INP-022`, `REQ-INP-023`, `REQ-INP-024`, `REQ-INP-025`, `REQ-INP-034`, `REQ-INP-035`, `REQ-INP-036`, `REQ-INP-037`, `REQ-INP-038`, `REQ-INP-070`, `REQ-INP-072`, `REQ-CMP-028`, `REQ-CMP-029`, `REQ-PRN-002`, `REQ-PRN-008`, `REQ-INP-010`, `REQ-INP-011`, `REQ-INP-012`, `REQ-INP-014`, `REQ-INP-015`, `REQ-INP-016`, `REQ-INP-017`, `REQ-INP-018`, `REQ-INP-019`, `REQ-INP-020`, `REQ-INP-026`, `REQ-INP-027`, `REQ-INP-063`, `REQ-INP-064` +- **AT-CON-007:** JSON `[]` and header-only CSV/TSV are valid zero-record datasets, while zero-byte inputs receive their format-specific input errors. With a custom configuration, two valid zero-record datasets have complete records and values phases with no record differences or value opportunities. In automatic mode, two header-only tabular datasets containing `record_id` behave likewise, while two empty JSON arrays produce `input.invalid_record_key` because they expose no selectable key. Per-record requirements produce neither findings nor not-assessable classifications; available tabular header structure still produces applicable dataset-level contract findings. A one-sided zero-record comparison reports every record as missing or extra when a valid key is available and otherwise receives the specified automatic-key error. + - Verifies: `REQ-INP-052`, `REQ-INP-053`, `REQ-INP-054`, `REQ-INP-055`, `REQ-INP-056`, `REQ-INP-057`, `REQ-INP-058`, `REQ-INP-059`, `REQ-INP-066`, `REQ-INP-067`, `REQ-INP-068`, `REQ-INP-069`, `REQ-INP-071`, `REQ-CMP-009`, `REQ-CMP-010`, `REQ-FND-022` +- **AT-CON-008:** Comparison-configuration YAML scalar resolution and cross-format typed dataset parsing are deterministic across supported environments. + - Verifies: `REQ-CFG-006`, `REQ-INP-039`, `REQ-INP-040`, `REQ-INP-041`, `REQ-INP-042`, `REQ-INP-043`, `REQ-INP-044`, `REQ-DEP-013` +- **AT-CON-011:** A complete custom YAML configuration conforming to Section 6.2 validates; omitted optional processing properties, collection representations, and dataset sides expand to their specified default or empty internal structures, while explicitly empty placeholder lists or mappings are rejected. + - Verifies: `REQ-CFG-003`, `REQ-CFG-005`, `REQ-CFG-014`, `REQ-CFG-060`, `REQ-CFG-061`, `REQ-CFG-062`, `REQ-CFG-063`, `REQ-CFG-069`, `REQ-CFG-070`, `REQ-CFG-075`, `REQ-CFG-076`, `REQ-CFG-137`, `REQ-CFG-138`, `REQ-CFG-139`, `REQ-CFG-140`, `REQ-CFG-141`, `REQ-CFG-143` +- **AT-CON-012:** Duplicate or unknown YAML keys, unsafe YAML features, unsupported schema versions, invalid enumerations, incompatible type/comparator combinations, and collection fields using field-level processing properties are rejected with precise configuration paths. This consolidated parameterized scenario also covers: Safe-loader tests confirm that configuration parsing cannot construct arbitrary objects or execute tagged payloads. + - Verifies: `REQ-CFG-007`, `REQ-CFG-008`, `REQ-CFG-009`, `REQ-CFG-010`, `REQ-CFG-013`, `REQ-CFG-017`, `REQ-CFG-048`, `REQ-CFG-051`, `REQ-CFG-052`, `REQ-CFG-065`, `REQ-CFG-078`, `REQ-CFG-079`, `REQ-CFG-080`, `REQ-CFG-085`, `REQ-CFG-091`, `REQ-CFG-145`, `REQ-SEC-012` +- **AT-CON-014:** Each authoritative schema has its specified canonical `$id`, is present in the source tree and built distribution, can be loaded through the installed package-resource API, and validates its own complete examples and controlled fixtures independently. Both JSON document families use root `schema_version`. Results structural validation requires no configuration-schema registration, enforces the exact top-level properties including `comparison_configuration_digest`, and rejects unknown properties and execution-error diagnostics. It accepts representative complete and incomplete results and enforces the exact permitted shape of every finding form. + - Verifies: `REQ-CFG-128`, `REQ-OUT-004`, `REQ-OUT-005`, `REQ-OUT-100`, `REQ-OUT-112` + - Verifies: `REQ-CFG-016`, `REQ-CFG-087`, `REQ-CFG-088`, `REQ-OUT-004`, `REQ-OUT-005`, `REQ-OUT-006`, `REQ-OUT-007`, `REQ-OUT-050`, `REQ-OUT-051`, `REQ-OUT-052`, `REQ-OUT-053`, `REQ-OUT-054`, `REQ-OUT-055`, `REQ-OUT-056`, `REQ-OUT-057`, `REQ-OUT-058`, `REQ-OUT-059`, `REQ-OUT-060`, `REQ-OUT-100` +- **AT-CON-015:** Configurations that are structurally schema-valid but violate a semantic rule in Section 6.2.9, including an in-scope or key name absent from the appropriate list or definitions, reuse of a source field name within one dataset side, invalid collection-representation placement or element mappings, and use of the reserved automatic-mode identifier by a custom configuration, are rejected with the relevant configuration path and rule. + - Verifies: `REQ-CFG-090`, `REQ-CFG-091`, `REQ-CFG-104`, `REQ-CFG-105`, `REQ-CFG-106`, `REQ-CFG-107`, `REQ-CFG-108`, `REQ-CFG-127`, `REQ-CFG-129`, `REQ-CFG-136`, `REQ-CFG-144` +- **AT-CON-016:** `review_priority` accepts only `low`, `normal`, or `high`; omission resolves to `normal` in the effective configuration. + - Verifies: `REQ-CFG-040` +- **AT-CON-017:** `fields.record_key` is required, non-empty, ordered, and free of duplicate component fields; every entry names a field in `fields.definitions` that satisfies all key-field constraints. + - Verifies: `REQ-CFG-024`, `REQ-CFG-025`, `REQ-CFG-026`, `REQ-CFG-027`, `REQ-CFG-029`, `REQ-CFG-034`, `REQ-CFG-104`, `REQ-CFG-105` +- **AT-CON-018:** `metadata.id` and `metadata.revision` are required non-empty strings; title and description are optional, and metadata does not alter comparison behaviour. + - Verifies: `REQ-CFG-018`, `REQ-CFG-020`, `REQ-CFG-022` +- **AT-CON-021:** A table-driven JSON parser suite verifies the record-oriented root structure, preserved string-like tokens and numerical lexical forms, and rejection of unquoted `NaN`, `Infinity`, and `-Infinity` as malformed JSON in every location. Results-schema fixtures accept only valid JSON integer lexical forms for `integer` source evidence and valid JSON numerical forms containing a fraction or exponent for `decimal` source evidence. Quoted non-finite representations remain strings; when explicitly parsed as decimals they produce an `invalid_field_value` and not-assessable opportunity in an attributable non-key field, but an execution error in a record-key field. + - Verifies: `REQ-INP-029`, `REQ-INP-030`, `REQ-INP-033`, `REQ-INP-047`, `REQ-INP-048`, `REQ-INP-049`, `REQ-INP-050`, `REQ-INP-051`, `REQ-INP-065` +- **AT-CON-022:** Every comparison resolves one effective configuration whose schema version, identifier, revision, record key, in-scope fields, field definitions, and comparison rules are validated and preserved in the saved configuration JSON. A supplied custom configuration is validated before either dataset is read; an automatically generated configuration is constructed after input parsing and field discovery but validated before comparison begins. Unknown custom keys fail with actionable locations. Runtime default expansion does not add properties to the saved document or discard explicit declarations or metadata. + - Verifies: `REQ-CFG-001`, `REQ-CFG-002`, `REQ-CFG-012`, `REQ-CFG-086`, `REQ-CFG-095`, `REQ-CFG-096`, `REQ-CFG-097`, `REQ-CFG-098`, `REQ-CFG-099`, `REQ-CFG-100`, `REQ-CFG-101`, `REQ-CFG-102`, `REQ-CFG-103` +- **AT-CON-023:** Parameterized configuration fixtures verify canonical field-name mapping, collection logical-type structure, the bidirectional relationship between omission of `logical_type` and `preserved_exact`, rejection of every processing property on a `preserved_exact` field, legal omission of operation parameters, placement and side-specific application of source and typed normalisation, and the required comparator declaration. They use the public names `source_fields`, `null_policy`, and `logical_type.collection_type`. + - Verifies: `REQ-CFG-028`, `REQ-CFG-032`, `REQ-CFG-033`, `REQ-CFG-049`, `REQ-CFG-050`, `REQ-CFG-064`, `REQ-CFG-066`, `REQ-CFG-067`, `REQ-CFG-077` +- **AT-CON-024:** Automatic strict-exact fixtures verify exact dataset-wide field discovery and deterministic generation of a schema-valid saved effective configuration. `record_id` is preferred when present on both sides and, if invalid, produces `input.invalid_record_key` without fallback. Without a shared `record_id`, exactly one common, complete, non-null, unique string field with at least one shared value is selected; zero candidates and multiple candidates produce actionable key errors, the latter listing candidate field names but no values. Tests reject numeric, null, missing, duplicate, heuristic, positional, ranked, and composite automatic keys. Every same-name non-key field is compared with `preserved_exact`; one-sided fields are exclusions; and no mapping, normalisation, coercion, tolerance, or type inference occurs. The HTML report presents the required automatic-mode warning. + - Verifies: `REQ-PRN-001`, `REQ-CFG-092`, `REQ-CFG-093`, `REQ-CFG-094`, `REQ-CFG-109`, `REQ-CFG-110`, `REQ-CFG-111`, `REQ-CFG-112`, `REQ-CFG-113`, `REQ-CFG-114`, `REQ-CFG-115`, `REQ-CFG-130`, `REQ-CFG-131`, `REQ-CFG-132`, `REQ-CFG-133`, `REQ-CFG-134`, `REQ-CFG-135`, `REQ-CFG-136`, `REQ-REC-006`, `REQ-REC-007`, `REQ-REC-008`, `REQ-REC-010` + +### 14.2 Record scenarios + +- **AT-REC-001:** Every reference-only record is reported as missing and every query-only record as extra, including when both occur together. + - Verifies: `REQ-INP-058`, `REQ-INP-059`, `REQ-CMP-011`, `REQ-CMP-012`, `REQ-FND-008`, `REQ-FND-009`, `REQ-PRN-003` +- **AT-REC-002:** Duplicate single and composite keys produce execution errors without overwriting data; each error identifies the affected dataset, duplicate normalised key, and available source-record locations. + - Verifies: `REQ-REC-003`, `REQ-REC-009`, `REQ-REC-010`, `REQ-REC-011`, `REQ-REC-012`, `REQ-REC-013`, `REQ-REC-014` +- **AT-REC-003:** Composite keys preserve multiple legitimate records belonging to one sample. + - Verifies: `REQ-REC-001`, `REQ-REC-002`, `REQ-CFG-024` +- **AT-REC-005:** Parameterized key fixtures verify that custom key names, aliases, composites, and normalisation are configuration-defined; the sole automatic-key exception follows Section 6.9; key values are not implicitly converted; no command-line key override exists; and findings retain enough source identity to distinguish records. + - Verifies: `REQ-REC-004`, `REQ-REC-005`, `REQ-REC-006`, `REQ-REC-007`, `REQ-REC-008`, `REQ-REC-015` + +### 14.3 Typed value and comparator scenarios + +- **AT-VAL-001:** Boolean `true`, integer `1`, decimal `1.0`, and textual `"1"` remain distinct under the applicable exact comparator. A parameterized source-category matrix verifies every directly accepted category, exact integer-to-decimal widening, rejection of implicit narrowing and stringification, rejection of parser-native objects for typed fields, explicit mapping for representations outside the matrix, null handling before typed parsing, and element-wise application to collections. The suite also verifies declared parsing rather than inference and enumerates the stable comparator registry. + - Verifies: `REQ-VAL-009`, `REQ-VAL-027`, `REQ-CMP-017`, `REQ-VAL-001`, `REQ-VAL-005`, `REQ-VAL-007`, `REQ-VAL-008`, `REQ-VAL-076`, `REQ-VAL-077`, `REQ-VAL-078`, `REQ-VAL-079`, `REQ-VAL-080`, `REQ-VAL-081`, `REQ-VAL-082`, `REQ-VAL-083`, `REQ-VAL-084`, `REQ-VAL-085`, `REQ-CMP-015` +- **AT-VAL-002:** Typed strings remain code-point-exact unless configured normalisations are applied in declared order. + - Verifies: `REQ-INP-013`, `REQ-VAL-012`, `REQ-VAL-013`, `REQ-VAL-070`, `REQ-CMP-016` +- **AT-VAL-003:** Integer parsing accepts signed ASCII decimal integers and leading zeros but rejects decimal points, exponents, booleans, and invalid text. This consolidated parameterized scenario also covers: Leading-zero identifiers remain strings unless explicitly transformed. + - Verifies: `REQ-VAL-015`, `REQ-VAL-016`, `REQ-VAL-017`, `REQ-VAL-018` +- **AT-VAL-004:** Decimal parsing is exact; accepts parser-native integers and decimals and textual forms such as `+1.2`, `01.2`, `1`, and `1E+2`; rejects `.5`, `1.`, `NaN`, and infinities; and never passes through binary floating-point. Invalid attributable non-key decimals are also checked as contract findings that become `not_assessable`, not execution errors. + - Verifies: `REQ-INP-031`, `REQ-INP-032`, `REQ-INP-045`, `REQ-INP-046`, `REQ-VAL-019`, `REQ-VAL-020`, `REQ-VAL-021`, `REQ-VAL-022`, `REQ-VAL-023`, `REQ-VAL-078`, `REQ-VAL-011` +- **AT-VAL-005:** Boolean parsing accepts native booleans and lowercase textual `true` or `false`; other representations require a mapping. + - Verifies: `REQ-VAL-024`, `REQ-VAL-025`, `REQ-VAL-026`, `REQ-VAL-027` +- **AT-VAL-006:** Dates reject invalid or non-ISO full dates; datetimes require offsets and compare as instants. + - Verifies: `REQ-VAL-028`, `REQ-VAL-029`, `REQ-VAL-030`, `REQ-VAL-031`, `REQ-VAL-032`, `REQ-VAL-033`, `REQ-VAL-034`, `REQ-VAL-035`, `REQ-VAL-036`, `REQ-VAL-092`, `REQ-CMP-024` +- **AT-VAL-007:** Lists preserve order and duplicates, sets reject typed-canonical duplicates and ignore order, and multisets ignore order while preserving occurrence counts. List elements support positional typed-exact comparison and numeric tolerance for numeric element types; sets and multisets accept only typed-exact element comparison, and every other element-comparator combination is rejected. This consolidated parameterized scenario also covers: the default and explicit `json_array` representations accept JSON arrays in JSON and JSON-array cell syntax in CSV/TSV; ordinary delimited text is rejected unless `delimited_text` is explicitly configured for that side; literal single- and multi-character delimiters, empty input, empty elements, lack of collection-level escaping, element normalisation, closed element mapping, and element typed parsing follow the defined order; and null collection elements produce the specified finding and `not_assessable` evidence. The suite covers every supported typed collection kind and its required element declaration. + - Verifies: `REQ-CFG-124`, `REQ-CFG-125`, `REQ-CFG-126`, `REQ-CFG-137`, `REQ-CFG-138`, `REQ-CFG-139`, `REQ-CFG-140`, `REQ-CFG-141`, `REQ-CFG-142`, `REQ-VAL-037`, `REQ-VAL-038`, `REQ-VAL-039`, `REQ-VAL-040`, `REQ-VAL-041`, `REQ-VAL-042`, `REQ-CMP-025`, `REQ-CMP-040`, `REQ-CMP-041`, `REQ-VAL-043`, `REQ-VAL-044`, `REQ-VAL-045`, `REQ-VAL-046`, `REQ-VAL-006`, `REQ-VAL-081`, `REQ-VAL-082`, `REQ-VAL-087`, `REQ-VAL-088`, `REQ-VAL-089`, `REQ-VAL-090`, `REQ-VAL-091` +- **AT-VAL-008:** Typed transformations follow Section 6.8 and retain evidence of the attributable source value. This consolidated parameterized scenario also covers: Parameterized normalisation fixtures exercise every registered source-text and typed-value operation, verify that source-text operations affect strings but pass non-strings through unchanged, and cover Unicode normalization, whitespace trimming, case folding, decimal quantisation, and datetime truncation. Rounding or precision reduction occurs only when explicitly configured. Deterministic set and multiset output ordering is verified as canonical serialization rather than configured normalisation. The suite also verifies retention of source lexical evidence. + - Verifies: `REQ-CFG-123`, `REQ-CFG-146`, `REQ-CFG-147`, `REQ-CFG-148`, `REQ-CFG-149`, `REQ-VAL-061`, `REQ-VAL-062`, `REQ-VAL-063`, `REQ-VAL-069`, `REQ-VAL-070`, `REQ-VAL-072`, `REQ-VAL-073`, `REQ-VAL-074`, `REQ-VAL-075`, `REQ-VAL-071`, `REQ-CMP-023`, `REQ-VAL-010` +- **AT-VAL-009:** Numeric tolerance accepts exactly one absolute or relative tolerance and rejects configurations containing neither or both. Each form uses exact decimal arithmetic and an inclusive boundary, with below, at, and above boundary cases; relative tolerance is reference-directed and permits no non-zero difference when the reference is zero. + - Verifies: `REQ-CFG-081`, `REQ-CFG-082`, `REQ-CFG-083`, `REQ-CFG-084`, `REQ-CMP-018`, `REQ-CMP-019`, `REQ-CMP-020`, `REQ-CMP-021`, `REQ-CMP-022` +- **AT-VAL-010:** All assessable differences are collected in one run. + - Verifies: `REQ-CMP-026`, `REQ-CMP-027` +- **AT-VAL-011:** Every field listed in `fields.in_scope` is assessed; defined fields omitted from that list and observed source fields not represented by a definition are `not_assessed` and represented by the required exclusion summaries. + - Verifies: `REQ-CFG-039`, `REQ-CMP-004`, `REQ-CMP-013`, `REQ-CMP-031`, `REQ-OUT-041` + +### 14.4 Phase and run-status scenarios + +- **AT-OUT-001:** Every comparison performs the contract, records, and values phases in order and records a completion status for each. Overall status is complete if and only if all three phase statuses are complete. + - Verifies: `REQ-CMP-001`, `REQ-RUN-012`, `REQ-RUN-023`, `REQ-OUT-013`, `REQ-OUT-014` +- **AT-OUT-002:** A finding or `not_assessable` item in an earlier phase does not prevent later assessment where prerequisites remain satisfied. + - Verifies: `REQ-CMP-002`, `REQ-CMP-003`, `REQ-RUN-007` +- **AT-OUT-005:** Complete, incomplete, invocation or input error, and unexpected internal error produce their documented exit behaviour. This consolidated parameterized scenario also covers: Fully performed contract and record phases remain complete despite their findings, and a fully performed comparison is `complete` whether it finds no differences or any combination of contract findings, missing records, extra records, and value mismatches. + - Verifies: `REQ-RUN-001`, `REQ-RUN-015`, `REQ-RUN-016`, `REQ-RUN-017`, `REQ-RUN-018`, `REQ-RUN-019`, `REQ-RUN-021`, `REQ-CLI-014`, `REQ-CLI-015`, `REQ-CLI-016`, `REQ-RUN-002` +- **AT-OUT-006:** A not-assessable value opportunity makes the values phase and run incomplete while leaving a fully performed contract phase complete; deliberately `not_assessed` content does not make any phase incomplete. This consolidated parameterized scenario also covers: Content excluded deliberately is `not_assessed`; configured content blocked by a failed prerequisite is `not_assessable`. + - Verifies: `REQ-RUN-003`, `REQ-RUN-004`, `REQ-RUN-005`, `REQ-RUN-016`, `REQ-RUN-018`, `REQ-RUN-020`, `REQ-RUN-021`, `REQ-RUN-022`, `REQ-CMP-004` +- **AT-OUT-007:** Invalid configuration, malformed or unreadable input, an incomplete or ambiguous record model, an enforced resource limit, and resource exhaustion produce `error`, never `incomplete` or a partial comparison result. + - Verifies: `REQ-RUN-017`, `REQ-RUN-010`, `REQ-RUN-011`, `REQ-DEP-011` +- **AT-OUT-008:** An end-to-end mixed-defect comparison exercises every conceptual processing step, including invalid contract values, deliberate exclusions, failed prerequisites, mandatory key processing, and continued comparison of unaffected values. This consolidated parameterized scenario also covers: A large mixed-content fixture verifies that every configured value opportunity is either assessed or explicitly classified and that no valid accepted content is silently skipped. + - Verifies: `REQ-CMP-005`, `REQ-CMP-008`, `REQ-CMP-014`, `REQ-CMP-030`, `REQ-CMP-037`, `REQ-CMP-038`, `REQ-CMP-039`, `REQ-RUN-006`, `REQ-DEP-010` +- **AT-OUT-010:** A table-driven finding suite generates every finding code and verifies its fixed classification, structured fields, required contextual evidence, deterministic local ID, human-readable message, summary-only successful matches, and absence of message-only semantics. `missing_record`, `extra_record`, and `value_mismatch` are always `comparison_difference`; every other finding code is always `assessment_issue`; and phase remains independently correct. This consolidated parameterized scenario also covers: For every finding code, result fixtures enforce the code-specific inclusion and omission of source and canonical values, deterministic messages derived from structured data, classification-first total finding order, duplicate coalescence, and sequential post-sort report-local IDs. Category incompatibility, invalid content within an accepted category, and comparison of two valid unequal values produce mutually exclusive `type_mismatch`, `invalid_field_value`, and `value_mismatch` findings. Independent reference and query contract violations produce separate side-specific findings, while comparison of two valid unequal values produces one `both` finding. Each not-assessable value opportunity has one applicable causal finding and does not generate a separate `not_assessable` finding. + - Verifies: `REQ-PRN-006`, `REQ-FND-001`, `REQ-FND-002`, `REQ-FND-003`, `REQ-FND-004`, `REQ-FND-005`, `REQ-FND-006`, `REQ-FND-012`, `REQ-FND-013`, `REQ-FND-014`, `REQ-FND-015`, `REQ-FND-016`, `REQ-FND-017`, `REQ-FND-018`, `REQ-FND-019`, `REQ-FND-020`, `REQ-FND-023`, `REQ-FND-024`, `REQ-FND-025`, `REQ-OUT-032`, `REQ-OUT-033`, `REQ-OUT-034`, `REQ-OUT-035`, `REQ-OUT-099`, `REQ-OUT-061`, `REQ-OUT-062`, `REQ-OUT-064`, `REQ-OUT-065`, `REQ-OUT-066`, `REQ-OUT-067`, `REQ-OUT-068` + +### 14.5 Evidence, CLI, and packaging scenarios + +- **AT-EVD-001:** Runs with identical exact bytes, basenames, configuration, software version, and runtime identity produce byte-identical canonical results JSON after normalizing only run ID and completion time, and byte-identical saved configuration JSON with an identical configuration digest. Serialization fixtures verify UTF-8 without a byte-order mark, two-space indentation, LF line endings, exactly one final newline, direct non-ASCII output, fixed-schema member order, and Unicode code-point order for dynamic members in both documents. Parameterized record-order and LF/CRLF variants preserve the defined comparison outcome while permitting only the documented byte-provenance, source-location, location-dependent message, and report-local ID differences. The comparison outcome also remains invariant across every supported Python and operating-system environment, including Unicode-sensitive fixtures. + - Verifies: `REQ-PRN-005`, `REQ-INP-014`, `REQ-CMP-033`, `REQ-OUT-012`, `REQ-OUT-095`, `REQ-OUT-096`, `REQ-OUT-097`, `REQ-OUT-098`, `REQ-OUT-125`, `REQ-OUT-133`, `REQ-DEP-013`, `REQ-CMP-032` +- **AT-EVD-002:** Results contain exact-byte SHA-256 input digests and input basenames without exposing absolute paths, raw command lines, environment variables, or secrets. The complete validated effective configuration is saved as the fixed sibling `comparison-configuration.json`, in custom and automatic modes. Results contain only its required top-level `comparison_configuration_digest`, with `algorithm: "sha256"` and a lowercase hexadecimal `value` matching the exact published bytes, including the final newline. The configuration filename, identity, revision, and schema version are not duplicated as configuration-reference properties. Source YAML formatting does not determine the digest. + - Verifies: `REQ-CFG-023`, `REQ-OUT-017`, `REQ-OUT-018`, `REQ-OUT-019`, `REQ-OUT-022`, `REQ-OUT-023`, `REQ-SEC-007`, `REQ-SEC-008` +- **AT-EVD-004:** Success, injected failure at each of the three member writes, publication-failure, and interrupted-run cases verify that no partial run directory appears complete. Staging is private, on the publication filesystem, identifiable as temporary, and removed after success and, where safe, after errors. Existing packages and arbitrary output-parent contents remain unchanged, including their permissions. Cleanup does not affect another invocation's temporary content. Input and configuration errors do not create an output parent; a publication error may leave a newly created empty parent. + - Verifies: `REQ-OUT-044`, `REQ-OUT-045`, `REQ-OUT-049`, `REQ-OUT-116`, `REQ-OUT-131`, `REQ-DEP-012`, `REQ-SEC-015`, `REQ-SEC-009`, `REQ-SEC-010`, `REQ-SEC-011` +- **AT-EVD-005:** Every complete comparison exits with code 0 and produces its evidence package, including when differences are reported. + - Verifies: `REQ-PRN-004`, `REQ-RUN-002`, `REQ-OUT-001`, `REQ-OUT-002`, `REQ-CLI-016` +- **AT-EVD-008:** Complete and incomplete runs publish one immediate child under the selected output parent, containing exactly the three regular files `comparison-results.json`, `comparison-configuration.json`, and `comparison-report.html`. Its name is derived exactly from the validated result's completion timestamp and full run UUID. Empty parents and parents with arbitrary contents are accepted; a missing parent is created privately only when its enclosing directory exists. A selected parent that is a file, symbolic link, or special filesystem object, or has a missing enclosing directory, is rejected. Parent-creation and publication I/O failures use the specified error codes. A file, empty directory, populated directory, or symbolic link occupying the exact run-directory path is preserved and causes a collision error. Successive and concurrent runs with distinct UUIDs, including runs with the same timestamp and runs using an initially missing parent, publish independently and preserve each other's evidence. Completion summaries identify the actual child using the specified relative-path, absolute-path, and filesystem-root rules without disclosing an absolute path. Filename handling is structural rather than character stripping. + - Verifies: `REQ-OUT-001`, `REQ-OUT-002`, `REQ-OUT-044`, `REQ-OUT-045`, `REQ-OUT-046`, `REQ-OUT-047`, `REQ-OUT-048`, `REQ-OUT-115`, `REQ-OUT-116`, `REQ-OUT-129`, `REQ-OUT-130`, `REQ-OUT-131`, `REQ-OUT-132`, `REQ-CLI-011` +- **AT-EVD-009:** A parameterized suite produces every version 1 invocation, configuration, input, resource, output, and internal execution-error code. Each case writes the exact `ERROR [.]: ` first-line form and only permitted non-sensitive continuation context, returns exit code 2 except for `internal.unexpected`, which returns 3, and publishes no new evidence package or filesystem report. Existing output-parent contents remain intact; an empty parent created during publication preparation may remain. Diagnostics contain no findings, finding codes, comparison summary metrics, phase statuses, record identifiers, source values, or ordinary-use traceback. Representative failures at each classification boundary verify that the most specific applicable code is selected. + - Verifies: `REQ-FND-007`, `REQ-RUN-008`, `REQ-RUN-009`, `REQ-RUN-010`, `REQ-RUN-011`, `REQ-RUN-024`, `REQ-RUN-025`, `REQ-RUN-026`, `REQ-OUT-008`, `REQ-DEP-014` +- **AT-EVD-010:** Routine logs, progress output, terminal diagnostics, and execution-error diagnostics omit record identifiers and source values. + - Verifies: `REQ-PRN-007`, `REQ-SEC-004`, `REQ-VAL-075` +- **AT-EVD-011:** Evidence packages warn that they may contain sensitive information, and findings contain record identifiers or source values only where needed to identify or explain the finding. + - Verifies: `REQ-PRN-007`, `REQ-OUT-030`, `REQ-OUT-031`, `REQ-SEC-005`, `REQ-SEC-006` +- **AT-EVD-012:** Core comparison completes without network access and makes no attempt to transmit inputs, comparison configurations, logs, or results. + - Verifies: `REQ-SEC-002`, `REQ-SEC-003`, `REQ-DEP-001`, `REQ-DEP-002` +- **AT-EVD-013:** Findings attributable to declared fields inherit their resolved review priority; other findings do not. HTML presentation may distinguish priorities but does not rely on colour alone, and priority never changes findings, counts, status, or exit code. + - Verifies: `REQ-CFG-041`, `REQ-CFG-042`, `REQ-CFG-043`, `REQ-CFG-044`, `REQ-CFG-045`, `REQ-OUT-034` +- **AT-PKG-001:** The built distribution is named `adviso-compare`, contains an importable `adviso_compare` package and every required subpackage, installs the `adviso-compare` executable in an isolated environment where its declared dependencies are available, and completes an end-to-end comparison through that executable. Installation may access package indexes. The installed executable requires no network service during comparison. The distribution contains the required offline documentation and integrity information. + - Verifies: `REQ-PRD-001`, `REQ-PRD-003`, `REQ-CFG-087`, `REQ-TST-013`, `REQ-TST-030`, `REQ-DEP-003`, `REQ-DEP-007` +- **AT-EVD-015:** Canonical results contain valid run, phase, software, runtime, and fixed-dialect metadata; run IDs are canonical lowercase UUIDv4 values; completion timestamps are UTC RFC 3339 values using `Z` and whole-second precision; Python implementation/version, normalized platform, and Unicode database version use their prescribed forms without identifying host details; start time and duration are absent; and overall status reconciles with phase statuses. + - Verifies: `REQ-OUT-009`, `REQ-OUT-010`, `REQ-OUT-011`, `REQ-OUT-014`, `REQ-OUT-015`, `REQ-OUT-016`, `REQ-OUT-020`, `REQ-OUT-121`, `REQ-OUT-122`, `REQ-OUT-123`, `REQ-OUT-124` +- **AT-EVD-016:** Parameterized single and composite record identities verify ordered source and canonical key arrays, null identities for an absent side, presence-state distinctions, recursive parser-native typed values, unique canonical rendering of every scalar type, UTC datetime rendering, canonical key-component rendering, deterministic set and multiset element order, and deterministic object-member ordering. Source-location fixtures verify tabular data-record and starting-line numbers across multiline records, field-name inclusion only for present fields, record-level locations for absent fields, JSON record and field pointers, RFC 6901 escaping, and null locations for absent records. + - Verifies: `REQ-OUT-021`, `REQ-OUT-026`, `REQ-OUT-027`, `REQ-OUT-028`, `REQ-OUT-029`, `REQ-OUT-089`, `REQ-OUT-090`, `REQ-OUT-091`, `REQ-OUT-092`, `REQ-OUT-093`, `REQ-OUT-094`, `REQ-OUT-117`, `REQ-OUT-118`, `REQ-OUT-119` +- **AT-EVD-018:** Parameterized result fixtures verify fixed-shape zero-inclusive summaries, record-count reconciliation, finding totals by classification, code, and priority, and exactly one matched, mismatched, or not-assessable classification for every in-scope non-key value opportunity, including optional, required, invalid, and prohibited values. Semantic checks also verify that configured-field exclusions agree with `fields.in_scope` and that undeclared-field exclusions agree with observed source fields and record counts. + - Verifies: `REQ-OUT-037`, `REQ-OUT-038`, `REQ-OUT-039`, `REQ-OUT-040`, `REQ-OUT-069`, `REQ-OUT-070`, `REQ-OUT-071`, `REQ-OUT-072`, `REQ-OUT-073`, `REQ-OUT-101`, `REQ-OUT-102`, `REQ-OUT-103`, `REQ-OUT-104`, `REQ-OUT-105`, `REQ-OUT-106`, `REQ-OUT-107`, `REQ-OUT-108` +- **AT-EVD-022:** Before publication, representative generated JSON pairs pass independent structural validation with Draft 2020-12 format assertion, byte-digest linkage, supported-version checks, configuration semantic validation, and all applicable result and cross-document checks against the comparison context. Injected schema, digest, or semantic inconsistencies, including malformed UUIDs, dates, and date-times, produce an unexpected internal error, create no output parent, and publish none of the three package members. Existing output-parent contents remain intact. When inspecting a published package, missing, unreadable, non-regular, malformed, duplicate-member, or invalid-number configuration files invalidate it. Whitespace-only byte changes with unchanged parsed content invalidate an unchanged digest. With a recomputed matching digest, key, field, priority, scope, or finding contradictions still fail semantic validation. Results-only schema validation does not establish package validity. + - Verifies: `REQ-OUT-109`, `REQ-OUT-110`, `REQ-OUT-114`, `REQ-OUT-131`, `REQ-OUT-134`, `REQ-OUT-101`, `REQ-OUT-107`, `REQ-OUT-108` +- **AT-EVD-019:** HTML generated solely from the digest-linked, validated results and saved configuration JSON uses an open non-proprietary format and presents the run purpose, phase and run statuses, input and configuration identities, counts, findings, discrepancies, limitations, exclusions, unassessed content, provenance, and no acceptance verdict. A displayed configuration is derived from the saved document, with no rereading of original YAML or other external factual source. The HTML remains self-contained and is never the sole canonical evidence format. Its headline distinguishes run completeness, comparison-difference count, and assessment-issue count. Detailed findings are organized primarily by classification with comparison differences first and phase retained as secondary traceability information. Complete and incomplete reports contain raw findings and metrics but no acceptance threshold, pass/fail verdict, or equivalent inferred laboratory decision. + - Verifies: `REQ-PRN-009`, `REQ-OUT-042`, `REQ-OUT-074`, `REQ-OUT-075`, `REQ-OUT-076`, `REQ-OUT-077`, `REQ-OUT-078`, `REQ-OUT-079`, `REQ-OUT-080`, `REQ-OUT-081`, `REQ-OUT-120`, `REQ-OUT-126`, `REQ-OUT-127`, `REQ-OUT-128`, `REQ-DEP-004`, `REQ-DEP-005`, `REQ-RUN-013` +- **AT-EVD-021:** Installed-CLI tests cover the required direct `adviso-compare` form, required reference, query, and output arguments, optional configuration, enumerated choices, invalid combinations before input access, rejection of subcommands, normal summaries on standard output, and the absence of a version 1 progress interface. This consolidated parameterized scenario also covers: Omitting `--configuration` selects automatic strict-exact mode and records its generated effective configuration; a supplied value is treated only as a custom comparison-configuration path. The reference and query formats are independently determined and recorded from recognised, case-insensitive filename extensions; a missing, unknown, or ambiguous extension causes an input error, and content that does not conform to the indicated format is rejected. Command-line `--help` describes every version 1 option and directs users to the full guide. + - Verifies: `REQ-PRD-002`, `REQ-INP-001`, `REQ-INP-002`, `REQ-INP-004`, `REQ-INP-060`, `REQ-INP-061`, `REQ-INP-062`, `REQ-CLI-001`, `REQ-CLI-002`, `REQ-CLI-003`, `REQ-CLI-006`, `REQ-CLI-007`, `REQ-INP-003`, `REQ-CFG-092`, `REQ-CLI-009`, `REQ-CLI-010`, `REQ-INP-005`, `REQ-INP-006`, `REQ-INP-007`, `REQ-INP-008`, `REQ-INP-009`, `REQ-CLI-013`, `REQ-CLI-004`, `REQ-DOC-005` + +### 14.6 Documentation scenarios + +- **AT-DOC-001:** The built distribution contains an offline user guide covering every topic required by Section 13.4, and the guide describes its bundled software and identifies the supported comparison-configuration and results schema versions. This consolidated parameterized scenario also covers: Every complete comparison-configuration and canonical-results example in the guide validates independently against its corresponding packaged schema, and every documented command-line invocation uses the version 1 interface. The worked package-validation procedure checks the fixed sibling configuration, exact-byte digest linkage, schema selection through each root `schema_version`, and the documented semantic-assurance limits for both automatic and custom packages. + - Verifies: `REQ-DOC-001`, `REQ-DOC-006`, `REQ-DOC-007`, `REQ-DOC-008`, `REQ-DOC-009`, `REQ-DOC-010`, `REQ-DOC-011`, `REQ-DOC-012`, `REQ-DOC-013`, `REQ-DOC-014`, `REQ-DOC-015`, `REQ-DOC-016`, `REQ-DOC-002`, `REQ-DOC-003`, `REQ-DOC-004`, `REQ-OUT-111` + +### 14.7 Fixture and compatibility scenarios + +- **AT-TRC-002:** Regenerating every generated fixture from its recorded source or generator produces byte-identical or semantically identical controlled test data, as applicable. + - Verifies: `REQ-TST-005` +- **AT-TRC-003:** Supported and unsupported comparison-configuration and results schema versions are exercised independently, using each document's own root `schema_version` and its document family. Software accepts the supported version combination and clearly rejects unknown versions and unsupported combinations. Results structural validation does not inspect or pin the saved configuration schema version: a valid results document can pass its own schema while full package validation rejects an unsupported configuration version even with a matching digest. Saved automatic configurations are valid effective evidence, while custom YAML using the reserved automatic identifier remains rejected. + - Verifies: `REQ-REL-002`, `REQ-REL-003`, `REQ-REL-004`, `REQ-OUT-113`, `REQ-OUT-134`, `REQ-CFG-136` diff --git a/packages/adviso-compare/docs/USER_GUIDE.md b/packages/adviso-compare/docs/USER_GUIDE.md new file mode 100644 index 0000000..2b82be8 --- /dev/null +++ b/packages/adviso-compare/docs/USER_GUIDE.md @@ -0,0 +1,1370 @@ +# `adviso-compare` user guide + +## Contents + +- [1. Introduction](#1-introduction) + - [1.1 Records, fields, and comparison rules](#11-records-fields-and-comparison-rules) + - [1.2 Findings and run status](#12-findings-and-run-status) +- [2. Installation](#2-installation) + - [2.1 Install with pip](#21-install-with-pip) + - [2.2 Install with pipx](#22-install-with-pipx) + - [2.3 Check the installation](#23-check-the-installation) +- [3. Quick start](#3-quick-start) + - [3.1 Run your first comparison](#31-run-your-first-comparison) + - [3.2 Read and interpret the results](#32-read-and-interpret-the-results) +- [4. Command and input reference](#4-command-and-input-reference) + - [4.1 Command options and exit codes](#41-command-options-and-exit-codes) + - [4.2 Input datasets](#42-input-datasets) +- [5. Custom comparison configurations](#5-custom-comparison-configurations) + - [5.1 A small custom comparison](#51-a-small-custom-comparison) + - [5.2 Runnable custom example with transformations](#52-runnable-custom-example-with-transformations) + - [5.3 Configuration checks and conventions](#53-configuration-checks-and-conventions) + - [5.4 Top-level properties](#54-top-level-properties) + - [5.5 Field definitions](#55-field-definitions) + - [5.6 Logical types](#56-logical-types) + - [5.7 Null policy and typed value descriptions](#57-null-policy-and-typed-value-descriptions) + - [5.8 Source normalisation](#58-source-normalisation) + - [5.9 Value mapping](#59-value-mapping) + - [5.10 Collections written as text](#510-collections-written-as-text) + - [5.11 Typed normalisation](#511-typed-normalisation) + - [5.12 Comparators](#512-comparators) + - [5.13 Processing order](#513-processing-order) +- [6. The evidence package](#6-the-evidence-package) +- [7. JSON output reference](#7-json-output-reference) + - [7.1 `comparison-configuration.json`](#71-comparison-configurationjson) + - [7.2 `comparison-results.json`](#72-comparison-resultsjson) + - [7.3 Structural and semantic validation](#73-structural-and-semantic-validation) +- [8. Errors and corrective action](#8-errors-and-corrective-action) +- [9. Security, governance, and limitations](#9-security-governance-and-limitations) +- [10. Reproducing the examples](#10-reproducing-the-examples) + +## 1. Introduction + +`adviso-compare` compares a reference dataset with a query dataset, such as the +output of a bioinformatics pipeline. A comparison configuration describes how +to pair records, associate fields, and translate values into a shared form. +The tool reports differences that remain after translation and problems that +prevented parts of the comparison. + +The output is comparison evidence. Your laboratory decides how that evidence +contributes to its validation and quality processes; the tool does not make an +acceptance decision or establish ISO 15189 compliance. + +### 1.1 Records, fields, and comparison rules + +A dataset contains **records**, such as rows in a CSV file. Each record has +**fields**, such as a sample identifier or a measurement. The **reference** +is the dataset you compare against; the **query** is the dataset being checked. + +A **record key** identifies corresponding records on the two sides. For +example, a sample identifier can pair a reference row with the query row for +the same sample. A key uses one field, or several fields together as a +**composite key**. Keys are unique within each dataset; record order does not +establish correspondence. + +A configuration can associate differently named source fields with one +**canonical field**: a shared name used within the comparison. For example, +reference field `expected` and query field `observed` could both represent the +canonical field `measurement`. A **logical type**, such as decimal or date, +describes how to interpret a value. A **comparator** is the rule used to decide +whether two values match. The resulting shared representations are called +**canonical values**. + +A **parser-native value** is the value and type read from the input before +configured transformations. CSV cells start as text; JSON can distinguish +text, numbers, booleans, and other value types. A scalar is a single value, +such as a string or number, rather than a collection of values. + +A present field can contain **null**, an explicit no-value marker. An absent +field is missing entirely; an empty string is present text with no characters. + +The **effective configuration** is the configuration used for a run. You can +supply a custom configuration, or let automatic mode generate one. Its +**scope** selects the fields to assess. Fields outside that scope are reported +as **exclusions** and are not compared. + +### 1.2 Findings and run status + +The report contains **findings**: individual differences or problems that +prevented assessment. Findings have two broad meanings: + +- A **comparison difference** remains after the applicable translation and + comparison rules have been applied. +- An **assessment issue** explains a problem applying those rules, such as a + required field being absent or a value that cannot be interpreted as declared. + +A run is **complete** when every applicable comparison was performed. It can +be complete and still report differences. A run is **incomplete** when some +intended value comparisons could not be performed. Both produce an **evidence +package**: a directory containing the results, configuration, and HTML report. +An execution error prevents a trustworthy result and produces no new package. + +## 2. Installation + +`adviso-compare` requires Python 3.11 or later. Supported Python versions are +CPython 3.11, 3.12, 3.13, 3.14, and 3.15, on Linux, macOS, and Windows. Use the +latest available patch release of your selected Python version. + +You can install it into an existing virtual environment with `pip`, or use +`pipx` to manage a dedicated environment for the tool. Creating a new +environment yourself is optional. + +In the commands below, replace the example wheel path with the actual file +supplied to you, including its versioned filename. + +### 2.1 Install with pip + +Activate the virtual environment you want to use, then install the wheel and +its dependencies: + +```console +python -m pip install /path/to/adviso_compare-VERSION-py3-none-any.whl +``` + +If you prefer a new environment, create and activate one before running that +installation command: + +```console +python -m venv .venv +. .venv/bin/activate +``` + +On Windows Command Prompt, activate it with `.venv\Scripts\activate`; in +PowerShell, use `.venv\Scripts\Activate.ps1`. + +### 2.2 Install with pipx + +If you use [pipx](https://pipx.pypa.io/stable/), install the wheel with: + +```console +pipx install /path/to/adviso_compare-VERSION-py3-none-any.whl +``` + +`pipx` creates and manages a separate virtual environment for `adviso-compare` +and makes the command available on your PATH. There is no need to activate +that environment to run the command. + +### 2.3 Check the installation + +Installation may use a package index to obtain dependencies. Once installed, +the comparison itself needs no network service. After either installation, +check that the command is available: + +```console +adviso-compare --version +adviso-compare --help +``` + +The full guide is installed with the software under +`share/doc/adviso-compare/USER_GUIDE.md` in the Python environment. +For a `pipx` installation, this is the environment managed by `pipx`; `pipx list` +shows where it keeps application environments. + +## 3. Quick start + +The installed examples provide a first comparison without creating a +configuration yourself. Run the automatic example, then use its report to +explore the results. Section 5 shows how to supply your own configuration. + +### 3.1 Run your first comparison + +**Automatic strict-exact mode** is suitable when both datasets already use the +same field names and representations. It generates the comparison configuration +for you. To try it, omit `--configuration`. + +#### 3.1.1 Runnable automatic example + +Copy the `examples` directory installed next to this guide into a writable +working directory outside the Python environment. Keep its `automatic` and +`custom` subdirectories together, then change into the copied `examples` +directory. The commands below create evidence beside your copies of the inputs, +leaving the installed files unchanged. + +From that copied directory, run: + +```console +adviso-compare \ + --reference automatic/reference.csv \ + --query automatic/query.csv \ + --output automatic-evidence +``` + +The example has no `record_id`. `sample_id` is the only valid key candidate, so +it is discovered automatically. The run is complete and reports one changed +`lineage`. The query-only `pipeline_version` field appears in the exclusions. + +The completion summary has this form, with a different run-directory name on +each invocation: + +```text +Run status: complete +Comparison differences: 1 +Assessment issues: 0 +Evidence package: automatic-evidence/20261111T143205Z-123e4567-e89b-42d3-a456-426614174000 +``` + +Run the same command again with `--output automatic-evidence` to add another +run directory while preserving the first. Section 6 shows the resulting layout. + +Automatic mode is deliberately conservative. Use a custom configuration when +source field names differ, values require translation, a composite key is +needed, or automatic key selection is ambiguous. + +#### 3.1.2 How automatic mode selects fields and keys + +`adviso-compare` first finds field names shared by both datasets. It selects +the record key as follows: + +1. If both sides contain `record_id`, that field is used. It must contain a + unique, non-null string in every record on both sides. +2. Otherwise, a candidate must be a shared field containing a unique, + non-null string in every record on both sides, with at least one value shared + between the datasets. +3. Exactly one candidate must remain. No candidate or more than one candidate + is an `input.invalid_record_key` error. + +The selected key is compared as a typed string. All other shared fields are +compared using strict parser-native equality: value types must match as well as +content. For example, JSON integer `1` does not equal JSON string `"1"`. +Fields found on only one side are reported as exclusions, not differences. + +The tool creates an effective configuration internally and saves it as +`comparison-configuration.json` alongside the results and report. + +### 3.2 Read and interpret the results + +Open `comparison-report.html` in the directory named by the completion +summary. Beside it are `comparison-results.json`, for software use and detailed +review, and `comparison-configuration.json`, the effective configuration. + +Begin with run completeness, then review comparison differences, assessment +issues, and exclusions. The automatic example reports a complete run with one +comparison difference and no assessment issues. Its query-only +`pipeline_version` field was excluded, so it did not create a finding. + +The report describes several aspects of the comparison: + +#### 3.2.1 The reporting model + +| Concept | What it describes | Examples | +| --- | --- | --- | +| Run status | Whether the comparison as a whole could be completed | `complete`, `incomplete`, `error` | +| Phase status | Whether one of the three comparison phases completed its applicable work | `complete`, `incomplete` | +| Finding | One reported difference or problem that requires attention | A missing record or an invalid field value | +| Finding classification | The broad meaning of a finding | `comparison_difference`, `assessment_issue` | +| Finding code | The specific type of finding | `value_mismatch`, `mapping_failure` | +| Value-opportunity outcome | What happened when one in-scope field was considered for one aligned record | `matched`, `mismatched`, `not_assessable` | +| Exclusion | A field that was deliberately or implicitly outside the comparison | A configured or undeclared field exclusion | +| Review priority | Optional presentation priority for a finding about a configured field | `low`, `normal`, `high` | + +A finding is an individual entry in the report. Every finding has one +classification and one more-specific finding code. The classification explains +the general nature of the finding; the code explains exactly what happened. + +#### 3.2.2 Comparison phases + +Every comparison performs three phases in order: + +1. **Contract:** checks that configured fields can be found and translated as + declared, including requiredness, null, type, validity, and mapping rules. +2. **Records:** pairs records using their keys and identifies + missing and extra records. +3. **Values:** compares each assessable, in-scope, non-key field in aligned + records. + +A problem in an earlier phase does not automatically stop all later work. The +tool continues wherever the required information remains valid and +unambiguous. The phase attached to a finding records where the finding arose; +it is separate from the finding's classification. + +#### 3.2.3 Findings, classifications, and codes + +There are two finding classifications. + +`comparison_difference` means that the relevant translation and comparison +prerequisites succeeded, and a difference remained. It includes a reference +record missing from the query, an extra query record, or two valid translated +values that do not match. + +`assessment_issue` means that the declared translation or assessment could not +be applied cleanly to some input content. For example, a required field may be +absent or a source value may not have an entry in a configured mapping. Such an +issue can be important, but the tool cannot call it a post-translation +difference because the intended translation did not succeed. + +The eight finding codes are: + +| Code | Classification | Meaning | +| --- | --- | --- | +| `missing_record` | `comparison_difference` | A reference record has no aligned query record. | +| `extra_record` | `comparison_difference` | A query record has no aligned reference record. | +| `value_mismatch` | `comparison_difference` | Two valid translated values differ under the comparator. | +| `missing_required_field` | `assessment_issue` | A required source field is absent. | +| `type_mismatch` | `assessment_issue` | The source value type cannot be used for the declared logical type. | +| `invalid_field_value` | `assessment_issue` | The source value type is acceptable, but the value itself is invalid. | +| `null_policy_violation` | `assessment_issue` | A null is present where null is not allowed. | +| `mapping_failure` | `assessment_issue` | A closed mapping has no entry for the source value. | + +Successful record and value matches are included in summary counts rather than +reported as individual findings. + +#### 3.2.4 Value-opportunity outcomes + +A value opportunity is one in-scope, non-key field considered for one pair of +aligned records. Every such opportunity is counted as exactly one of: + +- `matched`: both sides were assessable and matched under the configured + comparator; +- `mismatched`: both sides were assessable but did not match, producing a + `value_mismatch` finding; or +- `not_assessable`: the intended comparison could not be performed because a + prerequisite failed, producing the applicable `assessment_issue` finding. + +`not_assessable` is a summary outcome, not a finding code. The associated +finding explains why the comparison could not be performed. At least one +not-assessable opportunity makes the values phase, and therefore the run, +`incomplete`. + +#### 3.2.5 Run and phase status + +The possible run statuses are: + +- `complete`: every applicable comparison was performed; +- `incomplete`: the record model remains trustworthy, but at least one intended + value comparison was not assessable; and +- `error`: no trustworthy comparison result could be produced, for example + because an input was malformed or a record key was invalid. + +The contract, records, and values phases each have a status of `complete` or +`incomplete`. Overall run status is `complete` only when all three phases are +complete. An errored run has no evidence package and therefore no reported +phase statuses. + +#### 3.2.6 Exclusions and review priority + +An exclusion records a field that was outside the comparison: + +- `configured_field_excluded` means that the configuration describes the field + but leaves it outside the selected scope; +- `undeclared_field_excluded` means that a source field was observed but is not + represented by a field definition on that side. + +Excluded fields are not assessed. They do not produce findings or value +opportunities, and they do not make a run incomplete. This is different from +`not_assessable`, which describes an intended comparison that could not be +performed. + +`review_priority` may be `low`, `normal`, or `high`. It helps organise findings +about configured fields for human review. It does not change the comparison, +the finding classification, run status, or exit code, and it is not a statement +of clinical significance. Record findings do not carry a review priority; they +are counted as `unassigned` in the priority summary. + +#### 3.2.7 No acceptance verdict + +The tool reports what it compared, what differed, and what it could not assess. +It does not decide whether the results are acceptable, whether a pipeline has +passed validation, or whether an ISO 15189 requirement has been met. Those +decisions belong to the laboratory's separately governed validation process. + +## 4. Command and input reference + +### 4.1 Command options and exit codes + +The command has no subcommands: + +```text +adviso-compare \ + --reference REFERENCE \ + --query QUERY \ + --output OUTPUT \ + [--configuration CONFIGURATION] +``` + +| Option | Meaning | +| --- | --- | +| `--reference REFERENCE` | Reference dataset. Required. | +| `--query QUERY` | Query dataset produced by the pipeline. Required. | +| `--output OUTPUT` | Parent directory under which to create a new run directory. Required. | +| `--configuration CONFIGURATION` | Custom YAML comparison configuration. If omitted, automatic strict-exact mode is used. | +| `--version` | Print the installed version and exit. | +| `--help` | Print concise help and exit. | + +`--output` selects a parent directory. Each complete or incomplete run +creates its own directory there and preserves existing content. Section 6 +explains directory names, permissions, and publication errors. + +The command prints a short completion summary to standard output. An execution +error is printed to standard error. The exit codes are: + +| Code | Meaning | +| ---: | --- | +| `0` | The run is complete. This includes complete runs that found differences. | +| `1` | The run is incomplete because at least one intended value comparison was not assessable. An evidence package is still written. | +| `2` | Expected operational error, such as an invalid option, configuration, input, key, resource condition, or output destination. No evidence package is written. | +| `3` | Unexpected internal error. No evidence package is written. | + +Exit code `0` means the configured comparison completed. It does not indicate +acceptance of the query or its pipeline. + +### 4.2 Input datasets + +The reference and query can independently be CSV, TSV, or JSON. The +case-insensitive filename extension selects the format: `.csv`, `.tsv`, or +`.json`. There is no format override. Both files must be UTF-8. + +#### 4.2.1 CSV and TSV + +CSV uses commas; TSV uses tabs. Both use a double quote as the quote character. +A double quote inside a quoted cell is written twice. Quoted cells may contain +the delimiter or a line break. LF and CRLF line endings are accepted. + +A header is required. Header names must be non-empty and unique. Every data row +must contain the same number of cells as the header. All cells initially count +as strings, including empty cells and text that looks like a number or boolean. + +#### 4.2.2 JSON + +JSON must contain one array of record objects at its root, even when there is +only one record: + +```json +[ + {"sample_id": "S1", "result": "detected"}, + {"sample_id": "S2", "result": "not_detected"} +] +``` + +A single root object is not accepted. Every array item must be an object. +Top-level record field names must be non-empty and unique. Duplicate member +names anywhere in the JSON are rejected. + +JSON strings, integers, decimals, booleans, nulls, arrays, and objects retain +their natural JSON type. Decimal numbers are read exactly without first being +converted to binary floating point, and their original spelling is retained as +evidence. `NaN` and infinities are not valid JSON numbers. + +#### 4.2.3 Empty datasets + +`[]` is a valid zero-record JSON dataset. A header with no data rows is a valid +zero-record CSV or TSV dataset. A zero-byte file is not a valid dataset. + +A custom configuration can compare empty datasets when it supplies the needed +field and key information. Automatic mode cannot select a key from two empty +JSON arrays because they expose no fields. + +## 5. Custom comparison configurations + +A custom configuration lets you choose the record key, associate different +source field names, and declare how values are interpreted and compared. It +is one UTF-8 YAML document. The `.yaml` or `.yml` suffix is recommended so that +its format is easy to recognise. + +### 5.1 A small custom comparison + +This example pairs samples whose identifier fields have different names and +compares their measurements as decimals. In a working directory of your +choice, save the following as `reference.csv`: + +```csv +record_id,measurement +S1,1.00 +S2,2.00 +``` + +Save the query as `query.csv` in the same directory: + +```csv +sample_id,result +S1,1 +S2,2.10 +``` + +Save this complete configuration as `configuration.yaml`: + +```yaml +schema_version: "1.0" +metadata: + id: "org.example.simple-comparison" + revision: "1" +fields: + record_key: ["sample"] + in_scope: ["sample", "measurement"] + definitions: + sample: + source_fields: {reference: "record_id", query: "sample_id"} + required: {reference: true, query: true} + logical_type: "string" + null_policy: {allowed: false, nulls_equal: false} + comparator: {name: "typed_exact"} + measurement: + source_fields: {reference: "measurement", query: "result"} + required: {reference: true, query: true} + logical_type: "decimal" + null_policy: {allowed: false, nulls_equal: false} + comparator: {name: "numeric_exact"} +``` + +`schema_version` identifies the configuration format. `metadata` gives this +configuration a stable ID and revision; it does not change comparison rules. +`fields` describes record identity, scope, and the values to compare. + +The canonical field `sample` associates the two identifier names and provides +the record key. `measurement` associates the values to compare. Both fields +are required on both sides, and neither permits null: an explicit missing +value. An absent field is different from a present field containing null. +`typed_exact` compares the interpreted key strings; `numeric_exact` compares +exact decimal values. No tolerance or rounding is applied. + +From that directory, run: + +```console +adviso-compare \ + --reference reference.csv \ + --query query.csv \ + --configuration configuration.yaml \ + --output evidence +``` + +The run completes with one comparison difference and no assessment issues. +For `S1`, `1.00` and `1` represent the same decimal value. For `S2`, `2.00` and +`2.10` differ, producing one `value_mismatch` finding. The key identifies the +sample; it is not counted again as a measurement comparison. + +### 5.2 Runnable custom example with transformations + +For a richer example, use the writable copy of the `examples` directory from +Section 3.1.1. If you are starting here, copy the installed `examples` directory +to a working directory outside the Python environment first, then change into +that copy and run: + +```console +adviso-compare \ + --reference custom/reference.json \ + --query custom/query.csv \ + --configuration custom/configuration.yaml \ + --output custom-evidence +``` + +The configuration maps different source field names to shared canonical names. +It shows decimal quantisation and absolute tolerance, string trimming and case +folding, value mapping, and translation of slash-delimited text to a set. It +also declares `curator_note` but leaves it out of `fields.in_scope`, while the +query's undeclared `pipeline_version` is also excluded. The run is complete and +reports one `measurement` difference. + +A stable ID and revision, review of changes, and testing with representative +data help your laboratory manage each configuration as a controlled document. +The evidence package retains the complete effective configuration as +`comparison-configuration.json`. Local quality arrangements remain the +authority for approval and retention. + +### 5.3 Configuration checks and conventions + +The file is checked before either dataset is read. YAML aliases, anchors, +merge keys, explicit tags, duplicate keys, and unsafe +object constructors are rejected, as are unknown properties. Quoting textual +values helps prevent YAML from interpreting them as numbers, dates, or +booleans. In particular, `schema_version` is a quoted string, and decimal +parameters use strings such as `"0.1"`. The examples use quotes to make +intended string values clear. + +A JSON schema describes a document's permitted structure and values. +`comparison-configuration-v1.0.schema.json` defines the expected configuration +structure. After parsing the YAML, the tool checks it against this schema and +rejects configurations that do not conform. + +The tool also checks relationships between settings: key and in-scope fields +have definitions; source field names are unique on each dataset side; mapping +sources are not repeated, conflicting, or unreachable; and operations and +comparators suit their field. It rejects custom configurations using the +reserved automatic-mode ID +`adviso-compare:automatic-strict-exact`. + +### 5.4 Top-level properties + +| Property | Required | Meaning | +| --- | --- | --- | +| `schema_version` | Yes | Configuration format version; the supported version is `"1.0"`. | +| `metadata` | Yes | Identity and description of the configuration. It does not alter the comparison. | +| `fields` | Yes | Key, scope, field correspondence, and comparison rules. | + +`metadata` has these properties: + +| Property | Required | Meaning | +| --- | --- | --- | +| `id` | Yes | Stable, non-empty identifier chosen by the configuration owner. | +| `revision` | Yes | Non-empty revision string managed by the configuration owner. | +| `title` | No | Human-readable title; may be empty. | +| `description` | No | Human-readable description; may be empty. | + +`fields` has these properties: + +| Property | Required | Meaning | +| --- | --- | --- | +| `record_key` | Yes | Non-empty ordered list of canonical field names forming one key. Order matters for a composite key. | +| `in_scope` | Yes | Non-empty list of canonical fields to assess. Key fields must be included. List order does not affect results. | +| `definitions` | Yes | Non-empty mapping from user-chosen canonical field names to field definitions. | + +A definition not listed in `in_scope` is deliberately excluded and appears once +as `configured_field_excluded`. A source field not named by any definition on +its side (reference or query) appears as `undeclared_field_excluded`. Neither kind +is compared or makes a run incomplete. + +### 5.5 Field definitions + +Every entry in `fields.definitions` is an object with a canonical field name as +key, and has the following properties: + +| Property | Required | Meaning | +| --- | --- | --- | +| `source_fields` | Yes | `reference` and `query` give the source field name on each side. Both are required non-empty strings. | +| `required` | Yes | `reference` and `query` booleans say whether every applicable record on that side must contain the field. | +| `logical_type` | Usually | Scalar type or collection declaration. Omit only for `preserved_exact`. | +| `null_policy` | Yes | Defines whether null is allowed and how two nulls compare. | +| `source_normalisation` | No | Side-specific ordered text operations before mapping and type parsing. | +| `collection_representation` | Collections only, optional | Describes how either side writes a collection. | +| `value_mapping` | Scalar typed fields only, optional | Side-specific closed translation tables. | +| `typed_normalisation` | Scalar typed fields only, optional | Ordered operations applied to parsed values on both sides. | +| `comparator` | Yes | Comparison rule and, where needed, its parameters. | +| `review_priority` | No | `low`, `normal`, or `high`; defaults to `normal`. It helps organise review and does not change findings, status, exit code, or clinical significance. | + +For each record-key field, the tool requires an entry in `definitions` and +`in_scope`, a scalar logical type, and `typed_exact` comparison. The field is +required and non-nullable on both sides. Key fields may use explicit source +normalisation or value mapping. + +### 5.6 Logical types + +For a scalar field, `logical_type` is `string`, `integer`, `decimal`, `boolean`, +`date`, or `datetime`. Parsing is strict. In particular, CSV and TSV cells +start as strings and are parsed only because a logical type was declared. Dates use +`YYYY-MM-DD`. Datetimes use RFC 3339 with an explicit timezone. + +The tool accepts these source values for each declared type: + +| Logical type | Accepted parser-native input | +| --- | --- | +| `string` | String only. | +| `integer` | JSON integer, or text containing an optional sign and ASCII digits. Decimal points and exponents are not accepted. | +| `decimal` | JSON integer or decimal, or signed decimal text in plain or scientific notation. Text such as `.5` or `1.` is not accepted. | +| `boolean` | JSON boolean, or exactly the lowercase text `true` or `false`. | +| `date` | String containing a valid Gregorian `YYYY-MM-DD` date. | +| `datetime` | String containing a full RFC 3339 date and time with `Z` or a numeric offset. A local time without an offset is not accepted. | + +JSON objects cannot be converted to any of the logical types. They may be compared +as complete, untyped JSON values using `preserved_exact`. More generally, the tool +uses the declared logical type for parsing. Use `value_mapping` to describe +translations that type parsing does not provide. + +A collection uses an object: + +```yaml +logical_type: + collection_type: "set" + element_type: "string" + element_comparator: + name: "typed_exact" +``` + +`collection_type` is `list`, `set`, or `multiset`. `element_type` is one of the +scalar types. Nested collections are not supported. Lists keep order, sets +ignore order and reject duplicates, and multisets ignore order but retain how +many times each value occurs. Sets and multisets require `typed_exact` elements. +Lists allow `typed_exact`, or `numeric_tolerance` for integer or decimal +elements. + +### 5.7 Null policy and typed value descriptions + +`null_policy.allowed` and `null_policy.nulls_equal` are required booleans. If +null is not allowed, `nulls_equal` must be false. JSON null is always recognised +as null. A missing field is different from a present field containing null. + +Within a field's `null_policy`, optional `missing_tokens` may contain a +non-empty `reference` list, a non-empty `query` list, or both. Each item +describes a parser-native value to treat as null. For example, this fragment +belongs inside a field definition: + +```yaml +null_policy: + allowed: true + nulls_equal: true + missing_tokens: + reference: + - category: "string" + value: "NA" + query: + - category: "string" + value: "." +``` + +Each missing token describes a non-null source value using a category and a value. +The permitted categories are `string`, `integer`, `decimal`, and `boolean`. Strings, +integers, and decimals use a textual `value`; booleans use `true` or `false`. An +actual JSON `null` does not need to be listed because the tool recognises it +automatically. + +### 5.8 Source normalisation + +`source_normalisation` may have `reference`, `query`, or both. Each present +side is a non-empty ordered list. Operations affect only parser-native strings +from that side. Non-strings pass through unchanged. + +| Operation | Parameters | Effect | +| --- | --- | --- | +| `unicode_normalise` | `form`: `NFC`, `NFD`, `NFKC`, or `NFKD` | Applies the named Unicode normalisation form. | +| `trim` | `side`: `leading`, `trailing`, or `both` | Removes Unicode White_Space characters from the chosen end or ends. | +| `case_fold` | None; omit `parameters` | Applies locale-independent full Unicode case folding. | + +Operations run in list order. Case folding does not silently perform Unicode +normalisation; list both operations when both are needed. + +### 5.9 Value mapping + +`value_mapping` may have `reference`, `query`, or both. Each present side is a +non-empty list of `from` and `to` value descriptions: + +```yaml +value_mapping: + query: + - from: {category: "string", value: "pos"} + to: {category: "string", value: "detected"} +``` + +The mapping is closed: when a side has a mapping, every non-null value on that +side must match an entry. An unmapped value produces a `mapping_failure`; it is +not passed through. Many source values may map to the same destination. A +destination may be null, after which the null policy applies. + +A mapping destination may use `category: "null"` without a `value`. This converts +the mapped source value to null, after which the field’s `null_policy` is applied. +Mapping from null is not supported because an actual JSON null is recognised and +handled before value mapping. + +Mapping happens after source normalisation and missing-token recognition, and +before parsing to the logical type. + +### 5.10 Collections written as text + +`collection_representation` may have `reference`, `query`, or both. An omitted +side defaults to `json_array` with no element processing. + +Each side requires `format`: + +- `json_array` means a JSON array value, or a CSV/TSV string containing valid + JSON-array text. It must not have a `delimiter`. +- `delimited_text` means a parser-native string split on the required, + non-empty `delimiter` string. + +Optional `element_normalisation` is a non-empty ordered list of the text +operations in Section 5.8. Optional `element_mapping` is a non-empty closed +mapping whose `from` and `to` values must both be non-null. These act on each +element, not the collection as a whole. Collection fields cannot also use the +field-level `source_normalisation`, `value_mapping`, or `typed_normalisation`. + +### 5.11 Typed normalisation + +`typed_normalisation` is an optional, non-empty ordered list of operations +applied to parsed values from both the reference and query. Operations run +before the comparator is applied. + +#### Decimal quantisation + +`decimal_quantise` fixes the number of digits retained after the decimal point: + +```yaml +typed_normalisation: + - operation: "decimal_quantise" + parameters: + places: 2 + rounding: "half_even" +``` + +Here, `places: 2` means that values are quantised to two digits after the +decimal point. A value is not first converted to binary floating point; exact +decimal arithmetic is used. + +The available rounding methods are: + +| Method | Meaning | +| --- | --- | +| `half_even` | Round to the nearest value. If the discarded part is exactly halfway between two possible results, choose the result whose last retained digit is even. For example, at two decimal places, `1.235` becomes `1.24`, while `1.245` becomes `1.24`. | +| `half_up` | Round to the nearest value. If the discarded part is exactly halfway between two possible results, round away from zero. At two decimal places, `1.235` becomes `1.24` and `-1.235` becomes `-1.24`. | +| `down` | Discard digits beyond the requested number of decimal places, moving towards zero rather than rounding to the nearest value. At two decimal places, `1.239` becomes `1.23` and `-1.239` becomes `-1.23`. | + +`places: 0` quantises to a whole-number value, although the field remains +logically a decimal. Quantisation is applied independently to both reference +and query values before they are compared. + +#### Datetime truncation + +`datetime_truncate` limits fractional-second precision after the datetime has +been converted to UTC: + +```yaml +typed_normalisation: + - operation: "datetime_truncate" + parameters: + precision: "millisecond" +``` + +The permitted values are: + +- `second`: remove the entire fractional-second part; +- `millisecond`: retain at most three fractional digits; and +- `microsecond`: retain at most six fractional digits. + +Discarded digits are removed without rounding. For example, millisecond +truncation changes `.1238` seconds to `.123`, not `.124`. + +### 5.12 Comparators + +Every comparator is an object with `name`. The following take no parameters: + +| Name | Use | +| --- | --- | +| `preserved_exact` | Parser-native equality without a declared logical type. Array order matters; object member order does not. | +| `typed_exact` | Exact equality after typed parsing and configured processing. | +| `normalised_string` | Exact comparison of processed strings. | +| `numeric_exact` | Exact comparison of integer or decimal values. | +| `date_exact` | Exact canonical calendar date. | +| `datetime_exact` | Same instant after conversion to UTC. | +| `list_exact` | Ordered collection comparison. | +| `set_exact` | Order-independent unique collection comparison. | +| `multiset_exact` | Order-independent comparison retaining duplicate counts. | + +String comparators require `logical_type: "string"`; numeric comparators require +`integer` or `decimal`; date and datetime comparators require their matching +temporal type; and each collection comparator requires the collection type with +the same name. `normalised_string` also requires at least one applicable +normalisation operation. `preserved_exact` is the only comparator with no +`logical_type`, and it cannot be combined with normalisation, mapping, +collection representation, typed normalisation, or configured missing tokens. + +`numeric_tolerance` requires exactly one entry inside `parameters`. For +example, this field-level comparator allows an absolute difference of up to +`0.1`: + +```yaml +comparator: + name: "numeric_tolerance" + parameters: + absolute_tolerance: "0.1" +``` + +With `absolute_tolerance`, values match when their absolute difference is no +greater than the tolerance. Use `relative_tolerance` in its place to match when: + +```text +absolute difference <= relative tolerance × absolute reference value +``` + +The tolerance is a quoted, non-negative finite decimal. The boundary is +included. A relative tolerance around a zero reference allows only exact zero; +use an absolute tolerance when a non-zero difference around zero is intended. + +The schema restricts the possible shape of comparators. The tool's further +checks ensure that a comparator suits the declared logical type and collection +kind. + +### 5.13 Processing order + +For a scalar field, processing follows this order: + +1. distinguish absence from a present parser-native value; +2. apply side-specific source normalisation to strings; +3. recognise explicit null or configured missing tokens; for null, apply the + null policy and skip mapping and type parsing; +4. for non-null values, apply the side-specific closed value mapping; +5. if mapping produces null, apply the null policy and skip type parsing; +6. otherwise parse the declared logical type; +7. apply typed normalisation where applicable; and +8. compare the canonical values under the configured null and comparison rules. + +For a collection, whole-field missing-token and null handling happens before +the representation is decoded. Element normalisation, mapping, and typed +parsing then happen for each element before collection comparison. + +## 6. The evidence package + +Each complete or incomplete run publishes one new directory under `OUTPUT`. +For example, two successive runs can produce: + +```text +OUTPUT/ +├── 20261111T143205Z-123e4567-e89b-42d3-a456-426614174000/ +│ ├── comparison-results.json +│ ├── comparison-configuration.json +│ └── comparison-report.html +└── 20261111T145810Z-123e4567-e89b-42d3-a456-426614174001/ + ├── comparison-results.json + ├── comparison-configuration.json + └── comparison-report.html +``` + +Each run directory contains exactly these three regular evidence files. +Packages are validated and generated in private staging on the destination +filesystem before publication. The destination must support exclusive +directory rename; +if safe publication is unavailable, the run returns `output.write_failed` +and preserves existing content. + +The output parent may already exist and contain any files or directories. +Existing contents and permissions are preserved. If the parent does not exist, +the tool creates it privately; its enclosing directory must already exist. +The selected parent cannot be a symbolic link, regular file, or special +filesystem object. Symbolic links in ancestor directories are permitted. + +Each complete or incomplete run publishes a new immediate child named +`YYYYMMDDTHHMMSSZ-`. The timestamp and full UUID come directly from that +result's UTC `run.completed_at` and `run.id`. Two runs can share a timestamp +without sharing a directory. An occupied run-directory path is an error; +the tool never replaces it or chooses a different name for that run. + +On error, no new evidence package is published and existing parent contents +remain intact. A parent created during publication preparation may remain +empty. Input and configuration errors do not create it. Private temporary +staging is cleaned up after success and, where safe, after an error. + +The completion summary's `Evidence package:` line identifies the published +child. With a relative `--output`, it shows the relative parent and child. +With an absolute `--output`, it shows only the parent basename and child; for +a filesystem-root parent it shows only the child name. Absolute paths are not +printed. For automation, retain the selected parent path and use the reported +child name to locate that run. The reported directory identifies this run +reliably; concurrent runs may finish in a different order from when they started. + +Retention and disposal of accumulated evidence remain the laboratory's +responsibility; the tool does not remove earlier runs or maintain a `latest` +pointer. + +`comparison-results.json` is the canonical result for software use and detailed +review. `comparison-configuration.json` retains the complete effective +configuration: the selected custom document or the generated automatic +document, including metadata and explicit declarations. Omitted optional +properties remain absent; internal defaults are not added. List order is +preserved. The saved file is JSON, rather than a copy of the source YAML bytes; +`--configuration` continues to accept only custom YAML. + +Both JSON files use UTF-8 without a byte-order mark, two-space indentation, LF +line endings, and exactly one final newline. Non-ASCII text is emitted directly +unless JSON escaping is needed. Fixed properties follow their schema order; +dynamic names use Unicode code-point order. Identical effective configurations +produce identical saved bytes, without run identifiers or timestamps. + +Keep the three files together. The results link to the saved configuration by +its exact-byte SHA-256 digest, as explained in Section 7.2.2. +`comparison-report.html` is a self-contained, offline view made solely from the +validated results and saved configuration, with verified linkage. It adds fixed +explanatory text and external review space, but no comparison facts. Rendering +does not reread the original YAML. The report opens in an ordinary browser, +works offline, and does not require scripting. + +The report separates run completeness, comparison differences, and assessment +issues. It does not apply acceptance thresholds or give a pass/fail verdict. + +## 7. JSON output reference + +The evidence package contains two JSON documents with different purposes: + +| File | Contents | +| --- | --- | +| `comparison-configuration.json` | The effective configuration: its identity, field definitions, scope, and comparison rules. | +| `comparison-results.json` | The run's findings, counts, statuses, input provenance, and digest link to the configuration. | + +The subsections below describe the fields in each document. Section 7.3 +explains how to validate them together. + +### 7.1 `comparison-configuration.json` + +This is the complete effective configuration selected or generated for the +run, saved as JSON. Its schema is +`comparison-configuration-v1.0.schema.json`, identified by its own root +`schema_version` value `"1.0"`. + +The three root properties are `schema_version`, `metadata`, and `fields`. +All are required. Their fields are: + +| Property | Meaning | +| --- | --- | +| `schema_version` | Configuration document format, currently `"1.0"`. | +| `metadata.id` | Stable identifier of the configuration. | +| `metadata.revision` | Revision assigned by its owner, or by the tool for automatic mode. | +| `metadata.title` | Optional human-readable title. | +| `metadata.description` | Optional human-readable description. | +| `fields.record_key` | Ordered canonical field names identifying records. | +| `fields.in_scope` | Canonical fields selected for assessment, including the key fields. | +| `fields.definitions` | Definitions indexed by canonical field name. Each definition associates source names and supplies the field's requiredness, null policy, comparison rule, and any declared type or transformations. | + +Sections 5.4–5.13 describe the permitted configuration properties, values, +constraints, and interactions; the [field-definition reference](#55-field-definitions) +lists the settings within each `fields.definitions` entry. The same structure +applies to a parsed custom YAML configuration and to this saved JSON document. Metadata does not change +the comparison rules. + +The saved configuration preserves explicit declarations and list order. +Optional properties that were omitted remain absent; internal defaults are +not added. In automatic mode, `metadata.id` is +`adviso-compare:automatic-strict-exact` and `metadata.revision` is `"1.0"`. This +revision identifies the generated configuration, separately from its schema +version. + +The saved document contains no run ID or completion timestamp. Its identity +and revision are read here rather than duplicated in the results. Results link +to its exact saved bytes through `comparison_configuration_digest`. + +### 7.2 `comparison-results.json` + +This document describes the comparison outcome. Its schema is +`comparison-results-v1.0.schema.json`, identified by its root `schema_version` +value `"1.0"`. For automation, use structured properties, classifications, +and finding codes; the English `message` text is intended for human readers. + +The required root properties are: + +| Property | Meaning | +| --- | --- | +| `schema_version` | Results document format. | +| `run` | Run identity, status, and completion time. | +| `phases` | Completion status of each comparison phase. | +| `software` | Software identity and version used for the run. | +| `runtime` | Python, platform, and Unicode-data provenance. | +| `inputs` | Basenames, formats, sizes, and exact-byte input digests. | +| `record_key_fields` | Ordered reference, query, and canonical key-field names. | +| `comparison_configuration_digest` | SHA-256 link to the saved configuration bytes. | +| `summary` | Record, value-opportunity, and finding counts. | +| `exclusions` | Fields outside the comparison scope. | +| `findings` | Individual comparison differences and assessment issues. | + +Empty `exclusions` and `findings` arrays remain present. Unknown properties +are rejected at the defined object levels. + +#### 7.2.1 Run and provenance + +| Property | Meaning | +| --- | --- | +| `schema_version` | Must be `"1.0"`, identifying the results format. | +| `run.id` | Random lowercase UUID version 4 for this run. | +| `run.status` | `complete` or `incomplete`. Error runs do not produce this JSON. | +| `run.completed_at` | Completion time in UTC, as `YYYY-MM-DDTHH:MM:SSZ`. | +| `phases.contract` | `complete` or `incomplete` contract-phase status. | +| `phases.records` | `complete` or `incomplete` records-phase status. | +| `phases.values` | `complete` or `incomplete` values-phase status. | +| `software.name` | Always `adviso-compare`. | +| `software.version` | Installed software version. | +| `software.build` | Optional non-empty build identifier when one is available. | +| `runtime.python` | Python implementation and full version, such as `cpython-3.12.7`. | +| `runtime.platform` | General operating-system family and architecture, such as `linux-x86_64`; no host identity. | +| `runtime.unicode_version` | Unicode database version used by text operations. | + +`inputs.reference` and `inputs.query` each contain: + +| Property | Meaning | +| --- | --- | +| `basename` | Input filename without its directory. Treat this as potentially sensitive. | +| `format` | `csv`, `tsv`, or `json`. | +| `encoding` | Always `utf-8`. | +| `size_bytes` | Exact input size in bytes. | +| `digest.algorithm` | Always `sha256`. | +| `digest.value` | Lowercase 64-character SHA-256 digest of the exact bytes. | + +Absolute paths, usernames, hostnames, environment variables, working +directories, raw command lines, and dependency inventories are not included. + +#### 7.2.2 Record keys and configuration digest + +`record_key_fields.reference`, `.query`, and `.canonical` are ordered, +non-empty arrays of unique field names. Their common order is the component +order of a composite key. + +The required top-level `comparison_configuration_digest` has exactly two +properties: + +| Property | Meaning | +| --- | --- | +| `algorithm` | Always `sha256`. | +| `value` | Lowercase 64-character SHA-256 digest of the exact saved `comparison-configuration.json` bytes, including the final newline. | + +Verify this digest against the file bytes before parsing or reserializing the +configuration. It is not a digest of the custom source YAML. Even a whitespace +edit to the saved JSON changes its digest. The digest establishes content +linkage; it does not prove authenticity or laboratory approval. + +The configuration's schema version, ID, and revision are held in the saved +document's `schema_version`, `metadata.id`, and `metadata.revision`. They are +not duplicated in the results. The sibling filename is fixed; no configuration +path, URI, or alternative filename is selected by the results document. + +#### 7.2.3 Summary and exclusions + +`summary.records` contains non-negative counts: `reference`, `query`, `matched`, +`missing`, and `extra`. The reference count equals matched plus missing; the +query count equals matched plus extra. + +`summary.values` contains `matched`, `mismatched`, and `not_assessable` counts +for all in-scope non-key value opportunities. Each opportunity appears in +exactly one count. + +`summary.findings.total` is the total number of findings. +`by_classification` always contains `comparison_difference` and +`assessment_issue`. `by_code` always contains all eight finding codes. +`by_review_priority` always contains `low`, `normal`, `high`, and `unassigned`. +Zero-valued entries remain present. Each grouping sums to `total`. + +Each item in `exclusions` has one of two exact forms: + +- `configured_field_excluded`: `code` and `canonical_field`; +- `undeclared_field_excluded`: `code`, `side` (`reference` or `query`), + `source_field`, and non-negative `record_count`. + +Exclusions are not findings and do not affect run status. + +#### 7.2.4 Finding properties + +Every finding has `id`, `classification`, `code`, `phase`, `message`, and +`affected_side`. + +- `id` is a report-local sequence such as `F000001`. +- `classification` is `comparison_difference` or `assessment_issue`. +- `code` is one of the eight codes in Section 3.2.3. +- `phase` is `contract`, `records`, or `values`. +- `message` is deterministic English presentation text. It adds no fact that is + absent from the structured fields. +- `affected_side` is `reference`, `query`, or `both`, as allowed for the code. + +Properties are included only when their finding form needs them: + +| Property | Meaning | +| --- | --- | +| `record_identity` | Ordered `reference`, `query`, and `canonical` value arrays. A missing record's absent side is JSON null. A one-field key still uses a one-item array. | +| `source_locations` | Independent `reference` and `query` locations; a side is null if its record does not exist. | +| `field` | Canonical field name for a field finding. | +| `review_priority` | Resolved `low`, `normal`, or `high` priority for that field. | +| `values` | Side-specific presence and permitted value evidence. | + +CSV and TSV locations use one-based `record_number` and starting physical +`line_number`, with optional source `field`. JSON locations use an RFC 6901 +`json_pointer`. An absent field points to its containing record because the +missing member has no location. + +`values.reference` and `values.query` each have `state`: `present` or `absent`. +An absent side has no `source` or `canonical` value. A present side may include: + +- `source.category`: `string`, `integer`, `decimal`, `boolean`, `null`, `array`, + or `object`; `value` is present except for null and recursively contains typed + values for arrays and objects; +- `canonical.logical_type`: `string`, `integer`, `decimal`, `boolean`, `date`, + `datetime`, `list`, `set`, or `multiset`; scalar and collection forms contain + their uniquely rendered `value`, and collections also contain `element_type`. + +Source numbers retain their original lexical text. Canonical integers use +ordinary base-10 text. Canonical decimals use one normal scientific rendering. +Canonical datetimes are UTC. Lists retain order; sets and multisets use +deterministic order, with multiset duplicates retained. + +The schema defines exact finding forms. In summary: + +- missing and extra records have record identity and locations, but no field, + priority, or value evidence; +- record-specific missing-required-field findings have identity, locations, + field, priority, and presence states; the zero-record dataset-level form has + only field and priority in addition to the common properties; +- type, invalid-value, null-policy, and mapping findings have identity, + locations, field, priority, and only the value evidence needed to explain the + problem; +- value mismatches have identity, locations, field, priority, and evidence for + both sides. + +### 7.3 Structural and semantic validation + +The supported combination is results schema `1.0` with configuration schema +`1.0`. These formats are independently versioned. + +A JSON schema describes a document's permitted structure and values. The two +schemas are installed as resources in the `adviso_compare.schemas` Python +package. + +Select a schema using the document family and its root `schema_version`. +The fixed filenames distinguish the document families; the bare version string +does not identify a schema globally. Their canonical `$id` values identify +distinct schemas. Select supported schemas from trusted installed resources, +without downloading schemas or constructing arbitrary paths from document values. + +The software version and the two schema versions have separate lifecycles. +Supporting a compatible configuration format need not change the results +schema; features that change results structure or meaning can require a results +schema revision. Software must support the selected combination, rather than +assuming that the two version strings must match. + +Validation has three layers: + +| Layer | What it establishes | +| --- | --- | +| Independent structural validation | Each JSON document conforms to its own supported schema, including required properties, permitted values, finding forms, and recognised formats. The results schema neither loads the configuration schema nor constrains its version. | +| Exact-byte linkage | The required configuration sibling exists and its saved bytes match `comparison_configuration_digest`. | +| Semantic validation | The configuration rules, result counts, statuses, findings, and configuration-derived facts agree, using source comparison context where available. | + +A results-schema check alone is not full package validation. A valid digest +also does not establish that the configuration or comparison is semantically +valid. To inspect a saved package, use the Python interpreter from the +environment where `adviso-compare` is installed: + +- For installation with `pip`, activate the environment used in Section 2.1. + Its `python` command can import the installed package. +- For the `pipx` installation in Section 2.2, run `pipx list` and find the + directory shown after `venvs are in`. The tool's environment is the + `adviso-compare` directory within it. The interpreter paths are: + + | Platform | Python interpreter | + | --- | --- | + | macOS or Linux | `/adviso-compare/bin/python` | + | Windows | `\adviso-compare\Scripts\python.exe` | + + Replace `` with the reported path. When starting an + interpreter whose path contains spaces, quote its full path; in PowerShell, + precede a quoted executable path with `&`. + +Change into the published run directory, start that Python interpreter, and +paste the following code at its prompt. `Path(".")` selects the current run +directory: + +```python +from pathlib import Path + +from adviso_compare.reporting import validate_evidence_package + +validate_evidence_package(Path(".")) +print("Package checks passed for the saved evidence.") +``` + +The function returns normally on success and raises `ResultValidationError` +if the JSON evidence cannot be read or validated, or the package members are +invalid. It requires exactly the three fixed regular files. Its JSON +validation procedure is: + +1. Parse results as strict UTF-8 JSON, rejecting duplicate object members, + non-standard number constants, and non-finite numbers. Select the supported + results schema by document family and root `schema_version`, and validate + with format assertion enabled. +2. Require the fixed sibling `comparison-configuration.json` to be a readable + regular file, rejecting missing files, symbolic links, and other filesystem + objects. Read its exact bytes without following an alternative filename. +3. Compare SHA-256 of those bytes, including the final newline, with the + result's `comparison_configuration_digest` before using the contents. +4. Parse the configuration with the same strict JSON rules and independently + select and validate its schema using its own `schema_version`. +5. Check that the software supports the two schema versions together, then + validate configuration semantics. Saved automatic configurations are valid + evidence; the reserved-ID restriction still applies to custom YAML inputs. +6. Apply result and cross-document semantic checks using the saved + configuration and any available comparison context. + +Both structural validators use JSON Schema Draft 2020-12 format assertion. +If you implement these checks independently, enable equivalent format checking +(for example, `Draft202012Validator(schema, format_checker=FormatChecker())` +with Python's `jsonschema` package). With format checking enabled, the +validator rejects invalid recognised UUID, date, and date-time formats. Schemas are loaded from trusted local +package resources; no network access or schema registry linking the two +formats is needed. + +Semantic checks available from the saved documents include: + +- overall status agrees with phase statuses; +- record equations, value-opportunity counts, and finding totals reconcile; +- key field-name and identity arrays have the required lengths and order; +- findings and exclusions have the required order and no duplicates; +- finding IDs are sequential after sorting; and +- key declarations, finding field identities, review priorities, and + configured-field exclusions agree with the saved configuration. + +Before publication, `adviso-compare` additionally has the parsed input datasets +and comparison-phase results. It checks that the saved configuration agrees +with the selected effective configuration, input provenance matches the parsed +inputs, findings and summaries match the phase results, and undeclared-field +exclusions match observed source fields. Inspection of a saved package alone +cannot repeat those source-dependent checks or prove that the comparison was +performed correctly. Independent reproduction requires the original input +bytes and suitable comparison context. The snippet checks the saved JSON +pair and package membership; it does not regenerate or authenticate the HTML +report. + +The normative details are in [Specification Section 9.1.4](SPECIFICATION.md#914-structural-and-semantic-package-validation). + +## 8. Errors and corrective action + +The first error line has the form: + +```text +ERROR [category.code]: message +``` + +| Code or category | What to check | +| --- | --- | +| `invocation.invalid_arguments` | Run `adviso-compare --help`; supply all required options and no subcommand. | +| `configuration.unreadable` | Check the path and read permission. | +| `configuration.invalid_syntax` | Check UTF-8 YAML; remove aliases, anchors, tags, merges, and duplicate keys. | +| `configuration.schema_violation` | Use the reported YAML path to fix a missing, unknown, or invalid property. | +| `configuration.semantic_violation` | Check named fields, key rules, logical types, operations, mappings, and comparator compatibility. | +| `configuration.unsupported_version` | Use a configuration schema version supported by the installed tool. | +| `input.unreadable` | Check the input path and read permission. | +| `input.unsupported_format` | Give the input a single recognised `.csv`, `.tsv`, or `.json` extension. | +| `input.invalid_encoding` | Convert the input to valid UTF-8 without silent replacement. | +| `input.invalid_syntax` | Fix malformed CSV, TSV, or JSON syntax. | +| `input.invalid_structure` | Check headers, row widths, JSON root shape, record objects, and field names. | +| `input.invalid_record_key` | Ensure the chosen key is present, non-null, valid, and unique; in automatic mode remove ambiguity or use a custom configuration. | +| `resource.limit_exceeded` or `resource.exhausted` | Reduce input size or provide more resources, then rerun. No partial result is valid. | +| `output.invalid_destination` | Select a regular parent with an existing enclosing directory. Check whether the run-directory path is occupied; existing content is never replaced. | +| `output.write_failed` | Check parent-directory permissions, available storage, and filesystem support for exclusive directory rename. | +| `internal.unexpected` | Rerun once; if it persists, report the software version and safe reproduction details. Use synthetic examples when sharing reproduction details. | + +An assessment issue inside an otherwise readable and alignable dataset is a +finding, not an execution error. Review the evidence package for those issues. + +## 9. Security, governance, and limitations + +The tool operates locally and does not transmit inputs, configurations, or +results. The evidence package can contain sensitive laboratory or patient +information, including record identifiers, values needed to explain findings, +and input basenames. Store it with permissions, retention, backup, and disposal +controls suitable for the source data. The laboratory remains responsible for +appropriate pseudonymisation. + +On POSIX systems, newly created output parents and run directories have +owner-only permissions (`0700`), and evidence files use `0600`. Existing +parent permissions are retained. On other systems, apply the corresponding +filesystem access controls under laboratory policy. + +Routine terminal output and error diagnostics do not reproduce record +identifiers or source values. The tool does not provide de-identification, +identifier hashing, access control, encryption, or sensitivity policies. + +`adviso-compare` compares one complete reference dataset with one complete query +dataset. It does not download data, run a bioinformatics pipeline, subset a +validation dataset, apply acceptance thresholds, decide fitness for purpose, +or produce a complete ISO 15189 validation dossier. It supports the evidence +review that forms part of a wider, governed validation process. + +There is no fixed input-size or record-count limit. Available memory, +storage, and operating-system resources still impose practical limits. Resource +exhaustion produces an error and no partial evidence package. + +## 10. Reproducing the examples + +The examples use synthetic, non-sensitive data. Section 5.1 provides complete +file contents to save yourself. The other example inputs and YAML are +hand-maintained fixtures under `docs/examples/`, installed next to this guide. +No generation script is needed. Their expected stable outcomes are: + +| Example | Status | Comparison differences | Assessment issues | +| --- | --- | ---: | ---: | +| automatic (Section 3.1.1) | `complete` | 1 | 0 | +| small custom (Section 5.1) | `complete` | 1 | 0 | +| custom with transformations (Section 5.2) | `complete` | 1 | 0 | + +Run the commands in Sections 3.1.1, 5.1, and 5.2, then open the run directory +identified by each completion summary and validate the complete package +as shown in Section 7.3. The same output parents can be reused: each invocation +adds a new run directory. Run IDs and completion times change on every run. +Software and runtime provenance can change between environments. Input digests +change if the fixture bytes are edited. The comparison outcome above remains +the controlled check. diff --git a/packages/adviso-compare/docs/VERIFICATION_REPORT.md b/packages/adviso-compare/docs/VERIFICATION_REPORT.md new file mode 100644 index 0000000..ce9b1f1 --- /dev/null +++ b/packages/adviso-compare/docs/VERIFICATION_REPORT.md @@ -0,0 +1,404 @@ +# `adviso-compare` version 1 release-candidate verification + +Date: 10 November 2026 + +## Candidate reviewed + +This review covers the version 1 implementation in +`packages/adviso-compare`, based on Git revision `d1fd7a3` plus the uncommitted +Step 12 documentation, example, packaging, and verification changes present in +the working tree on the date above. It is therefore a development-candidate +review, not an attestation of an immutable release artefact. + +The behaviour specification and both version 1.0 schemas were treated as the +sources of truth. The candidate supports Python 3.10 or later in its package +metadata. Verification in this environment used CPython 3.10.12 on +Linux x86_64. + +## Outcome + +The implementation and documentation checks available in this environment +passed. The complete automated suite contains 300 passing tests. Both +user-guide examples completed through the real application and produced the +documented results. The wheel and source archive were built, inspected, and +installed in isolated environments. The installed executable completed the +tested automatic, custom, incomplete, and expected-error paths. + +This is not yet sufficient evidence for a final release decision. The supported +Python and operating-system matrix, CI enforcement, and independent review are +not available in this workspace and remain release-time evidence. + +## Automated evidence + +Command: + +```console +.venv/bin/pytest -q +``` + +Result: `300 passed in 29.48s`. + +The suite covers: + +- CSV, TSV, and JSON parsing, malformed inputs, retained locations, exact JSON + numbers, and deterministic field discovery; +- custom configuration loading, schema validation, semantic checks, mappings, + normalisation, collection representations, and automatic configuration; +- custom, preferred `record_id`, and discovered record keys, including invalid, + duplicate, and ambiguous keys; +- contract, record alignment, all version 1 comparators, findings, counts, + exclusions, completeness, ordering, and determinism; +- canonical-result assembly, JSON Schema validation with format assertion, and + semantic self-validation; +- HTML rendering, atomic publication, overwrite protection, rollback, and + cleanup; +- command options, completion summaries, exit codes, expected diagnostics, and + the unexpected-error boundary; +- wheel and source-archive construction and installation, packaged schemas, + wheel integrity metadata, the installed command, and end-to-end operation; + and +- structural validation and end-to-end execution of the automatic and custom + examples supplied with the user guide. + +Focused documentation and distribution checks were also run before the full +suite. After the final documentation edit, the full suite reran all of them. + +## Inspection-based evidence + +The user guide was reviewed against the command interface and both schema +property sets. It documents: + +- installation, verification, all command options, overwrite rules, exit + codes, and offline operation after installation; +- CSV, TSV, and JSON input rules; +- automatic key selection and generated strict-exact comparison behaviour; +- every custom-configuration property, optional-property behaviour, + operations, mappings, collections, comparators, and processing order; +- phases, classifications, finding codes, run status, and the absence of an + acceptance verdict; +- every canonical-results property and the conditional finding forms; +- the distinction between JSON Schema validation and semantic result + validation, including a format-asserting validation example; +- evidence-package and HTML interpretation, diagnostics and corrective action, + security boundaries, limitations, and fixture reproduction; and +- software and schema versions to which the guide applies. + +The examples use only small synthetic data. Their source files are maintained +directly under `docs/examples`; no hidden generator or external data is needed. +Each run has one comparison difference, no assessment issue, and complete +status. Variable run IDs, completion times, software/runtime provenance, and +byte evidence are deliberately not treated as fixed fixture output. + +The package README now points users to the full guide and gives the complete +command shape. Command-line help describes every option and directs users to +the guide. The guide and examples are present in both built distribution forms +and install under `share/doc/adviso-compare`. + +## Static, schema, and packaging checks + +The following checks passed: + +```console +git diff --check +.venv/bin/python -m compileall -q src tests +.venv/bin/adviso-compare --help +.venv/bin/adviso-compare --version +``` + +Both JSON schemas pass Draft 2020-12 schema checks in the test suite. Test +documents and generated example results are validated with format assertion and +the configuration-schema reference registered locally. + +No formatter, linter, type checker, Markdown checker, or link checker is +configured for this package. None was introduced during Step 12. Consequently, +there is no claim that such a check passed. + +## Process and release-time evidence still required + +The following items cannot be established by this local candidate review: + +- execution across the full supported Python and operating-system matrix; +- cross-environment invariance, including Unicode-sensitive behaviour; +- CI operation on proposed changes and protected branches; +- independent review of the release candidate and its controlled fixtures; +- immutable release version, release notes, compatibility statement, and + change-impact assessment; +- signing or other attestation of final source and build artefacts, if adopted; + and +- confirmation that the final published artefacts are byte-for-byte the ones + reviewed and approved. + +The current environment exposes only CPython 3.10.12. Package metadata says +`>=3.10`, so testing only this interpreter does not satisfy the supported- +version matrix requirement. The repository currently has no CI workflow to +provide that missing evidence. These are release blockers under the present +specification, not failures of the local behavioural suite. + +## Resource statement + +The candidate sets no fixed input-size or record-count safeguard. Comparisons +attempt to assess all configured content. Practical capacity depends on the +available memory, storage, and operating-system resources. The error boundary +handles memory exhaustion without publishing a partial evidence package, but +this review did not establish operational capacity limits for particular +dataset sizes. + +## Release-decision summary + +The candidate is suitable for independent review and supported-matrix testing. +No failure found in this Step 12 review requires a change to the documented +comparison behaviour or either normative schema. A final version 1 release +should not be declared solely from this report: the matrix, CI, independent +review, and immutable release evidence listed above still need to be supplied +or the corresponding release requirements deliberately revised. + +## Output-parent publication verification — 11 November 2026 + +This additional development verification covers Git revision `47dbecd` plus +the output-parent specification, test, implementation, and documentation +changes in the working tree. It is not an immutable-release attestation. The +earlier candidate review above remains a record of that candidate. + +The environment was CPython 3.12.16 on macOS arm64. The full suite command was: + +```console +.venv/bin/python -m pytest packages/adviso-compare/tests -q --tb=short --junitxml=.venv/output-directory-implementation-results.xml +``` + +Result: **317 passed in 14.66s**, with no failures, errors, or skips. + +The revised tests verify: + +- complete and incomplete evidence published as a new immediate child of an + eligible output parent, with the fixed two members and exact validated bytes; +- names derived from controlled completion timestamps and full run UUIDs; +- eligible existing parents with arbitrary contents, private parent creation, + rejection of ineligible parents, and preserved existing permissions; +- successive and concurrent runs, including an initially absent shared parent + and distinct runs with the same timestamp; +- occupied run paths of different filesystem kinds, both before staging and + appearing after staging, preserved with a collision error; +- staging-write and publication failures, including unavailable exclusive + rename support, with existing evidence preserved and owned staging cleaned; +- early errors that neither create a parent nor touch its existing contents; +- rejection of unsupported CLI arguments, updated help, and actual child-path + reporting with relative, absolute, and filesystem-root parents; +- schema-valid controlled examples and both schema definitions; and +- wheel and source-archive builds and installation, packaged schemas and + documentation, and installed-wheel CLI execution including repeated runs, + complete and incomplete results, and expected errors. The installed guide + is checked byte for byte against the maintained source guide. + +The distribution harness retains its existing dependency arrangement: the +installed-command environments obtain dependencies through the development +environment's site-packages. This check does not establish independent clean +dependency resolution. + +The following additional checks passed: + +```console +.venv/bin/python -m pip check +.venv/bin/python -m compileall -q packages/adviso-compare/src packages/adviso-compare/tests +.venv/bin/adviso-compare --help +.venv/bin/adviso-compare --version +git diff --check +``` + +Local links and fenced examples in the maintained README, guide, and +specification were checked. Requirement definitions are unique and their +references resolve. The schemas, their version identifiers and canonical +`$id` values, dependencies, and packaging configuration are unchanged. The +editable development installation was refreshed; its offline guide and +examples were synchronized separately because editable installation does not +copy these data files. + +Publication uses exclusive directory rename rather than an existence check +followed by a potentially replacing rename. API behaviour was reviewed against +the [Linux rename documentation](https://man7.org/linux/man-pages/man2/rename.2.html), +[Apple's rename documentation](https://github.com/apple-oss-distributions/xnu/blob/main/bsd/man/man2/rename.2), +and [Python's Windows rename contract](https://docs.python.org/3/library/os.html#os.rename). +The macOS native operation was exercised by the suite. Linux and Windows +native operations were not executed: this environment has no corresponding +test hosts or Linux container runtime. Full supported-platform and Python +matrix verification, CI enforcement, and independent review remain release +work. No formatter, linter, type checker, or Markdown linter is configured; +none is claimed to have passed. + +## User documentation verification — 11 November 2026 + +The output-directory plan's documentation step was reviewed against the +approved specification and implemented CLI. The package README and guide +describe the initial-release interface directly, including output-parent +eligibility and creation, run-directory names and members, safe publication, +errors, retention, and privacy-preserving completion paths. The guide includes +a representative completion summary and explains how to locate the HTML +report and repeat a comparison under the same parent. No interface evolution +or migration narrative was added. + +The console commands in guide Sections 4.1 and 5.11 were extracted and executed +directly with the supplied synthetic fixtures in a temporary working directory. +Each command was run twice with the same output parent. All four invocations +completed with one comparison difference and no assessment issues. Each +produced a distinct two-file package, and each first package's canonical JSON +remained byte-identical after the second run. The Python validation snippet +from Section 8.5 was executed unchanged from each published run directory and +passed for all four results. + +```console +.venv/bin/python -m pytest packages/adviso-compare/tests/test_documentation.py packages/adviso-compare/tests/test_distribution.py packages/adviso-compare/tests/test_schemas.py -q +git diff --check +``` + +Result: **10 passed in 13.21s**; `git diff --check` passed. These checks include +wheel and source-archive installation and equality of the installed wheel's +guide with the maintained guide. Local documentation links, code fences, and +current CLI references were checked. The editable environment's offline guide +was synchronized separately and confirmed to match the maintained guide. + +Production code, tests, schemas, dependencies, and packaging metadata were +unchanged during this documentation step. The full behavioural suite was not +rerun; the preceding implementation verification remains 317 passing tests. +No additional platform-matrix, lint, or type checks were run for this step; +the limitations recorded above still apply. + +## Separate configuration evidence verification — 11 November 2026 + +This development verification covers Git revision `b360d74` plus the working-tree +specification, schema, implementation, test, and documentation changes for the +three-file evidence package. It is not an immutable-release attestation. Earlier +sections remain records of their respective candidates. + +The environment was CPython 3.12.16 on macOS arm64. The final suite command was: + +```console +.venv/bin/python -m pytest packages/adviso-compare/tests -q --tb=short --junitxml=.venv/separate-configuration-final.xml +``` + +Result: **376 passed in 16.50s**, with no failures, errors, or skips. + +The verified contract includes: + +- exactly three fixed regular members: `comparison-results.json`, + `comparison-configuration.json`, and `comparison-report.html`; +- complete effective configuration preservation in custom and automatic modes, + including metadata, explicit declarations, list provenance, absent defaults, + canonical UTF-8 serialization, and immutable independent document views; +- results root `schema_version` and top-level + `comparison_configuration_digest`, with SHA-256 calculated from the exact + configuration bytes published, including their final newline; +- independent family/version schema selection, preserved canonical schema IDs + and `1.0` identifiers, no results-to-configuration schema reference, format + assertion, and explicitly supported schema combinations; +- strict JSON parsing, required configuration context, missing/unreadable or + non-regular configuration files, unsupported versions, malformed or duplicate + members, digest tampering, and cross-document semantic contradictions; +- retained finding, count, status, key, priority, exclusion, input-provenance, + and available comparison-context checks; +- HTML generation from the validated JSON pair, with no original-YAML reread; +- private staging of all three files, failure at each member write, exclusive + publication, preservation of existing content, collision handling, and + successive/concurrent runs; and +- automatic/custom and complete/incomplete integration, wheel and sdist builds + and installation, installed resources, and installed-wheel command execution. + +Existing tests were adapted at their established boundaries. The documentation +example test now extracts and executes the guide's package-validation snippet +against both generated example packages. No separate fixture family, helper +module, dependency, command, or test-framework change was introduced. The +configuration schema is unchanged. The revised results schema retains its +canonical ID and version while representing the initial-release contract. + +The README and guide describe the package directly, including independent +schema identities, exact-byte linkage, saved configuration metadata, and the +supported version combination. The guide distinguishes structural validation, +digest verification, and semantic checks, including which checks require source +comparison context. Its runnable procedure calls the installed +`validate_evidence_package` function; the text also describes trusted schema +selection and equivalent format assertion for independent consumers. It +explicitly limits saved-package inspection to available evidence and does not +claim HTML authentication or reproduction of the comparison from its inputs. + +The focused documentation, distribution, and schema check was: + +```console +.venv/bin/python -m pytest packages/adviso-compare/tests/test_documentation.py packages/adviso-compare/tests/test_distribution.py packages/adviso-compare/tests/test_schemas.py -q --tb=short --junitxml=.venv/separate-configuration-step5.xml +``` + +Result: **41 passed in 14.40s**. The installed wheel's guide is checked byte for +byte against the maintained guide. The distribution harness uses development +site-packages for dependencies; this is not independent dependency resolution. + +Both console commands from guide Sections 4.1 and 5.11 were separately extracted +and executed twice in a temporary copy of the supplied synthetic examples. +All four runs completed with one comparison difference and no assessment +issues. Each produced a distinct three-file package. The first package's three +files remained byte-identical after the second run. The Section 8.5 Python +snippet was extracted and executed unchanged from all four run directories; +all passed. + +Compilation, dependency consistency, and `git diff --check` passed. Local links, +heading fragments, and code fences in the repository README, package README, +guide, and specification were checked. Normative requirement definitions are +unique and their references resolve. A source search found no obsolete result +version property or embedded-configuration access in runtime code, tests, +schemas, the specification, or maintained user documentation. Earlier +development plans and verification records were not rewritten as current +product instructions. The editable environment's offline guide was synchronized +and confirmed byte-identical; its installed examples also match source. + +Production code, normative sources, dependencies, and packaging metadata were +unchanged during this documentation step. The implemented behaviour, schemas, +tests, and maintained documentation now agree on this functionality change. +Linux, Windows, other supported Python versions, CI enforcement, independent +review, and immutable release evidence remain release verification work. No +formatter, linter, type checker, or Markdown linter is configured, and none is +claimed to have run. Local completion of this change does not establish release +readiness across the supported matrix. + +## CI configuration and Python support verification — 2026-11-12 + +The supported runtime matrix is now CPython 3.11–3.15 on Linux, macOS, and +Windows. Package metadata sets Python 3.11 as the installation minimum. The +specification, README, user guide, architecture guide, and contribution guide +reflect this policy. Earlier interpreter and CI statements in this report +record the environments and configuration at their respective verification dates. + +The repository now contains `.github/workflows/adviso-compare-ci.yml`. It +configures all 15 Python/OS combinations, runs on pull requests into `main`, +pushes to `main`, a weekly schedule, and manual dispatch, and retains reports, +built archives, and dependency records for 30 days. The final +`adviso-compare CI passed` job requires every matrix job to succeed. No release +publication, formatter, linter, or type checker was added to the CI checks. + +The existing distribution test is parameterized over wheel and source archive. +Each archive is installed with its declared dependencies in a fresh environment, +with source builds isolated, outside the checkout and without development +`PYTHONPATH`. Both cases exercise version reporting, installed resources, +automatic/custom comparisons, repeated publication, expected errors, and saved +package validation. Dependency consistency and installed module locations are +checked. The built metadata test was first confirmed to fail against the former +minimum, then passed after updating package metadata. + +Local verification used CPython 3.12.16 on macOS ARM64: + +```console +python -m pytest packages/adviso-compare/tests -q --junitxml=ci-output/tests.xml --basetemp=ci-output/tmp +``` + +Result: **397 passed in 35.33s**, with `ci-output/` created before invoking pytest. +The focused clean installation run also passed both archive cases. These checks +used network access to obtain declared dependencies. The development editable +installation was refreshed for the updated metadata and bundled guide. + +Additional checks passed: temporary checksum-verified `actionlint` 1.7.12 +validation (without optional shellcheck/pyflakes integrations), YAML trigger and +15-job matrix checks, action commit-pin checks, package metadata inspection, +`pip check`, Python compilation, local documentation links/anchors and code +fences, and `git diff --check`. No schema content or comparison behaviour changed. + +This is local verification of the implementation, not evidence that the hosted +matrix passed. GitHub execution of all supported environments, branch-protection +configuration, and release review remain outstanding. Repository settings must +require the named final CI check; committing the workflow alone does not enforce +merging policy. Another person's approval is not a required merge check under +the chosen policy. These records do not attest an immutable release artefact. diff --git a/packages/adviso-compare/docs/examples/automatic/query.csv b/packages/adviso-compare/docs/examples/automatic/query.csv new file mode 100644 index 0000000..b32a8f4 --- /dev/null +++ b/packages/adviso-compare/docs/examples/automatic/query.csv @@ -0,0 +1,4 @@ +sample_id,lineage,comment,pipeline_version +SAMPLE-001,L1,expected,2.1 +SAMPLE-002,L2,expected,2.1 +SAMPLE-003,L1,expected,2.1 diff --git a/packages/adviso-compare/docs/examples/automatic/reference.csv b/packages/adviso-compare/docs/examples/automatic/reference.csv new file mode 100644 index 0000000..da57248 --- /dev/null +++ b/packages/adviso-compare/docs/examples/automatic/reference.csv @@ -0,0 +1,4 @@ +sample_id,lineage,comment +SAMPLE-001,L1,expected +SAMPLE-002,L1,expected +SAMPLE-003,L1,expected diff --git a/packages/adviso-compare/docs/examples/custom/configuration.yaml b/packages/adviso-compare/docs/examples/custom/configuration.yaml new file mode 100644 index 0000000..9fa5a3e --- /dev/null +++ b/packages/adviso-compare/docs/examples/custom/configuration.yaml @@ -0,0 +1,162 @@ +schema_version: "1.0" + +metadata: + id: "org.example.user-guide-comparison" + revision: "1.0.0" + title: "User-guide comparison example" + description: "Synthetic rules showing representative version 1 features" + +fields: + record_key: + - "sample" + in_scope: + - "sample" + - "measurement" + - "interpretation" + - "markers" + definitions: + sample: + source_fields: + reference: "sample_id" + query: "specimen_id" + required: + reference: true + query: true + logical_type: "string" + null_policy: + allowed: false + nulls_equal: false + comparator: + name: "typed_exact" + measurement: + source_fields: + reference: "expected_value" + query: "reported_value" + required: + reference: true + query: true + logical_type: "decimal" + null_policy: + allowed: false + nulls_equal: false + typed_normalisation: + - operation: "decimal_quantise" + parameters: + places: 3 + rounding: "half_even" + comparator: + name: "numeric_tolerance" + parameters: + absolute_tolerance: "0.01" + review_priority: "high" + interpretation: + source_fields: + reference: "expected_interpretation" + query: "reported_interpretation" + required: + reference: true + query: true + logical_type: "string" + null_policy: + allowed: true + nulls_equal: true + missing_tokens: + reference: + - category: "string" + value: "NA" + query: + - category: "string" + value: "." + source_normalisation: + reference: + - operation: "trim" + parameters: + side: "both" + - operation: "case_fold" + query: + - operation: "trim" + parameters: + side: "both" + - operation: "case_fold" + value_mapping: + reference: + - from: + category: "string" + value: "detected" + to: + category: "string" + value: "detected" + - from: + category: "string" + value: "not detected" + to: + category: "string" + value: "not_detected" + query: + - from: + category: "string" + value: "pos" + to: + category: "string" + value: "detected" + - from: + category: "string" + value: "neg" + to: + category: "string" + value: "not_detected" + comparator: + name: "typed_exact" + review_priority: "normal" + markers: + source_fields: + reference: "expected_markers" + query: "reported_markers" + required: + reference: true + query: true + logical_type: + collection_type: "set" + element_type: "string" + element_comparator: + name: "typed_exact" + null_policy: + allowed: false + nulls_equal: false + collection_representation: + query: + format: "delimited_text" + delimiter: "/" + element_normalisation: + - operation: "trim" + parameters: + side: "both" + - operation: "case_fold" + element_mapping: + - from: + category: "string" + value: "wild_type" + to: + category: "string" + value: "WT" + - from: + category: "string" + value: "mutant" + to: + category: "string" + value: "MUT" + comparator: + name: "set_exact" + review_priority: "high" + curator_note: + source_fields: + reference: "curator_note" + query: "curator_note" + required: + reference: false + query: false + null_policy: + allowed: true + nulls_equal: true + comparator: + name: "preserved_exact" diff --git a/packages/adviso-compare/docs/examples/custom/query.csv b/packages/adviso-compare/docs/examples/custom/query.csv new file mode 100644 index 0000000..a304ff7 --- /dev/null +++ b/packages/adviso-compare/docs/examples/custom/query.csv @@ -0,0 +1,3 @@ +specimen_id,reported_value,reported_interpretation,reported_markers,pipeline_version +SAMPLE-001,1.239,pos,wild_type/mutant,2.1 +SAMPLE-002,2.7,neg,wild_type,2.1 diff --git a/packages/adviso-compare/docs/examples/custom/reference.json b/packages/adviso-compare/docs/examples/custom/reference.json new file mode 100644 index 0000000..9fca7ec --- /dev/null +++ b/packages/adviso-compare/docs/examples/custom/reference.json @@ -0,0 +1,16 @@ +[ + { + "sample_id": "SAMPLE-001", + "expected_value": 1.234, + "expected_interpretation": " DETECTED ", + "expected_markers": ["WT", "MUT"], + "curator_note": "synthetic example" + }, + { + "sample_id": "SAMPLE-002", + "expected_value": 2.5, + "expected_interpretation": "not detected", + "expected_markers": ["WT"], + "curator_note": "synthetic example" + } +] diff --git a/packages/adviso-compare/pyproject.toml b/packages/adviso-compare/pyproject.toml new file mode 100644 index 0000000..54b11db --- /dev/null +++ b/packages/adviso-compare/pyproject.toml @@ -0,0 +1,84 @@ +[build-system] +requires = [ + "setuptools>=69", + "setuptools-scm>=8", + "wheel", +] +build-backend = "setuptools.build_meta" + +[project] +name = "adviso-compare" +dynamic = ["version"] +description = "Translate, compare, and report differences between structured bioinformatics datasets." +readme = "README.md" +requires-python = ">=3.11" +authors = [ + { name = "Bruhad Dave", email = "bd8@sanger.ac.uk" }, +] +keywords = [ + "bioinformatics", + "data validation", + "ISO 15189", +] +classifiers = [ + "Development Status :: 2 - Pre-Alpha", + "Environment :: Console", + "Intended Audience :: Healthcare Industry", + "Intended Audience :: Science/Research", + "Operating System :: OS Independent", + "Programming Language :: Python :: 3", +] +dependencies = [ + "jsonschema[format-nongpl]>=4.23,<5", + "PyYAML>=6.0,<7", +] + +[project.optional-dependencies] +dev = [ + "build>=1.2,<2", + "pytest>=8,<9", + "setuptools>=69", + "setuptools-scm>=8", + "wheel", +] + +[project.scripts] +adviso-compare = "adviso_compare.cli:main" + +[tool.setuptools] +package-dir = { "" = "src" } +include-package-data = true + +[tool.setuptools.packages.find] +where = ["src"] +include = ["adviso_compare*"] +namespaces = false + +[tool.setuptools.package-data] +"adviso_compare.schemas" = ["*.json"] + +[tool.setuptools.data-files] +"share/doc/adviso-compare" = ["docs/USER_GUIDE.md"] +"share/doc/adviso-compare/examples/automatic" = [ + "docs/examples/automatic/query.csv", + "docs/examples/automatic/reference.csv", +] +"share/doc/adviso-compare/examples/custom" = [ + "docs/examples/custom/configuration.yaml", + "docs/examples/custom/query.csv", + "docs/examples/custom/reference.json", +] + +[tool.setuptools_scm] +root = "../.." +relative_to = "pyproject.toml" +version_file = "src/adviso_compare/_version.py" +fallback_version = "0.0.0" + +[tool.pytest.ini_options] +addopts = [ + "--strict-config", + "--strict-markers", +] +testpaths = ["tests"] +tmp_path_retention_policy = "failed" diff --git a/packages/adviso-compare/src/adviso_compare/__init__.py b/packages/adviso-compare/src/adviso_compare/__init__.py new file mode 100644 index 0000000..5a872ca --- /dev/null +++ b/packages/adviso-compare/src/adviso_compare/__init__.py @@ -0,0 +1 @@ +"""adviso-compare.""" diff --git a/packages/adviso-compare/src/adviso_compare/alignment.py b/packages/adviso-compare/src/adviso_compare/alignment.py new file mode 100644 index 0000000..0d1b41f --- /dev/null +++ b/packages/adviso-compare/src/adviso_compare/alignment.py @@ -0,0 +1,191 @@ +"""Align validated reference and query records by canonical identity.""" + +from __future__ import annotations + +from dataclasses import dataclass +from enum import Enum +from types import MappingProxyType +from typing import Mapping + +from adviso_compare.inputs import InputSide, SourceLocation +from adviso_compare.records import KeyedRecord, RecordKey, RecordModel + + +class RecordsPhaseStatus(str, Enum): + """Completion state of the records phase.""" + + COMPLETE = "complete" + + +class RecordDisposition(str, Enum): + """Relationship of one canonical key across the two datasets.""" + + MATCHED = "matched" + MISSING = "missing" + EXTRA = "extra" + + +@dataclass(frozen=True, slots=True) +class RecordAlignment: + """Reference and query records sharing one canonical key, where present.""" + + key: RecordKey + reference: KeyedRecord | None + query: KeyedRecord | None + disposition: RecordDisposition + + @property + def canonical_identity(self) -> tuple[str, ...]: + """Return the canonical textual key components in configured order.""" + record = self.reference if self.reference is not None else self.query + if record is None: + raise AssertionError("record alignment has neither side") + return record.canonical_identity + + +@dataclass(frozen=True, slots=True) +class RecordFinding: + """One missing- or extra-record difference for later evidence construction.""" + + alignment: RecordAlignment + + @property + def code(self) -> str: + """Return the stable finding code implied by the alignment.""" + if self.alignment.disposition is RecordDisposition.MISSING: + return "missing_record" + if self.alignment.disposition is RecordDisposition.EXTRA: + return "extra_record" + raise AssertionError("matched alignment cannot produce a record finding") + + @property + def classification(self) -> str: + """Return the fixed classification for record differences.""" + return "comparison_difference" + + @property + def phase(self) -> str: + """Return the phase in which this difference was detected.""" + return "records" + + @property + def affected_side(self) -> InputSide: + """Return the side from which the aligned record is absent.""" + if self.alignment.disposition is RecordDisposition.MISSING: + return InputSide.QUERY + if self.alignment.disposition is RecordDisposition.EXTRA: + return InputSide.REFERENCE + raise AssertionError("matched alignment cannot affect a side") + + @property + def reference_location(self) -> SourceLocation | None: + """Return the reference record location, or None when it is absent.""" + if self.alignment.reference is None: + return None + return self.alignment.reference.record.location + + @property + def query_location(self) -> SourceLocation | None: + """Return the query record location, or None when it is absent.""" + if self.alignment.query is None: + return None + return self.alignment.query.record.location + + +@dataclass(frozen=True, slots=True) +class RecordCounts: + """Reconciled record counts for later canonical summary generation.""" + + reference: int + query: int + matched: int + missing: int + extra: int + + +@dataclass(frozen=True, slots=True) +class RecordsResult: + """Complete deterministic alignment of two valid record models.""" + + status: RecordsPhaseStatus + alignments: tuple[RecordAlignment, ...] + findings: tuple[RecordFinding, ...] + counts: RecordCounts + _alignment_index: Mapping[RecordKey, RecordAlignment] + + def alignment(self, record_key: RecordKey) -> RecordAlignment: + """Return the alignment for one canonical record key.""" + return self._alignment_index[record_key] + + @property + def matched(self) -> tuple[RecordAlignment, ...]: + """Return safely aligned records available to the values phase.""" + return tuple( + alignment + for alignment in self.alignments + if alignment.disposition is RecordDisposition.MATCHED + ) + + +def align_records( + reference: RecordModel, + query: RecordModel, +) -> RecordsResult: + """Classify the union of two valid record-key indexes.""" + keys = set(reference.by_key) | set(query.by_key) + ordered_keys = sorted( + keys, + key=lambda key: tuple(component.text for component in key), + ) + alignments: list[RecordAlignment] = [] + findings: list[RecordFinding] = [] + + for key in ordered_keys: + reference_record = reference.by_key.get(key) + query_record = query.by_key.get(key) + if reference_record is not None and query_record is not None: + disposition = RecordDisposition.MATCHED + elif reference_record is not None: + disposition = RecordDisposition.MISSING + elif query_record is not None: + disposition = RecordDisposition.EXTRA + else: + raise AssertionError("record-key union contains no record") + alignment = RecordAlignment( + key=key, + reference=reference_record, + query=query_record, + disposition=disposition, + ) + alignments.append(alignment) + if disposition is not RecordDisposition.MATCHED: + findings.append(RecordFinding(alignment)) + + matched = sum( + alignment.disposition is RecordDisposition.MATCHED + for alignment in alignments + ) + missing = sum( + alignment.disposition is RecordDisposition.MISSING + for alignment in alignments + ) + extra = sum( + alignment.disposition is RecordDisposition.EXTRA + for alignment in alignments + ) + alignment_tuple = tuple(alignments) + return RecordsResult( + status=RecordsPhaseStatus.COMPLETE, + alignments=alignment_tuple, + findings=tuple(findings), + counts=RecordCounts( + reference=len(reference.records), + query=len(query.records), + matched=matched, + missing=missing, + extra=extra, + ), + _alignment_index=MappingProxyType( + {alignment.key: alignment for alignment in alignment_tuple} + ), + ) diff --git a/packages/adviso-compare/src/adviso_compare/application.py b/packages/adviso-compare/src/adviso_compare/application.py new file mode 100644 index 0000000..846a814 --- /dev/null +++ b/packages/adviso-compare/src/adviso_compare/application.py @@ -0,0 +1,96 @@ +"""Application orchestration boundary for adviso-compare.""" + +from __future__ import annotations + +from dataclasses import dataclass +from pathlib import Path +from typing import Callable + +from adviso_compare.alignment import align_records +from adviso_compare.configuration import ( + EffectiveConfiguration, + load_comparison_configuration, +) +from adviso_compare.contract import assess_contract +from adviso_compare.inputs import InputSide, ParsedDataset, load_dataset +from adviso_compare.invocation import ComparisonInvocation, ComparisonOutcome +from adviso_compare.records import ( + RecordModel, + build_record_model, + generate_automatic_configuration, +) +from adviso_compare.reporting import publish_evidence_package +from adviso_compare.results import assemble_result +from adviso_compare.values import compare_values + + +@dataclass(frozen=True, slots=True) +class PreparedComparison: + """Validated configuration selection and losslessly parsed input datasets.""" + + invocation: ComparisonInvocation + configuration: EffectiveConfiguration + reference: ParsedDataset + query: ParsedDataset + reference_records: RecordModel + query_records: RecordModel + + +def prepare_comparison( + invocation: ComparisonInvocation, + *, + configuration_loader: Callable[ + [Path], EffectiveConfiguration + ] = load_comparison_configuration, + dataset_loader: Callable[[Path, InputSide], ParsedDataset] = load_dataset, +) -> PreparedComparison: + """Validate any custom configuration before accessing either dataset.""" + configuration = None + if invocation.configuration is not None: + configuration = configuration_loader(invocation.configuration) + reference = dataset_loader(invocation.reference, InputSide.REFERENCE) + query = dataset_loader(invocation.query, InputSide.QUERY) + if configuration is None: + configuration = generate_automatic_configuration(reference, query) + reference_records = build_record_model( + reference, + configuration, + InputSide.REFERENCE, + ) + query_records = build_record_model( + query, + configuration, + InputSide.QUERY, + ) + return PreparedComparison( + invocation=invocation, + configuration=configuration, + reference=reference, + query=query, + reference_records=reference_records, + query_records=query_records, + ) + + +def execute_comparison(invocation: ComparisonInvocation) -> ComparisonOutcome: + """Run every comparison phase and publish its validated evidence package.""" + prepared = prepare_comparison(invocation) + contract = assess_contract( + prepared.configuration, + reference=prepared.reference, + query=prepared.query, + reference_records=prepared.reference_records, + query_records=prepared.query_records, + ) + records = align_records(prepared.reference_records, prepared.query_records) + values = compare_values(prepared.configuration, contract, records) + result = assemble_result(prepared, contract, records, values) + document = result.document() + finding_counts = document["summary"]["findings"]["by_classification"] + published = publish_evidence_package(invocation.output, result) + return ComparisonOutcome( + run_status=document["run"]["status"], + output=published, + comparison_differences=finding_counts["comparison_difference"], + assessment_issues=finding_counts["assessment_issue"], + ) diff --git a/packages/adviso-compare/src/adviso_compare/cli.py b/packages/adviso-compare/src/adviso_compare/cli.py new file mode 100644 index 0000000..710c14b --- /dev/null +++ b/packages/adviso-compare/src/adviso_compare/cli.py @@ -0,0 +1,134 @@ +"""Thin command-line adapter for adviso-compare.""" + +from __future__ import annotations + +import argparse +import sys +from importlib.metadata import version +from pathlib import Path +from typing import NoReturn, Sequence + +from adviso_compare.configuration import ConfigurationError +from adviso_compare.inputs import InputError +from adviso_compare.invocation import ComparisonExecutor, ComparisonInvocation +from adviso_compare.records import RecordKeyError +from adviso_compare.reporting import OutputError + + +class _ArgumentParser(argparse.ArgumentParser): + """Argument parser that emits the stable invocation-error diagnostic.""" + + def error(self, message: str) -> NoReturn: + """Report invalid command-line syntax without touching comparison inputs.""" + if not message.startswith("the following arguments are required:"): + message = "invalid command-line arguments; use --help for usage" + self.exit(2, f"ERROR [invocation.invalid_arguments]: {message}\n") + + +def _build_parser() -> argparse.ArgumentParser: + """Construct the version 1 direct comparison interface.""" + parser = _ArgumentParser( + prog="adviso-compare", + description=( + "Compare a reference dataset with a query dataset and write a " + "three-file evidence package." + ), + epilog=( + "Full user guide: share/doc/adviso-compare/USER_GUIDE.md in the " + "Python installation." + ), + allow_abbrev=False, + ) + parser.add_argument( + "--version", + action="version", + version=f"%(prog)s {version('adviso-compare')}", + help="show the installed software version and exit", + ) + parser.add_argument( + "--reference", + required=True, + type=Path, + metavar="REFERENCE", + help="reference dataset in CSV, TSV, or JSON format", + ) + parser.add_argument( + "--query", + required=True, + type=Path, + metavar="QUERY", + help="query dataset in CSV, TSV, or JSON format", + ) + parser.add_argument( + "--output", + required=True, + type=Path, + metavar="OUTPUT", + help="parent directory under which to create a new run directory", + ) + parser.add_argument( + "--configuration", + type=Path, + metavar="CONFIGURATION", + help=( + "custom YAML comparison configuration; omit to use automatic " + "strict-exact mode" + ), + ) + return parser + + +def parse_invocation(arguments: Sequence[str] | None = None) -> ComparisonInvocation: + """Parse command-line text into an immutable comparison invocation.""" + namespace = _build_parser().parse_args(arguments) + return ComparisonInvocation( + reference=namespace.reference, + query=namespace.query, + output=namespace.output, + configuration=namespace.configuration, + ) + + +def _display_output_path(path: Path) -> str: + """Render a run path with its parent context but no absolute path.""" + if not path.is_absolute(): + return str(path) + return str(Path(path.parent.name) / path.name) + + +def main( + arguments: Sequence[str] | None = None, + *, + executor: ComparisonExecutor | None = None, +) -> int: + """Execute one invocation behind the stable command-line error boundary.""" + try: + invocation = parse_invocation(arguments) + if executor is None: + from adviso_compare.application import execute_comparison + + executor = execute_comparison + outcome = executor(invocation) + except (ConfigurationError, InputError, RecordKeyError, OutputError) as error: + print(error.diagnostic, file=sys.stderr) + return 2 + except MemoryError: + print( + "ERROR [resource.exhausted]: available memory was exhausted; " + "reduce input size and retry", + file=sys.stderr, + ) + return 2 + except Exception: + print( + "ERROR [internal.unexpected]: an unexpected internal error occurred; " + "rerun and report the failure if it persists", + file=sys.stderr, + ) + return 3 + + print(f"Run status: {outcome.run_status}") + print(f"Comparison differences: {outcome.comparison_differences}") + print(f"Assessment issues: {outcome.assessment_issues}") + print(f"Evidence package: {_display_output_path(outcome.output)}") + return outcome.exit_code diff --git a/packages/adviso-compare/src/adviso_compare/comparators.py b/packages/adviso-compare/src/adviso_compare/comparators.py new file mode 100644 index 0000000..d9e8357 --- /dev/null +++ b/packages/adviso-compare/src/adviso_compare/comparators.py @@ -0,0 +1,244 @@ +"""Deterministic comparison of successfully translated field values.""" + +from __future__ import annotations + +from decimal import Decimal +from fractions import Fraction +from types import MappingProxyType +from typing import Callable, Mapping + +from adviso_compare.configuration import ( + CollectionLogicalType, + Comparator, + FieldDefinition, +) +from adviso_compare.inputs import NativeCategory, NativeValue +from adviso_compare.translation import ( + CanonicalValue, + TranslatedValue, + ValueDisposition, +) + + +ComparatorFunction = Callable[ + [FieldDefinition, TranslatedValue, TranslatedValue], bool +] + + +def compare_translated_values( + field: FieldDefinition, + reference: TranslatedValue, + query: TranslatedValue, +) -> bool: + """Apply one field's registered comparator to two valid translations.""" + if ( + reference.disposition is not ValueDisposition.VALID + or query.disposition is not ValueDisposition.VALID + ): + raise ValueError("comparators require two valid translated values") + if reference.is_null or query.is_null: + return ( + reference.is_null + and query.is_null + and field.null_policy.nulls_equal + ) + try: + comparator = _COMPARATORS[field.comparator.name] + except KeyError as error: + raise AssertionError("validated comparator is not registered") from error + return comparator(field, reference, query) + + +def _preserved_exact( + _field: FieldDefinition, + reference: TranslatedValue, + query: TranslatedValue, +) -> bool: + """Compare parser-native values recursively without lexical coercion.""" + if reference.preserved is None or query.preserved is None: + raise AssertionError("preserved comparator received no preserved value") + return _native_equal(reference.preserved, query.preserved) + + +def _native_equal(reference: NativeValue, query: NativeValue) -> bool: + """Apply parser-native category and recursive content equality.""" + if reference.category is not query.category: + return False + if reference.category is NativeCategory.ARRAY: + reference_values = _native_array(reference) + query_values = _native_array(query) + return len(reference_values) == len(query_values) and all( + _native_equal(reference_item, query_item) + for reference_item, query_item in zip(reference_values, query_values) + ) + if reference.category is NativeCategory.OBJECT: + reference_members = _native_object(reference) + query_members = _native_object(query) + if set(reference_members) != set(query_members): + return False + return all( + _native_equal(reference_members[name], query_members[name]) + for name in reference_members + ) + return reference.value == query.value + + +def _native_array(value: NativeValue) -> tuple[NativeValue, ...]: + """Return a validated parser-native array's elements.""" + if not isinstance(value.value, tuple) or not all( + isinstance(item, NativeValue) for item in value.value + ): + raise AssertionError("parser-native array has unexpected content") + return value.value + + +def _native_object(value: NativeValue) -> dict[str, NativeValue]: + """Return a validated parser-native object's members by name.""" + if not isinstance(value.value, tuple): + raise AssertionError("parser-native object has unexpected content") + members: dict[str, NativeValue] = {} + for member in value.value: + if ( + not isinstance(member, tuple) + or len(member) != 2 + or not isinstance(member[0], str) + or not isinstance(member[1], NativeValue) + ): + raise AssertionError("parser-native object has unexpected member") + if member[0] in members: + raise AssertionError("parser-native object has a duplicate member") + members[member[0]] = member[1] + return members + + +def _canonical_exact( + _field: FieldDefinition, + reference: TranslatedValue, + query: TranslatedValue, +) -> bool: + """Compare two canonical scalar values exactly.""" + return _canonical(reference) == _canonical(query) + + +def _numeric_tolerance( + field: FieldDefinition, + reference: TranslatedValue, + query: TranslatedValue, +) -> bool: + """Compare two canonical numbers with exact configured tolerance arithmetic.""" + reference_value = _canonical(reference).value + query_value = _canonical(query).value + return _numbers_within_tolerance( + reference_value, + query_value, + field.comparator, + ) + + +def _collection_exact( + field: FieldDefinition, + reference: TranslatedValue, + query: TranslatedValue, +) -> bool: + """Apply the declared ordered or unordered collection equality.""" + logical_type = field.logical_type + if not isinstance(logical_type, CollectionLogicalType): + raise AssertionError("collection comparator received a scalar field") + reference_value = _canonical(reference) + query_value = _canonical(query) + if reference_value.logical_type != logical_type.collection_type: + raise AssertionError("reference collection has unexpected logical type") + if query_value.logical_type != logical_type.collection_type: + raise AssertionError("query collection has unexpected logical type") + if not isinstance(reference_value.value, tuple) or not isinstance( + query_value.value, tuple + ): + raise AssertionError("non-null collection has unexpected canonical value") + + if logical_type.collection_type in {"set", "multiset"}: + return reference_value.value == query_value.value + if len(reference_value.value) != len(query_value.value): + return False + return all( + _compare_collection_element( + reference_element, + query_element, + logical_type.element_comparator, + ) + for reference_element, query_element in zip( + reference_value.value, + query_value.value, + ) + ) + + +def _compare_collection_element( + reference: object, + query: object, + comparator: Comparator, +) -> bool: + """Compare one positional list element under its declared comparator.""" + if comparator.name == "typed_exact": + return reference == query + if comparator.name == "numeric_tolerance": + return _numbers_within_tolerance(reference, query, comparator) + raise AssertionError("validated collection element comparator is not registered") + + +def _numbers_within_tolerance( + reference: object, + query: object, + comparator: Comparator, +) -> bool: + """Evaluate absolute or reference-directed relative tolerance exactly.""" + reference_fraction = _number_fraction(reference) + query_fraction = _number_fraction(query) + difference = abs(reference_fraction - query_fraction) + if "absolute_tolerance" in comparator.parameters: + allowed = _tolerance_fraction( + comparator.parameters["absolute_tolerance"] + ) + elif "relative_tolerance" in comparator.parameters: + allowed = _tolerance_fraction( + comparator.parameters["relative_tolerance"] + ) * abs(reference_fraction) + else: + raise AssertionError("numeric tolerance has no validated parameter") + return difference <= allowed + + +def _number_fraction(value: object) -> Fraction: + """Convert a canonical integer or decimal to an exact rational value.""" + if isinstance(value, bool) or not isinstance(value, (int, Decimal)): + raise AssertionError("numeric comparator received a non-numeric value") + return Fraction(value) + + +def _tolerance_fraction(value: object) -> Fraction: + """Convert a validated decimal-string tolerance without binary floating point.""" + if not isinstance(value, str): + raise AssertionError("numeric tolerance parameter is not a string") + return Fraction(Decimal(value)) + + +def _canonical(value: TranslatedValue) -> CanonicalValue: + """Return a successfully translated canonical value.""" + if value.canonical is None: + raise AssertionError("typed comparator received no canonical value") + return value.canonical + + +_COMPARATORS: Mapping[str, ComparatorFunction] = MappingProxyType( + { + "preserved_exact": _preserved_exact, + "typed_exact": _canonical_exact, + "normalised_string": _canonical_exact, + "numeric_exact": _canonical_exact, + "numeric_tolerance": _numeric_tolerance, + "date_exact": _canonical_exact, + "datetime_exact": _canonical_exact, + "list_exact": _collection_exact, + "set_exact": _collection_exact, + "multiset_exact": _collection_exact, + } +) diff --git a/packages/adviso-compare/src/adviso_compare/configuration.py b/packages/adviso-compare/src/adviso_compare/configuration.py new file mode 100644 index 0000000..eec3ce9 --- /dev/null +++ b/packages/adviso-compare/src/adviso_compare/configuration.py @@ -0,0 +1,828 @@ +"""Safely validate and resolve custom or generated comparison configurations.""" + +from __future__ import annotations + +import copy +import json +import re +from dataclasses import dataclass, field as dataclass_field +from decimal import Decimal +from pathlib import Path +from types import MappingProxyType +from typing import Any, Generic, Mapping, TypeVar + +import yaml +from jsonschema import Draft202012Validator, FormatChecker, ValidationError +from yaml.constructor import ConstructorError +from yaml.nodes import MappingNode, ScalarNode +from yaml.tokens import AliasToken, AnchorToken, TagToken + +from adviso_compare.processing import ( + apply_source_text_operation, + field_comparator_is_compatible, + typed_normalisation_is_compatible, +) +from adviso_compare.schemas import load_schema + + +SUPPORTED_SCHEMA_VERSION = "1.0" +AUTOMATIC_CONFIGURATION_ID = "adviso-compare:automatic-strict-exact" + +JsonObject = dict[str, Any] +T = TypeVar("T") + + +@dataclass(frozen=True, slots=True) +class DatasetSides(Generic[T]): + """Resolved reference-side and query-side values of one declaration.""" + + reference: T + query: T + + +@dataclass(frozen=True, slots=True) +class Operation: + """One registered processing operation and its immutable parameters.""" + + name: str + parameters: Mapping[str, object] = dataclass_field( + default_factory=lambda: MappingProxyType({}) + ) + + +@dataclass(frozen=True, slots=True) +class SourceValueDescriptor: + """One explicitly typed value used by null or mapping rules.""" + + category: str + value: object = None + + +@dataclass(frozen=True, slots=True) +class ValueMappingEntry: + """One closed source-to-destination value mapping.""" + + source: SourceValueDescriptor + destination: SourceValueDescriptor + + +@dataclass(frozen=True, slots=True) +class Comparator: + """A comparator declaration and its immutable parameters.""" + + name: str + parameters: Mapping[str, object] = dataclass_field( + default_factory=lambda: MappingProxyType({}) + ) + + +@dataclass(frozen=True, slots=True) +class CollectionLogicalType: + """The resolved logical type of a collection-valued field.""" + + collection_type: str + element_type: str + element_comparator: Comparator + + +@dataclass(frozen=True, slots=True) +class NullPolicy: + """Resolved null acceptance and side-specific missing tokens.""" + + allowed: bool + nulls_equal: bool + missing_tokens: DatasetSides[tuple[SourceValueDescriptor, ...]] + + +@dataclass(frozen=True, slots=True) +class CollectionRepresentation: + """Resolved representation and element processing for one dataset side.""" + + format: str + delimiter: str | None + element_normalisation: tuple[Operation, ...] + element_mapping: tuple[ValueMappingEntry, ...] + + +@dataclass(frozen=True, slots=True) +class FieldDefinition: + """An immutable effective declaration for one canonical field.""" + + name: str + source_fields: DatasetSides[str] + required: DatasetSides[bool] + logical_type: str | CollectionLogicalType | None + null_policy: NullPolicy + source_normalisation: DatasetSides[tuple[Operation, ...]] + collection_representation: DatasetSides[CollectionRepresentation] | None + value_mapping: DatasetSides[tuple[ValueMappingEntry, ...]] + typed_normalisation: tuple[Operation, ...] + comparator: Comparator + review_priority: str + + +@dataclass(frozen=True, slots=True) +class ConfigurationMetadata: + """Identity and optional human-readable metadata for one configuration.""" + + id: str + revision: str + title: str | None + description: str | None + + +@dataclass(frozen=True, slots=True) +class EffectiveConfiguration: + """A validated custom configuration with immutable resolved application state.""" + + schema_version: str + metadata: ConfigurationMetadata + record_key: tuple[str, ...] + in_scope: tuple[str, ...] + fields: Mapping[str, FieldDefinition] + _document: JsonObject = dataclass_field(repr=False, compare=False) + + @property + def document(self) -> JsonObject: + """Return a fresh JSON-compatible copy of the validated source document.""" + return copy.deepcopy(self._document) + + def field(self, name: str) -> FieldDefinition: + """Return one resolved canonical field definition.""" + try: + return self.fields[name] + except KeyError as error: + raise KeyError(f"unknown canonical field: {name}") from error + + +@dataclass(slots=True) +class ConfigurationError(Exception): + """A classified expected failure while loading a custom configuration.""" + + code: str + path: str + message: str + + @property + def category(self) -> str: + """Return the stable execution-error category.""" + return "configuration" + + @property + def diagnostic(self) -> str: + """Render the stable single-line diagnostic.""" + return f"ERROR [configuration.{self.code}]: {self.path}: {self.message}" + + def __str__(self) -> str: + """Return the actionable path and message.""" + return f"{self.path}: {self.message}" + + +class _Yaml12SafeLoader(yaml.SafeLoader): + """Safe loader with YAML 1.2 core scalar resolution and strict mappings.""" + + yaml_implicit_resolvers = copy.deepcopy(yaml.SafeLoader.yaml_implicit_resolvers) + + def construct_mapping( + self, + node: MappingNode, + deep: bool = False, + ) -> dict[str, object]: + """Construct a string-keyed mapping while rejecting merges and duplicates.""" + if not isinstance(node, MappingNode): + raise ConstructorError(None, None, "expected a mapping", node.start_mark) + mapping: dict[str, object] = {} + for key_node, value_node in node.value: + if key_node.tag == "tag:yaml.org,2002:merge": + raise ConstructorError( + "while constructing a mapping", + node.start_mark, + "merge keys are not permitted", + key_node.start_mark, + ) + key = self.construct_object(key_node, deep=deep) + if not isinstance(key, str): + raise ConstructorError( + "while constructing a mapping", + node.start_mark, + "mapping keys must be strings", + key_node.start_mark, + ) + if key in mapping: + raise ConstructorError( + "while constructing a mapping", + node.start_mark, + "duplicate mapping key", + key_node.start_mark, + ) + mapping[key] = self.construct_object(value_node, deep=deep) + return mapping + + +for first_character, resolvers in tuple( + _Yaml12SafeLoader.yaml_implicit_resolvers.items() +): + _Yaml12SafeLoader.yaml_implicit_resolvers[first_character] = [ + (tag, expression) + for tag, expression in resolvers + if tag + not in { + "tag:yaml.org,2002:bool", + "tag:yaml.org,2002:float", + "tag:yaml.org,2002:int", + "tag:yaml.org,2002:null", + "tag:yaml.org,2002:timestamp", + } + ] + +_Yaml12SafeLoader.add_implicit_resolver( + "tag:yaml.org,2002:null", + re.compile(r"^(?:~|null|Null|NULL)$"), + ["~", "n", "N"], +) +_Yaml12SafeLoader.add_implicit_resolver( + "tag:yaml.org,2002:bool", + re.compile(r"^(?:true|True|TRUE|false|False|FALSE)$"), + ["t", "T", "f", "F"], +) +_Yaml12SafeLoader.add_implicit_resolver( + "tag:yaml.org,2002:int", + re.compile(r"^[-+]?(?:[0-9][0-9_]*|0o[0-7_]+|0x[0-9a-fA-F_]+)$"), + list("-+0123456789"), +) +_Yaml12SafeLoader.add_implicit_resolver( + "tag:yaml.org,2002:float", + re.compile( + r"^[-+]?(?:(?:[0-9][0-9_]*)?\.[0-9_]+" + r"|[0-9][0-9_]*\.(?:[0-9_]*)" + r"|[0-9][0-9_]*(?:[eE][-+]?[0-9]+))$" + ), + list("-+0123456789."), +) + + +def _construct_yaml12_integer(loader: _Yaml12SafeLoader, node: ScalarNode) -> int: + """Construct YAML 1.2 decimal, octal, or hexadecimal integer syntax.""" + value = loader.construct_scalar(node).replace("_", "") + sign = 1 + if value.startswith("-"): + sign = -1 + value = value[1:] + elif value.startswith("+"): + value = value[1:] + if value.startswith("0o"): + return sign * int(value[2:], 8) + if value.startswith("0x"): + return sign * int(value[2:], 16) + return sign * int(value, 10) + + +_Yaml12SafeLoader.add_constructor( + "tag:yaml.org,2002:int", + _construct_yaml12_integer, +) + + +def load_comparison_configuration(path: Path) -> EffectiveConfiguration: + """Load, structurally validate, and semantically resolve one custom YAML file.""" + try: + content = path.read_bytes() + except OSError as error: + raise ConfigurationError( + code="unreadable", + path="$", + message="comparison configuration could not be read", + ) from error + try: + text = content.decode("utf-8", errors="strict") + except UnicodeDecodeError as error: + raise ConfigurationError( + code="invalid_syntax", + path="$", + message="comparison configuration is not valid UTF-8", + ) from error + + document = _load_yaml_document(text) + if ( + isinstance(document, dict) + and isinstance(document.get("schema_version"), str) + and document["schema_version"] != SUPPORTED_SCHEMA_VERSION + ): + raise ConfigurationError( + code="unsupported_version", + path="$.schema_version", + message="comparison-configuration schema version is not supported", + ) + _validate_schema(document) + if not isinstance(document, dict): + raise AssertionError("schema accepted a non-object configuration") + _validate_semantics(document) + return _build_effective_configuration(document) + + +def resolve_automatic_configuration(document: JsonObject) -> EffectiveConfiguration: + """Validate and resolve the internally generated automatic configuration.""" + _validate_schema(document) + metadata = document.get("metadata") + if ( + not isinstance(metadata, dict) + or metadata.get("id") != AUTOMATIC_CONFIGURATION_ID + ): + raise AssertionError("automatic configuration has an unexpected identifier") + _validate_semantics(document, allow_automatic_identifier=True) + return _build_effective_configuration(document) + + +def validate_saved_configuration(document: JsonObject) -> None: + """Validate saved effective configuration from either comparison mode.""" + version = document.get("schema_version") + if not isinstance(version, str) or version != SUPPORTED_SCHEMA_VERSION: + raise ConfigurationError( + code="unsupported_version", + path="$.schema_version", + message="comparison-configuration schema version is not supported", + ) + _validate_schema(document, version=version) + _validate_semantics(document, allow_automatic_identifier=True) + + +def _load_yaml_document(text: str) -> object: + """Load exactly one safe YAML 1.2 document with forbidden features disabled.""" + try: + for token in yaml.scan(text, Loader=_Yaml12SafeLoader): + if isinstance(token, (AliasToken, AnchorToken, TagToken)): + raise ConfigurationError( + code="invalid_syntax", + path="$", + message=( + "YAML aliases, anchors, and explicit tags are not permitted" + ), + ) + return yaml.load(text, Loader=_Yaml12SafeLoader) + except ConfigurationError: + raise + except yaml.YAMLError as error: + raise ConfigurationError( + code="invalid_syntax", + path="$", + message="comparison configuration is not permitted YAML syntax", + ) from error + + +def _configuration_validator( + version: str = SUPPORTED_SCHEMA_VERSION, +) -> Draft202012Validator: + """Load the authoritative packaged schema through the resource API.""" + schema = load_schema("configuration", version) + return Draft202012Validator(schema, format_checker=FormatChecker()) + + +def _validate_schema( + document: object, *, version: str = SUPPORTED_SCHEMA_VERSION +) -> None: + """Raise the most deterministic actionable structural validation error.""" + errors = list(_configuration_validator(version).iter_errors(document)) + if not errors: + return + error = min(errors, key=_schema_error_sort_key) + path_components = list(error.absolute_path) + if error.validator == "required" and isinstance(error.instance, dict): + missing = sorted(set(error.validator_value) - set(error.instance)) + if missing: + path_components.append(missing[0]) + elif error.validator == "additionalProperties" and isinstance( + error.instance, dict + ): + permitted = set(error.schema.get("properties", {})) + extras = sorted(set(error.instance) - permitted) + if extras: + path_components.append(extras[0]) + path = _configuration_path(path_components) + raise ConfigurationError( + code="schema_violation", + path=path, + message=_schema_error_message(error), + ) + + +def _schema_error_sort_key(error: ValidationError) -> tuple[str, str]: + """Return a stable ordering key for competing schema failures.""" + return ( + _configuration_path(list(error.absolute_path)), + "/".join(str(component) for component in error.absolute_schema_path), + ) + + +def _schema_error_message(error: ValidationError) -> str: + """Describe a schema rule without reproducing configuration values.""" + messages = { + "required": "required property is missing", + "additionalProperties": "unknown property is not permitted", + "const": "value does not identify the required schema version or form", + "enum": "value is not one of the permitted choices", + "minItems": "list must contain at least one item", + "minLength": "string must not be empty", + "minProperties": "mapping must contain at least one property", + "uniqueItems": "list items must be unique", + "type": "value has the wrong type", + } + return messages.get( + str(error.validator), + f"value violates schema rule {error.validator}", + ) + + +def _configuration_path(components: list[object]) -> str: + """Render one unambiguous JSONPath-like configuration location.""" + path = "$" + for component in components: + if isinstance(component, int): + path += f"[{component}]" + elif re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", str(component)): + path += f".{component}" + else: + path += f"[{json.dumps(str(component), ensure_ascii=False)}]" + return path + + +def _semantic_error(path: str, message: str) -> None: + """Raise one semantic configuration failure.""" + raise ConfigurationError( + code="semantic_violation", + path=path, + message=message, + ) + + +def _validate_semantics( + document: JsonObject, + *, + allow_automatic_identifier: bool = False, +) -> None: + """Apply cross-property rules not reliably expressible in JSON Schema.""" + fields = document["fields"] + definitions = fields["definitions"] + in_scope = fields["in_scope"] + + for index, field_name in enumerate(fields["record_key"]): + path = f"$.fields.record_key[{index}]" + if field_name not in definitions: + _semantic_error(path, "record-key field has no field definition") + if field_name not in in_scope: + _semantic_error(path, "record-key field is not included in fields.in_scope") + _validate_key_field(field_name, definitions[field_name]) + + for index, field_name in enumerate(in_scope): + if field_name not in definitions: + _semantic_error( + f"$.fields.in_scope[{index}]", + "in-scope field has no field definition", + ) + + source_names: dict[str, dict[str, str]] = {"reference": {}, "query": {}} + for field_name, field in definitions.items(): + field_path = _field_path(field_name) + _validate_field_semantics(field_path, field) + for side in ("reference", "query"): + source_name = field["source_fields"][side] + previous = source_names[side].get(source_name) + if previous is not None: + _semantic_error( + f"{field_path}.source_fields.{side}", + f"source field is already used by canonical field {previous!r}", + ) + source_names[side][source_name] = field_name + + if ( + document["metadata"]["id"] == AUTOMATIC_CONFIGURATION_ID + and not allow_automatic_identifier + ): + _semantic_error( + "$.metadata.id", + "identifier is reserved for automatically generated configurations", + ) + + +def _validate_key_field(field_name: str, field: JsonObject) -> None: + """Validate the mandatory contract for one record-key field.""" + path = _field_path(field_name) + for side in ("reference", "query"): + if not field["required"][side]: + _semantic_error( + f"{path}.required.{side}", + "record-key field must be required on both sides", + ) + if field["null_policy"]["allowed"]: + _semantic_error( + f"{path}.null_policy.allowed", + "record-key field must not allow null", + ) + if not isinstance(field.get("logical_type"), str): + _semantic_error( + f"{path}.logical_type", + "record-key field must have a scalar logical type", + ) + if field["comparator"]["name"] != "typed_exact": + _semantic_error( + f"{path}.comparator.name", + "record-key field must use typed_exact", + ) + + +def _validate_field_semantics(path: str, field: JsonObject) -> None: + """Validate comparator, operation, and mapping relationships for one field.""" + logical_type = field.get("logical_type") + comparator_name = field["comparator"]["name"] + if logical_type is None: + if comparator_name != "preserved_exact": + _semantic_error( + f"{path}.comparator.name", + "field without logical_type must use preserved_exact", + ) + elif comparator_name == "preserved_exact": + _semantic_error( + f"{path}.comparator.name", + "preserved_exact field must omit logical_type", + ) + + _validate_comparator_compatibility(path, logical_type, field) + _validate_typed_normalisation(path, logical_type, field) + _validate_side_mappings(path, field) + _validate_collection_mappings(path, field) + + +def _validate_comparator_compatibility( + path: str, + logical_type: object, + field: JsonObject, +) -> None: + """Require the field comparator to match its resolved logical type.""" + comparator = field["comparator"]["name"] + if isinstance(logical_type, dict): + compatible = field_comparator_is_compatible( + comparator, + collection_type=logical_type["collection_type"], + ) + else: + compatible = field_comparator_is_compatible( + comparator, + scalar_type=logical_type, + ) + if not compatible: + _semantic_error( + f"{path}.comparator.name", + "comparator is incompatible with the field logical type", + ) + if comparator == "normalised_string": + source_operations = field.get("source_normalisation", {}) + if not source_operations.get("reference") and not source_operations.get( + "query" + ): + _semantic_error( + f"{path}.comparator.name", + "normalised_string requires a configured string normalisation", + ) + + +def _validate_typed_normalisation( + path: str, + logical_type: object, + field: JsonObject, +) -> None: + """Require each typed operation to match the scalar destination type.""" + for index, operation in enumerate(field.get("typed_normalisation", [])): + if not typed_normalisation_is_compatible( + operation["operation"], + logical_type if isinstance(logical_type, str) else None, + ): + _semantic_error( + f"{path}.typed_normalisation[{index}].operation", + "typed normalisation is incompatible with the field logical type", + ) + + +def _validate_side_mappings(path: str, field: JsonObject) -> None: + """Reject duplicate, colliding, and missing-token-unreachable field mappings.""" + mappings = field.get("value_mapping", {}) + source_operations = field.get("source_normalisation", {}) + missing_tokens = field["null_policy"].get("missing_tokens", {}) + for side in ("reference", "query"): + operations = source_operations.get(side, []) + missing = { + _descriptor_key(descriptor, operations) + for descriptor in missing_tokens.get(side, []) + } + seen: set[tuple[str, object]] = set() + for index, entry in enumerate(mappings.get(side, [])): + entry_path = f"{path}.value_mapping.{side}[{index}].from" + key = _descriptor_key(entry["from"], operations) + if key in seen: + _semantic_error( + entry_path, + "mapping source duplicates another source after normalisation", + ) + if key in missing: + _semantic_error( + entry_path, + "mapping source is unreachable because it is a missing token", + ) + seen.add(key) + + +def _validate_collection_mappings(path: str, field: JsonObject) -> None: + """Reject element mapping sources that collide after element normalisation.""" + for side, representation in field.get("collection_representation", {}).items(): + operations = representation.get("element_normalisation", []) + seen: set[tuple[str, object]] = set() + for index, entry in enumerate(representation.get("element_mapping", [])): + entry_path = ( + f"{path}.collection_representation.{side}.element_mapping" + f"[{index}].from" + ) + key = _descriptor_key(entry["from"], operations) + if key in seen: + _semantic_error( + entry_path, + "element mapping source duplicates another source after " + "normalisation", + ) + seen.add(key) + + +def _descriptor_key( + descriptor: JsonObject, + operations: list[JsonObject], +) -> tuple[str, object]: + """Return parser-native descriptor equality after configured text operations.""" + category = descriptor["category"] + value = descriptor.get("value") + if category == "integer": + value = int(value) + elif category == "decimal": + value = Decimal(value) + elif category == "string": + for operation in operations: + value = apply_source_text_operation( + value, + operation["operation"], + operation.get("parameters", {}), + ) + return category, value + + +def _field_path(field_name: str) -> str: + """Return the unambiguous configuration path for a canonical field.""" + return _configuration_path(["fields", "definitions", field_name]) + + +def _build_effective_configuration(document: JsonObject) -> EffectiveConfiguration: + """Resolve optional declarations into immutable application values.""" + metadata = document["metadata"] + fields = { + name: _build_field(name, field) + for name, field in document["fields"]["definitions"].items() + } + return EffectiveConfiguration( + schema_version=document["schema_version"], + metadata=ConfigurationMetadata( + id=metadata["id"], + revision=metadata["revision"], + title=metadata.get("title"), + description=metadata.get("description"), + ), + record_key=tuple(document["fields"]["record_key"]), + in_scope=tuple(document["fields"]["in_scope"]), + fields=MappingProxyType(fields), + _document=copy.deepcopy(document), + ) + + +def _build_field(name: str, field: JsonObject) -> FieldDefinition: + """Build one immutable field definition with resolved omissions.""" + logical_document = field.get("logical_type") + if isinstance(logical_document, dict): + logical_type: str | CollectionLogicalType | None = CollectionLogicalType( + collection_type=logical_document["collection_type"], + element_type=logical_document["element_type"], + element_comparator=_build_comparator( + logical_document["element_comparator"] + ), + ) + else: + logical_type = logical_document + + null_policy = field["null_policy"] + missing_tokens = null_policy.get("missing_tokens", {}) + source_normalisation = field.get("source_normalisation", {}) + value_mapping = field.get("value_mapping", {}) + collection_document = field.get("collection_representation", {}) + if isinstance(logical_type, CollectionLogicalType): + collection_representation: DatasetSides[CollectionRepresentation] | None + collection_representation = DatasetSides( + reference=_build_collection_representation( + collection_document.get("reference") + ), + query=_build_collection_representation(collection_document.get("query")), + ) + else: + collection_representation = None + + return FieldDefinition( + name=name, + source_fields=DatasetSides(**field["source_fields"]), + required=DatasetSides(**field["required"]), + logical_type=logical_type, + null_policy=NullPolicy( + allowed=null_policy["allowed"], + nulls_equal=null_policy["nulls_equal"], + missing_tokens=DatasetSides( + reference=tuple( + _build_descriptor(item) + for item in missing_tokens.get("reference", []) + ), + query=tuple( + _build_descriptor(item) for item in missing_tokens.get("query", []) + ), + ), + ), + source_normalisation=DatasetSides( + reference=tuple( + _build_operation(item) + for item in source_normalisation.get("reference", []) + ), + query=tuple( + _build_operation(item) + for item in source_normalisation.get("query", []) + ), + ), + collection_representation=collection_representation, + value_mapping=DatasetSides( + reference=tuple( + _build_mapping(item) for item in value_mapping.get("reference", []) + ), + query=tuple( + _build_mapping(item) for item in value_mapping.get("query", []) + ), + ), + typed_normalisation=tuple( + _build_operation(item) for item in field.get("typed_normalisation", []) + ), + comparator=_build_comparator(field["comparator"]), + review_priority=field.get("review_priority", "normal"), + ) + + +def _build_operation(document: JsonObject) -> Operation: + """Build one immutable processing operation.""" + return Operation( + name=document["operation"], + parameters=MappingProxyType(dict(document.get("parameters", {}))), + ) + + +def _build_comparator(document: JsonObject) -> Comparator: + """Build one immutable comparator declaration.""" + return Comparator( + name=document["name"], + parameters=MappingProxyType(dict(document.get("parameters", {}))), + ) + + +def _build_descriptor(document: JsonObject) -> SourceValueDescriptor: + """Build one immutable source-value descriptor.""" + return SourceValueDescriptor( + category=document["category"], + value=document.get("value"), + ) + + +def _build_mapping(document: JsonObject) -> ValueMappingEntry: + """Build one immutable value-mapping entry.""" + return ValueMappingEntry( + source=_build_descriptor(document["from"]), + destination=_build_descriptor(document["to"]), + ) + + +def _build_collection_representation( + document: JsonObject | None, +) -> CollectionRepresentation: + """Build one side's collection representation, applying omission defaults.""" + if document is None: + return CollectionRepresentation( + format="json_array", + delimiter=None, + element_normalisation=(), + element_mapping=(), + ) + return CollectionRepresentation( + format=document["format"], + delimiter=document.get("delimiter"), + element_normalisation=tuple( + _build_operation(item) + for item in document.get("element_normalisation", []) + ), + element_mapping=tuple( + _build_mapping(item) for item in document.get("element_mapping", []) + ), + ) diff --git a/packages/adviso-compare/src/adviso_compare/contract.py b/packages/adviso-compare/src/adviso_compare/contract.py new file mode 100644 index 0000000..3a84571 --- /dev/null +++ b/packages/adviso-compare/src/adviso_compare/contract.py @@ -0,0 +1,325 @@ +"""Assess the configured data contract without blocking unaffected content.""" + +from __future__ import annotations + +from dataclasses import dataclass +from enum import Enum +from types import MappingProxyType +from typing import Mapping, TypeAlias + +from adviso_compare.configuration import EffectiveConfiguration, FieldDefinition +from adviso_compare.inputs import ( + InputFormat, + InputSide, + JsonLocation, + ParsedDataset, + SourceLocation, + TabularLocation, +) +from adviso_compare.records import KeyedRecord, RecordKey, RecordModel +from adviso_compare.translation import ( + TranslatedValue, + TranslationIssueCode, + ValueDisposition, + translate_field_value, +) + + +class ContractPhaseStatus(str, Enum): + """Completion state of the contract phase.""" + + COMPLETE = "complete" + + +@dataclass(frozen=True, slots=True) +class FieldAssessment: + """Translation outcome for one configured field on one source record.""" + + side: InputSide + record: KeyedRecord + canonical_field: str + source_field: str + translated: TranslatedValue + + @property + def disposition(self) -> ValueDisposition: + """Return whether this field is valid, absent, or not assessable.""" + return self.translated.disposition + + @property + def location(self) -> SourceLocation: + """Return the field location, or containing record when absent.""" + if self.record.record.has_field(self.source_field): + return self.record.record.location_for(self.source_field) + return self.record.record.location + + +@dataclass(frozen=True, slots=True) +class ContractFinding: + """One causal contract issue retained for later evidence construction.""" + + code: str + side: InputSide + canonical_field: str + review_priority: str + record: KeyedRecord | None + assessment: FieldAssessment | None + + @property + def classification(self) -> str: + """Return the fixed classification for contract translation issues.""" + return "assessment_issue" + + @property + def phase(self) -> str: + """Return the phase in which this issue was detected.""" + return "contract" + + @property + def location(self) -> SourceLocation | None: + """Return the attributable source location when a record exists.""" + if self.assessment is None: + return None + return self.assessment.location + + +@dataclass(frozen=True, slots=True) +class ConfiguredFieldExclusion: + """One deliberately declared but out-of-scope canonical field.""" + + canonical_field: str + + @property + def code(self) -> str: + """Return the stable exclusion code.""" + return "configured_field_excluded" + + +@dataclass(frozen=True, slots=True) +class UndeclaredFieldExclusion: + """One observed source field not represented by a field definition.""" + + side: InputSide + source_field: str + record_count: int + + @property + def code(self) -> str: + """Return the stable exclusion code.""" + return "undeclared_field_excluded" + + +FieldExclusion: TypeAlias = ConfiguredFieldExclusion | UndeclaredFieldExclusion +AssessmentIndex: TypeAlias = Mapping[ + tuple[InputSide, RecordKey, str], FieldAssessment +] + + +@dataclass(frozen=True, slots=True) +class ContractResult: + """Complete contract outcomes needed by later comparison phases.""" + + status: ContractPhaseStatus + assessments: tuple[FieldAssessment, ...] + findings: tuple[ContractFinding, ...] + exclusions: tuple[FieldExclusion, ...] + _assessment_index: AssessmentIndex + + def assessment( + self, + side: InputSide, + record_key: RecordKey, + canonical_field: str, + ) -> FieldAssessment: + """Return one field assessment by side, record key, and canonical name.""" + return self._assessment_index[(side, record_key, canonical_field)] + + +def assess_contract( + configuration: EffectiveConfiguration, + *, + reference: ParsedDataset, + query: ParsedDataset, + reference_records: RecordModel, + query_records: RecordModel, +) -> ContractResult: + """Assess every applicable field contract and consolidate exclusions.""" + assessments: list[FieldAssessment] = [] + findings: list[ContractFinding] = [] + + for side, model in ( + (InputSide.REFERENCE, reference_records), + (InputSide.QUERY, query_records), + ): + for keyed_record in sorted( + model.records, + key=lambda item: item.canonical_identity, + ): + for canonical_field in sorted(configuration.in_scope): + field = configuration.field(canonical_field) + source_field = _for_side(field, side) + source = ( + keyed_record.record.value(source_field) + if keyed_record.record.has_field(source_field) + else None + ) + translated = translate_field_value(source, field, side) + assessment = FieldAssessment( + side=side, + record=keyed_record, + canonical_field=canonical_field, + source_field=source_field, + translated=translated, + ) + assessments.append(assessment) + if translated.disposition is ValueDisposition.NOT_ASSESSABLE: + findings.append(_finding_for(assessment, field)) + + findings.extend( + _zero_record_header_findings( + configuration, + reference if side is InputSide.REFERENCE else query, + side, + model, + ) + ) + + findings.sort(key=_finding_sort_key) + exclusions = _collect_exclusions(configuration, reference, query) + index = { + (assessment.side, assessment.record.key, assessment.canonical_field): assessment + for assessment in assessments + } + return ContractResult( + status=ContractPhaseStatus.COMPLETE, + assessments=tuple(assessments), + findings=tuple(findings), + exclusions=exclusions, + _assessment_index=MappingProxyType(index), + ) + + +def _finding_for( + assessment: FieldAssessment, + field: FieldDefinition, +) -> ContractFinding: + """Build the one causal finding for a failed field translation.""" + issue = assessment.translated.issue + if issue is None: + raise AssertionError("not-assessable translation has no causal issue") + return ContractFinding( + code=issue.code.value, + side=assessment.side, + canonical_field=assessment.canonical_field, + review_priority=field.review_priority, + record=assessment.record, + assessment=assessment, + ) + + +def _zero_record_header_findings( + configuration: EffectiveConfiguration, + dataset: ParsedDataset, + side: InputSide, + model: RecordModel, +) -> list[ContractFinding]: + """Assess required fields exposed by an empty tabular dataset's header.""" + if model.records: + return [] + if dataset.provenance.format is InputFormat.JSON: + return [] + + findings: list[ContractFinding] = [] + for canonical_field in sorted(configuration.in_scope): + field = configuration.field(canonical_field) + source_field = _for_side(field, side) + required = ( + field.required.reference + if side is InputSide.REFERENCE + else field.required.query + ) + if required and source_field not in dataset.field_names: + findings.append( + ContractFinding( + code=TranslationIssueCode.MISSING_REQUIRED_FIELD.value, + side=side, + canonical_field=canonical_field, + review_priority=field.review_priority, + record=None, + assessment=None, + ) + ) + return findings + + +def _collect_exclusions( + configuration: EffectiveConfiguration, + reference: ParsedDataset, + query: ParsedDataset, +) -> tuple[FieldExclusion, ...]: + """Return configured and undeclared exclusions in their specified order.""" + exclusions: list[FieldExclusion] = [ + ConfiguredFieldExclusion(canonical_field=name) + for name in sorted(set(configuration.fields) - set(configuration.in_scope)) + ] + for side, dataset in ( + (InputSide.REFERENCE, reference), + (InputSide.QUERY, query), + ): + represented = { + _for_side(field, side) for field in configuration.fields.values() + } + for source_field in sorted(set(dataset.field_names) - represented): + exclusions.append( + UndeclaredFieldExclusion( + side=side, + source_field=source_field, + record_count=sum( + record.has_field(source_field) for record in dataset.records + ), + ) + ) + return tuple(exclusions) + + +def _finding_sort_key(finding: ContractFinding) -> tuple[object, ...]: + """Apply the relevant prefix of the canonical total finding order.""" + code_order = { + "missing_required_field": 2, + "type_mismatch": 3, + "invalid_field_value": 4, + "null_policy_violation": 5, + "mapping_failure": 6, + } + side_order = {InputSide.REFERENCE: 0, InputSide.QUERY: 1} + return ( + finding.record is not None, + finding.record.canonical_identity if finding.record is not None else (), + finding.canonical_field, + code_order[finding.code], + side_order[finding.side], + _location_sort_key(finding.location), + ) + + +def _location_sort_key(location: SourceLocation | None) -> tuple[object, ...]: + """Return a deterministic order key for a possibly absent location.""" + if location is None: + return (0,) + if isinstance(location, TabularLocation): + return ( + 1, + location.record_number, + location.line_number, + location.field_name or "", + ) + if isinstance(location, JsonLocation): + return (1, location.pointer) + raise AssertionError("unknown source-location type") + + +def _for_side(field: FieldDefinition, side: InputSide) -> str: + """Return one field's source name for the selected dataset side.""" + if side is InputSide.REFERENCE: + return field.source_fields.reference + return field.source_fields.query diff --git a/packages/adviso-compare/src/adviso_compare/inputs.py b/packages/adviso-compare/src/adviso_compare/inputs.py new file mode 100644 index 0000000..e70ed2d --- /dev/null +++ b/packages/adviso-compare/src/adviso_compare/inputs.py @@ -0,0 +1,518 @@ +"""Deterministic, lossless parsing of supported comparison inputs.""" + +from __future__ import annotations + +import csv +import io +import json +from dataclasses import dataclass, field +from decimal import Decimal +from enum import Enum +from hashlib import sha256 +from pathlib import Path +from typing import TypeAlias + + +class InputFormat(str, Enum): + """A supported dataset serialization format.""" + + CSV = "csv" + TSV = "tsv" + JSON = "json" + + +class InputSide(str, Enum): + """The role an input dataset has in a comparison.""" + + REFERENCE = "reference" + QUERY = "query" + + +class NativeCategory(str, Enum): + """A value category assigned by the source-format parser.""" + + STRING = "string" + INTEGER = "integer" + DECIMAL = "decimal" + BOOLEAN = "boolean" + NULL = "null" + ARRAY = "array" + OBJECT = "object" + + +@dataclass(frozen=True, slots=True) +class NativeValue: + """A parser-native value with optional numerical lexical evidence. + + Lexical evidence is deliberately excluded from equality: numerical values + in the same category compare by their exact numerical content. + """ + + category: NativeCategory + value: object = None + lexical: str | None = field(default=None, compare=False) + + +@dataclass(frozen=True, slots=True) +class TabularLocation: + """A one-based tabular record and starting physical-line location.""" + + record_number: int + line_number: int + field_name: str | None = None + + +@dataclass(frozen=True, slots=True) +class JsonLocation: + """An RFC 6901 JSON Pointer location.""" + + pointer: str + + +SourceLocation: TypeAlias = TabularLocation | JsonLocation + + +@dataclass(frozen=True, slots=True) +class ParsedRecord: + """One immutable source record and its attributable location.""" + + members: tuple[tuple[str, NativeValue], ...] + location: SourceLocation + + @property + def field_names(self) -> tuple[str, ...]: + """Return source field names in deterministic parser order.""" + return tuple(name for name, _ in self.members) + + def value(self, field_name: str) -> NativeValue: + """Return the present source value for ``field_name``.""" + for name, value in self.members: + if name == field_name: + return value + raise KeyError(field_name) + + def has_field(self, field_name: str) -> bool: + """Return whether the source record contains ``field_name``.""" + return any(name == field_name for name, _ in self.members) + + def location_for(self, field_name: str) -> SourceLocation: + """Return a present field's location, or the record location if absent.""" + if not self.has_field(field_name): + return self.location + if isinstance(self.location, TabularLocation): + return TabularLocation( + record_number=self.location.record_number, + line_number=self.location.line_number, + field_name=field_name, + ) + return JsonLocation( + pointer=f"{self.location.pointer}/{_escape_json_pointer(field_name)}" + ) + + +@dataclass(frozen=True, slots=True) +class InputProvenance: + """Automatically captured evidence about exact input bytes.""" + + basename: str + format: InputFormat + encoding: str + size_bytes: int + sha256: str + + +@dataclass(frozen=True, slots=True) +class ParsedDataset: + """A losslessly parsed dataset before configured interpretation.""" + + provenance: InputProvenance + field_names: tuple[str, ...] + records: tuple[ParsedRecord, ...] + + +@dataclass(slots=True) +class InputError(Exception): + """A classified expected failure while discovering or parsing an input.""" + + code: str + side: InputSide + message: str + + @property + def category(self) -> str: + """Return the stable execution-error category.""" + return "input" + + @property + def diagnostic(self) -> str: + """Render the stable, single-line non-sensitive diagnostic.""" + return f"ERROR [input.{self.code}]: {self.message}" + + def __str__(self) -> str: + """Return the actionable message without exposing input content.""" + return self.message + + +class _DuplicateMember(ValueError): + """Signal a duplicate JSON object member before mapping construction.""" + + +class _NonFiniteNumber(ValueError): + """Signal a non-standard non-finite JSON numerical token.""" + + +@dataclass(slots=True) +class JsonValueError(ValueError): + """A syntax or structural failure while decoding one JSON value.""" + + kind: str + line: int | None = None + column: int | None = None + + +def load_dataset(path: Path, side: InputSide) -> ParsedDataset: + """Discover and parse one supported dataset from its exact bytes.""" + input_format = _discover_format(path, side) + try: + content = path.read_bytes() + except OSError as error: + raise InputError( + code="unreadable", + side=side, + message=f"{side.value} input could not be read", + ) from error + + provenance = InputProvenance( + basename=path.name, + format=input_format, + encoding="utf-8", + size_bytes=len(content), + sha256=sha256(content).hexdigest(), + ) + try: + text = content.decode("utf-8", errors="strict") + except UnicodeDecodeError as error: + raise InputError( + code="invalid_encoding", + side=side, + message=f"{side.value} input is not valid UTF-8", + ) from error + + if input_format is InputFormat.JSON: + field_names, records = _parse_json(text, side) + else: + delimiter = "," if input_format is InputFormat.CSV else "\t" + field_names, records = _parse_table(text, delimiter, side) + return ParsedDataset( + provenance=provenance, + field_names=field_names, + records=records, + ) + + +def _discover_format(path: Path, side: InputSide) -> InputFormat: + """Select a format solely from the final case-insensitive suffix.""" + suffix = path.suffix.casefold() + formats = { + ".csv": InputFormat.CSV, + ".tsv": InputFormat.TSV, + ".json": InputFormat.JSON, + } + try: + return formats[suffix] + except KeyError as error: + raise InputError( + code="unsupported_format", + side=side, + message=( + f"{side.value} input must have a .csv, .tsv, or .json " + "filename extension" + ), + ) from error + + +def _parse_table( + text: str, + delimiter: str, + side: InputSide, +) -> tuple[tuple[str, ...], tuple[ParsedRecord, ...]]: + """Parse one CSV or TSV document using the fixed version 1 dialect.""" + _validate_tabular_lexical_syntax(text, delimiter, side) + reader = csv.reader( + io.StringIO(text, newline=""), + delimiter=delimiter, + quotechar='"', + doublequote=True, + escapechar=None, + strict=True, + ) + try: + header = next(reader) + except StopIteration as error: + raise InputError( + code="invalid_structure", + side=side, + message=f"{side.value} tabular input must contain a header row", + ) from error + except csv.Error as error: + raise _tabular_syntax_error(side, reader.line_num) from error + + if not header or any(name == "" for name in header): + raise InputError( + code="invalid_structure", + side=side, + message=f"{side.value} tabular header contains an empty column name", + ) + if len(set(header)) != len(header): + raise InputError( + code="invalid_structure", + side=side, + message=f"{side.value} tabular header contains duplicate column names", + ) + + records: list[ParsedRecord] = [] + previous_ending_line = reader.line_num + while True: + starting_line = previous_ending_line + 1 + try: + row = next(reader) + except StopIteration: + break + except csv.Error as error: + raise _tabular_syntax_error(side, reader.line_num) from error + ending_line = reader.line_num + record_number = len(records) + 1 + if len(row) != len(header): + raise InputError( + code="invalid_structure", + side=side, + message=( + f"{side.value} tabular data record {record_number} starting " + f"on physical line {starting_line} has {len(row)} fields; " + f"expected {len(header)}" + ), + ) + members = tuple( + (name, NativeValue(NativeCategory.STRING, value)) + for name, value in zip(header, row) + ) + records.append( + ParsedRecord( + members=members, + location=TabularLocation( + record_number=record_number, + line_number=starting_line, + ), + ) + ) + previous_ending_line = ending_line + return tuple(header), tuple(records) + + +def _validate_tabular_lexical_syntax( + text: str, + delimiter: str, + side: InputSide, +) -> None: + """Reject quote and line-ending forms accepted by permissive CSV readers.""" + start_field = "start_field" + unquoted = "unquoted" + quoted = "quoted" + after_quote = "after_quote" + state = start_field + line_number = 1 + quoted_start_line: int | None = None + index = 0 + + while index < len(text): + character = text[index] + if character == "\r": + if index + 1 >= len(text) or text[index + 1] != "\n": + raise _tabular_syntax_error(side, line_number) + if state != quoted: + state = start_field + line_number += 1 + index += 2 + continue + if character == "\n": + if state != quoted: + state = start_field + line_number += 1 + index += 1 + continue + if character == delimiter: + if state != quoted: + state = start_field + index += 1 + continue + if character == '"': + if state == start_field: + state = quoted + quoted_start_line = line_number + elif state == unquoted: + raise _tabular_syntax_error(side, line_number) + elif state == quoted: + state = after_quote + else: + state = quoted + index += 1 + continue + if state == start_field: + state = unquoted + elif state == after_quote: + raise _tabular_syntax_error(side, line_number) + index += 1 + + if state == quoted: + raise _tabular_syntax_error(side, quoted_start_line or line_number) + + +def _tabular_syntax_error(side: InputSide, line_number: int) -> InputError: + """Construct a stable syntax error without reproducing parser input.""" + line_context = f" near physical line {line_number}" if line_number else "" + return InputError( + code="invalid_syntax", + side=side, + message=f"{side.value} tabular input has invalid quoted syntax{line_context}", + ) + + +def _parse_json( + text: str, + side: InputSide, +) -> tuple[tuple[str, ...], tuple[ParsedRecord, ...]]: + """Parse a record-oriented JSON array without lossy numerical conversion.""" + + try: + root = decode_json_value(text) + except JsonValueError as error: + if error.kind == "non_finite": + message = f"{side.value} JSON input contains a non-finite number" + elif error.kind == "duplicate_member": + message = f"{side.value} JSON input contains a duplicate object member" + else: + message = ( + f"{side.value} JSON input has invalid syntax at line " + f"{error.line}, column {error.column}" + ) + raise InputError( + code=( + "invalid_structure" + if error.kind == "duplicate_member" + else "invalid_syntax" + ), + side=side, + message=message, + ) from error + + if root.category is not NativeCategory.ARRAY: + raise InputError( + code="invalid_structure", + side=side, + message=( + f"{side.value} JSON root is {root.category.value}; it must be " + "one array of record objects" + ), + ) + + elements = root.value + if not isinstance(elements, tuple): + raise AssertionError("JSON array elements were not normalized") + records: list[ParsedRecord] = [] + all_field_names: set[str] = set() + for index, item in enumerate(elements): + if item.category is not NativeCategory.OBJECT: + raise InputError( + code="invalid_structure", + side=side, + message=( + f"{side.value} JSON array item {index} is " + f"{item.category.value}; every item must be a record object" + ), + ) + members = item.value + if not isinstance(members, tuple): + raise AssertionError("JSON object members were not normalized") + if any(name == "" for name, _ in members): + raise InputError( + code="invalid_structure", + side=side, + message=( + f"{side.value} JSON record at array item {index} " + "contains an empty field name" + ), + ) + all_field_names.update(name for name, _ in members) + records.append( + ParsedRecord( + members=members, + location=JsonLocation(pointer=f"/{index}"), + ) + ) + return tuple(sorted(all_field_names)), tuple(records) + + +def decode_json_value(text: str) -> NativeValue: + """Decode one JSON value while preserving exact parser-native categories.""" + + def parse_integer(lexical: str) -> NativeValue: + return NativeValue(NativeCategory.INTEGER, int(lexical), lexical) + + def parse_decimal(lexical: str) -> NativeValue: + return NativeValue(NativeCategory.DECIMAL, Decimal(lexical), lexical) + + def reject_constant(_lexical: str) -> object: + raise _NonFiniteNumber + + def parse_object(pairs: list[tuple[str, object]]) -> NativeValue: + names = [name for name, _ in pairs] + if len(set(names)) != len(names): + raise _DuplicateMember + members = tuple( + sorted( + ((name, _to_native(value)) for name, value in pairs), + key=lambda item: item[0], + ) + ) + return NativeValue(NativeCategory.OBJECT, members) + + try: + root = json.loads( + text, + parse_int=parse_integer, + parse_float=parse_decimal, + parse_constant=reject_constant, + object_pairs_hook=parse_object, + ) + except _NonFiniteNumber as error: + raise JsonValueError(kind="non_finite") from error + except json.JSONDecodeError as error: + raise JsonValueError( + kind="invalid_syntax", line=error.lineno, column=error.colno + ) from error + except _DuplicateMember as error: + raise JsonValueError(kind="duplicate_member") from error + return _to_native(root) + + +def _to_native(value: object) -> NativeValue: + """Recursively assign parser-native categories to JSON library values.""" + if isinstance(value, NativeValue): + return value + if value is None: + return NativeValue(NativeCategory.NULL) + if isinstance(value, bool): + return NativeValue(NativeCategory.BOOLEAN, value) + if isinstance(value, str): + return NativeValue(NativeCategory.STRING, value) + if isinstance(value, list): + return NativeValue( + NativeCategory.ARRAY, + tuple(_to_native(element) for element in value), + ) + raise TypeError(f"unsupported JSON parser value: {type(value).__name__}") + + +def _escape_json_pointer(member_name: str) -> str: + """Escape one JSON object member for use in an RFC 6901 pointer.""" + return member_name.replace("~", "~0").replace("/", "~1") diff --git a/packages/adviso-compare/src/adviso_compare/invocation.py b/packages/adviso-compare/src/adviso_compare/invocation.py new file mode 100644 index 0000000..d642c6c --- /dev/null +++ b/packages/adviso-compare/src/adviso_compare/invocation.py @@ -0,0 +1,40 @@ +"""Domain values at the command-line application boundary.""" + +from __future__ import annotations + +from dataclasses import dataclass +from pathlib import Path +from typing import Literal, Protocol + + +@dataclass(frozen=True, slots=True) +class ComparisonInvocation: + """User-selected input paths and output parent for one comparison.""" + + reference: Path + query: Path + output: Path + configuration: Path | None = None + + +@dataclass(frozen=True, slots=True) +class ComparisonOutcome: + """Non-sensitive facts needed by the command-line completion summary.""" + + run_status: Literal["complete", "incomplete"] + output: Path + comparison_differences: int + assessment_issues: int + + @property + def exit_code(self) -> int: + """Return the stable process code for a non-error comparison.""" + return 0 if self.run_status == "complete" else 1 + + +class ComparisonExecutor(Protocol): + """Callable application boundary used by the command-line adapter.""" + + def __call__(self, invocation: ComparisonInvocation) -> ComparisonOutcome: + """Execute one comparison and return its non-sensitive outcome.""" + ... diff --git a/packages/adviso-compare/src/adviso_compare/processing.py b/packages/adviso-compare/src/adviso_compare/processing.py new file mode 100644 index 0000000..7083540 --- /dev/null +++ b/packages/adviso-compare/src/adviso_compare/processing.py @@ -0,0 +1,95 @@ +"""Shared runtime semantics for configured value processing.""" + +from __future__ import annotations + +import unicodedata +from types import MappingProxyType +from typing import Mapping + + +_UNICODE_WHITE_SPACE_CHARACTERS = "".join( + chr(code_point) + for code_point in ( + *range(0x0009, 0x000E), + 0x0020, + 0x0085, + 0x00A0, + 0x1680, + *range(0x2000, 0x200B), + 0x2028, + 0x2029, + 0x202F, + 0x205F, + 0x3000, + ) +) + + +_SCALAR_COMPARATORS: Mapping[str, frozenset[str]] = MappingProxyType( + { + "string": frozenset({"typed_exact", "normalised_string"}), + "integer": frozenset( + {"typed_exact", "numeric_exact", "numeric_tolerance"} + ), + "decimal": frozenset( + {"typed_exact", "numeric_exact", "numeric_tolerance"} + ), + "boolean": frozenset({"typed_exact"}), + "date": frozenset({"typed_exact", "date_exact"}), + "datetime": frozenset({"typed_exact", "datetime_exact"}), + } +) + +_TYPED_NORMALISATION_TYPES: Mapping[str, str] = MappingProxyType( + { + "decimal_quantise": "decimal", + "datetime_truncate": "datetime", + } +) + + +def field_comparator_is_compatible( + comparator: str, + *, + scalar_type: str | None = None, + collection_type: str | None = None, +) -> bool: + """Return whether a comparator can assess the identified field type.""" + if collection_type is not None: + return comparator == f"{collection_type}_exact" + if scalar_type is None: + return comparator == "preserved_exact" + return comparator in _SCALAR_COMPARATORS[scalar_type] + + +def typed_normalisation_is_compatible( + operation: str, + logical_type: str | None, +) -> bool: + """Return whether a typed operation accepts the identified scalar type.""" + return _TYPED_NORMALISATION_TYPES[operation] == logical_type + + +def apply_source_text_operation( + value: str, + operation: str, + parameters: Mapping[str, object], +) -> str: + """Apply one registered source-text operation to a string value.""" + if operation == "unicode_normalise": + form = parameters["form"] + if not isinstance(form, str): + raise AssertionError("validated Unicode form is not a string") + return unicodedata.normalize(form, value) + if operation == "trim": + side = parameters["side"] + if side == "leading": + return value.lstrip(_UNICODE_WHITE_SPACE_CHARACTERS) + if side == "trailing": + return value.rstrip(_UNICODE_WHITE_SPACE_CHARACTERS) + if side == "both": + return value.strip(_UNICODE_WHITE_SPACE_CHARACTERS) + raise AssertionError("validated trim side is not registered") + if operation == "case_fold": + return value.casefold() + raise AssertionError(f"validated source operation is not registered: {operation}") diff --git a/packages/adviso-compare/src/adviso_compare/records.py b/packages/adviso-compare/src/adviso_compare/records.py new file mode 100644 index 0000000..2ba69a1 --- /dev/null +++ b/packages/adviso-compare/src/adviso_compare/records.py @@ -0,0 +1,399 @@ +"""Resolve unambiguous record identity for custom and automatic comparisons.""" + +from __future__ import annotations + +import json +from dataclasses import dataclass +from types import MappingProxyType +from typing import Mapping + +from adviso_compare.configuration import ( + AUTOMATIC_CONFIGURATION_ID, + EffectiveConfiguration, + FieldDefinition, + JsonObject, + resolve_automatic_configuration, +) +from adviso_compare.inputs import ( + InputSide, + JsonLocation, + NativeCategory, + NativeValue, + ParsedDataset, + ParsedRecord, + SourceLocation, + TabularLocation, +) +from adviso_compare.translation import ( + ValueDisposition, + render_canonical_scalar, + translate_field_value, +) + + +@dataclass(frozen=True, slots=True) +class CanonicalKeyComponent: + """One typed, uniquely rendered component of a canonical record key.""" + + logical_type: str + text: str + + +RecordKey = tuple[CanonicalKeyComponent, ...] + + +@dataclass(frozen=True, slots=True) +class KeyedRecord: + """A source record accompanied by its source and canonical identities.""" + + record: ParsedRecord + key: RecordKey + source_identity: tuple[str, ...] + canonical_identity: tuple[str, ...] + + +@dataclass(frozen=True, slots=True) +class RecordModel: + """All records from one dataset indexed without silent replacement.""" + + side: InputSide + records: tuple[KeyedRecord, ...] + by_key: Mapping[RecordKey, KeyedRecord] + + +@dataclass(slots=True) +class RecordKeyError(Exception): + """An expected input failure that prevents unambiguous record identity.""" + + message: str + side: InputSide | None = None + key_fields: tuple[str, ...] = () + candidate_fields: tuple[str, ...] = () + locations: tuple[SourceLocation, ...] = () + code: str = "invalid_record_key" + + @property + def category(self) -> str: + """Return the stable execution-error category.""" + return "input" + + @property + def diagnostic(self) -> str: + """Render a value-free, single-line execution diagnostic.""" + return f"ERROR [input.{self.code}]: {self.message}" + + def __str__(self) -> str: + """Return the actionable value-free message.""" + return self.message + + +def generate_automatic_configuration( + reference: ParsedDataset, + query: ParsedDataset, +) -> EffectiveConfiguration: + """Select one conservative key and build strict preserved-exact rules.""" + key_name = _select_automatic_key(reference, query) + common_fields = sorted(set(reference.field_names) & set(query.field_names)) + ordered_fields = [key_name] + ordered_fields.extend(name for name in common_fields if name != key_name) + + definitions: JsonObject = { + key_name: { + "source_fields": { + "reference": key_name, + "query": key_name, + }, + "required": {"reference": True, "query": True}, + "logical_type": "string", + "null_policy": {"allowed": False, "nulls_equal": False}, + "comparator": {"name": "typed_exact"}, + } + } + for field_name in ordered_fields[1:]: + definitions[field_name] = { + "source_fields": { + "reference": field_name, + "query": field_name, + }, + "required": {"reference": False, "query": False}, + "null_policy": {"allowed": True, "nulls_equal": True}, + "comparator": {"name": "preserved_exact"}, + } + + document: JsonObject = { + "schema_version": "1.0", + "metadata": { + "id": AUTOMATIC_CONFIGURATION_ID, + "revision": "1.0", + }, + "fields": { + "record_key": [key_name], + "in_scope": ordered_fields, + "definitions": definitions, + }, + } + return resolve_automatic_configuration(document) + + +def build_record_model( + dataset: ParsedDataset, + configuration: EffectiveConfiguration, + side: InputSide, +) -> RecordModel: + """Translate configured key fields and reject every ambiguous identity.""" + keyed_records: list[KeyedRecord] = [] + index: dict[RecordKey, KeyedRecord] = {} + source_key_fields = tuple( + _source_field(configuration.field(name), side) + for name in configuration.record_key + ) + + for record in dataset.records: + components: list[CanonicalKeyComponent] = [] + source_identity: list[str] = [] + for canonical_name, source_name in zip( + configuration.record_key, + source_key_fields, + ): + field = configuration.field(canonical_name) + if not record.has_field(source_name): + raise _key_value_error( + side, + source_name, + "is missing", + record.location, + source_key_fields, + ) + source = record.value(source_name) + translated = translate_field_value(source, field, side) + if translated.is_null or source.category is NativeCategory.NULL: + raise _key_value_error( + side, + source_name, + "is null", + record.location_for(source_name), + source_key_fields, + ) + if ( + translated.disposition is not ValueDisposition.VALID + or translated.canonical is None + ): + raise _key_value_error( + side, + source_name, + "is invalid", + record.location_for(source_name), + source_key_fields, + ) + logical_type = field.logical_type + if not isinstance(logical_type, str): + raise AssertionError("validated key field is not scalar") + canonical_text = render_canonical_scalar( + translated.canonical.value, + logical_type, + ) + components.append(CanonicalKeyComponent(logical_type, canonical_text)) + source_identity.append(_source_identity_text(source)) + + key = tuple(components) + keyed = KeyedRecord( + record=record, + key=key, + source_identity=tuple(source_identity), + canonical_identity=tuple(component.text for component in key), + ) + previous = index.get(key) + if previous is not None: + locations = (previous.record.location, record.location) + fields_text = ", ".join(repr(name) for name in source_key_fields) + raise RecordKeyError( + message=( + f"{side.value} duplicate record key using {fields_text} at " + f"{_format_location(locations[0])} and " + f"{_format_location(locations[1])}" + ), + side=side, + key_fields=source_key_fields, + locations=locations, + ) + index[key] = keyed + keyed_records.append(keyed) + + return RecordModel( + side=side, + records=tuple(keyed_records), + by_key=MappingProxyType(index), + ) + + +def _select_automatic_key( + reference: ParsedDataset, + query: ParsedDataset, +) -> str: + """Apply the fixed record_id preference and candidate criteria.""" + shared_fields = sorted(set(reference.field_names) & set(query.field_names)) + if "record_id" in shared_fields: + _validate_automatic_record_id(reference, InputSide.REFERENCE) + _validate_automatic_record_id(query, InputSide.QUERY) + return "record_id" + + candidates = tuple( + field_name + for field_name in shared_fields + if _is_automatic_candidate(field_name, reference, query) + ) + if len(candidates) == 1: + return candidates[0] + if not candidates: + raise RecordKeyError( + message=( + "no field satisfied the automatic record-key criteria after " + "considering both inputs" + ) + ) + names = ", ".join(repr(name) for name in candidates) + raise RecordKeyError( + message=( + "automatic record-key selection is ambiguous after considering both " + f"inputs; candidate fields are {names}" + ), + candidate_fields=candidates, + ) + + +def _validate_automatic_record_id( + dataset: ParsedDataset, + side: InputSide, +) -> None: + """Require the preferred automatic key to be complete, string, and unique.""" + seen: dict[str, ParsedRecord] = {} + for record in dataset.records: + if not record.has_field("record_id"): + raise _key_value_error( + side, + "record_id", + "is missing", + record.location, + ("record_id",), + ) + value = record.value("record_id") + if value.category is not NativeCategory.STRING: + reason = ( + "is null" + if value.category is NativeCategory.NULL + else "is not a parser-native string" + ) + raise _key_value_error( + side, + "record_id", + reason, + record.location_for("record_id"), + ("record_id",), + ) + text = value.value + if not isinstance(text, str): + raise AssertionError("parser-native string does not contain text") + previous = seen.get(text) + if previous is not None: + locations = (previous.location, record.location) + raise RecordKeyError( + message=( + f"{side.value} duplicate record key using 'record_id' at " + f"{_format_location(locations[0])} and " + f"{_format_location(locations[1])}" + ), + side=side, + key_fields=("record_id",), + locations=locations, + ) + seen[text] = record + + +def _is_automatic_candidate( + field_name: str, + reference: ParsedDataset, + query: ParsedDataset, +) -> bool: + """Return whether one shared field satisfies every automatic-key criterion.""" + reference_values = _complete_unique_strings(reference, field_name) + if reference_values is None: + return False + query_values = _complete_unique_strings(query, field_name) + if query_values is None: + return False + return not reference_values.isdisjoint(query_values) + + +def _complete_unique_strings( + dataset: ParsedDataset, + field_name: str, +) -> set[str] | None: + """Return unique source strings, or None when the candidate is invalid.""" + values: set[str] = set() + for record in dataset.records: + if not record.has_field(field_name): + return None + value = record.value(field_name) + if value.category is not NativeCategory.STRING: + return None + text = value.value + if not isinstance(text, str): + raise AssertionError("parser-native string does not contain text") + if text in values: + return None + values.add(text) + return values + + +def _key_value_error( + side: InputSide, + source_name: str, + reason: str, + location: SourceLocation, + key_fields: tuple[str, ...], +) -> RecordKeyError: + """Construct one attributable, value-free key error.""" + return RecordKeyError( + message=( + f"{side.value} key field {source_name!r} {reason} at " + f"{_format_location(location)}" + ), + side=side, + key_fields=key_fields, + locations=(location,), + ) + + +def _source_field(field: FieldDefinition, side: InputSide) -> str: + """Select a field's source name for one dataset side.""" + if side is InputSide.REFERENCE: + return field.source_fields.reference + return field.source_fields.query + + +def _source_identity_text(value: NativeValue) -> str: + """Render a scalar source key using its retained lexical representation.""" + if value.category is NativeCategory.STRING: + if not isinstance(value.value, str): + raise AssertionError("parser-native string does not contain text") + return value.value + if value.category in {NativeCategory.INTEGER, NativeCategory.DECIMAL}: + if value.lexical is not None: + return value.lexical + return str(value.value) + if value.category is NativeCategory.BOOLEAN: + return "true" if value.value else "false" + raise AssertionError("validated key source is not a non-null scalar") + + +def _format_location(location: SourceLocation) -> str: + """Render a non-sensitive source location for an execution diagnostic.""" + if isinstance(location, TabularLocation): + return ( + f"record {location.record_number}, physical line " + f"{location.line_number}" + ) + if isinstance(location, JsonLocation): + pointer = json.dumps(location.pointer, ensure_ascii=False) + return f"JSON pointer {pointer}" + raise AssertionError("unknown source-location type") diff --git a/packages/adviso-compare/src/adviso_compare/reporting.py b/packages/adviso-compare/src/adviso_compare/reporting.py new file mode 100644 index 0000000..5e86d07 --- /dev/null +++ b/packages/adviso-compare/src/adviso_compare/reporting.py @@ -0,0 +1,954 @@ +"""Render and atomically publish the version 1 evidence package.""" + +from __future__ import annotations + +import ctypes +import errno +import html +import json +import os +import shutil +import stat +import sys +import tempfile +from dataclasses import dataclass +from pathlib import Path +from typing import Any, Mapping +from uuid import uuid4 + +from adviso_compare.configuration import AUTOMATIC_CONFIGURATION_ID +from adviso_compare.results import ( + ComparisonEvidence, + ResultValidationError, + parse_evidence_json, + validate_result, +) + + +RESULTS_FILENAME = "comparison-results.json" +CONFIGURATION_FILENAME = "comparison-configuration.json" +REPORT_FILENAME = "comparison-report.html" +_AT_FDCWD = -100 +_RENAME_NOREPLACE = 1 +_RENAME_EXCL = 4 + + +# Public reporting API + + +@dataclass(slots=True) +class OutputError(Exception): + """An expected failure while selecting or publishing output.""" + + code: str + message: str + + @property + def category(self) -> str: + """Return the stable execution-error category.""" + return "output" + + @property + def diagnostic(self) -> str: + """Render the stable single-line non-sensitive diagnostic.""" + return f"ERROR [output.{self.code}]: {self.message}" + + def __str__(self) -> str: + """Return the concise actionable message.""" + return self.message + + +def render_html_report( + document: Mapping[str, Any], configuration: Mapping[str, Any] +) -> bytes: + """Render a self-contained view of validated, linked JSON documents.""" + run = document["run"] + phases = document["phases"] + inputs = document["inputs"] + metadata = configuration["metadata"] + summary = document["summary"] + finding_summary = summary["findings"] + exclusions = document["exclusions"] + findings = document["findings"] + + status = str(run["status"]) + difference_count = finding_summary["by_classification"][ + "comparison_difference" + ] + issue_count = finding_summary["by_classification"]["assessment_issue"] + sections = [ + "", + '', + "", + '', + '', + "adviso-compare evidence report", + "", + "", + "", + '", + '
', + '

Run summary

', + '
', + _metric("Run completeness", status.title(), status, "coverage"), + _metric( + "Comparison differences", str(difference_count), "difference", + "comparison-differences", + ), + _metric( + "Assessment issues", str(issue_count), "issue", "assessment-issues" + ), + "
", + '

' + " · ".join( + f"{name.title()}: {_escape(phases[name].title())}" + "" + for name in ("contract", "records", "values") + ) + "

", + '

This comparison translated the inputs ' + "under the saved configuration and performed contract, records, " + "and values phases. Completeness describes assessment coverage, " + "not acceptance. Review and " + "approval occur outside the tool.

", + "
", + '
' + '

Coverage and limitations

', + _coverage_summary(summary), + ] + if metadata["id"] == AUTOMATIC_CONFIGURATION_ID: + sections.append(_automatic_mode_notice()) + sections.extend( + ( + _limitations_section(exclusions, configuration), + "
", + _findings_section( + findings, document["record_key_fields"], configuration + ), + '
' + '

Supporting detail

' + '
Full counts and comparison phases', + _phase_section(phases), + _counts_section(summary), + "
", + _provenance_section(document, configuration), + _review_section(), + "
", + "", + "", + "", + ) + ) + return "\n".join(sections).encode("utf-8") + + +# Evidence-package publication + + +def validate_evidence_package(directory: Path) -> None: + """Validate saved JSON evidence, including fixed members and byte linkage. + + This checks the invariants available from the package; it cannot reproduce + the comparison without its source inputs and comparison context. + """ + directory = Path(directory) + try: + members = {member.name for member in directory.iterdir()} + except OSError as error: + raise ResultValidationError( + "evidence package is unreadable" + ) from error + if members != {RESULTS_FILENAME, CONFIGURATION_FILENAME, REPORT_FILENAME}: + raise ResultValidationError("evidence package members are invalid") + document = parse_evidence_json( + _read_regular_member(directory / RESULTS_FILENAME) + ) + configuration_bytes = _read_regular_member( + directory / CONFIGURATION_FILENAME + ) + _require_regular_member(directory / REPORT_FILENAME) + validate_result(document, configuration_bytes=configuration_bytes) + + +def _require_regular_member(path: Path) -> os.stat_result: + """Inspect a fixed sibling without accepting a symbolic link.""" + try: + status = path.lstat() + except OSError as error: + raise ResultValidationError( + "evidence member is unavailable" + ) from error + if not stat.S_ISREG(status.st_mode): + raise ResultValidationError("evidence member must be a regular file") + return status + + +def _read_regular_member(path: Path) -> bytes: + """Read a regular sibling, refusing links and replacement during open.""" + expected = _require_regular_member(path) + flags = os.O_RDONLY + for option in ("O_NOFOLLOW", "O_NONBLOCK", "O_BINARY"): + flags |= getattr(os, option, 0) + try: + descriptor = os.open(path, flags) + with os.fdopen(descriptor, "rb") as stream: + actual = os.fstat(stream.fileno()) + current = _require_regular_member(path) + if not ( + stat.S_ISREG(actual.st_mode) + and os.path.samestat(expected, actual) + and os.path.samestat(current, actual) + ): + raise ResultValidationError( + "evidence member changed during open" + ) + return stream.read() + except OSError as error: + raise ResultValidationError("evidence member is unreadable") from error + + +def publish_evidence_package(parent: Path, result: ComparisonEvidence) -> Path: + """Publish validated evidence in a child named from its run metadata.""" + document = result.document() + json_content = result.json_bytes + html_content = render_html_report( + document, result.configuration_document() + ) + run = document["run"] + timestamp = run["completed_at"].replace("-", "").replace(":", "") + parent = Path(parent) + destination = parent / f"{timestamp}-{run['id']}" + staging_root: Path | None = None + try: + _prepare_output_parent(parent) + _require_absent(destination) + staging_root = Path( + tempfile.mkdtemp(prefix=".adviso-compare.staging-", dir=parent) + ) + os.chmod(staging_root, 0o700) + stage = staging_root / "package" + stage.mkdir(mode=0o700) + _write_atomic_member(stage / RESULTS_FILENAME, json_content) + _write_atomic_member( + stage / CONFIGURATION_FILENAME, result.configuration_bytes + ) + _write_atomic_member(stage / REPORT_FILENAME, html_content) + _fsync_directory(stage) + _publish_new_package(stage, destination) + _fsync_directory(parent) + except OutputError: + raise + except OSError as error: + raise OutputError( + code="write_failed", + message=( + "the output parent or evidence package could not be written" + ), + ) from error + finally: + if staging_root is not None: + _remove_temporary_directory(staging_root) + return destination + + +def _prepare_output_parent(parent: Path) -> None: + """Accept or privately create a regular parent without reading contents.""" + try: + mode = parent.lstat().st_mode + except (FileNotFoundError, NotADirectoryError): + if not parent.parent.is_dir(): + raise OutputError( + code="invalid_destination", + message="the output parent's enclosing directory must exist", + ) from None + try: + parent.mkdir(mode=0o700) + except FileExistsError: + # A concurrent publisher may have created the shared parent. + pass + mode = parent.lstat().st_mode + if not stat.S_ISDIR(mode): + raise OutputError( + code="invalid_destination", + message=( + "the output parent must be a regular directory, not a link" + ), + ) + + +def _publish_new_package(stage: Path, destination: Path) -> None: + """Publish atomically without replacing an object at the final path.""" + try: + _rename_exclusively(stage, destination) + except OSError as error: + if error.errno in {errno.ENOTSUP, errno.ENOSYS, errno.EINVAL}: + raise OutputError( + code="write_failed", + message=( + "the destination does not support safe directory " + "publication; select a different filesystem" + ), + ) from error + if error.errno not in {errno.EEXIST, errno.ENOTEMPTY}: + raise + raise OutputError( + code="invalid_destination", + message="the run-directory path is already occupied", + ) from error + + +def _rename_exclusively(source: Path, destination: Path) -> None: + """Publish with the host's exclusive rename primitive.""" + if sys.platform == "win32": + # Windows os.rename refuses every existing destination. + os.rename(source, destination) + return + if sys.platform not in {"linux", "darwin"}: + raise OSError( + errno.ENOTSUP, "exclusive directory rename is unavailable" + ) + + library = ctypes.CDLL(None, use_errno=True) + try: + if sys.platform == "linux": + rename = library.renameat2 + rename.argtypes = ( + ctypes.c_int, ctypes.c_char_p, + ctypes.c_int, ctypes.c_char_p, ctypes.c_uint, + ) + rename.restype = ctypes.c_int + result = rename( + _AT_FDCWD, os.fsencode(source), + _AT_FDCWD, os.fsencode(destination), _RENAME_NOREPLACE, + ) + else: + rename = library.renamex_np + rename.argtypes = ( + ctypes.c_char_p, ctypes.c_char_p, ctypes.c_uint, + ) + rename.restype = ctypes.c_int + result = rename( + os.fsencode(source), os.fsencode(destination), _RENAME_EXCL, + ) + except AttributeError as error: + raise OSError( + errno.ENOTSUP, "exclusive directory rename is unavailable" + ) from error + if result != 0: + error_number = ctypes.get_errno() + raise OSError(error_number, os.strerror(error_number)) + + +def _require_absent(destination: Path) -> None: + """Refuse an occupied run path without following symbolic links.""" + try: + destination.lstat() + except FileNotFoundError: + return + raise OutputError( + code="invalid_destination", + message="the run-directory path is already occupied", + ) + + +def _write_atomic_member(path: Path, content: bytes) -> None: + """Write one private member and atomically give it its final staged name.""" + temporary = path.with_name(f".{path.name}.temporary-{uuid4().hex}") + descriptor: int | None = None + try: + descriptor = os.open( + temporary, + os.O_WRONLY | os.O_CREAT | os.O_EXCL, + 0o600, + ) + with os.fdopen(descriptor, "wb") as stream: + descriptor = None + stream.write(content) + stream.flush() + os.fsync(stream.fileno()) + os.chmod(temporary, 0o600) + os.replace(temporary, path) + finally: + if descriptor is not None: + os.close(descriptor) + try: + temporary.unlink() + except FileNotFoundError: + pass + + +def _remove_temporary_directory(path: Path) -> None: + """Best-effort removal of this invocation's private staging directory.""" + for _ in range(2): + try: + shutil.rmtree(path) + return + except FileNotFoundError: + return + except OSError: + continue + + +def _fsync_directory(path: Path) -> None: + """Request durable directory metadata where the platform supports it.""" + flags = os.O_RDONLY + if hasattr(os, "O_DIRECTORY"): + flags |= os.O_DIRECTORY + try: + descriptor = os.open(path, flags) + except OSError: + return + try: + os.fsync(descriptor) + except OSError: + pass + finally: + os.close(descriptor) + + +# HTML rendering helpers + + +def _metric(label: str, value: str, kind: str, target: str) -> str: + """Render one headline measure linked to its review context.""" + return ( + f'' + f"{_escape(label)}{_escape(value)}" + ) + + +def _phase_section(phases: Mapping[str, Any]) -> str: + """Render the ordered comparison-phase traceability table.""" + rows = "".join( + f"{_escape(name.title())}" + f"{_escape(str(phases[name]).title())}" + for name in ("contract", "records", "values") + ) + return ( + '
' + '

Comparison phases

' + "

The phases were performed in the order shown.

" + f"" + f"{rows}
PhaseCompletion status
" + ) + + +def _identity_section( + inputs: Mapping[str, Any], metadata: Mapping[str, Any], + run: Mapping[str, Any], +) -> str: + """Identify the compared inputs and configuration before the outcome.""" + title = ( + f"
Configuration title
{_escape(metadata['title'])}
" + if metadata.get("title") else "" + ) + return ( + '

Compared inputs ' + 'and configuration

' + f"
Reference
{_escape(inputs['reference']['basename'])}
" + f"
Query
{_escape(inputs['query']['basename'])}
" + + title + + "
Configuration identifier
" + f"
{_escape(metadata['id'])}
" + f"
Configuration revision
{_escape(metadata['revision'])}
" + f"
Completed at (UTC)
{_escape(run['completed_at'])}
" + "
" + ) + + +def _automatic_mode_notice() -> str: + """Render the required limitations warning for automatic mode.""" + return ( + '" + ) + + +def _counts_section(summary: Mapping[str, Any]) -> str: + """Render record, value, and finding metrics without deriving a verdict.""" + records = summary["records"] + values = summary["values"] + findings = summary["findings"] + return ( + '
' + '

Measured counts

' + "

Records

" + + _definition_list(records) + + "

Values

" + + _definition_list(values) + + "

Findings

Total findings: " + + f"{findings['total']}

" + + "

Findings by classification

" + + _definition_list(findings["by_classification"]) + + "

Findings by code

" + + _definition_list(findings["by_code"]) + + "

Findings by review priority

" + + _definition_list(findings["by_review_priority"]) + + "
" + ) + + +def _findings_section( + findings: list[Mapping[str, Any]], + key_fields: Mapping[str, Any], + configuration: Mapping[str, Any], +) -> str: + """Render findings classification-first with phase as traceability.""" + groups = [] + labels = ( + ("comparison_difference", "Comparison differences"), + ("assessment_issue", "Assessment issues"), + ) + for classification, label in labels: + selected = [ + finding + for finding in findings + if finding["classification"] == classification + ] + items = "".join( + _finding_card(finding, key_fields, configuration) + for finding in selected + ) + if not items: + items = "

None reported.

" + target = ( + "comparison-differences" + if classification == "comparison_difference" + else "assessment-issues" + ) + groups.append( + f'

' + f"{label} ({len(selected)})

{items}
" + ) + return ( + '

Finding details

' + + "".join(groups) + + "
" + ) + + +def _finding_card( + finding: Mapping[str, Any], key_fields: Mapping[str, Any], + configuration: Mapping[str, Any], +) -> str: + """Show the affected record, field and value evidence before raw detail.""" + priority = finding.get("review_priority", "unassigned") + structured = { + name: value + for name, value in finding.items() + if name not in {"id", "classification", "message", "phase", "review_priority"} + } + evidence = _escape(json.dumps(structured, ensure_ascii=False, indent=2)) + identity = finding.get("record_identity") + if identity is None: + context = "
Scope
Dataset-level finding
" + else: + context = ( + "
Record
" + + _escape(_key_text( + key_fields["canonical"], identity["canonical"] + )) + + "
" + ) + field = finding.get("field") + if field is not None: + context += f"
Field
{_escape(field)}
" + context += ( + "
Affected side
" + f"
{_escape(finding['affected_side'].title())}
" + ) + if "values" in finding: + definition = configuration["fields"]["definitions"][field] + comparison = _value_table(finding["values"], definition) + elif identity is not None: + comparison = _record_presence(identity, key_fields) + else: + comparison = "" + return ( + f'
' + f"

{_escape(finding['id'])} · " + f"{_escape(finding['code'].replace('_', ' ').capitalize())}

" + f"

{_escape(finding['message'])}

" + f'
{context}
' + f'

Phase: {_escape(finding["phase"])} ' + f'Priority: ' + f"{_escape(priority)}

" + + comparison + + "
Source locations and structured evidence" + "" + f"
{evidence}
" + "
" + ) + + +def _key_text(names: list[str], values: list[str]) -> str: + """Keep composite components and empty key strings unambiguous.""" + return "; ".join( + f"{name} = {json.dumps(value, ensure_ascii=False)}" + for name, value in zip(names, values) + ) + + +def _record_presence( + identity: Mapping[str, Any], key_fields: Mapping[str, Any] +) -> str: + """Present missing/extra records without inventing field-value evidence.""" + entries = {} + for side in ("reference", "query"): + entries[side] = ( + "Record absent" if identity[side] is None + else _key_text(key_fields[side], identity[side]) + ) + return _definition_list(entries) + + +def _value_table( + values: Mapping[str, Any], definition: Mapping[str, Any] +) -> str: + """Present recorded evidence without inferring omitted values.""" + rows = [] + for side in ("reference", "query"): + evidence = values[side] + if evidence["state"] == "absent": + source = canonical = ( + 'Absent field' + ) + else: + source = ( + _source_value(evidence["source"]) + if "source" in evidence else "Present; value not recorded" + ) + if "canonical" in evidence: + canonical = _canonical_value(evidence["canonical"]) + elif "logical_type" not in definition: + canonical = "Not applicable (untyped)" + else: + canonical = "Not recorded" + rows.append( + f'{side.title()}' + f"{source}{canonical}" + ) + return ( + '
' + "" + '' + '' + f"{''.join(rows)}
Value evidence
SideSource valueCanonical value
" + ) + + +def _source_value(value: Mapping[str, Any]) -> str: + """Show original lexical values and native types, including nested data.""" + if value["category"] == "null": + return 'Null (present)' + return ( + f'{_escape(value["category"])}' + f'{_escape(_source_text(value))}' + ) + + +def _source_text(value: Mapping[str, Any]) -> str: + """Render nested native values without converting numeric lexical text.""" + category = value["category"] + if category == "null": + return "null" + content = value["value"] + if category == "array": + return "[" + ", ".join(_source_text(item) for item in content) + "]" + if category == "object": + return "{" + ", ".join( + json.dumps(name, ensure_ascii=False) + ": " + + _source_text(content[name]) + for name in sorted(content) + ) + "}" + return _scalar_text(content, category) + + +def _scalar_text(value: Any, logical_type: str) -> str: + """Distinguish empty strings, string-like tokens, booleans and null.""" + if value is None or logical_type in {"string", "boolean"}: + return json.dumps(value, ensure_ascii=False) + return str(value) + + +def _canonical_value(value: Mapping[str, Any]) -> str: + """Show canonical type and content while preserving collection order.""" + logical_type = value["logical_type"] + content = value["value"] + if content is None: + rendered = "Null (present)" + elif "element_type" in value: + rendered = "[" + ", ".join( + _scalar_text(item, value["element_type"]) for item in content + ) + "]" + logical_type += f" of {value['element_type']}" + else: + rendered = _scalar_text(content, logical_type) + return ( + f'{_escape(logical_type)}' + f'{_escape(rendered)}' + ) + + +def _coverage_summary(summary: Mapping[str, Any]) -> str: + """Put the assessed volume and incomplete work beside the outcome.""" + records, values = summary["records"], summary["values"] + return ( + '

Records

' + f"

Reference: {records['reference']} · " + f"Query: {records['query']} · " + f"Matched pairs: {records['matched']}

" + "

Value comparisons

" + f"

Matched: {values['matched']} · " + f"Mismatched: {values['mismatched']} · " + f"Not assessable: {values['not_assessable']}

" + '

Counts cover in-scope non-key fields in ' + "matched record pairs.

" + ) + + +def _limitations_section( + exclusions: list[Mapping[str, Any]], + configuration: Mapping[str, Any], +) -> str: + """Render excluded and not-assessable content explicitly.""" + exclusion_items = "".join( + f"
  • {_escape(item['code'])}: " + f"{_escape(_exclusion_description(item))}
  • " + for item in exclusions + ) + if not exclusion_items: + exclusion_items = "
  • No field exclusions were reported.
  • " + fields = configuration["fields"]["in_scope"] + scope = ", ".join(f"{_escape(name)}" for name in fields) + return ( + '
    ' + f"Scope: {len(fields)} selected fields (including keys) · " + f"Exclusions: {len(exclusions)}" + f"

    Fields in scope: {scope}.

    " + f"
      {exclusion_items}
    " + ) + + +def _exclusion_description(item: Mapping[str, Any]) -> str: + """Describe one fixed exclusion form from its structured properties.""" + if item["code"] == "configured_field_excluded": + return f"configured canonical field {item['canonical_field']} was out of scope" + return ( + f"{item['side']} source field {item['source_field']} was undeclared " + f"({item['record_count']} records)" + ) + + +def _provenance_section( + document: Mapping[str, Any], configuration: Mapping[str, Any] +) -> str: + """Render provenance and saved configuration for reproduction.""" + run = document["run"] + software = document["software"] + runtime = document["runtime"] + inputs = document["inputs"] + input_rows = "".join( + "" + f"{_escape(side.title())}" + f"{_escape(value['basename'])}" + f"{_escape(value['format'])}" + f"{_escape(value['digest']['value'])}" + "" + for side, value in ( + ("reference", inputs["reference"]), + ("query", inputs["query"]), + ) + ) + config_json = _escape(json.dumps(configuration, ensure_ascii=False, indent=2)) + return ( + '

    Provenance and ' + "reproduction

    Software, schemas, input digests, " + "and configuration
    " + f"
    Run identifier
    {_escape(run['id'])}
    " + f"
    Completed at
    {_escape(run['completed_at'])}
    " + f"
    Software
    {_escape(software['name'])} " + f"{_escape(software['version'])}
    " + f"
    Python
    {_escape(runtime['python'])}
    " + f"
    Platform
    {_escape(runtime['platform'])}
    " + f"
    Unicode data
    {_escape(runtime['unicode_version'])}
    " + "
    Results schema
    " + f"{_escape(document['schema_version'])}
    " + "
    Configuration schema
    " + f"{_escape(configuration['schema_version'])}" + "
    " + "
    Configuration SHA-256
    " + f"{_escape(document['comparison_configuration_digest']['value'])}" + "
    " + "

    Input byte provenance

    " + "" + f"{input_rows}" + "
    SideBasenameFormatSHA-256
    Effective comparison configuration" + f"
    {config_json}
    " + ) + + +def _review_section() -> str: + """Provide generic space for governance outside the comparison tool.""" + return ( + '

    External review and ' + "approval

    Reviewer: ____________________

    " + "

    Date: ____________________

    Review notes:

    " + '
    ' + "
    " + ) + + +def _definition_list(values: Mapping[str, Any]) -> str: + """Render a compact labelled count list.""" + entries = "".join( + f"
    {_escape(name.replace('_', ' ').title())}
    {_escape(value)}
    " + for name, value in values.items() + ) + return f'
    {entries}
    ' + + +def _escape(value: object) -> str: + """Escape one canonical value for HTML text or attribute use.""" + return html.escape(str(value), quote=True) + + +_STYLES = """ +:root { + color-scheme: light; + font-family: system-ui, sans-serif; + line-height: 1.5; + color: #17202a; + background: #f3f5f7; +} +* { box-sizing: border-box; } +body { margin: 0; } +.page-header, main { max-width: 76rem; margin: 0 auto; padding: 1.25rem 2rem; } +.page-header { border-top: .35rem solid #244b6b; background: #fff; } +h1 { font-size: 1.65rem; margin: 0 0 .75rem; } +h2 { font-size: 1.3rem; margin: 0 0 .75rem; } +h3 { font-size: 1.1rem; } +h4 { font-size: 1rem; } +p { margin: .5rem 0; } +a { color: #174e80; text-underline-offset: .15em; } +a:hover { text-decoration-thickness: .15em; } +a:focus-visible, summary:focus-visible { + outline: .2rem solid #174e80; + outline-offset: .2rem; +} +[id] { scroll-margin-top: 1rem; } +nav { display: flex; flex-wrap: wrap; gap: .5rem 1.25rem; padding: .5rem 0; } +section { margin-block: 1.5rem; } +.page-header section { margin-block: .5rem; } +#identities h2 { font-size: 1rem; color: #465563; } +dl { display: grid; grid-template-columns: minmax(8rem, 1fr) 3fr; gap: .3rem 1rem; } +dt { font-weight: 650; } +dd { margin: 0; min-width: 0; overflow-wrap: anywhere; } +.identities { grid-template-columns: max-content 1fr max-content 1fr; font-size: .9rem; } +.warning, .notice { + border-left: .25rem solid #8a4b08; + padding: .6rem .85rem; + background: #fff4df; + font-size: .9rem; +} +.headline-grid, .coverage-grid { display: grid; gap: 1rem; } +.headline-grid { grid-template-columns: repeat(3, minmax(0, 1fr)); } +.metric { + border: 1px solid #b9c5d0; + border-top: .25rem solid #244b6b; + border-radius: .35rem; + padding: .75rem 1rem; + background: #fff; + color: inherit; + text-decoration: none; +} +.metric:hover { background: #eaf0f6; } +.metric span, .metric strong { display: block; } +.metric strong { font-size: 1.8rem; } +.metric-incomplete { border-top-color: #8a4b08; } +.phase-statuses { display: flex; flex-wrap: wrap; gap: .4rem; font-size: .9rem; } +.explanation { color: #465563; font-size: .9rem; } +.coverage-grid { grid-template-columns: repeat(2, minmax(0, 1fr)); } +.coverage-grid h3 { margin: .25rem 0; } +#coverage { border: 1px solid #c7d0d9; padding: 1rem; background: #fff; } +#coverage aside { margin: .75rem 0; } +details { margin-top: .75rem; } +summary { cursor: pointer; color: #174e80; font-weight: 600; padding: .4rem 0; } +details[open] > summary { margin-bottom: .5rem; } +.counts { grid-template-columns: repeat(2, minmax(8rem, max-content)); } +.finding { + border: 1px solid #c7d0d9; + border-left: .3rem solid #244b6b; + border-radius: .25rem; + padding: 1rem; + margin-block: 1rem; + background: #fff; +} +.finding h4 { margin: 0; } +.finding-context { grid-template-columns: max-content 1fr; margin-block: .75rem; } +.label { + display: inline-block; + border: 1px solid #667685; + border-radius: .25rem; + padding: .1rem .4rem; + margin: .1rem .4rem .1rem 0; + font-size: .85rem; +} +.priority-high::before { content: "▲ "; } +.priority-normal::before { content: "● "; } +.priority-low::before { content: "▼ "; } +.priority-unassigned::before { content: "— "; } +.table-scroll { overflow-x: auto; } +table { border-collapse: collapse; width: 100%; background: #fff; } +caption { text-align: left; font-weight: 650; padding-block: .4rem; } +th, td { + border: 1px solid #c7d0d9; + padding: .6rem; + text-align: left; + vertical-align: top; +} +thead { background: #eaf0f6; } +.value-evidence { table-layout: fixed; } +.value-evidence th:first-child { width: 18%; } +.value-type { display: block; color: #465563; font-size: .85rem; } +.value { display: block; white-space: pre-wrap; overflow-wrap: anywhere; } +.value-state { font-style: italic; } +pre { white-space: pre-wrap; overflow-wrap: anywhere; background: #eaf0f6; padding: 1rem; } +code { overflow-wrap: anywhere; } +.review-space { min-height: 8rem; border: 1px solid #667685; background: #fff; } +@media (max-width: 44rem) { + .page-header, main { padding: 1rem; } + .identities { grid-template-columns: minmax(6rem, 1fr) 2fr; } + .headline-grid, .coverage-grid { grid-template-columns: 1fr; } + .metric strong { font-size: 1.5rem; } + .value-evidence { table-layout: auto; } +} +@media print { + :root { background: #fff; font-size: 10pt; } + .page-header, main { max-width: none; padding: .5rem; } + nav { display: none; } + .finding { break-inside: avoid; } + .headline-grid { grid-template-columns: repeat(3, minmax(0, 1fr)); } + details::details-content { content-visibility: visible; } + details > * { display: block; } + .table-scroll { overflow: visible; } +} +""".strip() diff --git a/packages/adviso-compare/src/adviso_compare/results.py b/packages/adviso-compare/src/adviso_compare/results.py new file mode 100644 index 0000000..e7db1c7 --- /dev/null +++ b/packages/adviso-compare/src/adviso_compare/results.py @@ -0,0 +1,1256 @@ +"""Assemble, validate, and serialize canonical comparison results.""" + +from __future__ import annotations + +import json +import math +import platform as runtime_platform +import unicodedata +from collections import Counter +from dataclasses import dataclass, field +from datetime import datetime, timezone +from functools import lru_cache +from hashlib import sha256 +from typing import TYPE_CHECKING, Any, Mapping +from uuid import UUID, uuid4 + +from jsonschema import Draft202012Validator, FormatChecker, ValidationError + +from adviso_compare._version import __version__ +from adviso_compare.alignment import RecordAlignment, RecordFinding, RecordsResult +from adviso_compare.configuration import ( + ConfigurationError, + EffectiveConfiguration, + FieldDefinition, + validate_saved_configuration, +) +from adviso_compare.contract import ( + ConfiguredFieldExclusion, + ContractFinding, + ContractResult, + FieldAssessment, + UndeclaredFieldExclusion, +) +from adviso_compare.inputs import ( + InputSide, + JsonLocation, + NativeCategory, + NativeValue, + ParsedDataset, + SourceLocation, + TabularLocation, +) +from adviso_compare.schemas import load_schema +from adviso_compare.translation import ( + CanonicalValue, + TranslatedValue, + ValueDisposition, + render_canonical_scalar, +) +from adviso_compare.values import ValueFinding, ValuesResult + +if TYPE_CHECKING: + from adviso_compare.application import PreparedComparison + + +JsonObject = dict[str, Any] +FINDING_CODES = ( + "missing_record", + "extra_record", + "missing_required_field", + "type_mismatch", + "invalid_field_value", + "null_policy_violation", + "mapping_failure", + "value_mismatch", +) +CLASSIFICATIONS = ("comparison_difference", "assessment_issue") +REVIEW_PRIORITIES = ("low", "normal", "high", "unassigned") +SUPPORTED_SCHEMA_COMBINATIONS = frozenset({("1.0", "1.0")}) + + +# Public result types and assembly API + + +@dataclass(frozen=True, slots=True, init=False) +class ComparisonEvidence: + """Immutable result and configuration bytes validated in context.""" + + _json_bytes: bytes = field(repr=False) + _configuration_bytes: bytes = field(repr=False) + + @classmethod + def _from_validated_bytes( + cls, json_bytes: bytes, configuration_bytes: bytes + ) -> ComparisonEvidence: + """Create an artifact after contextual validation has succeeded.""" + instance = object.__new__(cls) + object.__setattr__(instance, "_json_bytes", json_bytes) + object.__setattr__( + instance, "_configuration_bytes", configuration_bytes + ) + return instance + + @property + def json_bytes(self) -> bytes: + """Return the exact UTF-8 JSON serialization selected for publication.""" + return self._json_bytes + + def document(self) -> JsonObject: + """Return a new mutable view of the canonical JSON document.""" + return parse_evidence_json(self._json_bytes) + + @property + def configuration_bytes(self) -> bytes: + """Return the exact configuration bytes hashed with the results.""" + return self._configuration_bytes + + def configuration_document(self) -> JsonObject: + """Return a fresh mutable view of the saved effective configuration.""" + return parse_evidence_json(self._configuration_bytes) + + +@dataclass(frozen=True, slots=True) +class RuntimeIdentity: + """Non-identifying software-runtime provenance.""" + + python: str + platform: str + unicode_version: str + + +@dataclass(slots=True) +class ResultValidationError(ValueError): + """Generated or saved evidence violates a package-validation rule.""" + + message: str + + def __str__(self) -> str: + """Return the concise invariant failure.""" + return self.message + + +def current_runtime_identity() -> RuntimeIdentity: + """Return normalized, non-identifying runtime provenance.""" + implementation = runtime_platform.python_implementation().casefold() + version = runtime_platform.python_version() + operating_system = runtime_platform.system().casefold() + operating_system = {"darwin": "macos"}.get( + operating_system, + operating_system, + ) + architecture = runtime_platform.machine().casefold() + architecture = { + "amd64": "x86_64", + "arm64": "aarch64", + }.get(architecture, architecture) + return RuntimeIdentity( + python=f"{implementation}-{version}", + platform=f"{operating_system}-{architecture}", + unicode_version=unicodedata.unidata_version, + ) + + +def assemble_result( + prepared: PreparedComparison, + contract: ContractResult, + records: RecordsResult, + values: ValuesResult, + *, + run_id: UUID | None = None, + completed_at: datetime | None = None, + software_version: str = __version__, + runtime: RuntimeIdentity | None = None, +) -> ComparisonEvidence: + """Serialize and contextually validate the linked evidence documents.""" + identifier = run_id or uuid4() + completion = completed_at or datetime.now(timezone.utc) + if identifier.version != 4: + raise ValueError("run_id must be a UUID version 4") + if completion.tzinfo is None or completion.utcoffset() is None: + raise ValueError("completed_at must be timezone-aware") + completion_text = completion.astimezone(timezone.utc).replace( + microsecond=0 + ).strftime("%Y-%m-%dT%H:%M:%SZ") + runtime_identity = runtime or current_runtime_identity() + configuration_document = prepared.configuration.document + ordered_configuration = _ordered_configuration(configuration_document) + if ordered_configuration != configuration_document: + raise ResultValidationError("configuration serialization lost content") + configuration_bytes = serialize_result(ordered_configuration) + + findings = _assemble_findings(prepared.configuration, contract, records, values) + phase_statuses = { + "contract": contract.status.value, + "records": records.status.value, + "values": values.status.value, + } + run_status = ( + "complete" + if all(status == "complete" for status in phase_statuses.values()) + else "incomplete" + ) + document: JsonObject = { + "schema_version": "1.0", + "run": { + "id": str(identifier), + "status": run_status, + "completed_at": completion_text, + }, + "phases": phase_statuses, + "software": {"name": "adviso-compare", "version": software_version}, + "runtime": { + "python": runtime_identity.python, + "platform": runtime_identity.platform, + "unicode_version": runtime_identity.unicode_version, + }, + "inputs": { + "reference": _input_document(prepared.reference), + "query": _input_document(prepared.query), + }, + "record_key_fields": _record_key_fields(prepared.configuration), + "comparison_configuration_digest": { + "algorithm": "sha256", + "value": sha256(configuration_bytes).hexdigest(), + }, + "summary": _summary_document(records, values, findings), + "exclusions": [_exclusion_document(item) for item in contract.exclusions], + "findings": findings, + } + json_bytes = serialize_result(document) + serialized_document = parse_evidence_json(json_bytes) + validate_result( + serialized_document, + configuration_bytes=configuration_bytes, + prepared=prepared, + contract=contract, + records=records, + values=values, + ) + return ComparisonEvidence._from_validated_bytes( + json_bytes, configuration_bytes + ) + + +def serialize_result(document: Mapping[str, object]) -> bytes: + """Serialize an ordered evidence document as canonical UTF-8 JSON.""" + return ( + json.dumps( + document, + ensure_ascii=False, + indent=2, + allow_nan=False, + ) + + "\n" + ).encode("utf-8") + + +def validate_result( + document: JsonObject, + *, + configuration_bytes: bytes | None = None, + prepared: PreparedComparison | None = None, + contract: ContractResult | None = None, + records: RecordsResult | None = None, + values: ValuesResult | None = None, +) -> None: + """Validate results, configuration byte linkage, and shared semantics. + + Source-dependent checks additionally use comparison context when provided. + Structural validation alone is available through the packaged schemas. + """ + version = document.get("schema_version") + if not isinstance(version, str): + raise ResultValidationError("results schema version is required") + try: + _results_validator(version).validate(document) + except (ValueError, ValidationError) as error: + raise ResultValidationError( + "canonical result failed schema validation" + ) from error + if configuration_bytes is None: + raise ResultValidationError("saved configuration bytes are required") + _require( + sha256(configuration_bytes).hexdigest() + == document["comparison_configuration_digest"]["value"], + "saved configuration digest does not match", + ) + configuration = parse_evidence_json(configuration_bytes) + try: + validate_saved_configuration(configuration) + except ConfigurationError as error: + raise ResultValidationError( + "saved configuration failed validation" + ) from error + _require( + (version, configuration["schema_version"]) + in SUPPORTED_SCHEMA_COMBINATIONS, + "unsupported results and configuration schema combination", + ) + _validate_semantics( + document, configuration, prepared, contract, records, values + ) + + +@lru_cache(maxsize=1) +def _results_validator(version: str) -> Draft202012Validator: + """Load the results schema independently with format assertion.""" + return Draft202012Validator( + load_schema("results", version), format_checker=FormatChecker() + ) + + +def parse_evidence_json(content: bytes) -> JsonObject: + """Parse strict UTF-8 JSON evidence, rejecting duplicate object members.""" + def object_members(pairs: list[tuple[str, Any]]) -> JsonObject: + document: JsonObject = {} + for name, value in pairs: + if name in document: + raise ValueError("duplicate JSON member") + document[name] = value + return document + + def reject_constant(value: str) -> Any: + raise ValueError("non-standard JSON number") + + def finite_float(value: str) -> float: + number = float(value) + if not math.isfinite(number): + raise ValueError("non-finite JSON number") + return number + + try: + document = json.loads( + content.decode("utf-8"), + object_pairs_hook=object_members, + parse_constant=reject_constant, + parse_float=finite_float, + ) + except (UnicodeDecodeError, ValueError) as error: + raise ResultValidationError( + "evidence is not strict UTF-8 JSON" + ) from error + if not isinstance(document, dict): + raise ResultValidationError("evidence JSON root is not an object") + return document + + +# Result-document assembly helpers + + +def _input_document(dataset: ParsedDataset) -> JsonObject: + """Render exact-byte input provenance without exposing a path.""" + provenance = dataset.provenance + return { + "basename": provenance.basename, + "format": provenance.format.value, + "encoding": provenance.encoding, + "size_bytes": provenance.size_bytes, + "digest": {"algorithm": "sha256", "value": provenance.sha256}, + } + + +def _record_key_fields(configuration: EffectiveConfiguration) -> JsonObject: + """Render ordered source and canonical key-field declarations.""" + return { + "reference": [ + configuration.field(name).source_fields.reference + for name in configuration.record_key + ], + "query": [ + configuration.field(name).source_fields.query + for name in configuration.record_key + ], + "canonical": list(configuration.record_key), + } + + +def _ordered_configuration(document: JsonObject) -> JsonObject: + """Return the configuration in fixed-schema and dynamic-name order.""" + metadata = document["metadata"] + fields = document["fields"] + definitions = fields["definitions"] + return { + "schema_version": document["schema_version"], + "metadata": _ordered_selected( + metadata, + ("id", "revision", "title", "description"), + ), + "fields": { + "record_key": fields["record_key"], + "in_scope": fields["in_scope"], + "definitions": { + name: _ordered_field_definition(definitions[name]) + for name in sorted(definitions) + }, + }, + } + + +def _ordered_field_definition(document: JsonObject) -> JsonObject: + """Order one saved field declaration without applying defaults.""" + ordered: JsonObject = {} + for name in ( + "source_fields", + "required", + "logical_type", + "null_policy", + "source_normalisation", + "collection_representation", + "value_mapping", + "typed_normalisation", + "comparator", + "review_priority", + ): + if name not in document: + continue + value = document[name] + if name in {"source_fields", "required", "source_normalisation"}: + ordered[name] = _ordered_sides(value) + elif name == "logical_type" and isinstance(value, dict): + logical = _ordered_selected( + value, + ("collection_type", "element_type", "element_comparator"), + ) + if "element_comparator" in logical: + logical["element_comparator"] = _ordered_named_parameters( + logical["element_comparator"] + ) + ordered[name] = logical + elif name == "null_policy": + null_policy = _ordered_selected( + value, + ("allowed", "nulls_equal", "missing_tokens"), + ) + if "missing_tokens" in null_policy: + null_policy["missing_tokens"] = _ordered_sides( + null_policy["missing_tokens"] + ) + ordered[name] = null_policy + elif name in {"collection_representation", "value_mapping"}: + ordered[name] = _ordered_sides(value) + elif name == "comparator": + ordered[name] = _ordered_named_parameters(value) + else: + ordered[name] = _ordered_nested(value) + return ordered + + +def _ordered_sides(document: object) -> object: + """Order a reference/query mapping and recursively order its content.""" + if not isinstance(document, dict): + return _ordered_nested(document) + return { + name: _ordered_nested(document[name]) + for name in ("reference", "query") + if name in document + } + + +def _ordered_named_parameters(document: JsonObject) -> JsonObject: + """Order an operation or comparator declaration.""" + return _ordered_selected(document, ("name", "operation", "parameters")) + + +def _ordered_selected( + document: Mapping[str, object], + names: tuple[str, ...], +) -> JsonObject: + """Copy selected fixed properties in documented schema order.""" + return { + name: _ordered_nested(document[name]) + for name in names + if name in document + } + + +def _ordered_nested(value: object) -> object: + """Order known fixed objects and otherwise use Unicode member order.""" + if isinstance(value, list): + return [_ordered_nested(item) for item in value] + if not isinstance(value, dict): + return value + keys = set(value) + if keys <= {"reference", "query"}: + return _ordered_sides(value) + if "operation" in value: + return _ordered_selected(value, ("operation", "parameters")) + if keys <= {"category", "value"} and "category" in value: + return _ordered_selected(value, ("category", "value")) + if keys <= {"from", "to"}: + return _ordered_selected(value, ("from", "to")) + if "format" in value: + return _ordered_selected( + value, + ("format", "delimiter", "element_normalisation", "element_mapping"), + ) + if keys <= {"name", "parameters"} and "name" in value: + return _ordered_named_parameters(value) + return {name: _ordered_nested(value[name]) for name in sorted(value)} + + +def _summary_document( + records: RecordsResult, + values: ValuesResult, + findings: list[JsonObject], +) -> JsonObject: + """Build fixed-shape, zero-inclusive reconciled summary counts.""" + code_counts = Counter(item["code"] for item in findings) + classification_counts = Counter(item["classification"] for item in findings) + priority_counts = Counter( + item.get("review_priority", "unassigned") for item in findings + ) + return { + "records": { + "reference": records.counts.reference, + "query": records.counts.query, + "matched": records.counts.matched, + "missing": records.counts.missing, + "extra": records.counts.extra, + }, + "values": { + "matched": values.counts.matched, + "mismatched": values.counts.mismatched, + "not_assessable": values.counts.not_assessable, + }, + "findings": { + "total": len(findings), + "by_classification": { + name: classification_counts[name] for name in CLASSIFICATIONS + }, + "by_code": {name: code_counts[name] for name in FINDING_CODES}, + "by_review_priority": { + name: priority_counts[name] for name in REVIEW_PRIORITIES + }, + }, + } + + +def _exclusion_document( + exclusion: ConfiguredFieldExclusion | UndeclaredFieldExclusion, +) -> JsonObject: + """Render one of the two closed exclusion forms.""" + if isinstance(exclusion, ConfiguredFieldExclusion): + return { + "code": exclusion.code, + "canonical_field": exclusion.canonical_field, + } + return { + "code": exclusion.code, + "side": exclusion.side.value, + "source_field": exclusion.source_field, + "record_count": exclusion.record_count, + } + + +# Finding and evidence construction + + +def _assemble_findings( + configuration: EffectiveConfiguration, + contract: ContractResult, + records: RecordsResult, + values: ValuesResult, +) -> list[JsonObject]: + """Convert, coalesce, sort, and identify every finding candidate.""" + candidates = [ + *( + _record_finding_document(finding) + for finding in records.findings + ), + *( + _contract_finding_document(configuration, records, contract, finding) + for finding in contract.findings + ), + *( + _value_finding_document(configuration, finding) + for finding in values.findings + ), + ] + unique: dict[tuple[object, ...], JsonObject] = {} + for candidate in candidates: + key = _finding_sort_key(candidate) + unique.setdefault(key, candidate) + ordered = [unique[key] for key in sorted(unique)] + return [ + _identified_finding(index, candidate) + for index, candidate in enumerate(ordered, start=1) + ] + + +def _record_finding_document(finding: RecordFinding) -> JsonObject: + """Build structured evidence for one missing or extra record.""" + return { + "classification": finding.classification, + "code": finding.code, + "phase": finding.phase, + "affected_side": finding.affected_side.value, + "record_identity": _record_identity(finding.alignment), + "source_locations": { + "reference": _location_document(finding.reference_location), + "query": _location_document(finding.query_location), + }, + } + + +def _contract_finding_document( + configuration: EffectiveConfiguration, + records: RecordsResult, + contract: ContractResult, + finding: ContractFinding, +) -> JsonObject: + """Build code-specific evidence for one failed contract prerequisite.""" + base: JsonObject = { + "classification": finding.classification, + "code": finding.code, + "phase": finding.phase, + "affected_side": finding.side.value, + } + if finding.record is None: + base["field"] = finding.canonical_field + base["review_priority"] = finding.review_priority + return base + + alignment = records.alignment(finding.record.key) + field = configuration.field(finding.canonical_field) + assessments = { + side: _assessment_for_alignment( + contract, + alignment, + side, + finding.canonical_field, + ) + for side in (InputSide.REFERENCE, InputSide.QUERY) + } + base["record_identity"] = _record_identity(alignment) + base["source_locations"] = _field_locations(field, alignment) + base["field"] = finding.canonical_field + base["review_priority"] = finding.review_priority + base["values"] = _contract_values(finding, field, assessments) + return base + + +def _value_finding_document( + configuration: EffectiveConfiguration, + finding: ValueFinding, +) -> JsonObject: + """Build complete two-sided evidence for one post-translation difference.""" + opportunity = finding.opportunity + field = configuration.field(finding.canonical_field) + return { + "classification": finding.classification, + "code": finding.code, + "phase": finding.phase, + "affected_side": finding.affected_side, + "record_identity": _record_identity(opportunity.alignment), + "source_locations": { + "reference": _location_document(finding.reference_location), + "query": _location_document(finding.query_location), + }, + "field": finding.canonical_field, + "review_priority": finding.review_priority, + "values": { + "reference": _field_evidence( + opportunity.reference.translated, + include_source=True, + include_canonical=field.logical_type is not None, + ), + "query": _field_evidence( + opportunity.query.translated, + include_source=True, + include_canonical=field.logical_type is not None, + ), + }, + } + + +def _assessment_for_alignment( + contract: ContractResult, + alignment: RecordAlignment, + side: InputSide, + canonical_field: str, +) -> FieldAssessment | None: + """Return the field assessment when the aligned side contains a record.""" + record = alignment.reference if side is InputSide.REFERENCE else alignment.query + if record is None: + return None + return contract.assessment(side, record.key, canonical_field) + + +def _contract_values( + finding: ContractFinding, + field: FieldDefinition, + assessments: Mapping[InputSide, FieldAssessment | None], +) -> JsonObject: + """Apply the finding-code-specific source-value minimisation rules.""" + values: JsonObject = {} + for side in (InputSide.REFERENCE, InputSide.QUERY): + assessment = assessments[side] + if assessment is None: + values[side.value] = {"state": "absent"} + continue + translated = assessment.translated + if finding.code == "missing_required_field": + values[side.value] = { + "state": ( + "absent" + if translated.disposition is ValueDisposition.NOT_ASSESSABLE + and translated.source is None + else "present" + ) + } + continue + affected = side is finding.side + evidence = _field_evidence( + translated, + include_source=affected, + include_canonical=False, + ) + if ( + affected + and finding.code == "null_policy_violation" + and field.logical_type is not None + ): + evidence["canonical"] = _null_canonical_document(field) + values[side.value] = evidence + return values + + +def _field_evidence( + translated: TranslatedValue, + *, + include_source: bool, + include_canonical: bool, +) -> JsonObject: + """Render one side's presence and permitted source/canonical evidence.""" + if translated.disposition is ValueDisposition.ABSENT or translated.source is None: + return {"state": "absent"} + evidence: JsonObject = {"state": "present"} + if include_source: + evidence["source"] = _source_value_document(translated.source) + if include_canonical and translated.canonical is not None: + evidence["canonical"] = _canonical_value_document(translated.canonical) + return evidence + + +def _null_canonical_document(field: FieldDefinition) -> JsonObject: + """Render the declared typed-null representation for a null violation.""" + logical_type = field.logical_type + if logical_type is None: + raise AssertionError("untyped null violation has no canonical null") + if isinstance(logical_type, str): + return {"logical_type": logical_type, "value": None} + return { + "logical_type": logical_type.collection_type, + "element_type": logical_type.element_type, + "value": None, + } + + +def _source_value_document(value: NativeValue) -> JsonObject: + """Render a recursively typed parser-native source value.""" + document: JsonObject = {"category": value.category.value} + if value.category is NativeCategory.NULL: + return document + if value.category is NativeCategory.STRING: + document["value"] = value.value + elif value.category in {NativeCategory.INTEGER, NativeCategory.DECIMAL}: + document["value"] = ( + value.lexical if value.lexical is not None else str(value.value) + ) + elif value.category is NativeCategory.BOOLEAN: + document["value"] = value.value + elif value.category is NativeCategory.ARRAY: + if not isinstance(value.value, tuple): + raise AssertionError("parser-native array does not contain a tuple") + document["value"] = [_source_value_document(item) for item in value.value] + elif value.category is NativeCategory.OBJECT: + if not isinstance(value.value, tuple): + raise AssertionError("parser-native object does not contain members") + document["value"] = { + name: _source_value_document(member) + for name, member in sorted(value.value, key=lambda item: item[0]) + } + else: + raise AssertionError("unregistered parser-native category") + return document + + +def _canonical_value_document(value: CanonicalValue) -> JsonObject: + """Render one typed canonical value in its unique evidence form.""" + if value.element_type is not None: + rendered = None + if value.value is not None: + if not isinstance(value.value, tuple): + raise AssertionError("canonical collection does not contain a tuple") + rendered = [ + _compact_canonical_scalar(item, value.element_type) + for item in value.value + ] + return { + "logical_type": value.logical_type, + "element_type": value.element_type, + "value": rendered, + } + rendered_value: object = value.value + if value.value is not None: + rendered_value = _compact_canonical_scalar(value.value, value.logical_type) + return {"logical_type": value.logical_type, "value": rendered_value} + + +def _compact_canonical_scalar(value: object, logical_type: str) -> object: + """Render a canonical scalar using the schema's compact scalar form.""" + if logical_type == "boolean": + return value + return render_canonical_scalar(value, logical_type) + + +def _record_identity(alignment: RecordAlignment) -> JsonObject: + """Render source-side and canonical ordered record identities.""" + return { + "reference": ( + list(alignment.reference.source_identity) + if alignment.reference is not None + else None + ), + "query": ( + list(alignment.query.source_identity) + if alignment.query is not None + else None + ), + "canonical": list(alignment.canonical_identity), + } + + +def _field_locations( + field: FieldDefinition, + alignment: RecordAlignment, +) -> JsonObject: + """Render each side's present-field or containing-record location.""" + return { + "reference": _location_document( + alignment.reference.record.location_for(field.source_fields.reference) + if alignment.reference is not None + else None + ), + "query": _location_document( + alignment.query.record.location_for(field.source_fields.query) + if alignment.query is not None + else None + ), + } + + +def _location_document(location: SourceLocation | None) -> JsonObject | None: + """Render one tabular or JSON source location.""" + if location is None: + return None + if isinstance(location, TabularLocation): + document: JsonObject = { + "record_number": location.record_number, + "line_number": location.line_number, + } + if location.field_name is not None: + document["field"] = location.field_name + return document + if isinstance(location, JsonLocation): + return {"json_pointer": location.pointer} + raise AssertionError("unknown source-location type") + + +def _identified_finding(index: int, candidate: JsonObject) -> JsonObject: + """Assign a sequential ID and deterministic presentation message.""" + document: JsonObject = { + "id": f"F{index:06d}", + "classification": candidate["classification"], + "code": candidate["code"], + "phase": candidate["phase"], + "message": _finding_message(candidate), + "affected_side": candidate["affected_side"], + } + for name in ( + "record_identity", + "source_locations", + "field", + "review_priority", + "values", + ): + if name in candidate: + document[name] = candidate[name] + return document + + +def _finding_message(finding: Mapping[str, object]) -> str: + """Derive concise English presentation text from structured properties.""" + code = finding["code"] + side = str(finding["affected_side"]) + field = finding.get("field") + if code == "missing_record": + return "The query record is missing." + if code == "extra_record": + return "The query contains an extra record." + if code == "missing_required_field": + return f"Required {side} field {field!r} is absent." + if code == "type_mismatch": + return f"The {side} value for field {field!r} has an incompatible type." + if code == "invalid_field_value": + return f"The {side} value for field {field!r} is invalid." + if code == "null_policy_violation": + return f"The {side} value for field {field!r} violates its null policy." + if code == "mapping_failure": + return f"The {side} value for field {field!r} has no configured mapping." + if code == "value_mismatch": + return f"Reference and query values for field {field!r} differ." + raise AssertionError("unregistered finding code") + + +def _finding_sort_key(finding: Mapping[str, object]) -> tuple[object, ...]: + """Return the complete canonical total-order and coalescence key.""" + classification_order = {name: index for index, name in enumerate(CLASSIFICATIONS)} + phase_order = {"contract": 0, "records": 1, "values": 2} + code_order = {name: index for index, name in enumerate(FINDING_CODES)} + side_order = {"reference": 0, "query": 1, "both": 2} + identity = finding.get("record_identity") + canonical_identity: tuple[str, ...] = () + if isinstance(identity, dict): + canonical_identity = tuple(identity["canonical"]) + remaining = { + key: value + for key, value in finding.items() + if key not in {"id", "message"} + } + return ( + classification_order[str(finding["classification"])], + phase_order[str(finding["phase"])], + identity is not None, + canonical_identity, + str(finding.get("field", "")), + code_order[str(finding["code"])], + side_order[str(finding["affected_side"])], + _locations_sort_key(finding.get("source_locations")), + json.dumps( + remaining, + ensure_ascii=False, + sort_keys=True, + separators=(",", ":"), + ), + ) + + +def _locations_sort_key(locations: object) -> tuple[object, ...]: + """Return the specified two-sided source-location ordering key.""" + if not isinstance(locations, dict): + return ((0,), (0,)) + return ( + _location_sort_key(locations.get("reference")), + _location_sort_key(locations.get("query")), + ) + + +def _location_sort_key(location: object) -> tuple[object, ...]: + """Return the specified order for one serialized location.""" + if location is None: + return (0,) + if not isinstance(location, dict): + raise ResultValidationError("source location is not an object or null") + if "record_number" in location: + return ( + 1, + location["record_number"], + location["line_number"], + location.get("field", ""), + ) + return (1, location["json_pointer"]) + + +# Semantic result validation + + +def _validate_semantics( + document: JsonObject, + configuration: JsonObject, + prepared: PreparedComparison | None, + contract: ContractResult | None, + domain_records: RecordsResult | None, + domain_values: ValuesResult | None, +) -> None: + """Verify invariants that JSON Schema cannot express.""" + phases = document["phases"] + expected_status = ( + "complete" + if all(value == "complete" for value in phases.values()) + else "incomplete" + ) + _require( + document["run"]["status"] == expected_status, + "run status disagrees with phases", + ) + + records = document["summary"]["records"] + _require( + records["reference"] == records["matched"] + records["missing"], + "reference record counts do not reconcile", + ) + _require( + records["query"] == records["matched"] + records["extra"], + "query record counts do not reconcile", + ) + configuration_fields = configuration["fields"] + compared_field_count = len( + set(configuration_fields["in_scope"]) + - set(configuration_fields["record_key"]) + ) + value_summary = document["summary"]["values"] + classified_opportunities = sum(value_summary.values()) + expected_opportunities = records["matched"] * compared_field_count + _require( + classified_opportunities == expected_opportunities, + "value opportunity counts do not reconcile", + ) + expected_values_status = ( + "incomplete" if value_summary["not_assessable"] else "complete" + ) + _require( + phases["values"] == expected_values_status, + "values phase status disagrees with not-assessable opportunities", + ) + if domain_records is not None: + _require( + records + == { + "reference": domain_records.counts.reference, + "query": domain_records.counts.query, + "matched": domain_records.counts.matched, + "missing": domain_records.counts.missing, + "extra": domain_records.counts.extra, + }, + "record summary disagrees with the records phase", + ) + if domain_values is not None: + _require( + document["summary"]["values"] + == { + "matched": domain_values.counts.matched, + "mismatched": domain_values.counts.mismatched, + "not_assessable": domain_values.counts.not_assessable, + }, + "value summary disagrees with the values phase", + ) + if ( + contract is not None + and domain_records is not None + and domain_values is not None + ): + expected_phases = { + "contract": contract.status.value, + "records": domain_records.status.value, + "values": domain_values.status.value, + } + _require(phases == expected_phases, "phase status disagrees with phase results") + if prepared is None: + raise ResultValidationError( + "phase-result validation requires prepared comparison context" + ) + expected_findings = _assemble_findings( + prepared.configuration, + contract, + domain_records, + domain_values, + ) + _require( + document["findings"] == expected_findings, + "findings disagree with the comparison phase results", + ) + + findings = document["findings"] + summary = document["summary"]["findings"] + _require(summary["total"] == len(findings), "finding total does not reconcile") + expected_classifications = Counter(item["classification"] for item in findings) + expected_codes = Counter(item["code"] for item in findings) + expected_priorities = Counter( + item.get("review_priority", "unassigned") for item in findings + ) + _require( + summary["by_classification"] + == {name: expected_classifications[name] for name in CLASSIFICATIONS}, + "finding classification counts do not reconcile", + ) + _require( + summary["by_code"] == {name: expected_codes[name] for name in FINDING_CODES}, + "finding code counts do not reconcile", + ) + _require( + summary["by_review_priority"] + == {name: expected_priorities[name] for name in REVIEW_PRIORITIES}, + "finding review-priority counts do not reconcile", + ) + + expected_ids = [f"F{index:06d}" for index in range(1, len(findings) + 1)] + _require( + [item["id"] for item in findings] == expected_ids, + "finding IDs are not sequential", + ) + finding_keys = [_finding_sort_key(item) for item in findings] + _require( + finding_keys == sorted(finding_keys), + "findings are not canonically ordered", + ) + _require( + len(finding_keys) == len(set(finding_keys)), + "duplicate findings are present", + ) + + key_fields = document["record_key_fields"] + key_length = len(key_fields["canonical"]) + _require( + len(key_fields["reference"]) == key_length + and len(key_fields["query"]) == key_length, + "record-key field arrays have inconsistent lengths", + ) + for finding in findings: + identity = finding.get("record_identity") + if identity is None: + continue + _require( + len(identity["canonical"]) == key_length + and ( + identity["reference"] is None + or len(identity["reference"]) == key_length + ) + and (identity["query"] is None or len(identity["query"]) == key_length), + "record identity has an inconsistent component count", + ) + + exclusion_keys = [_exclusion_sort_key(item) for item in document["exclusions"]] + _require( + exclusion_keys == sorted(exclusion_keys), + "exclusions are not canonically ordered", + ) + _require( + len(exclusion_keys) == len(set(exclusion_keys)), + "duplicate exclusions are present", + ) + _validate_configuration_derivations(document, configuration, prepared) + + +def _validate_configuration_derivations( + document: JsonObject, + configuration: JsonObject, + prepared: PreparedComparison | None, +) -> None: + """Cross-check configuration-derived evidence and available source context.""" + if prepared is not None: + _require( + configuration == prepared.configuration.document, + "saved configuration disagrees with the effective configuration", + ) + _require( + document["inputs"] + == { + "reference": _input_document(prepared.reference), + "query": _input_document(prepared.query), + }, + "input provenance disagrees with the parsed inputs", + ) + fields = configuration["fields"] + definitions = fields["definitions"] + record_key = fields["record_key"] + expected_key_fields = { + "reference": [ + definitions[name]["source_fields"]["reference"] for name in record_key + ], + "query": [ + definitions[name]["source_fields"]["query"] for name in record_key + ], + "canonical": record_key, + } + _require( + document["record_key_fields"] == expected_key_fields, + "record-key metadata disagrees with the saved configuration", + ) + for finding in document["findings"]: + field = finding.get("field") + if field is None: + continue + _require(field in definitions, "finding names an undeclared canonical field") + expected_priority = definitions[field].get("review_priority", "normal") + _require( + finding["review_priority"] == expected_priority, + "finding review priority disagrees with the saved configuration", + ) + + expected_configured = [ + {"code": "configured_field_excluded", "canonical_field": name} + for name in sorted(set(definitions) - set(fields["in_scope"])) + ] + actual_configured = [ + item + for item in document["exclusions"] + if item["code"] == "configured_field_excluded" + ] + _require( + actual_configured == expected_configured, + "configured-field exclusions disagree with the saved configuration", + ) + if prepared is None: + return + expected_undeclared = _expected_undeclared_exclusions( + prepared, + definitions, + ) + actual_undeclared = [ + item + for item in document["exclusions"] + if item["code"] == "undeclared_field_excluded" + ] + _require( + actual_undeclared == expected_undeclared, + "undeclared-field exclusions disagree with observed source fields", + ) + + +def _expected_undeclared_exclusions( + prepared: PreparedComparison, + definitions: Mapping[str, JsonObject], +) -> list[JsonObject]: + """Derive expected source-field exclusions from parsed datasets.""" + expected: list[JsonObject] = [] + for side, dataset in ( + ("reference", prepared.reference), + ("query", prepared.query), + ): + represented = { + definition["source_fields"][side] + for definition in definitions.values() + } + for source_field in sorted(set(dataset.field_names) - represented): + expected.append( + { + "code": "undeclared_field_excluded", + "side": side, + "source_field": source_field, + "record_count": sum( + record.has_field(source_field) for record in dataset.records + ), + } + ) + return expected + + +def _exclusion_sort_key(exclusion: Mapping[str, object]) -> tuple[object, ...]: + """Return the complete specified exclusion order and identity.""" + if exclusion["code"] == "configured_field_excluded": + return (0, exclusion["canonical_field"]) + side_order = {"reference": 0, "query": 1} + return ( + 1, + side_order[str(exclusion["side"])], + exclusion["source_field"], + exclusion["record_count"], + ) + + +def _require(condition: bool, message: str) -> None: + """Raise the internal validation exception for a failed invariant.""" + if not condition: + raise ResultValidationError(message) diff --git a/packages/adviso-compare/src/adviso_compare/schemas/__init__.py b/packages/adviso-compare/src/adviso_compare/schemas/__init__.py new file mode 100644 index 0000000..692d725 --- /dev/null +++ b/packages/adviso-compare/src/adviso_compare/schemas/__init__.py @@ -0,0 +1,25 @@ +"""Versioned machine-readable schemas distributed with adviso-compare.""" + +from __future__ import annotations + +import json +from importlib.resources import files +from typing import Any + + +_SCHEMA_RESOURCES = ( + ("configuration", "1.0", "comparison-configuration-v1.0.schema.json"), + ("results", "1.0", "comparison-results-v1.0.schema.json"), +) + + +def load_schema(family: str, version: str) -> dict[str, Any]: + """Load a supported schema by family and version from local resources.""" + for known_family, known_version, filename in _SCHEMA_RESOURCES: + if (family, version) == (known_family, known_version): + resource = files("adviso_compare.schemas").joinpath(filename) + document = json.loads(resource.read_text(encoding="utf-8")) + if not isinstance(document, dict): + raise ValueError("packaged schema root must be an object") + return document + raise ValueError("unsupported schema family or version") diff --git a/packages/adviso-compare/src/adviso_compare/schemas/comparison-configuration-v1.0.schema.json b/packages/adviso-compare/src/adviso_compare/schemas/comparison-configuration-v1.0.schema.json new file mode 100644 index 0000000..2cf895e --- /dev/null +++ b/packages/adviso-compare/src/adviso_compare/schemas/comparison-configuration-v1.0.schema.json @@ -0,0 +1,937 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://adviso-project.github.io/validation_toolkit/schemas/comparison-configuration-v1.0.schema.json", + "title": "adviso-compare configuration", + "description": "Normative structural schema for comparison-configuration schema version 1.0.", + "type": "object", + "additionalProperties": false, + "required": [ + "schema_version", + "metadata", + "fields" + ], + "properties": { + "schema_version": { + "const": "1.0" + }, + "metadata": { + "$ref": "#/$defs/configurationMetadata" + }, + "fields": { + "$ref": "#/$defs/fields" + } + }, + "$defs": { + "nonEmptyString": { + "type": "string", + "minLength": 1 + }, + "uniqueNonEmptyStrings": { + "type": "array", + "minItems": 1, + "uniqueItems": true, + "items": { + "$ref": "#/$defs/nonEmptyString" + } + }, + "configurationMetadata": { + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "revision" + ], + "properties": { + "id": { + "$ref": "#/$defs/nonEmptyString" + }, + "revision": { + "$ref": "#/$defs/nonEmptyString" + }, + "title": { + "type": "string" + }, + "description": { + "type": "string" + } + } + }, + "fields": { + "type": "object", + "additionalProperties": false, + "required": [ + "record_key", + "in_scope", + "definitions" + ], + "properties": { + "record_key": { + "$ref": "#/$defs/uniqueNonEmptyStrings" + }, + "in_scope": { + "$ref": "#/$defs/uniqueNonEmptyStrings" + }, + "definitions": { + "type": "object", + "minProperties": 1, + "propertyNames": { + "$ref": "#/$defs/nonEmptyString" + }, + "additionalProperties": { + "$ref": "#/$defs/fieldDefinition" + } + } + } + }, + "fieldDefinition": { + "type": "object", + "additionalProperties": false, + "required": [ + "source_fields", + "required", + "null_policy", + "comparator" + ], + "properties": { + "source_fields": { + "type": "object", + "additionalProperties": false, + "required": [ + "reference", + "query" + ], + "properties": { + "reference": { + "$ref": "#/$defs/nonEmptyString" + }, + "query": { + "$ref": "#/$defs/nonEmptyString" + } + } + }, + "required": { + "type": "object", + "additionalProperties": false, + "required": [ + "reference", + "query" + ], + "properties": { + "reference": { + "type": "boolean" + }, + "query": { + "type": "boolean" + } + } + }, + "logical_type": { + "$ref": "#/$defs/logicalType" + }, + "null_policy": { + "$ref": "#/$defs/nullPolicy" + }, + "source_normalisation": { + "type": "object", + "additionalProperties": false, + "minProperties": 1, + "properties": { + "reference": { + "type": "array", + "minItems": 1, + "items": { + "$ref": "#/$defs/sourceNormalisation" + } + }, + "query": { + "type": "array", + "minItems": 1, + "items": { + "$ref": "#/$defs/sourceNormalisation" + } + } + } + }, + "collection_representation": { + "$ref": "#/$defs/collectionRepresentation" + }, + "value_mapping": { + "$ref": "#/$defs/valueMapping" + }, + "typed_normalisation": { + "type": "array", + "minItems": 1, + "items": { + "$ref": "#/$defs/typedNormalisation" + } + }, + "comparator": { + "$ref": "#/$defs/comparator" + }, + "review_priority": { + "default": "normal", + "enum": [ + "low", + "normal", + "high" + ] + } + }, + "allOf": [ + { + "if": { + "not": { + "required": [ + "logical_type" + ] + } + }, + "then": { + "properties": { + "comparator": { + "properties": { + "name": { + "const": "preserved_exact" + } + } + } + }, + "not": { + "anyOf": [ + { + "required": [ + "value_mapping" + ] + }, + { + "required": [ + "typed_normalisation" + ] + }, + { + "required": [ + "collection_representation" + ] + } + ] + } + } + }, + { + "if": { + "properties": { + "comparator": { + "properties": { + "name": { + "const": "preserved_exact" + } + }, + "required": [ + "name" + ] + } + }, + "required": [ + "comparator" + ] + }, + "then": { + "not": { + "anyOf": [ + { + "required": [ + "logical_type" + ] + }, + { + "required": [ + "source_normalisation" + ] + }, + { + "required": [ + "value_mapping" + ] + }, + { + "required": [ + "typed_normalisation" + ] + }, + { + "required": [ + "collection_representation" + ] + }, + { + "properties": { + "null_policy": { + "required": [ + "missing_tokens" + ] + } + }, + "required": [ + "null_policy" + ] + } + ] + } + } + }, + { + "if": { + "required": [ + "collection_representation" + ] + }, + "then": { + "properties": { + "logical_type": { + "type": "object" + } + }, + "required": [ + "logical_type" + ] + } + }, + { + "if": { + "properties": { + "logical_type": { + "type": "object" + } + }, + "required": [ + "logical_type" + ] + }, + "then": { + "not": { + "anyOf": [ + { + "required": [ + "source_normalisation" + ] + }, + { + "required": [ + "value_mapping" + ] + }, + { + "required": [ + "typed_normalisation" + ] + } + ] + } + } + } + ] + }, + "scalarLogicalType": { + "enum": [ + "string", + "integer", + "decimal", + "boolean", + "date", + "datetime" + ] + }, + "logicalType": { + "oneOf": [ + { + "$ref": "#/$defs/scalarLogicalType" + }, + { + "type": "object", + "additionalProperties": false, + "required": [ + "collection_type", + "element_type", + "element_comparator" + ], + "properties": { + "collection_type": { + "enum": [ + "list", + "set", + "multiset" + ] + }, + "element_type": { + "$ref": "#/$defs/scalarLogicalType" + }, + "element_comparator": { + "$ref": "#/$defs/comparator" + } + }, + "allOf": [ + { + "properties": { + "element_comparator": { + "properties": { + "name": { + "enum": [ + "typed_exact", + "numeric_tolerance" + ] + } + } + } + } + }, + { + "if": { + "properties": { + "collection_type": { + "enum": [ + "set", + "multiset" + ] + } + }, + "required": [ + "collection_type" + ] + }, + "then": { + "properties": { + "element_comparator": { + "properties": { + "name": { + "const": "typed_exact" + } + } + } + } + } + }, + { + "if": { + "properties": { + "element_comparator": { + "properties": { + "name": { + "const": "numeric_tolerance" + } + }, + "required": [ + "name" + ] + } + }, + "required": [ + "element_comparator" + ] + }, + "then": { + "properties": { + "collection_type": { + "const": "list" + }, + "element_type": { + "enum": [ + "integer", + "decimal" + ] + } + } + } + } + ] + } + ] + }, + "nullPolicy": { + "type": "object", + "additionalProperties": false, + "required": [ + "allowed", + "nulls_equal" + ], + "properties": { + "allowed": { + "type": "boolean" + }, + "nulls_equal": { + "type": "boolean" + }, + "missing_tokens": { + "type": "object", + "additionalProperties": false, + "minProperties": 1, + "properties": { + "reference": { + "type": "array", + "minItems": 1, + "items": { + "$ref": "#/$defs/nonNullSourceValueDescriptor" + } + }, + "query": { + "type": "array", + "minItems": 1, + "items": { + "$ref": "#/$defs/nonNullSourceValueDescriptor" + } + } + } + } + }, + "allOf": [ + { + "if": { + "properties": { + "allowed": { + "const": false + } + }, + "required": [ + "allowed" + ] + }, + "then": { + "properties": { + "nulls_equal": { + "const": false + } + } + } + } + ] + }, + "sourceValueDescriptor": { + "oneOf": [ + { + "type": "object", + "additionalProperties": false, + "required": [ + "category", + "value" + ], + "properties": { + "category": { + "const": "string" + }, + "value": { + "type": "string" + } + } + }, + { + "type": "object", + "additionalProperties": false, + "required": [ + "category", + "value" + ], + "properties": { + "category": { + "const": "integer" + }, + "value": { + "type": "string", + "pattern": "^-?(?:0|[1-9][0-9]*)$" + } + } + }, + { + "type": "object", + "additionalProperties": false, + "required": [ + "category", + "value" + ], + "properties": { + "category": { + "const": "decimal" + }, + "value": { + "type": "string", + "pattern": "^-?(?:(?:0|[1-9][0-9]*)\\.[0-9]+|(?:0|[1-9][0-9]*)(?:[eE][+-]?[0-9]+)|(?:0|[1-9][0-9]*)\\.[0-9]+(?:[eE][+-]?[0-9]+))$" + } + } + }, + { + "type": "object", + "additionalProperties": false, + "required": [ + "category", + "value" + ], + "properties": { + "category": { + "const": "boolean" + }, + "value": { + "type": "boolean" + } + } + }, + { + "type": "object", + "additionalProperties": false, + "required": [ + "category" + ], + "properties": { + "category": { + "const": "null" + } + } + } + ] + }, + "nonNullSourceValueDescriptor": { + "allOf": [ + { + "$ref": "#/$defs/sourceValueDescriptor" + }, + { + "not": { + "properties": { + "category": { + "const": "null" + } + }, + "required": [ + "category" + ] + } + } + ] + }, + "sourceNormalisation": { + "oneOf": [ + { + "type": "object", + "additionalProperties": false, + "required": [ + "operation", + "parameters" + ], + "properties": { + "operation": { + "const": "unicode_normalise" + }, + "parameters": { + "type": "object", + "additionalProperties": false, + "required": [ + "form" + ], + "properties": { + "form": { + "enum": [ + "NFC", + "NFD", + "NFKC", + "NFKD" + ] + } + } + } + } + }, + { + "type": "object", + "additionalProperties": false, + "required": [ + "operation", + "parameters" + ], + "properties": { + "operation": { + "const": "trim" + }, + "parameters": { + "type": "object", + "additionalProperties": false, + "required": [ + "side" + ], + "properties": { + "side": { + "enum": [ + "leading", + "trailing", + "both" + ] + } + } + } + } + }, + { + "type": "object", + "additionalProperties": false, + "required": [ + "operation" + ], + "properties": { + "operation": { + "const": "case_fold" + }, + "parameters": { + "type": "object", + "maxProperties": 0 + } + } + } + ] + }, + "collectionRepresentation": { + "type": "object", + "additionalProperties": false, + "minProperties": 1, + "properties": { + "reference": { + "$ref": "#/$defs/collectionRepresentationSide" + }, + "query": { + "$ref": "#/$defs/collectionRepresentationSide" + } + } + }, + "collectionRepresentationSide": { + "type": "object", + "additionalProperties": false, + "required": [ + "format" + ], + "properties": { + "format": { + "enum": [ + "json_array", + "delimited_text" + ] + }, + "delimiter": { + "type": "string", + "minLength": 1 + }, + "element_normalisation": { + "type": "array", + "minItems": 1, + "items": { + "$ref": "#/$defs/sourceNormalisation" + } + }, + "element_mapping": { + "type": "array", + "minItems": 1, + "items": { + "$ref": "#/$defs/nonNullValueMappingEntry" + } + } + }, + "allOf": [ + { + "if": { + "properties": { + "format": { + "const": "delimited_text" + } + }, + "required": [ + "format" + ] + }, + "then": { + "required": [ + "delimiter" + ] + }, + "else": { + "not": { + "required": [ + "delimiter" + ] + } + } + } + ] + }, + "typedNormalisation": { + "oneOf": [ + { + "type": "object", + "additionalProperties": false, + "required": [ + "operation", + "parameters" + ], + "properties": { + "operation": { + "const": "decimal_quantise" + }, + "parameters": { + "type": "object", + "additionalProperties": false, + "required": [ + "places", + "rounding" + ], + "properties": { + "places": { + "type": "integer", + "minimum": 0 + }, + "rounding": { + "enum": [ + "half_even", + "half_up", + "down" + ] + } + } + } + } + }, + { + "type": "object", + "additionalProperties": false, + "required": [ + "operation", + "parameters" + ], + "properties": { + "operation": { + "const": "datetime_truncate" + }, + "parameters": { + "type": "object", + "additionalProperties": false, + "required": [ + "precision" + ], + "properties": { + "precision": { + "enum": [ + "second", + "millisecond", + "microsecond" + ] + } + } + } + } + } + ] + }, + "valueMapping": { + "type": "object", + "additionalProperties": false, + "minProperties": 1, + "properties": { + "reference": { + "type": "array", + "minItems": 1, + "items": { + "$ref": "#/$defs/valueMappingEntry" + } + }, + "query": { + "type": "array", + "minItems": 1, + "items": { + "$ref": "#/$defs/valueMappingEntry" + } + } + } + }, + "valueMappingEntry": { + "type": "object", + "additionalProperties": false, + "required": [ + "from", + "to" + ], + "properties": { + "from": { + "$ref": "#/$defs/nonNullSourceValueDescriptor" + }, + "to": { + "$ref": "#/$defs/sourceValueDescriptor" + } + } + }, + "nonNullValueMappingEntry": { + "type": "object", + "additionalProperties": false, + "required": [ + "from", + "to" + ], + "properties": { + "from": { + "$ref": "#/$defs/nonNullSourceValueDescriptor" + }, + "to": { + "$ref": "#/$defs/nonNullSourceValueDescriptor" + } + } + }, + "comparator": { + "oneOf": [ + { + "type": "object", + "additionalProperties": false, + "required": [ + "name" + ], + "properties": { + "name": { + "enum": [ + "preserved_exact", + "typed_exact", + "normalised_string", + "numeric_exact", + "date_exact", + "datetime_exact", + "list_exact", + "set_exact", + "multiset_exact" + ] + } + } + }, + { + "type": "object", + "additionalProperties": false, + "required": [ + "name", + "parameters" + ], + "properties": { + "name": { + "const": "numeric_tolerance" + }, + "parameters": { + "type": "object", + "additionalProperties": false, + "minProperties": 1, + "maxProperties": 1, + "properties": { + "absolute_tolerance": { + "$ref": "#/$defs/nonNegativeDecimalString" + }, + "relative_tolerance": { + "$ref": "#/$defs/nonNegativeDecimalString" + } + } + } + } + } + ] + }, + "nonNegativeDecimalString": { + "type": "string", + "pattern": "^(?:0|[1-9][0-9]*)(?:\\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$" + } + } +} diff --git a/packages/adviso-compare/src/adviso_compare/schemas/comparison-results-v1.0.schema.json b/packages/adviso-compare/src/adviso_compare/schemas/comparison-results-v1.0.schema.json new file mode 100644 index 0000000..542fc42 --- /dev/null +++ b/packages/adviso-compare/src/adviso_compare/schemas/comparison-results-v1.0.schema.json @@ -0,0 +1,1514 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://adviso-project.github.io/validation_toolkit/schemas/comparison-results-v1.0.schema.json", + "title": "adviso-compare results", + "description": "Normative schema for canonical comparison results schema version 1.0. Execution-error diagnostics are not comparison results and do not validate against this schema.", + "type": "object", + "additionalProperties": false, + "required": [ + "schema_version", + "run", + "phases", + "software", + "runtime", + "inputs", + "record_key_fields", + "comparison_configuration_digest", + "summary", + "exclusions", + "findings" + ], + "properties": { + "schema_version": { + "const": "1.0" + }, + "run": { + "$ref": "#/$defs/run" + }, + "phases": { + "$ref": "#/$defs/phases" + }, + "software": { + "$ref": "#/$defs/software" + }, + "runtime": { + "$ref": "#/$defs/runtime" + }, + "inputs": { + "$ref": "#/$defs/inputs" + }, + "record_key_fields": { + "$ref": "#/$defs/recordKeyFields" + }, + "comparison_configuration_digest": { + "$ref": "#/$defs/sha256Digest" + }, + "summary": { + "$ref": "#/$defs/summary" + }, + "exclusions": { + "type": "array", + "items": { + "$ref": "#/$defs/exclusion" + } + }, + "findings": { + "type": "array", + "items": { + "$ref": "#/$defs/finding" + } + } + }, + "$defs": { + "nonEmptyString": { + "type": "string", + "minLength": 1 + }, + "nonNegativeInteger": { + "type": "integer", + "minimum": 0 + }, + "phaseStatus": { + "enum": [ + "complete", + "incomplete" + ] + }, + "run": { + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "status", + "completed_at" + ], + "properties": { + "id": { + "type": "string", + "format": "uuid", + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" + }, + "status": { + "$ref": "#/$defs/phaseStatus" + }, + "completed_at": { + "type": "string", + "format": "date-time", + "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$" + } + } + }, + "phases": { + "type": "object", + "additionalProperties": false, + "required": [ + "contract", + "records", + "values" + ], + "properties": { + "contract": { + "$ref": "#/$defs/phaseStatus" + }, + "records": { + "$ref": "#/$defs/phaseStatus" + }, + "values": { + "$ref": "#/$defs/phaseStatus" + } + } + }, + "software": { + "type": "object", + "additionalProperties": false, + "required": [ + "name", + "version" + ], + "properties": { + "name": { + "const": "adviso-compare" + }, + "version": { + "$ref": "#/$defs/nonEmptyString" + }, + "build": { + "$ref": "#/$defs/nonEmptyString" + } + } + }, + "runtime": { + "type": "object", + "additionalProperties": false, + "required": [ + "python", + "platform", + "unicode_version" + ], + "properties": { + "python": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]*-[0-9]+\\.[0-9]+\\.[0-9]+(?:[a-z]+[0-9]+)?$" + }, + "platform": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]*-[a-z0-9_]+$" + }, + "unicode_version": { + "type": "string", + "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$" + } + } + }, + "sha256Digest": { + "type": "object", + "additionalProperties": false, + "required": [ + "algorithm", + "value" + ], + "properties": { + "algorithm": { + "const": "sha256" + }, + "value": { + "type": "string", + "minLength": 64, + "maxLength": 64, + "pattern": "^[0-9a-f]{64}$" + } + } + }, + "input": { + "type": "object", + "additionalProperties": false, + "required": [ + "basename", + "format", + "encoding", + "size_bytes", + "digest" + ], + "properties": { + "basename": { + "$ref": "#/$defs/nonEmptyString" + }, + "format": { + "enum": [ + "csv", + "tsv", + "json" + ] + }, + "encoding": { + "const": "utf-8" + }, + "size_bytes": { + "$ref": "#/$defs/nonNegativeInteger" + }, + "digest": { + "$ref": "#/$defs/sha256Digest" + } + } + }, + "inputs": { + "type": "object", + "additionalProperties": false, + "required": [ + "reference", + "query" + ], + "properties": { + "reference": { + "$ref": "#/$defs/input" + }, + "query": { + "$ref": "#/$defs/input" + } + } + }, + "nonEmptyStringArray": { + "type": "array", + "minItems": 1, + "uniqueItems": true, + "items": { + "$ref": "#/$defs/nonEmptyString" + } + }, + "recordKeyFields": { + "type": "object", + "additionalProperties": false, + "required": [ + "reference", + "query", + "canonical" + ], + "properties": { + "reference": { + "$ref": "#/$defs/nonEmptyStringArray" + }, + "query": { + "$ref": "#/$defs/nonEmptyStringArray" + }, + "canonical": { + "$ref": "#/$defs/nonEmptyStringArray" + } + } + }, + "recordSummary": { + "type": "object", + "additionalProperties": false, + "required": [ + "reference", + "query", + "matched", + "missing", + "extra" + ], + "properties": { + "reference": { + "$ref": "#/$defs/nonNegativeInteger" + }, + "query": { + "$ref": "#/$defs/nonNegativeInteger" + }, + "matched": { + "$ref": "#/$defs/nonNegativeInteger" + }, + "missing": { + "$ref": "#/$defs/nonNegativeInteger" + }, + "extra": { + "$ref": "#/$defs/nonNegativeInteger" + } + } + }, + "valueSummary": { + "type": "object", + "additionalProperties": false, + "required": [ + "matched", + "mismatched", + "not_assessable" + ], + "properties": { + "matched": { + "$ref": "#/$defs/nonNegativeInteger" + }, + "mismatched": { + "$ref": "#/$defs/nonNegativeInteger" + }, + "not_assessable": { + "$ref": "#/$defs/nonNegativeInteger" + } + } + }, + "findingCountsByCode": { + "type": "object", + "additionalProperties": false, + "required": [ + "missing_record", + "extra_record", + "missing_required_field", + "type_mismatch", + "invalid_field_value", + "null_policy_violation", + "mapping_failure", + "value_mismatch" + ], + "properties": { + "missing_record": { + "$ref": "#/$defs/nonNegativeInteger" + }, + "extra_record": { + "$ref": "#/$defs/nonNegativeInteger" + }, + "missing_required_field": { + "$ref": "#/$defs/nonNegativeInteger" + }, + "type_mismatch": { + "$ref": "#/$defs/nonNegativeInteger" + }, + "invalid_field_value": { + "$ref": "#/$defs/nonNegativeInteger" + }, + "null_policy_violation": { + "$ref": "#/$defs/nonNegativeInteger" + }, + "mapping_failure": { + "$ref": "#/$defs/nonNegativeInteger" + }, + "value_mismatch": { + "$ref": "#/$defs/nonNegativeInteger" + } + } + }, + "findingCountsByClassification": { + "type": "object", + "additionalProperties": false, + "required": [ + "comparison_difference", + "assessment_issue" + ], + "properties": { + "comparison_difference": { + "$ref": "#/$defs/nonNegativeInteger" + }, + "assessment_issue": { + "$ref": "#/$defs/nonNegativeInteger" + } + } + }, + "findingCountsByReviewPriority": { + "type": "object", + "additionalProperties": false, + "required": [ + "low", + "normal", + "high", + "unassigned" + ], + "properties": { + "low": { + "$ref": "#/$defs/nonNegativeInteger" + }, + "normal": { + "$ref": "#/$defs/nonNegativeInteger" + }, + "high": { + "$ref": "#/$defs/nonNegativeInteger" + }, + "unassigned": { + "$ref": "#/$defs/nonNegativeInteger" + } + } + }, + "findingSummary": { + "type": "object", + "additionalProperties": false, + "required": [ + "total", + "by_classification", + "by_code", + "by_review_priority" + ], + "properties": { + "total": { + "$ref": "#/$defs/nonNegativeInteger" + }, + "by_classification": { + "$ref": "#/$defs/findingCountsByClassification" + }, + "by_code": { + "$ref": "#/$defs/findingCountsByCode" + }, + "by_review_priority": { + "$ref": "#/$defs/findingCountsByReviewPriority" + } + } + }, + "summary": { + "type": "object", + "additionalProperties": false, + "required": [ + "records", + "values", + "findings" + ], + "properties": { + "records": { + "$ref": "#/$defs/recordSummary" + }, + "values": { + "$ref": "#/$defs/valueSummary" + }, + "findings": { + "$ref": "#/$defs/findingSummary" + } + } + }, + "exclusion": { + "oneOf": [ + { + "type": "object", + "additionalProperties": false, + "required": [ + "code", + "canonical_field" + ], + "properties": { + "code": { + "const": "configured_field_excluded" + }, + "canonical_field": { + "$ref": "#/$defs/nonEmptyString" + } + } + }, + { + "type": "object", + "additionalProperties": false, + "required": [ + "code", + "side", + "source_field", + "record_count" + ], + "properties": { + "code": { + "const": "undeclared_field_excluded" + }, + "side": { + "enum": [ + "reference", + "query" + ] + }, + "source_field": { + "$ref": "#/$defs/nonEmptyString" + }, + "record_count": { + "$ref": "#/$defs/nonNegativeInteger" + } + } + } + ] + }, + "recordIdentityValues": { + "type": "array", + "minItems": 1, + "items": { + "type": "string" + } + }, + "nullableRecordIdentityValues": { + "oneOf": [ + { + "$ref": "#/$defs/recordIdentityValues" + }, + { + "type": "null" + } + ] + }, + "recordIdentity": { + "type": "object", + "additionalProperties": false, + "required": [ + "reference", + "query", + "canonical" + ], + "properties": { + "reference": { + "$ref": "#/$defs/nullableRecordIdentityValues" + }, + "query": { + "$ref": "#/$defs/nullableRecordIdentityValues" + }, + "canonical": { + "$ref": "#/$defs/recordIdentityValues" + } + } + }, + "tabularSourceLocation": { + "type": "object", + "additionalProperties": false, + "required": [ + "record_number", + "line_number" + ], + "properties": { + "record_number": { + "type": "integer", + "minimum": 1 + }, + "line_number": { + "type": "integer", + "minimum": 1 + }, + "field": { + "$ref": "#/$defs/nonEmptyString" + } + } + }, + "jsonSourceLocation": { + "type": "object", + "additionalProperties": false, + "required": [ + "json_pointer" + ], + "properties": { + "json_pointer": { + "type": "string", + "pattern": "^(?:/(?:[^~/]|~[01])*)*$" + } + } + }, + "sourceLocation": { + "oneOf": [ + { + "$ref": "#/$defs/tabularSourceLocation" + }, + { + "$ref": "#/$defs/jsonSourceLocation" + } + ] + }, + "nullableSourceLocation": { + "oneOf": [ + { + "$ref": "#/$defs/sourceLocation" + }, + { + "type": "null" + } + ] + }, + "sourceLocations": { + "type": "object", + "additionalProperties": false, + "required": [ + "reference", + "query" + ], + "properties": { + "reference": { + "$ref": "#/$defs/nullableSourceLocation" + }, + "query": { + "$ref": "#/$defs/nullableSourceLocation" + } + } + }, + "sourceValue": { + "oneOf": [ + { + "type": "object", + "additionalProperties": false, + "required": [ + "category", + "value" + ], + "properties": { + "category": { + "const": "string" + }, + "value": { + "type": "string" + } + } + }, + { + "type": "object", + "additionalProperties": false, + "required": [ + "category", + "value" + ], + "properties": { + "category": { + "const": "integer" + }, + "value": { + "type": "string", + "pattern": "^-?(?:0|[1-9][0-9]*)$" + } + } + }, + { + "type": "object", + "additionalProperties": false, + "required": [ + "category", + "value" + ], + "properties": { + "category": { + "const": "decimal" + }, + "value": { + "type": "string", + "pattern": "^-?(?:0|[1-9][0-9]*)(?:(?:\\.[0-9]+)(?:[eE][+-]?[0-9]+)?|[eE][+-]?[0-9]+)$" + } + } + }, + { + "type": "object", + "additionalProperties": false, + "required": [ + "category", + "value" + ], + "properties": { + "category": { + "const": "boolean" + }, + "value": { + "type": "boolean" + } + } + }, + { + "type": "object", + "additionalProperties": false, + "required": [ + "category" + ], + "properties": { + "category": { + "const": "null" + } + } + }, + { + "type": "object", + "additionalProperties": false, + "required": [ + "category", + "value" + ], + "properties": { + "category": { + "const": "array" + }, + "value": { + "type": "array", + "items": { + "$ref": "#/$defs/sourceValue" + } + } + } + }, + { + "type": "object", + "additionalProperties": false, + "required": [ + "category", + "value" + ], + "properties": { + "category": { + "const": "object" + }, + "value": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/sourceValue" + } + } + } + } + ] + }, + "canonicalIntegerText": { + "type": "string", + "pattern": "^(?:0|-[1-9][0-9]*|[1-9][0-9]*)$" + }, + "canonicalDecimalText": { + "type": "string", + "pattern": "^(?:0|-?[1-9](?:\\.[0-9]*[1-9])?(?:e-?[1-9][0-9]*)?)$" + }, + "canonicalValue": { + "oneOf": [ + { + "type": "object", + "additionalProperties": false, + "required": [ + "logical_type", + "value" + ], + "properties": { + "logical_type": { + "const": "string" + }, + "value": { + "type": "string" + } + } + }, + { + "type": "object", + "additionalProperties": false, + "required": [ + "logical_type", + "value" + ], + "properties": { + "logical_type": { + "const": "integer" + }, + "value": { + "$ref": "#/$defs/canonicalIntegerText" + } + } + }, + { + "type": "object", + "additionalProperties": false, + "required": [ + "logical_type", + "value" + ], + "properties": { + "logical_type": { + "const": "decimal" + }, + "value": { + "$ref": "#/$defs/canonicalDecimalText" + } + } + }, + { + "type": "object", + "additionalProperties": false, + "required": [ + "logical_type", + "value" + ], + "properties": { + "logical_type": { + "const": "boolean" + }, + "value": { + "type": "boolean" + } + } + }, + { + "type": "object", + "additionalProperties": false, + "required": [ + "logical_type", + "value" + ], + "properties": { + "logical_type": { + "const": "date" + }, + "value": { + "type": "string", + "format": "date" + } + } + }, + { + "type": "object", + "additionalProperties": false, + "required": [ + "logical_type", + "value" + ], + "properties": { + "logical_type": { + "const": "datetime" + }, + "value": { + "type": "string", + "format": "date-time", + "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:\\.[0-9]*[1-9])?Z$" + } + } + }, + { + "type": "object", + "additionalProperties": false, + "required": [ + "logical_type", + "value" + ], + "properties": { + "logical_type": { + "enum": [ + "string", + "integer", + "decimal", + "boolean", + "date", + "datetime" + ] + }, + "value": { + "type": "null" + } + } + }, + { + "$ref": "#/$defs/canonicalCollectionValue" + } + ] + }, + "canonicalCollectionValue": { + "type": "object", + "additionalProperties": false, + "required": [ + "logical_type", + "element_type", + "value" + ], + "properties": { + "logical_type": { + "enum": [ + "list", + "set", + "multiset" + ] + }, + "element_type": { + "enum": [ + "string", + "integer", + "decimal", + "boolean", + "date", + "datetime" + ] + }, + "value": { + "oneOf": [ + { + "type": "array" + }, + { + "type": "null" + } + ] + } + }, + "allOf": [ + { + "if": { + "properties": { + "element_type": { + "const": "boolean" + } + }, + "required": [ + "element_type" + ] + }, + "then": { + "properties": { + "value": { + "items": { + "type": "boolean" + } + } + } + }, + "else": { + "properties": { + "value": { + "items": { + "type": "string" + } + } + } + } + }, + { + "if": { + "properties": { + "element_type": { + "const": "integer" + } + }, + "required": [ + "element_type" + ] + }, + "then": { + "properties": { + "value": { + "items": { + "$ref": "#/$defs/canonicalIntegerText" + } + } + } + } + }, + { + "if": { + "properties": { + "element_type": { + "const": "decimal" + } + }, + "required": [ + "element_type" + ] + }, + "then": { + "properties": { + "value": { + "items": { + "$ref": "#/$defs/canonicalDecimalText" + } + } + } + } + }, + { + "if": { + "properties": { + "element_type": { + "const": "date" + } + }, + "required": [ + "element_type" + ] + }, + "then": { + "properties": { + "value": { + "items": { + "type": "string", + "format": "date" + } + } + } + } + }, + { + "if": { + "properties": { + "element_type": { + "const": "datetime" + } + }, + "required": [ + "element_type" + ] + }, + "then": { + "properties": { + "value": { + "items": { + "type": "string", + "format": "date-time", + "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:\\.[0-9]*[1-9])?Z$" + } + } + } + } + }, + { + "if": { + "properties": { + "logical_type": { + "const": "set" + }, + "value": { + "type": "array" + } + }, + "required": [ + "logical_type", + "value" + ] + }, + "then": { + "properties": { + "value": { + "uniqueItems": true + } + } + } + } + ] + }, + "fieldEvidence": { + "type": "object", + "additionalProperties": false, + "required": [ + "state" + ], + "properties": { + "state": { + "enum": [ + "present", + "absent" + ] + }, + "source": { + "$ref": "#/$defs/sourceValue" + }, + "canonical": { + "$ref": "#/$defs/canonicalValue" + } + }, + "allOf": [ + { + "if": { + "properties": { + "state": { + "const": "absent" + } + }, + "required": [ + "state" + ] + }, + "then": { + "properties": { + "source": false, + "canonical": false + } + } + } + ] + }, + "findingValues": { + "type": "object", + "additionalProperties": false, + "required": [ + "reference", + "query" + ], + "properties": { + "reference": { + "$ref": "#/$defs/fieldEvidence" + }, + "query": { + "$ref": "#/$defs/fieldEvidence" + } + } + }, + "finding": { + "oneOf": [ + { + "allOf": [ + { + "$ref": "#/$defs/findingShape" + }, + { + "properties": { + "code": { + "const": "missing_record" + } + }, + "required": [ + "code" + ], + "not": { + "anyOf": [ + { "required": ["field"] }, + { "required": ["review_priority"] }, + { "required": ["values"] } + ] + } + } + ] + }, + { + "allOf": [ + { + "$ref": "#/$defs/findingShape" + }, + { + "properties": { + "code": { + "const": "extra_record" + } + }, + "required": [ + "code" + ], + "not": { + "anyOf": [ + { "required": ["field"] }, + { "required": ["review_priority"] }, + { "required": ["values"] } + ] + } + } + ] + }, + { + "allOf": [ + { + "$ref": "#/$defs/findingShape" + }, + { + "properties": { + "code": { + "const": "missing_required_field" + } + }, + "required": [ + "code", + "record_identity", + "source_locations", + "field", + "review_priority", + "values" + ] + } + ] + }, + { + "allOf": [ + { + "$ref": "#/$defs/findingShape" + }, + { + "properties": { + "code": { + "const": "missing_required_field" + } + }, + "required": [ + "code", + "field", + "review_priority" + ], + "not": { + "anyOf": [ + { "required": ["record_identity"] }, + { "required": ["source_locations"] }, + { "required": ["values"] } + ] + } + } + ] + }, + { + "allOf": [ + { + "$ref": "#/$defs/findingShape" + }, + { + "properties": { + "code": { + "enum": [ + "type_mismatch", + "invalid_field_value", + "null_policy_violation", + "mapping_failure" + ] + } + }, + "required": [ + "code", + "record_identity", + "source_locations", + "field", + "review_priority", + "values" + ] + } + ] + }, + { + "allOf": [ + { + "$ref": "#/$defs/findingShape" + }, + { + "properties": { + "code": { + "const": "value_mismatch" + } + }, + "required": [ + "code", + "record_identity", + "source_locations", + "field", + "review_priority", + "values" + ] + } + ] + } + ] + }, + "findingShape": { + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "classification", + "code", + "phase", + "message", + "affected_side" + ], + "properties": { + "id": { + "type": "string", + "pattern": "^F[0-9]{6,}$" + }, + "classification": { + "enum": [ + "comparison_difference", + "assessment_issue" + ] + }, + "code": { + "enum": [ + "missing_record", + "extra_record", + "missing_required_field", + "type_mismatch", + "invalid_field_value", + "null_policy_violation", + "mapping_failure", + "value_mismatch" + ] + }, + "phase": { + "enum": [ + "contract", + "records", + "values" + ] + }, + "message": { + "$ref": "#/$defs/nonEmptyString" + }, + "affected_side": { + "enum": [ + "reference", + "query", + "both" + ] + }, + "record_identity": { + "$ref": "#/$defs/recordIdentity" + }, + "source_locations": { + "$ref": "#/$defs/sourceLocations" + }, + "field": { + "$ref": "#/$defs/nonEmptyString" + }, + "review_priority": { + "enum": [ + "low", + "normal", + "high" + ] + }, + "values": { + "$ref": "#/$defs/findingValues" + } + }, + "allOf": [ + { + "if": { + "properties": { + "code": { + "const": "missing_record" + } + }, + "required": [ + "code" + ] + }, + "then": { + "required": [ + "record_identity", + "source_locations" + ], + "properties": { + "classification": { + "const": "comparison_difference" + }, + "phase": { + "const": "records" + }, + "affected_side": { + "const": "query" + }, + "record_identity": { + "properties": { + "reference": { + "$ref": "#/$defs/recordIdentityValues" + }, + "query": { + "type": "null" + } + } + } + } + } + }, + { + "if": { + "properties": { + "code": { + "const": "extra_record" + } + }, + "required": [ + "code" + ] + }, + "then": { + "required": [ + "record_identity", + "source_locations" + ], + "properties": { + "classification": { + "const": "comparison_difference" + }, + "phase": { + "const": "records" + }, + "affected_side": { + "const": "reference" + }, + "record_identity": { + "properties": { + "reference": { + "type": "null" + }, + "query": { + "$ref": "#/$defs/recordIdentityValues" + } + } + } + } + } + }, + { + "if": { + "properties": { + "code": { + "enum": [ + "type_mismatch", + "invalid_field_value", + "null_policy_violation", + "mapping_failure" + ] + } + }, + "required": [ + "code" + ] + }, + "then": { + "required": [ + "record_identity", + "source_locations", + "field", + "review_priority", + "values" + ], + "properties": { + "classification": { + "const": "assessment_issue" + }, + "phase": { + "const": "contract" + }, + "affected_side": { + "enum": [ + "reference", + "query" + ] + } + } + } + }, + { + "if": { + "properties": { + "code": { + "const": "missing_required_field" + } + }, + "required": [ + "code" + ] + }, + "then": { + "required": [ + "field", + "review_priority" + ], + "properties": { + "classification": { + "const": "assessment_issue" + }, + "phase": { + "const": "contract" + }, + "affected_side": { + "enum": [ + "reference", + "query" + ] + } + }, + "oneOf": [ + { + "required": [ + "record_identity", + "source_locations", + "values" + ] + }, + { + "not": { + "anyOf": [ + { + "required": [ + "record_identity" + ] + }, + { + "required": [ + "source_locations" + ] + }, + { + "required": [ + "values" + ] + } + ] + } + } + ] + } + }, + { + "if": { + "properties": { + "code": { + "const": "value_mismatch" + } + }, + "required": [ + "code" + ] + }, + "then": { + "required": [ + "record_identity", + "source_locations", + "field", + "review_priority", + "values" + ], + "properties": { + "classification": { + "const": "comparison_difference" + }, + "phase": { + "const": "values" + }, + "affected_side": { + "const": "both" + } + } + } + } + ] + } + } +} diff --git a/packages/adviso-compare/src/adviso_compare/translation.py b/packages/adviso-compare/src/adviso_compare/translation.py new file mode 100644 index 0000000..3f682f9 --- /dev/null +++ b/packages/adviso-compare/src/adviso_compare/translation.py @@ -0,0 +1,655 @@ +"""Translate configured source field values into canonical typed values.""" + +from __future__ import annotations + +import re +from dataclasses import dataclass +from datetime import date, datetime, timedelta, timezone +from decimal import Decimal, ROUND_DOWN, ROUND_HALF_EVEN, ROUND_HALF_UP, localcontext +from enum import Enum +from typing import TypeVar + +from adviso_compare.configuration import ( + CollectionLogicalType, + CollectionRepresentation, + DatasetSides, + FieldDefinition, + Operation, + SourceValueDescriptor, + ValueMappingEntry, +) +from adviso_compare.inputs import ( + InputSide, + JsonValueError, + NativeCategory, + NativeValue, + decode_json_value, +) +from adviso_compare.processing import apply_source_text_operation + + +_INTEGER_PATTERN = re.compile(r"^[+-]?[0-9]+$") +_DECIMAL_PATTERN = re.compile( + r"^[+-]?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$" +) +_DATE_PATTERN = re.compile(r"^[0-9]{4}-[0-9]{2}-[0-9]{2}$") +_DATETIME_PATTERN = re.compile( + r"^(?P[0-9]{4}-[0-9]{2}-[0-9]{2})[Tt]" + r"(?P[0-9]{2}):(?P[0-9]{2}):(?P[0-9]{2})" + r"(?:\.(?P[0-9]+))?" + r"(?P[Zz]|[+-][0-9]{2}:[0-9]{2})$" +) +T = TypeVar("T") + + +class ValueDisposition(str, Enum): + """The assessment state of one configured field value.""" + + VALID = "valid" + ABSENT = "absent" + NOT_ASSESSABLE = "not_assessable" + NOT_ASSESSED = "not_assessed" + + +class TranslationIssueCode(str, Enum): + """The causal finding code for an unsuccessful field translation.""" + + MISSING_REQUIRED_FIELD = "missing_required_field" + TYPE_MISMATCH = "type_mismatch" + INVALID_FIELD_VALUE = "invalid_field_value" + NULL_POLICY_VIOLATION = "null_policy_violation" + MAPPING_FAILURE = "mapping_failure" + + +class TranslationStage(str, Enum): + """The processing stage at which an attributable value became unusable.""" + + PRESENCE = "presence" + NULL_POLICY = "null_policy" + VALUE_MAPPING = "value_mapping" + TYPE_PARSING = "type_parsing" + TYPED_NORMALISATION = "typed_normalisation" + COLLECTION_DECODING = "collection_decoding" + ELEMENT_MAPPING = "element_mapping" + ELEMENT_PARSING = "element_parsing" + COLLECTION_VALIDATION = "collection_validation" + + +@dataclass(frozen=True, slots=True) +class TranslationIssue: + """A structured cause for one not-assessable translated value.""" + + code: TranslationIssueCode + stage: TranslationStage + element_index: int | None = None + + +@dataclass(frozen=True, slots=True) +class CanonicalValue: + """One scalar, null, or collection value in its declared logical type.""" + + logical_type: str + value: object + element_type: str | None = None + + +@dataclass(frozen=True, slots=True) +class TranslatedValue: + """The complete source-to-canonical outcome for one field on one side.""" + + disposition: ValueDisposition + source: NativeValue | None + canonical: CanonicalValue | None = None + preserved: NativeValue | None = None + is_null: bool = False + issue: TranslationIssue | None = None + + +@dataclass(frozen=True, slots=True) +class _ExactDateTime: + """A UTC whole second plus an exact non-negative fractional second.""" + + utc_second: datetime + fraction: Decimal + + +class _TypeMismatch(ValueError): + """The parser-native category is incompatible with a logical type.""" + + +class _InvalidValue(ValueError): + """The parser-native category is accepted but its content is invalid.""" + + +def translate_field_value( + source: NativeValue | None, + field: FieldDefinition, + side: InputSide, + *, + in_scope: bool = True, +) -> TranslatedValue: + """Apply the configured translation pipeline to one attributable field value.""" + if not in_scope: + return TranslatedValue(ValueDisposition.NOT_ASSESSED, source) + if source is None: + if _for_side(field.required, side): + return _failure( + source, + TranslationIssueCode.MISSING_REQUIRED_FIELD, + TranslationStage.PRESENCE, + ) + return TranslatedValue(ValueDisposition.ABSENT, source) + + if field.logical_type is None: + if source.category is NativeCategory.NULL: + return _apply_null_policy(source, source, field) + return TranslatedValue( + ValueDisposition.VALID, + source, + preserved=source, + ) + + source_operations = _for_side(field.source_normalisation, side) + working = _apply_source_operations(source, source_operations) + if working.category is NativeCategory.NULL or _matches_any_descriptor( + working, + _for_side(field.null_policy.missing_tokens, side), + source_operations, + ): + return _apply_null_policy(source, working, field) + + mappings = _for_side(field.value_mapping, side) + if mappings: + mapped = _mapped_value(working, mappings, source_operations) + if mapped is None: + return _failure( + source, + TranslationIssueCode.MAPPING_FAILURE, + TranslationStage.VALUE_MAPPING, + ) + working = mapped + if working.category is NativeCategory.NULL: + return _apply_null_policy(source, working, field) + + if isinstance(field.logical_type, CollectionLogicalType): + return _translate_collection(source, working, field, side) + + try: + value = _parse_scalar(working, field.logical_type) + for operation in field.typed_normalisation: + value = _apply_typed_operation(value, operation) + value = _finalize_scalar(value, field.logical_type) + except _TypeMismatch: + return _failure( + source, + TranslationIssueCode.TYPE_MISMATCH, + TranslationStage.TYPE_PARSING, + ) + except _InvalidValue: + return _failure( + source, + TranslationIssueCode.INVALID_FIELD_VALUE, + TranslationStage.TYPE_PARSING, + ) + return TranslatedValue( + ValueDisposition.VALID, + source, + canonical=CanonicalValue(field.logical_type, value), + ) + + +def _apply_null_policy( + source: NativeValue, + _working: NativeValue, + field: FieldDefinition, +) -> TranslatedValue: + """Return the configured outcome for a recognised or mapped null value.""" + if not field.null_policy.allowed: + return _failure( + source, + TranslationIssueCode.NULL_POLICY_VIOLATION, + TranslationStage.NULL_POLICY, + ) + if field.logical_type is None: + return TranslatedValue( + ValueDisposition.VALID, + source, + preserved=source, + is_null=True, + ) + if isinstance(field.logical_type, CollectionLogicalType): + canonical = CanonicalValue( + field.logical_type.collection_type, + None, + element_type=field.logical_type.element_type, + ) + else: + canonical = CanonicalValue(field.logical_type, None) + return TranslatedValue( + ValueDisposition.VALID, + source, + canonical=canonical, + is_null=True, + ) + + +def _translate_collection( + source: NativeValue, + working: NativeValue, + field: FieldDefinition, + side: InputSide, +) -> TranslatedValue: + """Decode and translate every element of one declared collection value.""" + logical_type = field.logical_type + if not isinstance(logical_type, CollectionLogicalType): + raise AssertionError("collection translation received a scalar field") + representations = field.collection_representation + if representations is None: + raise AssertionError("resolved collection field has no representations") + representation = _for_side(representations, side) + try: + elements = _decode_collection(working, representation) + except _TypeMismatch: + return _failure( + source, + TranslationIssueCode.TYPE_MISMATCH, + TranslationStage.COLLECTION_DECODING, + ) + except _InvalidValue: + return _failure( + source, + TranslationIssueCode.INVALID_FIELD_VALUE, + TranslationStage.COLLECTION_DECODING, + ) + + canonical_elements: list[object] = [] + for index, element in enumerate(elements): + if element.category is NativeCategory.NULL: + return _failure( + source, + TranslationIssueCode.INVALID_FIELD_VALUE, + TranslationStage.ELEMENT_PARSING, + element_index=index, + ) + element = _apply_source_operations( + element, + representation.element_normalisation, + ) + if representation.element_mapping: + mapped = _mapped_value( + element, + representation.element_mapping, + representation.element_normalisation, + ) + if mapped is None: + return _failure( + source, + TranslationIssueCode.MAPPING_FAILURE, + TranslationStage.ELEMENT_MAPPING, + element_index=index, + ) + element = mapped + try: + parsed = _parse_scalar(element, logical_type.element_type) + canonical_elements.append( + _finalize_scalar(parsed, logical_type.element_type) + ) + except _TypeMismatch: + return _failure( + source, + TranslationIssueCode.TYPE_MISMATCH, + TranslationStage.ELEMENT_PARSING, + element_index=index, + ) + except _InvalidValue: + return _failure( + source, + TranslationIssueCode.INVALID_FIELD_VALUE, + TranslationStage.ELEMENT_PARSING, + element_index=index, + ) + + if logical_type.collection_type == "set": + if len(set(canonical_elements)) != len(canonical_elements): + return _failure( + source, + TranslationIssueCode.INVALID_FIELD_VALUE, + TranslationStage.COLLECTION_VALIDATION, + ) + canonical_elements.sort( + key=lambda value: render_canonical_scalar( + value, logical_type.element_type + ) + ) + elif logical_type.collection_type == "multiset": + canonical_elements.sort( + key=lambda value: render_canonical_scalar( + value, logical_type.element_type + ) + ) + + return TranslatedValue( + ValueDisposition.VALID, + source, + canonical=CanonicalValue( + logical_type.collection_type, + tuple(canonical_elements), + element_type=logical_type.element_type, + ), + ) + + +def _decode_collection( + value: NativeValue, + representation: CollectionRepresentation, +) -> tuple[NativeValue, ...]: + """Decode one side's declared source representation into native elements.""" + if representation.format == "delimited_text": + if value.category is not NativeCategory.STRING: + raise _TypeMismatch + if not isinstance(value.value, str): + raise AssertionError("parser-native string does not contain text") + if value.value == "": + return () + return tuple( + NativeValue(NativeCategory.STRING, element) + for element in value.value.split(representation.delimiter) + ) + + if value.category is NativeCategory.STRING: + if not isinstance(value.value, str): + raise AssertionError("parser-native string does not contain text") + try: + decoded = decode_json_value(value.value) + except JsonValueError as error: + raise _InvalidValue from error + elif value.category is NativeCategory.ARRAY: + decoded = value + else: + raise _TypeMismatch + if decoded.category is not NativeCategory.ARRAY: + raise _InvalidValue + if not isinstance(decoded.value, tuple): + raise AssertionError("parser-native array does not contain a tuple") + return decoded.value + + +def _apply_source_operations( + value: NativeValue, + operations: tuple[Operation, ...], +) -> NativeValue: + """Apply ordered source-text operations only to parser-native strings.""" + if value.category is not NativeCategory.STRING: + return value + text = value.value + if not isinstance(text, str): + raise AssertionError("parser-native string does not contain text") + for operation in operations: + text = apply_source_text_operation( + text, + operation.name, + operation.parameters, + ) + return NativeValue(NativeCategory.STRING, text) + + +def _mapped_value( + value: NativeValue, + mappings: tuple[ValueMappingEntry, ...], + source_operations: tuple[Operation, ...], +) -> NativeValue | None: + """Return the destination of one closed mapping or signal no match.""" + for mapping in mappings: + if _matches_descriptor(value, mapping.source, source_operations): + return _descriptor_value(mapping.destination) + return None + + +def _matches_any_descriptor( + value: NativeValue, + descriptors: tuple[SourceValueDescriptor, ...], + source_operations: tuple[Operation, ...], +) -> bool: + """Return whether a value equals any configured source descriptor.""" + return any( + _matches_descriptor(value, descriptor, source_operations) + for descriptor in descriptors + ) + + +def _matches_descriptor( + value: NativeValue, + descriptor: SourceValueDescriptor, + source_operations: tuple[Operation, ...], +) -> bool: + """Compare a native value with a typed descriptor by category and content.""" + expected = _apply_source_operations( + _descriptor_value(descriptor), + source_operations, + ) + return value.category is expected.category and value.value == expected.value + + +def _descriptor_value(descriptor: SourceValueDescriptor) -> NativeValue: + """Convert a validated descriptor into its parser-native representation.""" + category = NativeCategory(descriptor.category) + if category is NativeCategory.NULL: + return NativeValue(category) + if category is NativeCategory.INTEGER: + lexical = str(descriptor.value) + return NativeValue(category, int(lexical), lexical) + if category is NativeCategory.DECIMAL: + lexical = str(descriptor.value) + return NativeValue(category, Decimal(lexical), lexical) + return NativeValue(category, descriptor.value) + + +def _parse_scalar(value: NativeValue, logical_type: str) -> object: + """Parse one non-null native scalar into its declared logical type.""" + if logical_type == "string": + if value.category is not NativeCategory.STRING: + raise _TypeMismatch + return value.value + if logical_type == "integer": + if value.category is NativeCategory.INTEGER: + return value.value + if value.category is not NativeCategory.STRING: + raise _TypeMismatch + if not isinstance(value.value, str) or not _INTEGER_PATTERN.fullmatch( + value.value + ): + raise _InvalidValue + return int(value.value) + if logical_type == "decimal": + if value.category is NativeCategory.INTEGER: + return Decimal(value.value) + if value.category is NativeCategory.DECIMAL: + return value.value + if value.category is not NativeCategory.STRING: + raise _TypeMismatch + if not isinstance(value.value, str) or not _DECIMAL_PATTERN.fullmatch( + value.value + ): + raise _InvalidValue + parsed = Decimal(value.value) + if not parsed.is_finite(): + raise _InvalidValue + return parsed + if logical_type == "boolean": + if value.category is NativeCategory.BOOLEAN: + return value.value + if value.category is not NativeCategory.STRING: + raise _TypeMismatch + if value.value == "true": + return True + if value.value == "false": + return False + raise _InvalidValue + if logical_type == "date": + if value.category is not NativeCategory.STRING: + raise _TypeMismatch + if not isinstance(value.value, str) or not _DATE_PATTERN.fullmatch(value.value): + raise _InvalidValue + try: + return date.fromisoformat(value.value).isoformat() + except ValueError as error: + raise _InvalidValue from error + if logical_type == "datetime": + if value.category is not NativeCategory.STRING: + raise _TypeMismatch + if not isinstance(value.value, str): + raise _InvalidValue + return _parse_datetime(value.value) + raise AssertionError(f"validated logical type is not registered: {logical_type}") + + +def _parse_datetime(value: str) -> _ExactDateTime: + """Parse one offset-bearing datetime without losing fractional precision.""" + match = _DATETIME_PATTERN.fullmatch(value) + if match is None: + raise _InvalidValue + second = int(match["second"]) + if second > 59: + raise _InvalidValue + offset_text = match["offset"] + if offset_text in {"Z", "z"}: + offset = timezone.utc + else: + if offset_text == "-00:00": + raise _InvalidValue + offset_hour = int(offset_text[1:3]) + offset_minute = int(offset_text[4:6]) + if offset_hour > 23 or offset_minute > 59: + raise _InvalidValue + delta = timedelta(hours=offset_hour, minutes=offset_minute) + if offset_text.startswith("-"): + delta = -delta + try: + offset = timezone(delta) + except ValueError as error: + raise _InvalidValue from error + try: + local = datetime( + *map(int, match["date"].split("-")), + int(match["hour"]), + int(match["minute"]), + second, + tzinfo=offset, + ) + except ValueError as error: + raise _InvalidValue from error + fraction_text = match["fraction"] + fraction = Decimal(f"0.{fraction_text}") if fraction_text else Decimal(0) + try: + utc_second = local.astimezone(timezone.utc) + except (OverflowError, ValueError) as error: + raise _InvalidValue from error + return _ExactDateTime(utc_second, fraction) + + +def _apply_typed_operation(value: object, operation: Operation) -> object: + """Apply one validated typed-value operation.""" + if operation.name == "decimal_quantise": + if not isinstance(value, Decimal): + raise AssertionError("decimal operation received a non-decimal value") + places = operation.parameters["places"] + rounding_name = operation.parameters["rounding"] + if not isinstance(places, int) or not isinstance(rounding_name, str): + raise AssertionError("validated decimal operation parameters are invalid") + rounding = { + "half_even": ROUND_HALF_EVEN, + "half_up": ROUND_HALF_UP, + "down": ROUND_DOWN, + }[rounding_name] + quantum = Decimal(1).scaleb(-places) + integer_digits = max(value.adjusted() + 1, 1) if value else 1 + with localcontext() as context: + context.prec = ( + max(len(value.as_tuple().digits), integer_digits + places) + 2 + ) + return value.quantize(quantum, rounding=rounding) + if operation.name == "datetime_truncate": + if not isinstance(value, _ExactDateTime): + raise AssertionError("datetime operation received a non-datetime value") + precision = operation.parameters["precision"] + places = {"second": 0, "millisecond": 3, "microsecond": 6}[precision] + if places == 0: + fraction = Decimal(0) + else: + fraction = value.fraction.quantize( + Decimal(1).scaleb(-places), + rounding=ROUND_DOWN, + ) + return _ExactDateTime(value.utc_second, fraction) + raise AssertionError( + f"validated typed operation is not registered: {operation.name}" + ) + + +def _finalize_scalar(value: object, logical_type: str) -> object: + """Convert internal exact temporal state to its unique canonical value.""" + if logical_type == "datetime": + if not isinstance(value, _ExactDateTime): + raise AssertionError("parsed datetime has unexpected internal type") + return _render_datetime(value) + return value + + +def _render_datetime(value: _ExactDateTime) -> str: + """Render an exact UTC datetime using the canonical results representation.""" + instant = value.utc_second + text = ( + f"{instant.year:04d}-{instant.month:02d}-{instant.day:02d}T" + f"{instant.hour:02d}:{instant.minute:02d}:{instant.second:02d}" + ) + if value.fraction: + fraction = format(value.fraction, "f").partition(".")[2].rstrip("0") + text += f".{fraction}" + return f"{text}Z" + + +def render_canonical_scalar(value: object, logical_type: str) -> str: + """Render a canonical scalar for deterministic collection ordering.""" + if logical_type == "boolean": + return "true" if value else "false" + if logical_type == "decimal": + if not isinstance(value, Decimal): + raise AssertionError("canonical decimal has unexpected internal type") + return _render_decimal(value) + return str(value) + + +def _render_decimal(value: Decimal) -> str: + """Render one finite decimal in the canonical normalized scientific form.""" + if value.is_zero(): + return "0" + normalized = value.normalize() + sign = "-" if normalized.is_signed() else "" + digits = "".join(str(digit) for digit in normalized.as_tuple().digits) + exponent = normalized.adjusted() + coefficient = digits[0] + if len(digits) > 1: + coefficient += f".{digits[1:]}" + if exponent: + coefficient += f"e{exponent}" + return f"{sign}{coefficient}" + + +def _failure( + source: NativeValue | None, + code: TranslationIssueCode, + stage: TranslationStage, + *, + element_index: int | None = None, +) -> TranslatedValue: + """Construct one attributable not-assessable translation outcome.""" + return TranslatedValue( + ValueDisposition.NOT_ASSESSABLE, + source, + issue=TranslationIssue(code, stage, element_index), + ) + + +def _for_side(sides: DatasetSides[T], side: InputSide) -> T: + """Select one resolved side-specific configuration value.""" + return sides.reference if side is InputSide.REFERENCE else sides.query diff --git a/packages/adviso-compare/src/adviso_compare/values.py b/packages/adviso-compare/src/adviso_compare/values.py new file mode 100644 index 0000000..bbe1071 --- /dev/null +++ b/packages/adviso-compare/src/adviso_compare/values.py @@ -0,0 +1,218 @@ +"""Compare every assessable non-key value in safely aligned records.""" + +from __future__ import annotations + +from dataclasses import dataclass +from enum import Enum +from typing import Literal + +from adviso_compare.alignment import RecordAlignment, RecordsResult +from adviso_compare.comparators import compare_translated_values +from adviso_compare.configuration import EffectiveConfiguration +from adviso_compare.contract import ContractResult, FieldAssessment +from adviso_compare.inputs import InputSide, SourceLocation +from adviso_compare.translation import ValueDisposition + + +class ValuesPhaseStatus(str, Enum): + """Completion state of the values phase.""" + + COMPLETE = "complete" + INCOMPLETE = "incomplete" + + +class ValueOpportunityDisposition(str, Enum): + """Outcome of one aligned, in-scope, non-key field opportunity.""" + + MATCHED = "matched" + MISMATCHED = "mismatched" + NOT_ASSESSABLE = "not_assessable" + + +@dataclass(frozen=True, slots=True) +class ValueOpportunity: + """One field comparison opportunity across an aligned record pair.""" + + alignment: RecordAlignment + canonical_field: str + reference: FieldAssessment + query: FieldAssessment + disposition: ValueOpportunityDisposition + + +@dataclass(frozen=True, slots=True) +class ValueFinding: + """One post-translation value difference for later evidence construction.""" + + opportunity: ValueOpportunity + review_priority: str + + @property + def code(self) -> str: + """Return the stable value-difference finding code.""" + return "value_mismatch" + + @property + def classification(self) -> str: + """Return the fixed classification for post-translation differences.""" + return "comparison_difference" + + @property + def phase(self) -> str: + """Return the phase in which the difference was detected.""" + return "values" + + @property + def affected_side(self) -> Literal["both"]: + """Return the fixed two-sided scope of a value comparison.""" + return "both" + + @property + def canonical_field(self) -> str: + """Return the compared canonical field name.""" + return self.opportunity.canonical_field + + @property + def reference_location(self) -> SourceLocation: + """Return the reference field or containing-record location.""" + return self.opportunity.reference.location + + @property + def query_location(self) -> SourceLocation: + """Return the query field or containing-record location.""" + return self.opportunity.query.location + + +@dataclass(frozen=True, slots=True) +class ValueCounts: + """Complete counts of in-scope non-key value opportunities.""" + + matched: int + mismatched: int + not_assessable: int + + +@dataclass(frozen=True, slots=True) +class ValuesResult: + """All deterministic values-phase outcomes for safely aligned records.""" + + status: ValuesPhaseStatus + opportunities: tuple[ValueOpportunity, ...] + findings: tuple[ValueFinding, ...] + counts: ValueCounts + + +def compare_values( + configuration: EffectiveConfiguration, + contract: ContractResult, + records: RecordsResult, +) -> ValuesResult: + """Classify every aligned in-scope non-key value opportunity exactly once.""" + compared_fields = sorted( + set(configuration.in_scope) - set(configuration.record_key) + ) + opportunities: list[ValueOpportunity] = [] + findings: list[ValueFinding] = [] + + for alignment in records.matched: + if alignment.reference is None or alignment.query is None: + raise AssertionError("matched alignment does not contain both records") + for canonical_field in compared_fields: + reference = contract.assessment( + InputSide.REFERENCE, + alignment.key, + canonical_field, + ) + query = contract.assessment( + InputSide.QUERY, + alignment.key, + canonical_field, + ) + disposition = _compare_opportunity( + configuration, + canonical_field, + reference, + query, + ) + opportunity = ValueOpportunity( + alignment=alignment, + canonical_field=canonical_field, + reference=reference, + query=query, + disposition=disposition, + ) + opportunities.append(opportunity) + if disposition is ValueOpportunityDisposition.MISMATCHED: + findings.append( + ValueFinding( + opportunity=opportunity, + review_priority=configuration.field( + canonical_field + ).review_priority, + ) + ) + + matched = sum( + item.disposition is ValueOpportunityDisposition.MATCHED + for item in opportunities + ) + mismatched = sum( + item.disposition is ValueOpportunityDisposition.MISMATCHED + for item in opportunities + ) + not_assessable = sum( + item.disposition is ValueOpportunityDisposition.NOT_ASSESSABLE + for item in opportunities + ) + status = ( + ValuesPhaseStatus.INCOMPLETE + if not_assessable + else ValuesPhaseStatus.COMPLETE + ) + return ValuesResult( + status=status, + opportunities=tuple(opportunities), + findings=tuple(findings), + counts=ValueCounts( + matched=matched, + mismatched=mismatched, + not_assessable=not_assessable, + ), + ) + + +def _compare_opportunity( + configuration: EffectiveConfiguration, + canonical_field: str, + reference: FieldAssessment, + query: FieldAssessment, +) -> ValueOpportunityDisposition: + """Classify one opportunity from its two contract assessments.""" + if ( + reference.disposition is ValueDisposition.NOT_ASSESSABLE + or query.disposition is ValueDisposition.NOT_ASSESSABLE + ): + return ValueOpportunityDisposition.NOT_ASSESSABLE + if ( + reference.disposition is ValueDisposition.ABSENT + and query.disposition is ValueDisposition.ABSENT + ): + return ValueOpportunityDisposition.MATCHED + if ( + reference.disposition is ValueDisposition.ABSENT + or query.disposition is ValueDisposition.ABSENT + ): + return ValueOpportunityDisposition.MISMATCHED + if ( + reference.disposition is not ValueDisposition.VALID + or query.disposition is not ValueDisposition.VALID + ): + raise AssertionError("value opportunity has an unexpected contract state") + matches = compare_translated_values( + configuration.field(canonical_field), + reference.translated, + query.translated, + ) + if matches: + return ValueOpportunityDisposition.MATCHED + return ValueOpportunityDisposition.MISMATCHED diff --git a/packages/adviso-compare/tests/README.md b/packages/adviso-compare/tests/README.md new file mode 100644 index 0000000..1b757df --- /dev/null +++ b/packages/adviso-compare/tests/README.md @@ -0,0 +1,17 @@ +# Version 1 test conventions + +Tests use descriptive behavioural names and assertions that remain meaningful +without the development specification. Test modules, names, markers, fixtures, +and snapshots do not embed specification requirement identifiers or acceptance +scenario identifiers. During development, any formal traceability is maintained +in the specification and review records as a one-way reference to the tests. + +Reusable synthetic documents are built in `tests/support/documents.py`. Builders +return new objects on every call so tests can modify a document without leaking +state into another test. Fixed values are intentional: generated fixtures must +be deterministic and reviewable. A future generated on-disk fixture must record +its generator and regeneration command alongside the fixture. + +Schema loading and validator construction live in `tests/support/schemas.py`. +Structural validators load each document's packaged schema independently and +enable JSON Schema format assertion. diff --git a/tests/__init__.py b/packages/adviso-compare/tests/__init__.py similarity index 100% rename from tests/__init__.py rename to packages/adviso-compare/tests/__init__.py diff --git a/packages/adviso-compare/tests/support/__init__.py b/packages/adviso-compare/tests/support/__init__.py new file mode 100644 index 0000000..b0436bc --- /dev/null +++ b/packages/adviso-compare/tests/support/__init__.py @@ -0,0 +1,2 @@ +"""Reusable support for the adviso-compare test suite.""" + diff --git a/packages/adviso-compare/tests/support/documents.py b/packages/adviso-compare/tests/support/documents.py new file mode 100644 index 0000000..21f6e88 --- /dev/null +++ b/packages/adviso-compare/tests/support/documents.py @@ -0,0 +1,189 @@ +"""Deterministic synthetic documents used by schema-level tests.""" + +from __future__ import annotations + +import json +from hashlib import sha256 +from typing import Any, Literal + + +JsonObject = dict[str, Any] + + +def minimal_configuration() -> JsonObject: + """Return a fresh, structurally valid comparison configuration.""" + return { + "schema_version": "1.0", + "metadata": { + "id": "org.example.synthetic-exact-comparison", + "revision": "1.0.0", + }, + "fields": { + "record_key": ["record_id"], + "in_scope": ["record_id", "measured_value"], + "definitions": { + "record_id": { + "source_fields": { + "reference": "reference_id", + "query": "query_id", + }, + "required": {"reference": True, "query": True}, + "logical_type": "string", + "null_policy": {"allowed": False, "nulls_equal": False}, + "comparator": {"name": "typed_exact"}, + }, + "measured_value": { + "source_fields": { + "reference": "expected_value", + "query": "observed_value", + }, + "required": {"reference": True, "query": True}, + "logical_type": "decimal", + "null_policy": {"allowed": False, "nulls_equal": False}, + "comparator": {"name": "numeric_exact"}, + }, + }, + }, + } + + +def minimal_configuration_bytes() -> bytes: + """Return deterministic saved bytes for the controlled configuration.""" + document = minimal_configuration() + definitions = document["fields"]["definitions"] + document["fields"]["definitions"] = { + name: definitions[name] for name in sorted(definitions) + } + return (json.dumps(document, ensure_ascii=False, indent=2) + "\n").encode( + "utf-8" + ) + + +def minimal_result( + *, status: Literal["complete", "incomplete"] = "complete" +) -> JsonObject: + """Return a fresh, structurally valid canonical result.""" + zero_by_code = { + "missing_record": 0, + "extra_record": 0, + "missing_required_field": 0, + "type_mismatch": 0, + "invalid_field_value": 0, + "null_policy_violation": 0, + "mapping_failure": 0, + "value_mismatch": 0, + } + records = { + "reference": 0, + "query": 0, + "matched": 0, + "missing": 0, + "extra": 0, + } + values = {"matched": 0, "mismatched": 0, "not_assessable": 0} + findings: list[JsonObject] = [] + phases = { + "contract": "complete", + "records": "complete", + "values": "complete", + } + + if status == "incomplete": + records = { + "reference": 1, + "query": 1, + "matched": 1, + "missing": 0, + "extra": 0, + } + values = {"matched": 0, "mismatched": 0, "not_assessable": 1} + zero_by_code["missing_required_field"] = 1 + phases["values"] = "incomplete" + findings = [ + { + "id": "F000001", + "classification": "assessment_issue", + "code": "missing_required_field", + "phase": "contract", + "message": "Required query field observed_value is absent.", + "affected_side": "query", + "record_identity": { + "reference": ["sample-1"], + "query": ["sample-1"], + "canonical": ["sample-1"], + }, + "source_locations": { + "reference": {"json_pointer": "/0/expected_value"}, + "query": {"json_pointer": "/0"}, + }, + "field": "measured_value", + "review_priority": "normal", + "values": { + "reference": {"state": "present"}, + "query": {"state": "absent"}, + }, + } + ] + + return { + "schema_version": "1.0", + "run": { + "id": "123e4567-e89b-42d3-a456-426614174000", + "status": status, + "completed_at": "2026-01-02T03:04:05Z", + }, + "phases": { + **phases, + }, + "software": {"name": "adviso-compare", "version": "1.0.0"}, + "runtime": { + "python": "cpython-3.10.12", + "platform": "linux-x86_64", + "unicode_version": "14.0.0", + }, + "inputs": { + "reference": { + "basename": "reference.json", + "format": "json", + "encoding": "utf-8", + "size_bytes": 2, + "digest": {"algorithm": "sha256", "value": "0" * 64}, + }, + "query": { + "basename": "query.json", + "format": "json", + "encoding": "utf-8", + "size_bytes": 2, + "digest": {"algorithm": "sha256", "value": "1" * 64}, + }, + }, + "record_key_fields": { + "reference": ["reference_id"], + "query": ["query_id"], + "canonical": ["record_id"], + }, + "comparison_configuration_digest": { + "algorithm": "sha256", + "value": sha256(minimal_configuration_bytes()).hexdigest(), + }, + "summary": { + "records": records, + "values": values, + "findings": { + "total": len(findings), + "by_classification": { + "comparison_difference": 0, + "assessment_issue": len(findings), + }, + "by_code": zero_by_code, + "by_review_priority": { + "low": 0, + "normal": len(findings), + "high": 0, + "unassigned": 0, + }, + }, + }, + "exclusions": [], + "findings": findings, + } diff --git a/packages/adviso-compare/tests/support/evidence.py b/packages/adviso-compare/tests/support/evidence.py new file mode 100644 index 0000000..2cb5f4f --- /dev/null +++ b/packages/adviso-compare/tests/support/evidence.py @@ -0,0 +1,46 @@ +"""Assertions for the published evidence layout used by integration tests.""" + +from __future__ import annotations + +import json +import re +from datetime import datetime +from hashlib import sha256 +from pathlib import Path + +from tests.support.schemas import configuration_validator, results_validator + + +def assert_run_package(parent: Path, child: Path | None = None) -> Path: + """Check a child package's members, schema, and metadata-derived name.""" + if child is None: + children = list(parent.iterdir()) + assert len(children) == 1 + child = children[0] + assert child.parent == parent + assert child.is_dir() + assert sorted(path.name for path in child.iterdir()) == [ + "comparison-configuration.json", + "comparison-report.html", + "comparison-results.json", + ] + result = json.loads( + (child / "comparison-results.json").read_text(encoding="utf-8") + ) + results_validator().validate(result) + configuration_path = child / "comparison-configuration.json" + assert not configuration_path.is_symlink() + configuration_bytes = configuration_path.read_bytes() + configuration = json.loads(configuration_bytes.decode("utf-8")) + configuration_validator().validate(configuration) + assert result["comparison_configuration_digest"] == { + "algorithm": "sha256", + "value": sha256(configuration_bytes).hexdigest(), + } + match = re.fullmatch(r"([0-9]{8}T[0-9]{6}Z)-([0-9a-f-]{36})", child.name) + assert match is not None + timestamp = datetime.strptime(match[1], "%Y%m%dT%H%M%SZ") + completed_at = timestamp.strftime("%Y-%m-%dT%H:%M:%SZ") + assert completed_at == result["run"]["completed_at"] + assert match[2] == result["run"]["id"] + return child diff --git a/packages/adviso-compare/tests/support/schemas.py b/packages/adviso-compare/tests/support/schemas.py new file mode 100644 index 0000000..5860783 --- /dev/null +++ b/packages/adviso-compare/tests/support/schemas.py @@ -0,0 +1,34 @@ +"""Helpers for loading and validating packaged version 1 schemas.""" + +from __future__ import annotations + +import json +from importlib.resources import files +from typing import Any + +from jsonschema import Draft202012Validator, FormatChecker + + +CONFIGURATION_SCHEMA_FILE = "comparison-configuration-v1.0.schema.json" +RESULTS_SCHEMA_FILE = "comparison-results-v1.0.schema.json" +SCHEMA_PACKAGE = "adviso_compare.schemas" + +JsonObject = dict[str, Any] + + +def load_packaged_schema(filename: str) -> JsonObject: + """Load a schema through the installed-package resource interface.""" + resource = files(SCHEMA_PACKAGE).joinpath(filename) + return json.loads(resource.read_text(encoding="utf-8")) + + +def configuration_validator() -> Draft202012Validator: + """Return the version 1 comparison-configuration validator.""" + schema = load_packaged_schema(CONFIGURATION_SCHEMA_FILE) + return Draft202012Validator(schema, format_checker=FormatChecker()) + + +def results_validator() -> Draft202012Validator: + """Return the standalone version 1 canonical-results validator.""" + schema = load_packaged_schema(RESULTS_SCHEMA_FILE) + return Draft202012Validator(schema, format_checker=FormatChecker()) diff --git a/packages/adviso-compare/tests/test_alignment.py b/packages/adviso-compare/tests/test_alignment.py new file mode 100644 index 0000000..ed55b96 --- /dev/null +++ b/packages/adviso-compare/tests/test_alignment.py @@ -0,0 +1,307 @@ +"""Behavioural tests for deterministic record alignment.""" + +from __future__ import annotations + +from pathlib import Path + +import pytest +import yaml + +from adviso_compare.alignment import ( + RecordDisposition, + RecordsResult, + RecordsPhaseStatus, + align_records, +) +from adviso_compare.application import PreparedComparison, prepare_comparison +from adviso_compare.inputs import InputSide, JsonLocation +from adviso_compare.invocation import ComparisonInvocation +from tests.support.documents import JsonObject, minimal_configuration + + +def _write(path: Path, text: str) -> Path: + """Write one controlled UTF-8 document.""" + path.write_text(text, encoding="utf-8") + return path + + +def _prepare( + tmp_path: Path, + reference_text: str, + query_text: str, + configuration: JsonObject | None = None, +) -> PreparedComparison: + """Prepare two JSON datasets with an optional custom configuration.""" + reference = _write(tmp_path / "reference.json", reference_text) + query = _write(tmp_path / "query.json", query_text) + configuration_path = None + if configuration is not None: + configuration_path = _write( + tmp_path / "configuration.yaml", + yaml.safe_dump(configuration, sort_keys=False), + ) + return prepare_comparison( + ComparisonInvocation( + reference=reference, + query=query, + output=tmp_path / "evidence", + configuration=configuration_path, + ) + ) + + +def _align(prepared: PreparedComparison) -> RecordsResult: + """Align the prepared record models through the records-phase boundary.""" + return align_records( + prepared.reference_records, + prepared.query_records, + ) + + +def test_reordered_inputs_have_the_same_complete_alignment(tmp_path: Path) -> None: + """Input occurrence order does not affect matches or canonical ordering.""" + first = _prepare( + tmp_path, + '[{"record_id":"S2","value":2},{"record_id":"S1","value":1}]', + '[{"record_id":"S1","value":1},{"record_id":"S2","value":2}]', + ) + second_path = tmp_path / "reordered" + second_path.mkdir() + second = _prepare( + second_path, + '[{"record_id":"S1","value":1},{"record_id":"S2","value":2}]', + '[{"record_id":"S2","value":2},{"record_id":"S1","value":1}]', + ) + + first_result = _align(first) + second_result = _align(second) + + assert first_result.status is RecordsPhaseStatus.COMPLETE + assert first_result.findings == second_result.findings == () + assert [ + (alignment.canonical_identity, alignment.disposition) + for alignment in first_result.alignments + ] == [ + (("S1",), RecordDisposition.MATCHED), + (("S2",), RecordDisposition.MATCHED), + ] + assert [ + (alignment.canonical_identity, alignment.disposition) + for alignment in second_result.alignments + ] == [ + (("S1",), RecordDisposition.MATCHED), + (("S2",), RecordDisposition.MATCHED), + ] + assert first_result.counts == second_result.counts + + +def test_composite_keys_preserve_multiple_records_for_one_sample( + tmp_path: Path, +) -> None: + """Ordered composite identity aligns distinct records sharing a sample ID.""" + configuration = minimal_configuration() + fields = configuration["fields"] + fields["record_key"] = ["record_id", "batch"] + fields["in_scope"].insert(1, "batch") + fields["definitions"]["batch"] = { + "source_fields": { + "reference": "reference_batch", + "query": "query_batch", + }, + "required": {"reference": True, "query": True}, + "logical_type": "integer", + "null_policy": {"allowed": False, "nulls_equal": False}, + "comparator": {"name": "typed_exact"}, + } + prepared = _prepare( + tmp_path, + ( + '[{"reference_id":"S1","reference_batch":"01"},' + '{"reference_id":"S1","reference_batch":"02"}]' + ), + ( + '[{"query_id":"S1","query_batch":"2"},' + '{"query_id":"S1","query_batch":"1"}]' + ), + configuration, + ) + + result = _align(prepared) + + assert [alignment.canonical_identity for alignment in result.alignments] == [ + ("S1", "1"), + ("S1", "2"), + ] + assert all( + alignment.disposition is RecordDisposition.MATCHED + for alignment in result.alignments + ) + assert [ + ( + alignment.reference.source_identity, + alignment.query.source_identity, + ) + for alignment in result.alignments + if alignment.reference is not None and alignment.query is not None + ] == [ + (("S1", "01"), ("S1", "1")), + (("S1", "02"), ("S1", "2")), + ] + + +def test_missing_and_extra_records_are_all_reported_deterministically( + tmp_path: Path, +) -> None: + """The union retains its matched intersection and every one-sided record.""" + prepared = _prepare( + tmp_path, + ( + '[{"record_id":"S3"},{"record_id":"S1"},' + '{"record_id":"S2"}]' + ), + ( + '[{"record_id":"S5"},{"record_id":"S1"},' + '{"record_id":"S4"}]' + ), + ) + + result = _align(prepared) + reordered_path = tmp_path / "reordered" + reordered_path.mkdir() + reordered = _prepare( + reordered_path, + ( + '[{"record_id":"S2"},{"record_id":"S3"},' + '{"record_id":"S1"}]' + ), + ( + '[{"record_id":"S4"},{"record_id":"S5"},' + '{"record_id":"S1"}]' + ), + ) + reordered_result = _align(reordered) + + assert result.status is RecordsPhaseStatus.COMPLETE + alignment_outcome = [ + (alignment.canonical_identity, alignment.disposition) + for alignment in result.alignments + ] + assert alignment_outcome == [ + (("S1",), RecordDisposition.MATCHED), + (("S2",), RecordDisposition.MISSING), + (("S3",), RecordDisposition.MISSING), + (("S4",), RecordDisposition.EXTRA), + (("S5",), RecordDisposition.EXTRA), + ] + assert [ + (alignment.canonical_identity, alignment.disposition) + for alignment in reordered_result.alignments + ] == alignment_outcome + finding_outcome = [ + ( + finding.code, + finding.affected_side, + finding.alignment.canonical_identity, + finding.alignment.reference.source_identity + if finding.alignment.reference is not None + else None, + finding.alignment.query.source_identity + if finding.alignment.query is not None + else None, + ) + for finding in result.findings + ] + assert finding_outcome == [ + ("missing_record", InputSide.QUERY, ("S2",), ("S2",), None), + ("missing_record", InputSide.QUERY, ("S3",), ("S3",), None), + ("extra_record", InputSide.REFERENCE, ("S4",), None, ("S4",)), + ("extra_record", InputSide.REFERENCE, ("S5",), None, ("S5",)), + ] + assert [ + ( + finding.code, + finding.affected_side, + finding.alignment.canonical_identity, + finding.alignment.reference.source_identity + if finding.alignment.reference is not None + else None, + finding.alignment.query.source_identity + if finding.alignment.query is not None + else None, + ) + for finding in reordered_result.findings + ] == finding_outcome + assert all( + finding.classification == "comparison_difference" + and finding.phase == "records" + for finding in result.findings + ) + assert result.findings[0].reference_location == JsonLocation("/2") + assert result.findings[0].query_location is None + assert result.findings[-1].reference_location is None + assert result.findings[-1].query_location == JsonLocation("/0") + assert [ + (finding.reference_location, finding.query_location) + for finding in reordered_result.findings + ] != [ + (finding.reference_location, finding.query_location) + for finding in result.findings + ] + assert result.matched == (result.alignments[0],) + assert result.alignment(result.matched[0].key) is result.matched[0] + assert reordered_result.counts == result.counts + assert result.counts.reference == result.counts.matched + result.counts.missing + assert result.counts.query == result.counts.matched + result.counts.extra + assert ( + result.counts.reference, + result.counts.query, + result.counts.matched, + result.counts.missing, + result.counts.extra, + ) == (3, 3, 1, 2, 2) + + +@pytest.mark.parametrize( + ("reference_text", "query_text", "expected_counts", "finding_codes"), + [ + ("[]", "[]", (0, 0, 0, 0, 0), ()), + ( + '[{"reference_id":"S1"}]', + "[]", + (1, 0, 0, 1, 0), + ("missing_record",), + ), + ( + "[]", + '[{"query_id":"S1"}]', + (0, 1, 0, 0, 1), + ("extra_record",), + ), + ], +) +def test_empty_and_one_sided_datasets_reconcile_without_special_cases( + tmp_path: Path, + reference_text: str, + query_text: str, + expected_counts: tuple[int, int, int, int, int], + finding_codes: tuple[str, ...], +) -> None: + """The same union rules cover empty, reference-only, and query-only inputs.""" + prepared = _prepare( + tmp_path, + reference_text, + query_text, + minimal_configuration(), + ) + + result = _align(prepared) + + assert result.status is RecordsPhaseStatus.COMPLETE + assert ( + result.counts.reference, + result.counts.query, + result.counts.matched, + result.counts.missing, + result.counts.extra, + ) == expected_counts + assert tuple(finding.code for finding in result.findings) == finding_codes diff --git a/packages/adviso-compare/tests/test_cli.py b/packages/adviso-compare/tests/test_cli.py new file mode 100644 index 0000000..9db2d92 --- /dev/null +++ b/packages/adviso-compare/tests/test_cli.py @@ -0,0 +1,575 @@ +"""Behavioural tests for the direct adviso-compare command line.""" + +from __future__ import annotations + +from contextlib import contextmanager +from dataclasses import FrozenInstanceError +from importlib.metadata import version +from pathlib import Path +from typing import Iterator + +import pytest +import yaml + +import adviso_compare.cli as cli +from adviso_compare.cli import main, parse_invocation +from adviso_compare.configuration import ConfigurationError +from adviso_compare.inputs import InputError, InputSide +from adviso_compare.invocation import ComparisonInvocation, ComparisonOutcome +from adviso_compare.records import RecordKeyError +from adviso_compare.reporting import OutputError +from adviso_compare.results import ResultValidationError +from tests.support.documents import minimal_configuration +from tests.support.evidence import assert_run_package + + +@pytest.mark.parametrize( + ("optional_arguments", "expected_configuration"), + [ + ([], None), + (["--configuration", "rules.yaml"], Path("rules.yaml")), + ], +) +def test_direct_arguments_create_an_immutable_invocation_without_reading_inputs( + optional_arguments: list[str], + expected_configuration: Path | None, +) -> None: + """Parsing records paths and flags without requiring any path to exist.""" + arguments = [ + "--reference", + "does-not-exist-reference.csv", + "--query", + "does-not-exist-query.json", + "--output", + "does-not-exist-output", + *optional_arguments, + ] + + invocation = parse_invocation(arguments) + + assert invocation == ComparisonInvocation( + reference=Path("does-not-exist-reference.csv"), + query=Path("does-not-exist-query.json"), + output=Path("does-not-exist-output"), + configuration=expected_configuration, + ) + assert not hasattr(invocation, "overwrite") + with pytest.raises(FrozenInstanceError): + invocation.output = Path("other") # type: ignore[misc] + + +def test_main_dispatches_the_invocation_through_an_injected_executor( + capsys: pytest.CaptureFixture[str], +) -> None: + """CLI orchestration passes one domain value to an independently testable core.""" + received: list[ComparisonInvocation] = [] + + def execute(invocation: ComparisonInvocation) -> ComparisonOutcome: + received.append(invocation) + return ComparisonOutcome( + run_status="complete", + output=invocation.output / "selected-run", + comparison_differences=2, + assessment_issues=1, + ) + + exit_code = main( + [ + "--reference", + "reference.csv", + "--query", + "query.tsv", + "--output", + "evidence", + ], + executor=execute, + ) + + assert exit_code == 0 + assert received == [ + ComparisonInvocation( + reference=Path("reference.csv"), + query=Path("query.tsv"), + output=Path("evidence"), + ) + ] + expected = Path("evidence") / "selected-run" + assert capsys.readouterr().out.endswith(f"Evidence package: {expected}\n") + + +@pytest.mark.parametrize( + ( + "automatic", + "incomplete", + "expected_exit", + "expected_status", + "expected_differences", + "expected_issues", + ), + [ + (False, False, 0, "complete", 1, 0), + (False, True, 1, "incomplete", 0, 1), + (True, False, 0, "complete", 1, 0), + ], +) +def test_cli_executes_custom_automatic_and_incomplete_comparisons_end_to_end( + tmp_path: Path, + capsys: pytest.CaptureFixture[str], + automatic: bool, + incomplete: bool, + expected_exit: int, + expected_status: str, + expected_differences: int, + expected_issues: int, +) -> None: + """The default executor writes evidence and reports a non-sensitive summary.""" + if automatic: + reference_text = '[{"record_id":"S1","result":1}]' + query_text = '[{"record_id":"S1","result":2}]' + configuration_arguments: list[str] = [] + else: + reference_text = '[{"reference_id":"S1","expected_value":1}]' + query_text = ( + '[{"query_id":"S1"}]' + if incomplete + else '[{"query_id":"S1","observed_value":2}]' + ) + configuration = tmp_path / "configuration.yaml" + configuration.write_text( + yaml.safe_dump(minimal_configuration(), sort_keys=False), + encoding="utf-8", + ) + configuration_arguments = ["--configuration", str(configuration)] + reference = tmp_path / "reference.json" + query = tmp_path / "query.json" + output = tmp_path / "evidence" + reference.write_text(reference_text, encoding="utf-8") + query.write_text(query_text, encoding="utf-8") + + exit_code = main( + [ + "--reference", + str(reference), + "--query", + str(query), + "--output", + str(output), + *configuration_arguments, + ] + ) + + captured = capsys.readouterr() + assert exit_code == expected_exit + assert captured.err == "" + selected = assert_run_package(output) + assert captured.out == ( + f"Run status: {expected_status}\n" + f"Comparison differences: {expected_differences}\n" + f"Assessment issues: {expected_issues}\n" + f"Evidence package: {Path(output.name) / selected.name}\n" + ) + assert str(tmp_path) not in captured.out + + +@pytest.mark.parametrize("through_cleanup", [False, True]) +@pytest.mark.parametrize( + ("error", "expected_diagnostic"), + [ + ( + ConfigurationError("schema_violation", "rules.yaml", "is invalid"), + "ERROR [configuration.schema_violation]: rules.yaml: is invalid\n", + ), + ( + InputError("invalid_syntax", InputSide.QUERY, "query input is invalid"), + "ERROR [input.invalid_syntax]: query input is invalid\n", + ), + ( + RecordKeyError("no automatic record key could be established"), + "ERROR [input.invalid_record_key]: no automatic record key could be established\n", + ), + ( + OutputError("invalid_destination", "run path already exists"), + "ERROR [output.invalid_destination]: run path already exists\n", + ), + ], +) +def test_expected_execution_errors_have_stable_diagnostics_and_exit_two( + tmp_path: Path, + capsys: pytest.CaptureFixture[str], + error: Exception, + expected_diagnostic: str, + through_cleanup: bool, +) -> None: + """Classified operational failures publish nothing and omit tracebacks.""" + output = tmp_path / "evidence" + cleanup_finished = False + original_args = error.args + + @contextmanager + def cleanup() -> Iterator[None]: + nonlocal cleanup_finished + try: + yield + finally: + cleanup_finished = True + + def fail(_: ComparisonInvocation) -> ComparisonOutcome: + if through_cleanup: + try: + with cleanup(): + raise error + except type(error) as observed: + assert observed is error + raise + raise error + + exit_code = main( + [ + "--reference", + "reference.json", + "--query", + "query.json", + "--output", + str(output), + ], + executor=fail, + ) + + captured = capsys.readouterr() + assert exit_code == 2 + assert captured.out == "" + assert captured.err == expected_diagnostic + assert "Traceback" not in captured.err + assert not output.exists() + assert error.args == original_args + assert cleanup_finished is through_cleanup + + +@pytest.mark.parametrize( + "failure", ["input", "configuration", "validation", "linkage", "html"] +) +@pytest.mark.parametrize("parent_exists", [False, True]) +def test_default_executor_errors_preserve_existing_content_without_new_output( + tmp_path: Path, + capsys: pytest.CaptureFixture[str], + monkeypatch: pytest.MonkeyPatch, + failure: str, + parent_exists: bool, +) -> None: + """Pre-publication failures leave absent parents and existing data alone.""" + output = tmp_path / "evidence" + if parent_exists: + output.mkdir() + (output / "keep.txt").write_bytes(b"keep") + mode = output.stat().st_mode + reference = tmp_path / "reference.json" + query = tmp_path / "query.json" + query.write_text('[{"record_id":"S1","result":1}]', encoding="utf-8") + arguments = [ + "--reference", str(reference), "--query", str(query), + "--output", str(output), + ] + if failure != "input": + reference.write_bytes(query.read_bytes()) + if failure == "configuration": + configuration = tmp_path / "configuration.yaml" + configuration.write_text("[", encoding="utf-8") + arguments.extend(["--configuration", str(configuration)]) + failure_attempted = False + if failure in {"validation", "linkage", "html"}: + + def fail(*args: object, **kwargs: object) -> None: + nonlocal failure_attempted + if failure == "linkage": + assert isinstance(kwargs.get("configuration_bytes"), bytes) + failure_attempted = True + raise ResultValidationError("sensitive implementation detail") + + target = { + "validation": "adviso_compare.application.assemble_result", + "linkage": "adviso_compare.results.validate_result", + "html": "adviso_compare.reporting.render_html_report", + }[failure] + monkeypatch.setattr(target, fail) + + exit_code = main(arguments) + + captured = capsys.readouterr() + expected_code = { + "input": "input.unreadable", + "configuration": "configuration.invalid_syntax", + "validation": "internal.unexpected", + "linkage": "internal.unexpected", + "html": "internal.unexpected", + }[failure] + if failure in {"validation", "linkage", "html"}: + assert failure_attempted + assert exit_code == ( + 3 if failure in {"validation", "linkage", "html"} else 2 + ) + assert captured.out == "" + assert captured.err.startswith(f"ERROR [{expected_code}]: ") + assert captured.err.count("\n") == 1 + assert "Traceback" not in captured.err + assert "sensitive implementation detail" not in captured.err + assert str(tmp_path) not in captured.err + if parent_exists: + assert list(output.iterdir()) == [output / "keep.txt"] + assert (output / "keep.txt").read_bytes() == b"keep" + assert output.stat().st_mode == mode + else: + assert not output.exists() + assert not list(tmp_path.glob(".evidence.*")) + + +@pytest.mark.parametrize( + ("error", "expected_diagnostic", "expected_exit"), + [ + ( + MemoryError(), + "ERROR [resource.exhausted]: available memory was exhausted; " + "reduce input size and retry\n", + 2, + ), + ( + ResultValidationError("sensitive implementation detail"), + "ERROR [internal.unexpected]: an unexpected internal error occurred; " + "rerun and report the failure if it persists\n", + 3, + ), + ], +) +def test_resource_exhaustion_and_unexpected_failures_are_safely_isolated( + tmp_path: Path, + capsys: pytest.CaptureFixture[str], + error: Exception, + expected_diagnostic: str, + expected_exit: int, +) -> None: + """Boundary failures expose neither traceback nor exception content.""" + output = tmp_path / "evidence" + + def fail(_: ComparisonInvocation) -> ComparisonOutcome: + raise error + + exit_code = main( + [ + "--reference", + "reference.json", + "--query", + "query.json", + "--output", + str(output), + ], + executor=fail, + ) + + captured = capsys.readouterr() + assert exit_code == expected_exit + assert captured.out == "" + assert captured.err == expected_diagnostic + assert "Traceback" not in captured.err + assert "sensitive implementation detail" not in captured.err + assert not output.exists() + + +def test_unexpected_parser_failure_uses_the_internal_error_boundary( + capsys: pytest.CaptureFixture[str], + monkeypatch: pytest.MonkeyPatch, +) -> None: + """Non-argparse failures before execution produce no traceback or details.""" + sensitive_detail = "sensitive parser implementation detail" + + def fail_parser(_: object = None) -> ComparisonInvocation: + raise RuntimeError(sensitive_detail) + + monkeypatch.setattr(cli, "parse_invocation", fail_parser) + + exit_code = main([]) + + captured = capsys.readouterr() + assert exit_code == 3 + assert captured.out == "" + assert captured.err == ( + "ERROR [internal.unexpected]: an unexpected internal error occurred; " + "rerun and report the failure if it persists\n" + ) + assert sensitive_detail not in captured.err + assert "Traceback" not in captured.err + + +@pytest.mark.parametrize("missing_option", ["--reference", "--query", "--output"]) +def test_each_required_argument_is_rejected_before_execution( + missing_option: str, + capsys: pytest.CaptureFixture[str], +) -> None: + """Missing required paths are concise invocation errors and never reach the core.""" + arguments = [ + "--reference", + "reference.csv", + "--query", + "query.csv", + "--output", + "evidence", + ] + option_index = arguments.index(missing_option) + del arguments[option_index : option_index + 2] + + def unexpected_executor(invocation: ComparisonInvocation) -> ComparisonOutcome: + raise AssertionError(f"executor received invalid invocation: {invocation!r}") + + with pytest.raises(SystemExit) as error: + main(arguments, executor=unexpected_executor) + + captured = capsys.readouterr() + assert error.value.code == 2 + assert captured.out == "" + assert captured.err.startswith("ERROR [invocation.invalid_arguments]: ") + assert missing_option in captured.err + assert captured.err.count("\n") == 1 + + +@pytest.mark.parametrize("unsupported", ["compare", "--overwrite"]) +def test_unsupported_arguments_are_rejected_before_execution( + capsys: pytest.CaptureFixture[str], + unsupported: str, +) -> None: + """Unsupported syntax is rejected before comparison execution.""" + arguments = [ + unsupported, + "--reference", + "reference.csv", + "--query", + "query.csv", + "--output", + "evidence", + ] + + def unexpected_executor(invocation: ComparisonInvocation) -> ComparisonOutcome: + raise AssertionError(f"executor received invalid invocation: {invocation!r}") + + with pytest.raises(SystemExit) as error: + main(arguments, executor=unexpected_executor) + + captured = capsys.readouterr() + assert error.value.code == 2 + assert captured.out == "" + assert captured.err == ( + "ERROR [invocation.invalid_arguments]: invalid command-line arguments; " + "use --help for usage\n" + ) + + +def test_invalid_argument_diagnostic_does_not_repeat_argument_text( + capsys: pytest.CaptureFixture[str], +) -> None: + """Unknown argument text cannot disclose an identifier in a diagnostic.""" + sensitive_argument = "patient-identifier-123" + + with pytest.raises(SystemExit) as error: + main( + [ + "--reference", + "reference.csv", + "--query", + "query.csv", + "--output", + "evidence", + sensitive_argument, + ] + ) + + captured = capsys.readouterr() + assert error.value.code == 2 + assert sensitive_argument not in captured.err + assert captured.err == ( + "ERROR [invocation.invalid_arguments]: invalid command-line arguments; " + "use --help for usage\n" + ) + + +def test_help_documents_the_complete_direct_interface_and_user_guide( + capsys: pytest.CaptureFixture[str], +) -> None: + """Help works alone and describes every version 1 command-line option.""" + + def unexpected_executor(invocation: ComparisonInvocation) -> ComparisonOutcome: + raise AssertionError(f"executor was called for help: {invocation!r}") + + with pytest.raises(SystemExit) as error: + main(["--help"], executor=unexpected_executor) + + captured = capsys.readouterr() + assert error.value.code == 0 + assert captured.err == "" + assert "usage: adviso-compare" in captured.out + for option in ( + "--reference", + "--query", + "--output", + "--configuration", + "--help", + "--version", + ): + assert option in captured.out + assert "user guide" in captured.out.lower() + assert "share/doc/adviso-compare/USER_GUIDE.md" in captured.out + assert "subcommand" not in captured.out.lower() + assert "three-file evidence package" in " ".join(captured.out.split()) + assert "--overwrite" not in captured.out + assert "parent" in captured.out.lower() + + +def test_version_works_without_comparison_arguments( + capsys: pytest.CaptureFixture[str], +) -> None: + """Version reporting exits successfully without dispatching a comparison.""" + + def unexpected_executor(invocation: ComparisonInvocation) -> ComparisonOutcome: + raise AssertionError(f"executor was called for version: {invocation!r}") + + with pytest.raises(SystemExit) as error: + main(["--version"], executor=unexpected_executor) + + captured = capsys.readouterr() + assert error.value.code == 0 + assert captured.err == "" + assert captured.out == f"adviso-compare {version('adviso-compare')}\n" + + +@pytest.mark.parametrize("parent_kind", ["relative", "absolute", "root"]) +def test_completion_summary_identifies_the_child_without_absolute_paths( + tmp_path: Path, + capsys: pytest.CaptureFixture[str], + parent_kind: str, +) -> None: + """Summary paths retain parent context without revealing host details.""" + if parent_kind == "relative": + parent = Path("nested") / "evidence" + expected = parent / "selected-run" + elif parent_kind == "absolute": + parent = tmp_path / "evidence" + expected = Path("evidence") / "selected-run" + else: + parent = Path(tmp_path.anchor) + expected = Path("selected-run") + + def execute(invocation: ComparisonInvocation) -> ComparisonOutcome: + assert invocation.output == parent + return ComparisonOutcome( + run_status="complete", + output=parent / "selected-run", + comparison_differences=0, + assessment_issues=0, + ) + + exit_code = main( + ["--reference", "r.csv", "--query", "q.csv", "--output", str(parent)], + executor=execute, + ) + + captured = capsys.readouterr() + assert exit_code == 0 + assert captured.err == "" + assert captured.out.endswith(f"Evidence package: {expected}\n") + assert str(tmp_path) not in captured.out diff --git a/packages/adviso-compare/tests/test_configuration.py b/packages/adviso-compare/tests/test_configuration.py new file mode 100644 index 0000000..b6728aa --- /dev/null +++ b/packages/adviso-compare/tests/test_configuration.py @@ -0,0 +1,668 @@ +"""Behavioural tests for custom comparison-configuration loading.""" + +from __future__ import annotations + +from pathlib import Path +from typing import Callable + +import pytest +import yaml + +from adviso_compare.application import prepare_comparison +from adviso_compare.configuration import ( + ConfigurationError, + load_comparison_configuration, +) +from adviso_compare.inputs import InputSide, ParsedDataset +from adviso_compare.invocation import ComparisonInvocation +from tests.support.documents import JsonObject, minimal_configuration + + +ConfigurationMutation = Callable[[JsonObject], None] + + +def _write_yaml(path: Path, document: JsonObject) -> Path: + """Write a controlled YAML configuration and return its path.""" + path.write_text(yaml.safe_dump(document, sort_keys=False), encoding="utf-8") + return path + + +def _load_document(tmp_path: Path, document: JsonObject): + """Load one mapping through the production YAML boundary.""" + return load_comparison_configuration(_write_yaml(tmp_path / "rules.yaml", document)) + + +def _add_mapping_field(document: JsonObject) -> JsonObject: + """Return a configuration containing one mapped string field.""" + field = document["fields"]["definitions"]["measured_value"] + field["logical_type"] = "string" + field["comparator"] = {"name": "typed_exact"} + field["value_mapping"] = { + "reference": [ + { + "from": {"category": "string", "value": "positive"}, + "to": {"category": "string", "value": "detected"}, + } + ] + } + return document + + +def _add_collection_field(document: JsonObject) -> JsonObject: + """Return a configuration containing one set-valued field.""" + field = document["fields"]["definitions"]["measured_value"] + field["logical_type"] = { + "collection_type": "set", + "element_type": "string", + "element_comparator": {"name": "typed_exact"}, + } + field["comparator"] = {"name": "set_exact"} + field["collection_representation"] = { + "query": { + "format": "delimited_text", + "delimiter": "/", + "element_normalisation": [{"operation": "case_fold"}], + "element_mapping": [ + { + "from": {"category": "string", "value": "wild_type"}, + "to": {"category": "string", "value": "WT"}, + } + ], + } + } + return document + + +def test_valid_configuration_resolves_immutable_defaults_without_altering_document( + tmp_path: Path, +) -> None: + """Resolve omitted processing state without changing the document.""" + original = minimal_configuration() + + configuration = _load_document(tmp_path, original) + + assert configuration.schema_version == "1.0" + assert configuration.metadata.id == "org.example.synthetic-exact-comparison" + assert configuration.record_key == ("record_id",) + assert configuration.in_scope == ("record_id", "measured_value") + measured = configuration.field("measured_value") + assert measured.review_priority == "normal" + assert measured.source_normalisation.reference == () + assert measured.source_normalisation.query == () + assert measured.value_mapping.reference == () + assert measured.value_mapping.query == () + assert measured.typed_normalisation == () + assert measured.null_policy.missing_tokens.reference == () + assert measured.null_policy.missing_tokens.query == () + assert "review_priority" not in configuration.document["fields"]["definitions"][ + "measured_value" + ] + + returned_document = configuration.document + returned_document["metadata"]["id"] = "changed" + assert configuration.document == original + + +def test_collection_representation_resolves_omitted_side_to_json_array( + tmp_path: Path, +) -> None: + """Collection-side defaults are explicit in immutable application state.""" + configuration = _load_document( + tmp_path, _add_collection_field(minimal_configuration()) + ) + + field = configuration.field("measured_value") + representations = field.collection_representation + assert representations is not None + assert representations.reference.format == "json_array" + assert representations.reference.delimiter is None + assert representations.reference.element_normalisation == () + assert representations.query.format == "delimited_text" + assert representations.query.delimiter == "/" + assert representations.query.element_normalisation[0].name == ( + "case_fold" + ) + + +def test_valid_mapping_and_normalisation_declarations_resolve_in_order( + tmp_path: Path, +) -> None: + """A representative scalar adaptor becomes ordered immutable application state.""" + document = _add_mapping_field(minimal_configuration()) + field = document["fields"]["definitions"]["measured_value"] + field["source_normalisation"] = { + "reference": [ + {"operation": "trim", "parameters": {"side": "both"}}, + {"operation": "case_fold"}, + ] + } + field["review_priority"] = "high" + + configuration = _load_document(tmp_path, document) + + resolved = configuration.field("measured_value") + operation_names = tuple( + operation.name for operation in resolved.source_normalisation.reference + ) + assert operation_names == ("trim", "case_fold") + assert resolved.value_mapping.reference[0].source.value == "positive" + assert resolved.value_mapping.reference[0].destination.value == "detected" + assert resolved.value_mapping.query == () + assert resolved.review_priority == "high" + + +def test_yaml_12_core_scalars_do_not_apply_yaml_11_boolean_or_timestamp_rules( + tmp_path: Path, +) -> None: + """Common YAML 1.1 words and dates remain strings under YAML 1.2 rules.""" + text = yaml.safe_dump(minimal_configuration(), sort_keys=False) + text = text.replace( + " revision: 1.0.0\n", + " revision: 1.0.0\n title: yes\n description: 2026-11-06\n", + ) + path = tmp_path / "rules.yaml" + path.write_text(text, encoding="utf-8") + + configuration = load_comparison_configuration(path) + + assert configuration.document["metadata"]["title"] == "yes" + assert configuration.document["metadata"]["description"] == "2026-11-06" + + +def test_yaml_12_leading_zero_integer_is_decimal_not_yaml_11_octal( + tmp_path: Path, +) -> None: + """YAML 1.2 decimal construction is used after implicit scalar resolution.""" + document = minimal_configuration() + field = document["fields"]["definitions"]["measured_value"] + field["typed_normalisation"] = [ + { + "operation": "decimal_quantise", + "parameters": {"places": 1, "rounding": "half_even"}, + } + ] + text = yaml.safe_dump(document, sort_keys=False).replace("places: 1", "places: 01") + path = tmp_path / "rules.yaml" + path.write_text(text, encoding="utf-8") + + configuration = load_comparison_configuration(path) + + operation = configuration.field("measured_value").typed_normalisation[0] + assert operation.parameters == {"places": 1, "rounding": "half_even"} + + +@pytest.mark.parametrize( + "text", + [ + 'schema_version: "1.0"\nschema_version: "1.0"\n', + 'metadata: &metadata\n id: "example"\ncopy: *metadata\n', + 'metadata: !!map {id: "example"}\n', + 'metadata:\n <<: {id: "example"}\n', + '---\nschema_version: "1.0"\n---\nschema_version: "1.0"\n', + 'payload: !!python/object/apply:os.system ["false"]\n', + ], + ids=["duplicate", "anchor-alias", "explicit-tag", "merge", "multiple", "unsafe"], +) +def test_forbidden_yaml_features_are_invalid_syntax( + tmp_path: Path, + text: str, +) -> None: + """The loader rejects ambiguous or executable YAML features before validation.""" + path = tmp_path / "rules.yaml" + path.write_text(text, encoding="utf-8") + + with pytest.raises(ConfigurationError) as raised: + load_comparison_configuration(path) + + assert raised.value.code == "invalid_syntax" + assert raised.value.path == "$" + assert raised.value.diagnostic.startswith( + "ERROR [configuration.invalid_syntax]: $: " + ) + + +def _unknown_source_operation(document: JsonObject) -> None: + document["fields"]["definitions"]["measured_value"][ + "source_normalisation" + ] = {"reference": [{"operation": "invented"}]} + + +def _invalid_numeric_tolerance(document: JsonObject) -> None: + document["fields"]["definitions"]["measured_value"]["comparator"] = { + "name": "numeric_tolerance", + "parameters": { + "absolute_tolerance": "0.1", + "relative_tolerance": "0.1", + }, + } + + +def _null_mapping_source(document: JsonObject) -> None: + field = _add_mapping_field(document)["fields"]["definitions"]["measured_value"] + field["value_mapping"]["reference"][0]["from"] = {"category": "null"} + + +def _preserved_field_with_processing(document: JsonObject) -> None: + field = document["fields"]["definitions"]["measured_value"] + field.pop("logical_type") + field["comparator"] = {"name": "preserved_exact"} + field["source_normalisation"] = { + "reference": [{"operation": "case_fold"}] + } + + +def _collection_with_field_processing(document: JsonObject) -> None: + field = _add_collection_field(document)["fields"]["definitions"][ + "measured_value" + ] + field["source_normalisation"] = { + "reference": [{"operation": "case_fold"}] + } + + +@pytest.mark.parametrize( + ("mutation", "expected_path"), + [ + (lambda document: document.update({"unknown": True}), "$.unknown"), + (lambda document: document["metadata"].pop("revision"), "$.metadata.revision"), + (lambda document: document["metadata"].update({"id": None}), "$.metadata.id"), + ( + lambda document: document["fields"]["definitions"][ + "measured_value" + ].update({"source_normalisation": {}}), + "$.fields.definitions.measured_value.source_normalisation", + ), + ( + lambda document: document["fields"]["definitions"][ + "measured_value" + ].update({"review_priority": "urgent"}), + "$.fields.definitions.measured_value.review_priority", + ), + ( + _unknown_source_operation, + "$.fields.definitions.measured_value.source_normalisation.reference[0]", + ), + ( + _invalid_numeric_tolerance, + "$.fields.definitions.measured_value.comparator", + ), + ( + _null_mapping_source, + "$.fields.definitions.measured_value.value_mapping.reference[0].from", + ), + ( + _preserved_field_with_processing, + "$.fields.definitions.measured_value", + ), + ( + _collection_with_field_processing, + "$.fields.definitions.measured_value", + ), + ], + ids=[ + "unknown", + "required", + "null", + "empty-optional", + "enum", + "unknown-operation", + "tolerance-parameters", + "null-mapping-source", + "preserved-processing", + "collection-field-processing", + ], +) +def test_schema_violations_report_the_relevant_configuration_path( + tmp_path: Path, + mutation: ConfigurationMutation, + expected_path: str, +) -> None: + """Structural failures are distinct and point to the affected property.""" + document = minimal_configuration() + mutation(document) + + with pytest.raises(ConfigurationError) as raised: + _load_document(tmp_path, document) + + assert raised.value.code == "schema_violation" + assert raised.value.path == expected_path + assert expected_path in raised.value.diagnostic + + +def _key_names_unknown(document: JsonObject) -> None: + document["fields"]["record_key"] = ["unknown"] + + +def _scope_name_unknown(document: JsonObject) -> None: + document["fields"]["in_scope"].append("unknown") + + +def _key_not_in_scope(document: JsonObject) -> None: + document["fields"]["in_scope"].remove("record_id") + + +def _key_not_required(document: JsonObject) -> None: + document["fields"]["definitions"]["record_id"]["required"]["query"] = False + + +def _key_allows_null(document: JsonObject) -> None: + field = document["fields"]["definitions"]["record_id"] + field["null_policy"] = {"allowed": True, "nulls_equal": True} + + +def _key_is_collection(document: JsonObject) -> None: + field = document["fields"]["definitions"]["record_id"] + field["logical_type"] = { + "collection_type": "set", + "element_type": "string", + "element_comparator": {"name": "typed_exact"}, + } + field["comparator"] = {"name": "set_exact"} + + +def _key_comparator_not_typed_exact(document: JsonObject) -> None: + field = document["fields"]["definitions"]["record_id"] + field["logical_type"] = "integer" + field["comparator"] = {"name": "numeric_exact"} + + +def _incompatible_comparator(document: JsonObject) -> None: + document["fields"]["definitions"]["measured_value"]["comparator"] = { + "name": "date_exact" + } + + +def _incompatible_normalisation(document: JsonObject) -> None: + document["fields"]["definitions"]["measured_value"][ + "typed_normalisation" + ] = [ + { + "operation": "datetime_truncate", + "parameters": {"precision": "second"}, + } + ] + + +def _normalised_string_without_operation(document: JsonObject) -> None: + field = document["fields"]["definitions"]["measured_value"] + field["logical_type"] = "string" + field["comparator"] = {"name": "normalised_string"} + + +def _duplicate_reference_source(document: JsonObject) -> None: + fields = document["fields"]["definitions"] + fields["measured_value"]["source_fields"]["reference"] = "reference_id" + + +def _duplicate_query_source(document: JsonObject) -> None: + fields = document["fields"]["definitions"] + fields["measured_value"]["source_fields"]["query"] = "query_id" + + +def _reserved_identifier(document: JsonObject) -> None: + document["metadata"]["id"] = "adviso-compare:automatic-strict-exact" + + +def _duplicate_mapping_source(document: JsonObject) -> None: + field = _add_mapping_field(document)["fields"]["definitions"]["measured_value"] + field["value_mapping"]["reference"].append( + { + "from": {"category": "string", "value": "positive"}, + "to": {"category": "string", "value": "present"}, + } + ) + + +def _mapping_sources_collide_after_normalisation(document: JsonObject) -> None: + field = _add_mapping_field(document)["fields"]["definitions"]["measured_value"] + field["value_mapping"]["reference"][0]["from"]["value"] = " É " + field["source_normalisation"] = { + "reference": [ + {"operation": "unicode_normalise", "parameters": {"form": "NFC"}}, + {"operation": "trim", "parameters": {"side": "both"}}, + {"operation": "case_fold"}, + ] + } + field["value_mapping"]["reference"].append( + { + "from": {"category": "string", "value": "e\u0301"}, + "to": {"category": "string", "value": "present"}, + } + ) + + +def _numeric_mapping_sources_are_equal(document: JsonObject) -> None: + field = document["fields"]["definitions"]["measured_value"] + field["value_mapping"] = { + "reference": [ + { + "from": {"category": "decimal", "value": "1.0"}, + "to": {"category": "decimal", "value": "1.0"}, + }, + { + "from": {"category": "decimal", "value": "1.00"}, + "to": {"category": "decimal", "value": "2.0"}, + }, + ] + } + + +def _mapping_source_is_missing_token(document: JsonObject) -> None: + field = _add_mapping_field(document)["fields"]["definitions"]["measured_value"] + field["null_policy"] = { + "allowed": True, + "nulls_equal": True, + "missing_tokens": { + "reference": [{"category": "string", "value": "positive"}] + }, + } + + +def _element_mapping_sources_collide(document: JsonObject) -> None: + field = _add_collection_field(document)["fields"]["definitions"][ + "measured_value" + ] + field["collection_representation"]["query"]["element_mapping"].append( + { + "from": {"category": "string", "value": "WILD_TYPE"}, + "to": {"category": "string", "value": "wild"}, + } + ) + + +@pytest.mark.parametrize( + ("mutation", "expected_path", "expected_reason"), + [ + ( + _key_names_unknown, + "$.fields.record_key[0]", + "record-key field has no field definition", + ), + ( + _scope_name_unknown, + "$.fields.in_scope[2]", + "in-scope field has no field definition", + ), + ( + _key_not_in_scope, + "$.fields.record_key[0]", + "record-key field is not included in fields.in_scope", + ), + ( + _key_not_required, + "$.fields.definitions.record_id.required.query", + "record-key field must be required on both sides", + ), + ( + _key_allows_null, + "$.fields.definitions.record_id.null_policy.allowed", + "record-key field must not allow null", + ), + ( + _key_is_collection, + "$.fields.definitions.record_id.logical_type", + "record-key field must have a scalar logical type", + ), + ( + _key_comparator_not_typed_exact, + "$.fields.definitions.record_id.comparator.name", + "record-key field must use typed_exact", + ), + ( + _incompatible_comparator, + "$.fields.definitions.measured_value.comparator.name", + "comparator is incompatible with the field logical type", + ), + ( + _incompatible_normalisation, + "$.fields.definitions.measured_value.typed_normalisation[0].operation", + "typed normalisation is incompatible with the field logical type", + ), + ( + _normalised_string_without_operation, + "$.fields.definitions.measured_value.comparator.name", + "normalised_string requires a configured string normalisation", + ), + ( + _duplicate_reference_source, + "$.fields.definitions.measured_value.source_fields.reference", + "source field is already used by canonical field", + ), + ( + _duplicate_query_source, + "$.fields.definitions.measured_value.source_fields.query", + "source field is already used by canonical field", + ), + ( + _reserved_identifier, + "$.metadata.id", + "identifier is reserved for automatically generated configurations", + ), + ( + _duplicate_mapping_source, + "$.fields.definitions.measured_value.value_mapping.reference[1].from", + "mapping source duplicates another source after normalisation", + ), + ( + _mapping_sources_collide_after_normalisation, + "$.fields.definitions.measured_value.value_mapping.reference[1].from", + "mapping source duplicates another source after normalisation", + ), + ( + _numeric_mapping_sources_are_equal, + "$.fields.definitions.measured_value.value_mapping.reference[1].from", + "mapping source duplicates another source after normalisation", + ), + ( + _mapping_source_is_missing_token, + "$.fields.definitions.measured_value.value_mapping.reference[0].from", + "mapping source is unreachable because it is a missing token", + ), + ( + _element_mapping_sources_collide, + "$.fields.definitions.measured_value.collection_representation.query." + "element_mapping[1].from", + "element mapping source duplicates another source after normalisation", + ), + ], + ids=[ + "key-reference", + "scope-reference", + "key-scope", + "key-contract", + "key-null", + "key-collection", + "key-comparator", + "comparator-type", + "normalisation-type", + "normalised-string", + "source-reuse", + "source-reuse-query", + "reserved-id", + "mapping-duplicate", + "mapping-normalised-duplicate", + "mapping-numeric-duplicate", + "mapping-unreachable", + "element-mapping-normalised-duplicate", + ], +) +def test_semantic_violations_report_the_specific_configuration_path( + tmp_path: Path, + mutation: ConfigurationMutation, + expected_path: str, + expected_reason: str, +) -> None: + """Cross-property failures are detected only after structural validation.""" + document = minimal_configuration() + mutation(document) + + with pytest.raises(ConfigurationError) as raised: + _load_document(tmp_path, document) + + assert raised.value.code == "semantic_violation" + assert raised.value.path == expected_path + assert expected_reason in raised.value.message + assert expected_path in raised.value.diagnostic + assert expected_reason in raised.value.diagnostic + + +def test_unsupported_version_and_unreadable_file_have_distinct_errors( + tmp_path: Path, +) -> None: + """Version negotiation and filesystem access retain their taxonomy.""" + unsupported = minimal_configuration() + unsupported["schema_version"] = "2.0" + + with pytest.raises(ConfigurationError) as version_error: + _load_document(tmp_path, unsupported) + with pytest.raises(ConfigurationError) as read_error: + load_comparison_configuration(tmp_path / "missing.yaml") + + assert version_error.value.code == "unsupported_version" + assert version_error.value.path == "$.schema_version" + assert read_error.value.code == "unreadable" + assert read_error.value.path == "$" + assert str(tmp_path) not in read_error.value.diagnostic + + +def test_invalid_utf8_and_non_mapping_root_are_classified_separately( + tmp_path: Path, +) -> None: + """Byte/YAML failures precede schema validation of a parsed root value.""" + invalid_utf8 = tmp_path / "encoding.yaml" + invalid_utf8.write_bytes(b"\xff") + sequence_root = tmp_path / "sequence.yaml" + sequence_root.write_text("- item\n", encoding="utf-8") + + with pytest.raises(ConfigurationError) as encoding_error: + load_comparison_configuration(invalid_utf8) + with pytest.raises(ConfigurationError) as root_error: + load_comparison_configuration(sequence_root) + + assert encoding_error.value.code == "invalid_syntax" + assert root_error.value.code == "schema_violation" + assert root_error.value.path == "$" + + +def test_custom_configuration_failure_precedes_all_dataset_access( + tmp_path: Path, +) -> None: + """Orchestration cannot inspect an input before custom rules are trustworthy.""" + document = minimal_configuration() + _reserved_identifier(document) + configuration_path = _write_yaml(tmp_path / "invalid.yaml", document) + invocation = ComparisonInvocation( + reference=tmp_path / "missing-reference.csv", + query=tmp_path / "missing-query.json", + output=tmp_path / "evidence", + configuration=configuration_path, + ) + + def unexpected_dataset_loader(path: Path, side: InputSide) -> ParsedDataset: + raise AssertionError(f"dataset loader accessed {side.value}: {path!r}") + + with pytest.raises(ConfigurationError) as raised: + prepare_comparison(invocation, dataset_loader=unexpected_dataset_loader) + + assert raised.value.code == "semantic_violation" + assert raised.value.path == "$.metadata.id" diff --git a/packages/adviso-compare/tests/test_contract.py b/packages/adviso-compare/tests/test_contract.py new file mode 100644 index 0000000..a95c3b3 --- /dev/null +++ b/packages/adviso-compare/tests/test_contract.py @@ -0,0 +1,444 @@ +"""Behavioural tests for contract assessment and exclusions.""" + +from __future__ import annotations + +from pathlib import Path + +import yaml + +from adviso_compare.application import PreparedComparison, prepare_comparison +from adviso_compare.contract import ( + ConfiguredFieldExclusion, + ContractPhaseStatus, + ContractResult, + UndeclaredFieldExclusion, + assess_contract, +) +from adviso_compare.inputs import InputSide +from adviso_compare.invocation import ComparisonInvocation +from adviso_compare.translation import ValueDisposition +from tests.support.documents import JsonObject, minimal_configuration + + +def _write(path: Path, text: str) -> Path: + """Write one controlled UTF-8 document.""" + path.write_text(text, encoding="utf-8") + return path + + +def _field( + reference_name: str, + query_name: str, + *, + logical_type: str = "decimal", + required_reference: bool = True, + required_query: bool = True, + review_priority: str | None = None, +) -> JsonObject: + """Create one typed field declaration for a contract fixture.""" + field: JsonObject = { + "source_fields": { + "reference": reference_name, + "query": query_name, + }, + "required": { + "reference": required_reference, + "query": required_query, + }, + "logical_type": logical_type, + "null_policy": {"allowed": False, "nulls_equal": False}, + "comparator": {"name": "typed_exact"}, + } + if review_priority is not None: + field["review_priority"] = review_priority + return field + + +def _mixed_configuration() -> JsonObject: + """Declare every contract outcome alongside unaffected and excluded fields.""" + document = minimal_configuration() + fields = document["fields"] + definitions = fields["definitions"] + fields["in_scope"] = [ + "record_id", + "measured_value", + "required_field", + "typed_field", + "invalid_field", + "null_field", + "mapped_field", + "optional_field", + ] + definitions["required_field"] = _field( + "required_reference", + "required_query", + review_priority="high", + ) + definitions["typed_field"] = _field( + "typed_reference", + "typed_query", + review_priority="low", + ) + definitions["invalid_field"] = _field( + "invalid_reference", + "invalid_query", + ) + definitions["null_field"] = _field( + "null_reference", + "null_query", + review_priority="high", + ) + definitions["mapped_field"] = _field( + "mapped_reference", + "mapped_query", + logical_type="string", + review_priority="low", + ) + definitions["mapped_field"]["value_mapping"] = { + "reference": [ + { + "from": {"category": "string", "value": "known"}, + "to": {"category": "string", "value": "canonical"}, + } + ], + "query": [ + { + "from": {"category": "string", "value": "known"}, + "to": {"category": "string", "value": "canonical"}, + } + ], + } + definitions["optional_field"] = _field( + "optional_reference", + "optional_query", + required_reference=False, + required_query=False, + ) + definitions["excluded_field"] = _field( + "excluded_reference", + "excluded_query", + ) + return document + + +def _prepare_mixed_comparison(tmp_path: Path) -> PreparedComparison: + """Create two aligned heterogeneous datasets with independent defects.""" + reference = _write( + tmp_path / "reference.json", + ( + '[{"reference_id":"S1","expected_value":1,' + '"required_reference":1,"typed_reference":true,' + '"invalid_reference":"NaN","null_reference":1,' + '"mapped_reference":"unknown","excluded_reference":1,' + '"common_extra":"r1","reference_extra":"only"},' + '{"reference_id":"S2","expected_value":2,' + '"required_reference":2,"typed_reference":2,' + '"invalid_reference":"2","null_reference":2,' + '"mapped_reference":"known","excluded_reference":2,' + '"common_extra":"r2"}]' + ), + ) + query = _write( + tmp_path / "query.json", + ( + '[{"query_id":"S1","observed_value":1,' + '"typed_query":[],"invalid_query":"1",' + '"null_query":null,"mapped_query":"known",' + '"excluded_query":1,"common_extra":"q1",' + '"query_extra":"first"},' + '{"query_id":"S2","observed_value":2,' + '"required_query":2,"typed_query":2,"invalid_query":"2",' + '"null_query":2,"mapped_query":"known","excluded_query":2,' + '"query_extra":"second"}]' + ), + ) + configuration = _write( + tmp_path / "configuration.yaml", + yaml.safe_dump(_mixed_configuration(), sort_keys=False), + ) + return prepare_comparison( + ComparisonInvocation( + reference=reference, + query=query, + output=tmp_path / "evidence", + configuration=configuration, + ) + ) + + +def _assess(prepared: PreparedComparison) -> ContractResult: + """Pass a prepared comparison's domain inputs to the contract boundary.""" + return assess_contract( + prepared.configuration, + reference=prepared.reference, + query=prepared.query, + reference_records=prepared.reference_records, + query_records=prepared.query_records, + ) + + +def test_mixed_contract_collects_every_causal_finding_and_continues( + tmp_path: Path, +) -> None: + """Independent defects block only their values and retain valid assessments.""" + prepared = _prepare_mixed_comparison(tmp_path) + + result = _assess(prepared) + + assert result.status is ContractPhaseStatus.COMPLETE + observed = [ + ( + finding.code, + finding.side, + finding.canonical_field, + finding.review_priority, + finding.record.canonical_identity if finding.record else None, + ) + for finding in result.findings + ] + assert observed == [ + ( + "invalid_field_value", + InputSide.REFERENCE, + "invalid_field", + "normal", + ("S1",), + ), + ("mapping_failure", InputSide.REFERENCE, "mapped_field", "low", ("S1",)), + ("null_policy_violation", InputSide.QUERY, "null_field", "high", ("S1",)), + ("missing_required_field", InputSide.QUERY, "required_field", "high", ("S1",)), + ("type_mismatch", InputSide.REFERENCE, "typed_field", "low", ("S1",)), + ("type_mismatch", InputSide.QUERY, "typed_field", "low", ("S1",)), + ] + assert all( + finding.classification == "assessment_issue" for finding in result.findings + ) + assert all(finding.phase == "contract" for finding in result.findings) + assert all(finding.location is not None for finding in result.findings) + + key = prepared.reference_records.records[0].key + assert result.assessment(InputSide.REFERENCE, key, "invalid_field").disposition is ( + ValueDisposition.NOT_ASSESSABLE + ) + assert result.assessment(InputSide.QUERY, key, "required_field").disposition is ( + ValueDisposition.NOT_ASSESSABLE + ) + measured = result.assessment(InputSide.REFERENCE, key, "measured_value") + assert measured.disposition is ValueDisposition.VALID + second_key = prepared.reference_records.records[1].key + mapped = result.assessment(InputSide.REFERENCE, second_key, "mapped_field") + optional = result.assessment(InputSide.QUERY, second_key, "optional_field") + assert mapped.disposition is ValueDisposition.VALID + assert optional.disposition is ValueDisposition.ABSENT + + assessment_identities = [ + ( + assessment.side, + assessment.record.canonical_identity, + assessment.canonical_field, + ) + for assessment in result.assessments + ] + assert len(assessment_identities) == 32 + assert len(set(assessment_identities)) == 32 + + blocked = { + ( + assessment.side, + assessment.record.key, + assessment.canonical_field, + ) + for assessment in result.assessments + if assessment.disposition is ValueDisposition.NOT_ASSESSABLE + } + causal_findings = { + (finding.side, finding.record.key, finding.canonical_field) + for finding in result.findings + if finding.record is not None + } + assert blocked == causal_findings + assert len(blocked) == len(result.findings) == 6 + + unaffected = [ + assessment + for assessment in result.assessments + if assessment.record.canonical_identity == ("S2",) + ] + assert len(unaffected) == 16 + assert {assessment.disposition for assessment in unaffected} == { + ValueDisposition.VALID, + ValueDisposition.ABSENT, + } + + +def test_contract_consolidates_configured_and_undeclared_exclusions( + tmp_path: Path, +) -> None: + """Out-of-scope fields produce ordered summaries rather than per-record findings.""" + prepared = _prepare_mixed_comparison(tmp_path) + + result = _assess(prepared) + + assert result.exclusions == ( + ConfiguredFieldExclusion(canonical_field="excluded_field"), + UndeclaredFieldExclusion( + side=InputSide.REFERENCE, + source_field="common_extra", + record_count=2, + ), + UndeclaredFieldExclusion( + side=InputSide.REFERENCE, + source_field="reference_extra", + record_count=1, + ), + UndeclaredFieldExclusion( + side=InputSide.QUERY, + source_field="common_extra", + record_count=1, + ), + UndeclaredFieldExclusion( + side=InputSide.QUERY, + source_field="query_extra", + record_count=2, + ), + ) + assert all( + assessment.canonical_field != "excluded_field" + for assessment in result.assessments + ) + assert len(result.findings) == 6 + + +def test_zero_record_headers_support_dataset_contract_checks_and_zero_counts( + tmp_path: Path, +) -> None: + """Tabular structure remains assessable without inventing record opportunities.""" + document = minimal_configuration() + document["fields"]["definitions"]["header_only_excluded"] = _field( + "excluded_reference", + "excluded_query", + ) + reference = _write( + tmp_path / "reference.csv", + "reference_id,header_extra\n", + ) + query = _write( + tmp_path / "query.tsv", + "query_id\tobserved_value\tquery_extra\n", + ) + configuration = _write( + tmp_path / "configuration.yaml", + yaml.safe_dump(document, sort_keys=False), + ) + prepared = prepare_comparison( + ComparisonInvocation( + reference=reference, + query=query, + output=tmp_path / "evidence", + configuration=configuration, + ) + ) + + result = _assess(prepared) + + assert result.status is ContractPhaseStatus.COMPLETE + assert result.assessments == () + assert [ + (finding.code, finding.side, finding.canonical_field, finding.record) + for finding in result.findings + ] == [ + ("missing_required_field", InputSide.REFERENCE, "measured_value", None), + ] + assert result.findings[0].location is None + assert result.exclusions == ( + ConfiguredFieldExclusion(canonical_field="header_only_excluded"), + UndeclaredFieldExclusion( + side=InputSide.REFERENCE, + source_field="header_extra", + record_count=0, + ), + UndeclaredFieldExclusion( + side=InputSide.QUERY, + source_field="query_extra", + record_count=0, + ), + ) + + +def test_empty_json_exposes_no_structure_for_dataset_missing_field_findings( + tmp_path: Path, +) -> None: + """Custom configuration permits empty JSON without inferring field absence.""" + reference = _write(tmp_path / "reference.json", "[]") + query = _write(tmp_path / "query.json", "[]") + configuration = _write( + tmp_path / "configuration.yaml", + yaml.safe_dump(minimal_configuration(), sort_keys=False), + ) + prepared = prepare_comparison( + ComparisonInvocation( + reference=reference, + query=query, + output=tmp_path / "evidence", + configuration=configuration, + ) + ) + + result = _assess(prepared) + + assert result.status is ContractPhaseStatus.COMPLETE + assert result.assessments == () + assert result.findings == () + assert result.exclusions == () + + +def test_automatic_configuration_drives_contract_assessment_and_exclusions( + tmp_path: Path, +) -> None: + """Generated correspondence assesses common fields and excludes side-only ones.""" + reference = _write( + tmp_path / "reference.json", + '[{"record_id":"S1","shared":1,"reference_only":"context"}]', + ) + query = _write( + tmp_path / "query.json", + '[{"record_id":"S1","shared":1,"query_only":"context"}]', + ) + prepared = prepare_comparison( + ComparisonInvocation( + reference=reference, + query=query, + output=tmp_path / "evidence", + ) + ) + + result = _assess(prepared) + + assert result.status is ContractPhaseStatus.COMPLETE + assert result.findings == () + assert [ + ( + assessment.side, + assessment.record.canonical_identity, + assessment.canonical_field, + assessment.disposition, + ) + for assessment in result.assessments + ] == [ + (InputSide.REFERENCE, ("S1",), "record_id", ValueDisposition.VALID), + (InputSide.REFERENCE, ("S1",), "shared", ValueDisposition.VALID), + (InputSide.QUERY, ("S1",), "record_id", ValueDisposition.VALID), + (InputSide.QUERY, ("S1",), "shared", ValueDisposition.VALID), + ] + assert result.exclusions == ( + UndeclaredFieldExclusion( + side=InputSide.REFERENCE, + source_field="reference_only", + record_count=1, + ), + UndeclaredFieldExclusion( + side=InputSide.QUERY, + source_field="query_only", + record_count=1, + ), + ) diff --git a/packages/adviso-compare/tests/test_distribution.py b/packages/adviso-compare/tests/test_distribution.py new file mode 100644 index 0000000..69be490 --- /dev/null +++ b/packages/adviso-compare/tests/test_distribution.py @@ -0,0 +1,379 @@ +"""Built-distribution and installed-product checks.""" + +from __future__ import annotations + +import json +import os +import subprocess +import sys +import tarfile +import venv +import zipfile +from email.parser import BytesParser +from pathlib import Path + +import pytest + +from tests.support.documents import minimal_configuration +from tests.support.evidence import assert_run_package + +REQUIRED_PACKAGE_MEMBERS = { + "adviso_compare/__init__.py", + "adviso_compare/schemas/__init__.py", + "adviso_compare/schemas/comparison-configuration-v1.0.schema.json", + "adviso_compare/schemas/comparison-results-v1.0.schema.json", +} + +REQUIRED_DOCUMENTATION_MEMBERS = { + "share/doc/adviso-compare/USER_GUIDE.md", + "share/doc/adviso-compare/examples/automatic/query.csv", + "share/doc/adviso-compare/examples/automatic/reference.csv", + "share/doc/adviso-compare/examples/custom/configuration.yaml", + "share/doc/adviso-compare/examples/custom/query.csv", + "share/doc/adviso-compare/examples/custom/reference.json", +} + + +def _relative_sdist_members(archive: Path) -> set[str]: + """Return source-distribution members without its generated root directory.""" + with tarfile.open(archive, mode="r:gz") as distribution: + members = {member.name for member in distribution.getmembers()} + + roots = {member.partition("/")[0] for member in members} + assert len(roots) == 1 + root = roots.pop() + return { + member.removeprefix(f"{root}/") + for member in members + if member != root + } + + +def _installed_python(environment: Path) -> Path: + """Return the Python executable created by ``venv`` on this platform.""" + executable = "python.exe" if sys.platform == "win32" else "python" + return environment / ("Scripts" if sys.platform == "win32" else "bin") / executable + + +def _installed_executable(environment: Path) -> Path: + """Return the installed adviso-compare command on this platform.""" + executable = ( + "adviso-compare.exe" if sys.platform == "win32" else "adviso-compare" + ) + scripts = "Scripts" if sys.platform == "win32" else "bin" + return environment / scripts / executable + + +@pytest.fixture(scope="module") +def built_distributions( + tmp_path_factory: pytest.TempPathFactory, +) -> tuple[Path, Path]: + """Build both archives once, retaining them with the test-run evidence.""" + project_root = Path(__file__).resolve().parents[1] + output = tmp_path_factory.getbasetemp() / "distributions" + subprocess.run( + [ + sys.executable, + "-m", + "build", + "--no-isolation", + "--outdir", + str(output), + str(project_root), + ], + check=True, + capture_output=True, + text=True, + ) + return next(output.glob("*.whl")), next(output.glob("*.tar.gz")) + + +@pytest.mark.parametrize("archive_format", ["wheel", "sdist"]) +def test_distributions_and_installed_executable_cover_the_product_path( + tmp_path: Path, + monkeypatch: pytest.MonkeyPatch, + built_distributions: tuple[Path, Path], + archive_format: str, +) -> None: + """Clean installations carry resources and run the complete product path.""" + project_root = Path(__file__).resolve().parents[1] + wheel, source_distribution = built_distributions + # Commands run outside the checkout without borrowed development packages. + monkeypatch.chdir(tmp_path) + runtime_environment = os.environ.copy() + runtime_environment.pop("PYTHONPATH", None) + runtime_environment.pop("PYTHONHOME", None) + + with zipfile.ZipFile(wheel) as distribution: + wheel_members = set(distribution.namelist()) + metadata_member = next( + member + for member in wheel_members + if member.endswith(".dist-info/METADATA") + ) + metadata = BytesParser().parsebytes(distribution.read(metadata_member)) + record_member = next( + member for member in wheel_members if member.endswith(".dist-info/RECORD") + ) + assert distribution.read(record_member) + sdist_members = _relative_sdist_members(source_distribution) + + assert metadata["Name"] == "adviso-compare" + assert metadata["Requires-Python"] == ">=3.11" + assert REQUIRED_PACKAGE_MEMBERS <= wheel_members + assert all( + any(member.endswith(path) for member in wheel_members) + for path in REQUIRED_DOCUMENTATION_MEMBERS + ) + assert { + f"src/{member}" for member in REQUIRED_PACKAGE_MEMBERS + } <= sdist_members + assert { + "docs/USER_GUIDE.md", + "docs/examples/automatic/query.csv", + "docs/examples/automatic/reference.csv", + "docs/examples/custom/configuration.yaml", + "docs/examples/custom/query.csv", + "docs/examples/custom/reference.json", + } <= sdist_members + + environment = tmp_path / "installed" + venv.EnvBuilder(with_pip=True).create(environment) + installed_python = _installed_python(environment) + subprocess.run( + [ + str(installed_python), + "-m", + "pip", + "install", + "--disable-pip-version-check", + str(wheel if archive_format == "wheel" else source_distribution), + ], + check=True, + capture_output=True, + text=True, + env=runtime_environment, + ) + subprocess.run( + [str(installed_python), "-m", "pip", "check"], + check=True, + capture_output=True, + text=True, + env=runtime_environment, + ) + dependencies = subprocess.run( + [str(installed_python), "-m", "pip", "list", "--format=freeze"], + check=True, + capture_output=True, + text=True, + env=runtime_environment, + ) + (wheel.parent / f"{archive_format}-dependencies.txt").write_text( + dependencies.stdout, encoding="utf-8" + ) + resource_check = ( + "import json; " + "from importlib.resources import files; " + "root = files('adviso_compare.schemas'); " + "names = ['comparison-configuration-v1.0.schema.json', " + "'comparison-results-v1.0.schema.json']; " + "assert all(json.loads(root.joinpath(name).read_text(encoding='utf-8')) " + "for name in names)" + ) + subprocess.run( + [str(installed_python), "-c", resource_check], + check=True, + capture_output=True, + text=True, + env=runtime_environment, + ) + installed_guide = ( + environment / "share" / "doc" / "adviso-compare" / "USER_GUIDE.md" + ) + assert installed_guide.is_file() + assert "# `adviso-compare` user guide" in installed_guide.read_text( + encoding="utf-8" + ) + assert installed_guide.read_bytes() == ( + project_root / "docs" / "USER_GUIDE.md" + ).read_bytes() + + executable = _installed_executable(environment) + installed_location_check = ( + "from pathlib import Path; import adviso_compare, jsonschema, yaml; " + "assert all(Path(module.__file__).is_relative_to(" + f"Path({str(environment)!r})) " + "for module in (adviso_compare, jsonschema, yaml))" + ) + subprocess.run( + [str(installed_python), "-c", installed_location_check], + check=True, + capture_output=True, + text=True, + env=runtime_environment, + ) + version = subprocess.run( + [str(executable), "--version"], + check=True, + capture_output=True, + text=True, + env=runtime_environment, + ) + assert version.stdout.strip() == f"adviso-compare {metadata['Version']}" + for member in REQUIRED_DOCUMENTATION_MEMBERS: + relative = member.removeprefix("share/doc/adviso-compare/") + assert (environment / member).read_bytes() == ( + project_root / "docs" / relative + ).read_bytes() + + automatic = tmp_path / "automatic" + automatic.mkdir() + automatic_reference = automatic / "reference.json" + automatic_query = automatic / "query.json" + automatic_output = automatic / "evidence" + automatic_reference.write_text( + '[{"record_id":"S1","result":1}]', + encoding="utf-8", + ) + automatic_query.write_text( + '[{"record_id":"S1","result":2}]', + encoding="utf-8", + ) + completed = subprocess.run( + [ + str(executable), + "--reference", + str(automatic_reference), + "--query", + str(automatic_query), + "--output", + str(automatic_output), + ], + check=False, + capture_output=True, + text=True, + env=runtime_environment, + ) + assert completed.returncode == 0 + assert completed.stderr == "" + assert "Run status: complete\n" in completed.stdout + assert str(tmp_path) not in completed.stdout + automatic_package = assert_run_package(automatic_output) + saved_automatic = json.loads( + (automatic_package / "comparison-configuration.json").read_text( + encoding="utf-8" + ) + ) + assert saved_automatic["metadata"]["id"] == ( + "adviso-compare:automatic-strict-exact" + ) + displayed = Path(automatic_output.name) / automatic_package.name + assert f"Evidence package: {displayed}\n" in completed.stdout + original_bytes = { + member.name: member.read_bytes() + for member in automatic_package.iterdir() + } + repeated = subprocess.run( + completed.args, + check=False, + capture_output=True, + text=True, + env=runtime_environment, + ) + assert repeated.returncode == 0 + assert repeated.stderr == "" + additional = set(automatic_output.iterdir()) - {automatic_package} + assert len(additional) == 1 + repeated_package = assert_run_package(automatic_output, additional.pop()) + displayed = Path(automatic_output.name) / repeated_package.name + assert f"Evidence package: {displayed}\n" in repeated.stdout + assert str(tmp_path) not in repeated.stdout + assert { + member.name: member.read_bytes() + for member in automatic_package.iterdir() + } == original_bytes + + custom = tmp_path / "custom" + custom.mkdir() + custom_reference = custom / "reference.json" + custom_query = custom / "query.json" + custom_configuration = custom / "configuration.yaml" + custom_output = custom / "evidence" + custom_reference.write_text( + '[{"reference_id":"S1","expected_value":1}]', + encoding="utf-8", + ) + custom_query.write_text('[{"query_id":"S1"}]', encoding="utf-8") + custom_configuration.write_text( + json.dumps(minimal_configuration()), + encoding="utf-8", + ) + incomplete = subprocess.run( + [ + str(executable), + "--reference", + str(custom_reference), + "--query", + str(custom_query), + "--output", + str(custom_output), + "--configuration", + str(custom_configuration), + ], + check=False, + capture_output=True, + text=True, + env=runtime_environment, + ) + assert incomplete.returncode == 1 + assert incomplete.stderr == "" + assert "Run status: incomplete\n" in incomplete.stdout + assert str(tmp_path) not in incomplete.stdout + custom_package = assert_run_package(custom_output) + assert json.loads( + (custom_package / "comparison-configuration.json").read_text( + encoding="utf-8" + ) + ) == minimal_configuration() + assert ( + f"Evidence package: {Path(custom_output.name) / custom_package.name}\n" + in incomplete.stdout + ) + + failed_output = tmp_path / "failed-evidence" + failed = subprocess.run( + [ + str(executable), + "--reference", + str(tmp_path / "missing.json"), + "--query", + str(automatic_query), + "--output", + str(failed_output), + ], + check=False, + capture_output=True, + text=True, + env=runtime_environment, + ) + assert failed.returncode == 2 + assert failed.stdout == "" + assert failed.stderr == ( + "ERROR [input.unreadable]: reference input could not be read\n" + ) + assert not failed_output.exists() + + for package in (automatic_package, repeated_package, custom_package): + subprocess.run( + [ + str(installed_python), + "-c", + "from pathlib import Path; " + "from adviso_compare.reporting import validate_evidence_package; " + f"validate_evidence_package(Path({str(package)!r}))", + ], + check=True, + capture_output=True, + text=True, + env=runtime_environment, + ) diff --git a/packages/adviso-compare/tests/test_documentation.py b/packages/adviso-compare/tests/test_documentation.py new file mode 100644 index 0000000..b64b6ea --- /dev/null +++ b/packages/adviso-compare/tests/test_documentation.py @@ -0,0 +1,145 @@ +"""Checks for the runnable, maintained user-guide examples.""" + +from __future__ import annotations + +import json +import re +import shutil +import subprocess +import sys +from pathlib import Path + +import pytest +import yaml + +from adviso_compare.application import execute_comparison +from adviso_compare.configuration import load_comparison_configuration +from adviso_compare.invocation import ComparisonInvocation +from tests.support.documents import minimal_configuration +from tests.support.evidence import assert_run_package +from tests.support.schemas import configuration_validator, results_validator + + +PROJECT_ROOT = Path(__file__).resolve().parents[1] +EXAMPLES = PROJECT_ROOT / "docs" / "examples" + + +@pytest.mark.parametrize( + ("example", "reference_name", "query_name", "configuration_name"), + [ + ("automatic", "reference.csv", "query.csv", None), + ("introductory", "reference.csv", "query.csv", "configuration.yaml"), + ("custom", "reference.json", "query.csv", "configuration.yaml"), + ], +) +def test_user_guide_examples_run_with_the_documented_outcome( + tmp_path: Path, + example: str, + reference_name: str, + query_name: str, + configuration_name: str | None, +) -> None: + """Each guide example is runnable and produces schema-valid evidence.""" + guide = (PROJECT_ROOT / "docs" / "USER_GUIDE.md").read_text( + encoding="utf-8" + ) + working = tmp_path / example + if example == "introductory": + assert configuration_name is not None + working.mkdir() + tutorial = guide.split(" A small custom comparison\n", 1)[1] + tutorial = tutorial.split("\n### ", 1)[0] + inputs = re.findall(r"```csv\n(.*?)\n```", tutorial, re.S) + configurations = re.findall(r"```yaml\n(.*?)\n```", tutorial, re.S) + assert len(inputs) == 2 + assert len(configurations) == 1 + for name, content in zip( + (reference_name, query_name, configuration_name), + (*inputs, configurations[0]), + ): + (working / name).write_text(content + "\n", encoding="utf-8") + else: + shutil.copytree(EXAMPLES / example, working) + configuration = ( + working / configuration_name if configuration_name is not None else None + ) + if configuration is not None: + document = yaml.safe_load(configuration.read_text(encoding="utf-8")) + configuration_validator().validate(document) + + outcome = execute_comparison( + ComparisonInvocation( + reference=working / reference_name, + query=working / query_name, + output=working / "evidence", + configuration=configuration, + ) + ) + selected = assert_run_package(working / "evidence", outcome.output) + result = json.loads( + (selected / "comparison-results.json").read_text( + encoding="utf-8" + ) + ) + + results_validator().validate(result) + saved = json.loads( + (selected / "comparison-configuration.json").read_text( + encoding="utf-8" + ) + ) + if configuration is not None: + assert saved == document + else: + assert saved["metadata"]["id"] == "adviso-compare:automatic-strict-exact" + assert outcome.run_status == "complete" + assert outcome.comparison_differences == 1 + assert outcome.assessment_issues == 0 + assert outcome.exit_code == 0 + validation_section = guide.split( + " Structural and semantic validation\n", 1 + )[1].split("\n## ", 1)[0] + snippets = re.findall(r"```python\n(.*?)\n```", validation_section, re.S) + assert len(snippets) == 1 + checked = subprocess.run( + [sys.executable, "-c", snippets[0]], + cwd=selected, + check=True, + capture_output=True, + text=True, + ) + assert checked.stdout == "Package checks passed for the saved evidence.\n" + assert checked.stderr == "" + + +@pytest.mark.parametrize( + "heading", ["Null policy and typed value descriptions", "Comparators"] +) +def test_configuration_fragments_fit_a_complete_field_definition( + tmp_path: Path, heading: str +) -> None: + """Guide fragments can be inserted into a configuration and validated.""" + guide = (PROJECT_ROOT / "docs" / "USER_GUIDE.md").read_text( + encoding="utf-8" + ) + section = guide.split(f" {heading}\n", 1)[1].split("\n### ", 1)[0] + snippets = re.findall(r"```yaml\n(.*?)\n```", section, re.S) + assert len(snippets) == 1 + fragment = yaml.safe_load(snippets[0]) + document = minimal_configuration() + document["fields"]["definitions"]["measured_value"].update(fragment) + configuration_validator().validate(document) + path = tmp_path / "configuration.yaml" + path.write_text(yaml.safe_dump(document, sort_keys=False), encoding="utf-8") + + assert load_comparison_configuration(path).document == document + + +def test_user_guide_identifies_supported_schemas_and_maintained_examples() -> None: + """The offline guide names its supported schemas and both example modes.""" + guide = (PROJECT_ROOT / "docs" / "USER_GUIDE.md").read_text(encoding="utf-8") + + assert "comparison-configuration-v1.0.schema.json" in guide + assert "comparison-results-v1.0.schema.json" in guide + assert "Automatic strict-exact mode" in guide + assert "Runnable custom example" in guide diff --git a/packages/adviso-compare/tests/test_inputs.py b/packages/adviso-compare/tests/test_inputs.py new file mode 100644 index 0000000..2220d70 --- /dev/null +++ b/packages/adviso-compare/tests/test_inputs.py @@ -0,0 +1,480 @@ +"""Behavioural tests for deterministic dataset input parsing.""" + +from __future__ import annotations + +import json +from contextlib import contextmanager +from decimal import Decimal +from hashlib import sha256 +from pathlib import Path +from typing import Iterator + +import pytest + +from adviso_compare.inputs import ( + InputError, + InputFormat, + InputSide, + JsonLocation, + JsonValueError, + NativeCategory, + NativeValue, + TabularLocation, + decode_json_value, + load_dataset, +) + + +def _write_bytes(path: Path, content: bytes) -> Path: + """Write one controlled input and return its path.""" + path.write_bytes(content) + return path + + +@pytest.mark.parametrize( + ("filename", "content", "expected_format"), + [ + ("REFERENCE.CSV", b"record_id,value\nS1,alpha\n", InputFormat.CSV), + ("reference.TsV", b"record_id\tvalue\nS1\talpha\n", InputFormat.TSV), + ("reference.JsOn", b'[{"record_id":"S1","value":"alpha"}]', InputFormat.JSON), + ], +) +def test_format_and_exact_byte_provenance_are_discovered_independently( + tmp_path: Path, + filename: str, + content: bytes, + expected_format: InputFormat, +) -> None: + """The final case-insensitive suffix selects format and bytes supply provenance.""" + path = _write_bytes(tmp_path / filename, content) + + dataset = load_dataset(path, InputSide.REFERENCE) + + assert dataset.provenance.basename == filename + assert dataset.provenance.format is expected_format + assert dataset.provenance.encoding == "utf-8" + assert dataset.provenance.size_bytes == len(content) + assert dataset.provenance.sha256 == sha256(content).hexdigest() + assert len(dataset.records) == 1 + + +@pytest.mark.parametrize( + ("suffix", "delimiter"), + [("csv", ","), ("tsv", "\t")], +) +def test_fixed_tabular_dialects_preserve_strings_and_record_locations( + tmp_path: Path, + suffix: str, + delimiter: str, +) -> None: + """Quoted syntax, multiline cells, and physical locations follow one dialect.""" + content = ( + f'record_id{delimiter}result{delimiter}note\r\n' + f'S1{delimiter}"a{delimiter}b"{delimiter}"first\r\nsecond"\r\n' + f'S2{delimiter}"""quoted"""{delimiter}\r\n' + ).encode() + path = _write_bytes(tmp_path / f"records.{suffix}", content) + + dataset = load_dataset(path, InputSide.QUERY) + + assert dataset.field_names == ("record_id", "result", "note") + assert len(dataset.records) == 2 + first, second = dataset.records + assert first.value("result").category is NativeCategory.STRING + assert first.value("result").value == f"a{delimiter}b" + assert first.value("note").value == "first\r\nsecond" + assert second.value("result").value == '"quoted"' + assert second.value("note").value == "" + assert first.location == TabularLocation(record_number=1, line_number=2) + assert first.location_for("note") == TabularLocation( + record_number=1, + line_number=2, + field_name="note", + ) + assert second.location == TabularLocation(record_number=2, line_number=4) + + +def test_lf_and_crlf_inputs_have_equal_records_but_distinct_byte_provenance( + tmp_path: Path, +) -> None: + """Accepted line-ending variants preserve parsed content, not byte evidence.""" + lf_path = _write_bytes(tmp_path / "lf.csv", b"record_id,value\nS1,alpha\n") + crlf_path = _write_bytes( + tmp_path / "crlf.csv", b"record_id,value\r\nS1,alpha\r\n" + ) + + lf_dataset = load_dataset(lf_path, InputSide.REFERENCE) + crlf_dataset = load_dataset(crlf_path, InputSide.REFERENCE) + + assert lf_dataset.records == crlf_dataset.records + assert lf_dataset.provenance.sha256 != crlf_dataset.provenance.sha256 + assert lf_dataset.provenance.size_bytes != crlf_dataset.provenance.size_bytes + + +def test_json_preserves_native_categories_lexical_numbers_and_pointers( + tmp_path: Path, +) -> None: + """JSON values remain lossless and attributable before configured processing.""" + content = ( + b'[{"text":"01","integer":1,"decimal":1.00,"exponent":1e-1,' + b'"boolean":true,"nothing":null,"array":[1,"x"],' + b'"object":{"z":2,"a":1},"quoted_nonfinite":"NaN",' + b'"a/b~c":"located"}]' + ) + path = _write_bytes(tmp_path / "records.json", content) + + dataset = load_dataset(path, InputSide.REFERENCE) + + assert dataset.field_names == ( + "a/b~c", + "array", + "boolean", + "decimal", + "exponent", + "integer", + "nothing", + "object", + "quoted_nonfinite", + "text", + ) + record = dataset.records[0] + assert record.location == JsonLocation(pointer="/0") + assert record.location_for("a/b~c") == JsonLocation(pointer="/0/a~1b~0c") + assert record.value("text").category is NativeCategory.STRING + assert record.value("text").value == "01" + assert record.value("integer").category is NativeCategory.INTEGER + assert record.value("integer").value == 1 + assert record.value("integer").lexical == "1" + assert record.value("decimal").category is NativeCategory.DECIMAL + assert record.value("decimal").value == Decimal("1.00") + assert record.value("decimal").lexical == "1.00" + assert record.value("exponent").value == Decimal("1e-1") + assert record.value("exponent").lexical == "1e-1" + assert record.value("boolean").category is NativeCategory.BOOLEAN + assert record.value("nothing").category is NativeCategory.NULL + assert record.has_field("nothing") + assert not record.has_field("missing") + assert record.location_for("missing") == record.location + assert record.value("quoted_nonfinite") == NativeValue( + NativeCategory.STRING, "NaN" + ) + assert record.value("array").category is NativeCategory.ARRAY + assert record.value("array").value[0].category is NativeCategory.INTEGER + assert record.value("object").category is NativeCategory.OBJECT + assert tuple(name for name, _ in record.value("object").value) == ("a", "z") + + +def test_json_record_field_names_are_nonempty_but_nested_empty_names_are_data( + tmp_path: Path, +) -> None: + """Only names that participate in dataset-wide field discovery are nonempty.""" + invalid = _write_bytes( + tmp_path / "invalid.json", + b'[{"record_id":"S1","":"value"}]', + ) + nested = _write_bytes( + tmp_path / "nested.json", + b'[{"record_id":"S1","value":{"":"retained"}}]', + ) + + with pytest.raises(InputError) as raised: + load_dataset(invalid, InputSide.REFERENCE) + + assert raised.value.code == "invalid_structure" + assert "empty field name" in raised.value.message + dataset = load_dataset(nested, InputSide.QUERY) + nested_members = dataset.records[0].value("value").value + assert nested_members == (("", NativeValue(NativeCategory.STRING, "retained")),) + + +def test_parser_native_equality_is_recursive_and_category_preserving( + tmp_path: Path, +) -> None: + """Objects ignore member order while arrays and native categories remain exact.""" + first = load_dataset( + _write_bytes( + tmp_path / "first.json", + b'[{"value":{"b":1.00,"a":[1,2]},"other":1}]', + ), + InputSide.REFERENCE, + ).records[0] + second = load_dataset( + _write_bytes( + tmp_path / "second.json", + b'[{"other":1.0,"value":{"a":[1,2],"b":1.0}}]', + ), + InputSide.QUERY, + ).records[0] + reversed_array = load_dataset( + _write_bytes( + tmp_path / "third.json", + b'[{"value":{"a":[2,1],"b":1.0}}]', + ), + InputSide.QUERY, + ).records[0] + + assert first.value("value") == second.value("value") + assert first.value("other") != second.value("other") + assert first.value("value") != reversed_array.value("value") + + +@pytest.mark.parametrize( + ("filename", "content", "expected_fields"), + [ + ("empty.json", b"[]", ()), + ("empty.csv", b"record_id,value\n", ("record_id", "value")), + ("empty.tsv", b"record_id\tvalue\n", ("record_id", "value")), + ], +) +def test_structurally_valid_empty_datasets_remain_valid( + tmp_path: Path, + filename: str, + content: bytes, + expected_fields: tuple[str, ...], +) -> None: + """An empty record collection is distinct from an empty input file.""" + dataset = load_dataset( + _write_bytes(tmp_path / filename, content), InputSide.REFERENCE + ) + + assert dataset.records == () + assert dataset.field_names == expected_fields + + +@pytest.mark.parametrize(("suffix", "delimiter"), [("csv", ","), ("tsv", "\t")]) +@pytest.mark.parametrize( + ("body", "line_number"), + [ + ('"unterminated', 2), + ('unquoted"quote', 2), + ('"closed"trailing', 2), + ('"backslash\\"escape"', 2), + ("bare\rcarriage-return", 2), + ], +) +def test_malformed_tabular_quote_and_line_syntax_is_rejected_for_each_dialect( + tmp_path: Path, + suffix: str, + delimiter: str, + body: str, + line_number: int, +) -> None: + """Both fixed dialects reject non-standard quoting and record endings.""" + content = f"record_id{delimiter}value\nS1{delimiter}{body}\n".encode() + path = _write_bytes(tmp_path / f"records.{suffix}", content) + + with pytest.raises(InputError) as raised: + load_dataset(path, InputSide.QUERY) + + assert raised.value.code == "invalid_syntax" + assert f"physical line {line_number}" in raised.value.message + + +@pytest.mark.parametrize(("suffix", "delimiter"), [("csv", ","), ("tsv", "\t")]) +@pytest.mark.parametrize( + ("document_template", "message_fragment"), + [ + ("field{d}field\n", "duplicate column names"), + ("field{d}\n", "empty column name"), + ("field{d}other\none\n", "has 1 fields; expected 2"), + ("field{d}other\none{d}two{d}three\n", "has 3 fields; expected 2"), + ("field{d}other\n\n", "has 0 fields; expected 2"), + ], +) +def test_invalid_tabular_structure_is_rejected_for_each_dialect( + tmp_path: Path, + suffix: str, + delimiter: str, + document_template: str, + message_fragment: str, +) -> None: + """Headers, row widths, and blank physical records are checked symmetrically.""" + content = document_template.format(d=delimiter) + path = _write_bytes(tmp_path / f"records.{suffix}", content.encode()) + + with pytest.raises(InputError) as raised: + load_dataset(path, InputSide.REFERENCE) + + assert raised.value.code == "invalid_structure" + assert message_fragment in raised.value.message + + +@pytest.mark.parametrize("suffix", ["csv", "tsv", "json"]) +def test_invalid_utf8_is_rejected_before_format_parsing( + tmp_path: Path, + suffix: str, +) -> None: + """The UTF-8 requirement is identical for every supported format.""" + path = _write_bytes(tmp_path / f"records.{suffix}", b"\xff") + + with pytest.raises(InputError) as raised: + load_dataset(path, InputSide.REFERENCE) + + assert raised.value.code == "invalid_encoding" + + +@pytest.mark.parametrize( + "document", + [ + b"NaN", + b'[{"value":Infinity}]', + b'[{"value":{"nested":-Infinity}}]', + b'[{"value":[NaN]}]', + ], + ids=["root", "field", "nested-object", "nested-array"], +) +def test_non_finite_json_tokens_are_rejected_in_every_structural_context( + tmp_path: Path, + document: bytes, +) -> None: + """No parser location enables non-standard JSON numerical constants.""" + path = _write_bytes(tmp_path / "records.json", document) + + with pytest.raises(InputError) as raised: + load_dataset(path, InputSide.QUERY) + + assert raised.value.code == "invalid_syntax" + assert raised.value.message == "query JSON input contains a non-finite number" + + +@pytest.mark.parametrize( + ("content", "message_fragment"), + [ + (b"{}", "JSON root is object"), + (b"1", "JSON root is integer"), + (b'"record"', "JSON root is string"), + (b"[1]", "array item 0 is integer"), + (b'[{"record_id":"S1"},[]]', "array item 1 is array"), + ], +) +def test_invalid_json_roots_identify_the_value_and_required_structure( + tmp_path: Path, + content: bytes, + message_fragment: str, +) -> None: + """Root errors identify the safe structural category and offending index.""" + path = _write_bytes(tmp_path / "records.json", content) + + with pytest.raises(InputError) as raised: + load_dataset(path, InputSide.REFERENCE) + + assert raised.value.code == "invalid_structure" + assert message_fragment in raised.value.message + assert "record object" in raised.value.message + + +@pytest.mark.parametrize( + "content", + [ + pytest.param(b'[\n {"a": 1},\n]', id="array-trailing-comma"), + pytest.param(b'[\n {"a": 1,}\n]', id="object-trailing-comma"), + pytest.param(b'[\n {"a": }\n]', id="missing-value"), + ], +) +def test_malformed_json_reports_its_parser_location( + tmp_path: Path, content: bytes +) -> None: + """Syntax diagnostics preserve the running JSON parser's location.""" + # Python versions can attribute trailing commas to different positions. + with pytest.raises(json.JSONDecodeError) as parser_error: + json.loads(content) + location = parser_error.value + path = _write_bytes(tmp_path / "records.json", content) + + with pytest.raises(InputError) as raised: + load_dataset(path, InputSide.QUERY) + + assert raised.value.code == "invalid_syntax" + assert raised.value.message == ( + f"query JSON input has invalid syntax at line {location.lineno}, " + f"column {location.colno}" + ) + + +@pytest.mark.parametrize( + ("text", "kind"), + [("[\n", "invalid_syntax"), ('{"x":1,"x":2}', "duplicate_member"), + ("NaN", "non_finite")], +) +def test_json_errors_survive_cleanup_with_their_original_context( + text: str, kind: str +) -> None: + """Cleanup preserves the parser error, its cause, and location metadata.""" + originals: list[JsonValueError] = [] + causes: list[BaseException | None] = [] + cleanup_finished = False + + @contextmanager + def cleanup() -> Iterator[None]: + nonlocal cleanup_finished + try: + yield + finally: + cleanup_finished = True + + with pytest.raises(JsonValueError) as raised: + with cleanup(): + try: + decode_json_value(text) + except JsonValueError as error: + originals.append(error) + causes.append(error.__cause__) + raise + + assert cleanup_finished + assert raised.value is originals[0] + assert raised.value.__cause__ is causes[0] + assert raised.value.kind == kind + if kind == "invalid_syntax": + assert (raised.value.line, raised.value.column) == (2, 1) + else: + assert (raised.value.line, raised.value.column) == (None, None) + + +@pytest.mark.parametrize( + ("filename", "content", "expected_code"), + [ + ("records", b"record_id\n", "unsupported_format"), + ("records.txt", b"record_id\n", "unsupported_format"), + ("records.json", b"[", "invalid_syntax"), + ("records.json", b"", "invalid_syntax"), + ("records.csv", b"", "invalid_structure"), + ("records.tsv", b"", "invalid_structure"), + ("records.json", b'[{"a":1,"a":2}]', "invalid_structure"), + ("records.json", b'[{"a":{"b":1,"b":2}}]', "invalid_structure"), + ], +) +def test_invalid_inputs_are_rejected_with_the_specific_input_error( + tmp_path: Path, + filename: str, + content: bytes, + expected_code: str, +) -> None: + """Malformed bytes, syntax, and structures are not repaired or inferred.""" + path = _write_bytes(tmp_path / filename, content) + + with pytest.raises(InputError) as raised: + load_dataset(path, InputSide.QUERY) + + assert raised.value.category == "input" + assert raised.value.code == expected_code + assert raised.value.side is InputSide.QUERY + assert raised.value.diagnostic.startswith(f"ERROR [input.{expected_code}]: ") + assert str(tmp_path) not in raised.value.diagnostic + assert "\n" not in raised.value.diagnostic + + +def test_unreadable_input_is_classified_without_exposing_its_path( + tmp_path: Path, +) -> None: + """Filesystem failures use a stable error without leaking an absolute path.""" + path = tmp_path / "missing.json" + + with pytest.raises(InputError) as raised: + load_dataset(path, InputSide.REFERENCE) + + assert raised.value.code == "unreadable" + assert raised.value.diagnostic == ( + "ERROR [input.unreadable]: reference input could not be read" + ) + assert str(path) not in raised.value.diagnostic diff --git a/packages/adviso-compare/tests/test_records.py b/packages/adviso-compare/tests/test_records.py new file mode 100644 index 0000000..6425d67 --- /dev/null +++ b/packages/adviso-compare/tests/test_records.py @@ -0,0 +1,528 @@ +"""Behavioural tests for record identity and automatic configuration.""" + +from __future__ import annotations + +import json +from pathlib import Path +from typing import Callable + +import pytest +import yaml + +from adviso_compare.application import prepare_comparison +from adviso_compare.configuration import EffectiveConfiguration +from adviso_compare.inputs import InputSide, JsonLocation, TabularLocation +from adviso_compare.invocation import ComparisonInvocation +from adviso_compare.records import RecordKeyError +from tests.support.documents import JsonObject, minimal_configuration + + +def _write(path: Path, text: str) -> Path: + """Write one controlled UTF-8 test document.""" + path.write_text(text, encoding="utf-8") + return path + + +def _write_configuration(tmp_path: Path, document: JsonObject) -> Path: + """Write one controlled custom configuration.""" + return _write( + tmp_path / "configuration.yaml", + yaml.safe_dump(document, sort_keys=False), + ) + + +def _invocation( + tmp_path: Path, + reference: Path, + query: Path, + configuration: Path | None = None, +) -> ComparisonInvocation: + """Build an invocation whose unused output remains inside the test directory.""" + return ComparisonInvocation( + reference=reference, + query=query, + output=tmp_path / "evidence", + configuration=configuration, + ) + + +def _composite_configuration() -> JsonObject: + """Declare aliased, normalized string and parsed integer key components.""" + document = minimal_configuration() + fields = document["fields"] + fields["record_key"] = ["record_id", "batch"] + fields["in_scope"].insert(1, "batch") + key = fields["definitions"]["record_id"] + key["source_normalisation"] = { + "reference": [ + {"operation": "trim", "parameters": {"side": "both"}}, + {"operation": "case_fold"}, + ], + "query": [{"operation": "case_fold"}], + } + key["value_mapping"] = { + "reference": [ + { + "from": {"category": "string", "value": " S1 "}, + "to": {"category": "string", "value": "sample-1"}, + } + ], + "query": [ + { + "from": {"category": "string", "value": "s1"}, + "to": {"category": "string", "value": "sample-1"}, + } + ], + } + fields["definitions"]["batch"] = { + "source_fields": { + "reference": "reference_batch", + "query": "query_batch", + }, + "required": {"reference": True, "query": True}, + "logical_type": "integer", + "null_policy": {"allowed": False, "nulls_equal": False}, + "comparator": {"name": "typed_exact"}, + } + return document + + +def test_custom_aliases_and_composite_key_processing_create_matching_identities( + tmp_path: Path, +) -> None: + """Each custom key component uses its declared source name and translation.""" + reference = _write( + tmp_path / "reference.csv", + "reference_id,reference_batch\n S1 ,01\n", + ) + query = _write( + tmp_path / "query.json", + '[{"query_id":"s1","query_batch":"1"}]', + ) + configuration = _write_configuration(tmp_path, _composite_configuration()) + + prepared = prepare_comparison( + _invocation(tmp_path, reference, query, configuration) + ) + + reference_record = prepared.reference_records.records[0] + query_record = prepared.query_records.records[0] + assert reference_record.key == query_record.key + assert reference_record.source_identity == (" S1 ", "01") + assert query_record.source_identity == ("s1", "1") + assert reference_record.canonical_identity == ("sample-1", "1") + assert prepared.configuration.record_key == ("record_id", "batch") + + +def _missing_key(document: JsonObject) -> None: + """Leave the required reference alias absent from a JSON record.""" + + +def _null_key(document: JsonObject) -> None: + """No configuration mutation is needed for a prohibited source null.""" + + +def _invalid_key(document: JsonObject) -> None: + """Use the composite declaration so its integer component can be invalid.""" + composite = _composite_configuration() + document.clear() + document.update(composite) + + +@pytest.mark.parametrize( + ("mutation", "reference_text", "message_fragment", "location"), + [ + ( + _missing_key, + '[{"expected_value":"1"}]', + "reference key field 'reference_id' is missing", + JsonLocation("/0"), + ), + ( + _null_key, + '[{"reference_id":null}]', + "reference key field 'reference_id' is null", + JsonLocation("/0/reference_id"), + ), + ( + _invalid_key, + ( + "reference_id,reference_batch\n" + "S1,not-an-integer\n" + ), + "reference key field 'reference_batch' is invalid", + TabularLocation(1, 2, "reference_batch"), + ), + ], +) +def test_missing_null_and_invalid_custom_keys_are_attributable_input_errors( + tmp_path: Path, + mutation: Callable[[JsonObject], None], + reference_text: str, + message_fragment: str, + location: object, +) -> None: + """A custom key defect stops record-model construction at its source location.""" + document = minimal_configuration() + mutation(document) + suffix = "csv" if reference_text.startswith("reference_id,") else "json" + reference = _write(tmp_path / f"reference.{suffix}", reference_text) + query = _write(tmp_path / "query.csv", "query_id\nS1\n") + configuration = _write_configuration(tmp_path, document) + + with pytest.raises(RecordKeyError) as raised: + prepare_comparison( + _invocation(tmp_path, reference, query, configuration) + ) + + error = raised.value + assert error.code == "invalid_record_key" + assert error.side is InputSide.REFERENCE + assert message_fragment in error.message + assert error.locations == (location,) + assert "not-an-integer" not in error.diagnostic + + +@pytest.mark.parametrize( + "duplicate_side", + [InputSide.REFERENCE, InputSide.QUERY], +) +def test_duplicate_canonical_keys_report_both_locations_without_overwriting( + tmp_path: Path, + duplicate_side: InputSide, +) -> None: + """Explicit normalization can reveal a duplicate without losing either record.""" + document = minimal_configuration() + key = document["fields"]["definitions"]["record_id"] + key["source_normalisation"] = { + "reference": [{"operation": "case_fold"}], + "query": [{"operation": "case_fold"}], + } + duplicate = "S1\ns1\n" + singleton = "s1\n" + reference = _write( + tmp_path / "reference.csv", + "reference_id\n" + + (duplicate if duplicate_side is InputSide.REFERENCE else singleton), + ) + query = _write( + tmp_path / "query.csv", + "query_id\n" + + (duplicate if duplicate_side is InputSide.QUERY else singleton), + ) + configuration = _write_configuration(tmp_path, document) + + with pytest.raises(RecordKeyError) as raised: + prepare_comparison( + _invocation(tmp_path, reference, query, configuration) + ) + + error = raised.value + assert error.side is duplicate_side + assert "duplicate record key" in error.message + assert error.locations == ( + TabularLocation(1, 2), + TabularLocation(2, 3), + ) + assert "S1" not in error.diagnostic + assert "s1" not in error.diagnostic + + +def test_key_error_diagnostic_escapes_control_characters_in_json_pointer( + tmp_path: Path, +) -> None: + """An exact structured location cannot introduce a diagnostic line break.""" + document = minimal_configuration() + document["fields"]["definitions"]["record_id"]["source_fields"][ + "reference" + ] = "id\nline" + reference = _write( + tmp_path / "reference.json", + json.dumps([{"id\nline": None}]), + ) + query = _write(tmp_path / "query.csv", "query_id\nS1\n") + configuration = _write_configuration(tmp_path, document) + + with pytest.raises(RecordKeyError) as raised: + prepare_comparison( + _invocation(tmp_path, reference, query, configuration) + ) + + assert raised.value.locations == (JsonLocation("/0/id\nline"),) + assert "\n" not in raised.value.diagnostic + assert r"\n" in raised.value.diagnostic + + +def test_automatic_record_id_declares_shared_fields_and_omits_one_sided_fields( + tmp_path: Path, +) -> None: + """Shared record_id is preferred and only exact same-name fields are declared.""" + reference = _write( + tmp_path / "reference.json", + '[{"record_id":"S1","z":1,"a":"x","reference_note":"r"}]', + ) + query = _write( + tmp_path / "query.csv", + "record_id,a,z,query_note\nS1,x,1,q\n", + ) + + prepared = prepare_comparison(_invocation(tmp_path, reference, query)) + + configuration = prepared.configuration + assert configuration.metadata.id == "adviso-compare:automatic-strict-exact" + assert configuration.metadata.revision == "1.0" + assert configuration.record_key == ("record_id",) + assert configuration.in_scope == ("record_id", "a", "z") + assert tuple(configuration.fields) == ("record_id", "a", "z") + key = configuration.field("record_id") + assert key.logical_type == "string" + assert key.required.reference and key.required.query + assert not key.null_policy.allowed + for field_name in ("a", "z"): + field = configuration.field(field_name) + assert field.logical_type is None + assert field.comparator.name == "preserved_exact" + assert not field.required.reference and not field.required.query + assert field.null_policy.allowed and field.null_policy.nulls_equal + assert "reference_note" not in configuration.fields + assert "query_note" not in configuration.fields + assert configuration.document["fields"]["definitions"]["a"] == { + "source_fields": {"reference": "a", "query": "a"}, + "required": {"reference": False, "query": False}, + "null_policy": {"allowed": True, "nulls_equal": True}, + "comparator": {"name": "preserved_exact"}, + } + + +def test_automatic_configuration_is_invariant_to_input_and_field_order( + tmp_path: Path, +) -> None: + """Equivalent record, member, and column orderings produce identical rules.""" + first_reference = _write( + tmp_path / "first-reference.json", + ( + '[{"record_id":"S2","b":2,"a":"y"},' + '{"record_id":"S1","a":"x","b":1}]' + ), + ) + first_query = _write( + tmp_path / "first-query.csv", + "record_id,b,a\nS1,1,x\nS2,2,y\n", + ) + second_reference = _write( + tmp_path / "second-reference.json", + ( + '[{"a":"x","b":1,"record_id":"S1"},' + '{"a":"y","record_id":"S2","b":2}]' + ), + ) + second_query = _write( + tmp_path / "second-query.csv", + "a,record_id,b\ny,S2,2\nx,S1,1\n", + ) + + first = prepare_comparison( + _invocation(tmp_path, first_reference, first_query) + ) + second = prepare_comparison( + _invocation(tmp_path, second_reference, second_query) + ) + + assert first.configuration.document == second.configuration.document + assert set(first.reference_records.by_key) == set(second.reference_records.by_key) + assert set(first.query_records.by_key) == set(second.query_records.by_key) + + +def test_automatic_discovery_selects_the_only_exact_shared_string_candidate( + tmp_path: Path, +) -> None: + """A non-record_id candidate requires completeness, uniqueness, and overlap.""" + reference = _write( + tmp_path / "reference.json", + '[{"sample":"S1","value":"a"},{"sample":"S2","value":"b"}]', + ) + query = _write( + tmp_path / "query.json", + '[{"sample":"S1","value":"x"},{"sample":"S3","value":"y"}]', + ) + + prepared = prepare_comparison(_invocation(tmp_path, reference, query)) + + assert prepared.configuration.record_key == ("sample",) + assert prepared.reference_records.records[0].canonical_identity == ("S1",) + + +@pytest.mark.parametrize( + ("reference_text", "query_text", "message_fragment", "candidates"), + [ + ( + '[{"sample":"R1","value":1}]', + '[{"sample":"Q1","value":1}]', + "no field satisfied the automatic record-key criteria", + (), + ), + ( + '[{"sample":"S1","accession":"A1"}]', + '[{"sample":"S1","accession":"A1"}]', + "automatic record-key selection is ambiguous", + ("accession", "sample"), + ), + ( + ( + '[{"part_a":"A","part_b":"1"},' + '{"part_a":"A","part_b":"2"},' + '{"part_a":"B","part_b":"1"},' + '{"part_a":"B","part_b":"2"}]' + ), + ( + '[{"part_a":"A","part_b":"1"},' + '{"part_a":"A","part_b":"2"},' + '{"part_a":"B","part_b":"1"},' + '{"part_a":"B","part_b":"2"}]' + ), + "no field satisfied the automatic record-key criteria", + (), + ), + ], +) +def test_automatic_discovery_rejects_zero_or_multiple_candidates_without_values( + tmp_path: Path, + reference_text: str, + query_text: str, + message_fragment: str, + candidates: tuple[str, ...], +) -> None: + """Automatic discovery neither guesses nor ranks otherwise valid candidates.""" + reference = _write(tmp_path / "reference.json", reference_text) + query = _write(tmp_path / "query.json", query_text) + + with pytest.raises(RecordKeyError) as raised: + prepare_comparison(_invocation(tmp_path, reference, query)) + + error = raised.value + assert error.side is None + assert message_fragment in error.message + assert error.candidate_fields == candidates + assert "S1" not in error.diagnostic + assert "A1" not in error.diagnostic + + +def test_invalid_automatic_candidates_are_ignored_without_coercion( + tmp_path: Path, +) -> None: + """Only a complete, non-null, unique parser-native string can be selected.""" + reference = _write( + tmp_path / "reference.json", + ( + '[{"sample":"S1","numeric":1,"nullable":"x",' + '"sometimes":"p","duplicate":"d"},' + '{"sample":"S2","numeric":2,"nullable":null,' + '"duplicate":"d"}]' + ), + ) + query = _write( + tmp_path / "query.json", + ( + '[{"sample":"S1","numeric":1,"nullable":"x",' + '"sometimes":"p","duplicate":"d"},' + '{"sample":"S3","numeric":3,"nullable":"y",' + '"sometimes":"q","duplicate":"d"}]' + ), + ) + + prepared = prepare_comparison(_invocation(tmp_path, reference, query)) + + assert prepared.configuration.record_key == ("sample",) + + +@pytest.mark.parametrize( + ("query_text", "message_fragment"), + [ + ( + ( + '[{"record_id":"Q1","sample":"S1"},' + '{"sample":"S2"}]' + ), + "is missing", + ), + ('[{"record_id":null,"sample":"S1"}]', "is null"), + ('[{"record_id":1,"sample":"S1"}]', "is not a parser-native string"), + ( + ( + '[{"record_id":"Q1","sample":"S1"},' + '{"record_id":"Q1","sample":"S2"}]' + ), + "duplicate record key", + ), + ], +) +def test_invalid_shared_record_id_never_falls_back_to_another_candidate( + tmp_path: Path, + query_text: str, + message_fragment: str, +) -> None: + """Every preferred-key defect is fatal even when sample could identify records.""" + reference = _write( + tmp_path / "reference.json", + ( + '[{"record_id":"R1","sample":"S1"},' + '{"record_id":"R2","sample":"S2"}]' + ), + ) + query = _write(tmp_path / "query.json", query_text) + + with pytest.raises(RecordKeyError) as raised: + prepare_comparison(_invocation(tmp_path, reference, query)) + + error = raised.value + assert error.side is InputSide.QUERY + assert error.key_fields == ("record_id",) + assert message_fragment in error.message + assert "sample" not in error.message + + +def test_header_only_record_id_is_valid_but_empty_json_has_no_automatic_key( + tmp_path: Path, +) -> None: + """Tabular headers expose record_id while empty JSON exposes no fields.""" + reference_csv = _write(tmp_path / "reference.csv", "record_id,value\n") + query_tsv = _write(tmp_path / "query.tsv", "record_id\tvalue\n") + + prepared = prepare_comparison( + _invocation(tmp_path, reference_csv, query_tsv) + ) + + assert prepared.configuration.record_key == ("record_id",) + assert prepared.reference_records.records == () + assert prepared.query_records.records == () + + empty_reference = _write(tmp_path / "empty-reference.json", "[]") + empty_query = _write(tmp_path / "empty-query.json", "[]") + with pytest.raises(RecordKeyError) as raised: + prepare_comparison( + _invocation(tmp_path, empty_reference, empty_query) + ) + assert "no field satisfied" in raised.value.message + + +def test_generated_document_is_schema_valid_and_reserved_id_remains_internal( + tmp_path: Path, +) -> None: + """Automatic configuration is valid but cannot be supplied as custom YAML.""" + reference = _write(tmp_path / "reference.csv", "record_id\nS1\n") + query = _write(tmp_path / "query.csv", "record_id\nS1\n") + prepared = prepare_comparison(_invocation(tmp_path, reference, query)) + generated = prepared.configuration.document + custom_path = _write_configuration(tmp_path, generated) + + from adviso_compare.configuration import ( # local to emphasize the boundary + ConfigurationError, + load_comparison_configuration, + ) + + with pytest.raises(ConfigurationError) as raised: + load_comparison_configuration(custom_path) + + assert raised.value.code == "semantic_violation" + assert raised.value.path == "$.metadata.id" + assert isinstance(prepared.configuration, EffectiveConfiguration) diff --git a/packages/adviso-compare/tests/test_reporting.py b/packages/adviso-compare/tests/test_reporting.py new file mode 100644 index 0000000..097e7ba --- /dev/null +++ b/packages/adviso-compare/tests/test_reporting.py @@ -0,0 +1,812 @@ +"""Behavioural tests for HTML rendering and evidence-package publication.""" + +from __future__ import annotations + +import errno +import json +import os +import stat +from concurrent.futures import ThreadPoolExecutor +from datetime import datetime, timezone +from hashlib import sha256 +from html.parser import HTMLParser +from pathlib import Path +from threading import Barrier +from typing import Any +from uuid import UUID + +import pytest +import yaml + +import adviso_compare.reporting as reporting +from adviso_compare.alignment import align_records +from adviso_compare.application import execute_comparison, prepare_comparison +from adviso_compare.contract import assess_contract +from adviso_compare.invocation import ComparisonInvocation +from adviso_compare.reporting import ( + OutputError, + publish_evidence_package, + render_html_report, +) +from adviso_compare.results import ( + ComparisonEvidence, + ResultValidationError, + RuntimeIdentity, + assemble_result, +) +from adviso_compare.values import compare_values +from tests.support.documents import ( + minimal_configuration, minimal_configuration_bytes, minimal_result, +) +from tests.support.schemas import configuration_validator, results_validator + + +def _generated_evidence( + tmp_path: Path, + *, + incomplete: bool = False, + automatic: bool = False, + reference_value: object = 1, + query_value: object = 2, + run_id: UUID = UUID("123e4567-e89b-42d3-a456-426614174000"), +) -> ComparisonEvidence: + """Generate canonical evidence through all three comparison phases.""" + tmp_path.mkdir(parents=True, exist_ok=True) + if automatic: + reference_text = json.dumps([ + {"record_id": "S1", "result": reference_value} + ]) + query_text = json.dumps([ + {"record_id": "S1", "result": query_value} + ]) + configuration = None + else: + reference_text = '[{"reference_id":"S1","expected_value":1}]' + query_text = ( + '[{"query_id":"S1"}]' + if incomplete + else '[{"query_id":"S1","observed_value":2}]' + ) + configuration = minimal_configuration() + reference = tmp_path / "reference.json" + query = tmp_path / "query.json" + reference.write_text(reference_text, encoding="utf-8") + query.write_text(query_text, encoding="utf-8") + configuration_path = None + if configuration is not None: + configuration_path = tmp_path / "configuration.yaml" + configuration_path.write_text( + yaml.safe_dump(configuration, sort_keys=False), + encoding="utf-8", + ) + prepared = prepare_comparison( + ComparisonInvocation( + reference=reference, + query=query, + output=tmp_path / "unused-evidence", + configuration=configuration_path, + ) + ) + contract = assess_contract( + prepared.configuration, + reference=prepared.reference, + query=prepared.query, + reference_records=prepared.reference_records, + query_records=prepared.query_records, + ) + records = align_records(prepared.reference_records, prepared.query_records) + values = compare_values(prepared.configuration, contract, records) + result = assemble_result( + prepared, + contract, + records, + values, + run_id=run_id, + completed_at=datetime(2026, 11, 9, 12, 34, 56, tzinfo=timezone.utc), + software_version="1.2.3", + runtime=RuntimeIdentity( + python="cpython-3.12.7", + platform="linux-x86_64", + unicode_version="15.1.0", + ), + ) + return result + + +def _publish(parent: Path, result: ComparisonEvidence) -> Path: + """Publish generated, validated evidence under the selected parent.""" + return publish_evidence_package(parent, result) + + +def _snapshot(directory: Path) -> dict[str, tuple[int, bytes | str | None]]: + """Capture names, permissions, and content without following symlinks.""" + snapshot = {} + for path in (directory, *sorted(directory.rglob("*"))): + mode = path.lstat().st_mode + content = None + if stat.S_ISLNK(mode): + content = os.readlink(path) + elif stat.S_ISREG(mode): + content = path.read_bytes() + snapshot[path.relative_to(directory).as_posix()] = (mode, content) + return snapshot + + +class _ReportView(HTMLParser): + """Read default-visible text and navigation targets.""" + + def __init__(self, report: str) -> None: + super().__init__() + self.visible: list[str] = [] + self.findings: list[str] = [] + self.ids: list[str] = [] + self.links: list[str] = [] + self.hidden = 0 + self.in_finding = False + self.feed(report) + + def handle_starttag( + self, tag: str, attrs: list[tuple[str, str | None]] + ) -> None: + attributes = dict(attrs) + if attributes.get("id"): + self.ids.append(attributes["id"]) + if tag == "a" and attributes.get("href", "").startswith("#"): + self.links.append(attributes["href"][1:]) + if tag in {"details", "style", "script"}: + self.hidden += 1 + if tag == "article": + self.in_finding = True + + def handle_endtag(self, tag: str) -> None: + if tag in {"details", "style", "script"}: + self.hidden -= 1 + if tag == "article": + self.in_finding = False + + def handle_data(self, data: str) -> None: + if not self.hidden: + self.visible.append(data) + if self.in_finding: + self.findings.append(data) + + +def test_html_report_is_a_self_contained_view_of_both_json_documents() -> None: + """The report presents facts from the linked result and configuration.""" + result = minimal_result(status="incomplete") + result["exclusions"] = [ + { + "code": "undeclared_field_excluded", + "side": "query", + "source_field": "unreported