Skip to content

feat(validation): add oold meta vendor command - #146

Merged
simontaurus merged 1 commit into
mainfrom
feat/meta-vendor-command
Aug 31, 2026
Merged

feat(validation): add oold meta vendor command#146
simontaurus merged 1 commit into
mainfrom
feat/meta-vendor-command

Conversation

@LukasGold

@LukasGold LukasGold commented Aug 31, 2026

Copy link
Copy Markdown
Contributor

Closes #123.

Vendoring a meta-schema version was a hand-run bash loop in docs/maintaining-meta-schemas.md. Every trap in it was one the documentation had to warn about, and each had been hit at least once. A command removes all three by construction instead:

Trap How the command removes it
git show applies the checkout's autocrlf filter, writing CRLF on Windows, changing every digest and failing only on Linux CI bytes come from git cat-file blob straight off the subprocess pipe into write_bytes, with no text mode anywhere on the path
copying the wrong file set, which has grown twice the file set is read from the tag's own meta/ tree, and recorded as that version's files override only when it differs from the shared default
updating the files but not fixtures.tag the fixture slice is refreshed from the same tag in the same call, and the tag recorded

The command

oold meta vendor <version> --from <path-to-oold-schema>, wired into the existing meta group beside list and fetch. It writes the files, records tag, commit, commit date and a sha256 per file into index.json, derives id_base from the vendored wrapper's own $id, refreshes tests/data/oold/ from the same tag, and refuses to overwrite a tracked version without --force.

The same trap, found in review, one level up

index.json is the one file the command writes as text rather than bytes, and it was going through Path.write_text, whose default newline=None translates to os.linesep and would author CRLF on Windows. It is harmless on a machine with core.autocrlf=true, which normalizes it back, and the committed blob is LF today. It would not be harmless for a contributor with autocrlf off, which is the default on Linux.

Fixed by passing newline="\n" explicitly, with test_the_written_index_json_has_no_crlf asserting on the bytes rather than the text, since that is the form of the check that travels across platforms. .gitattributes is deliberately not changed: meta/index.json is legitimately CRLF in a Windows working tree, and the existing line-ending test reads the working tree.

Acceptance

The issue names three existing tests as the acceptance criteria, and they pass unchanged: test_recorded_checksums_match_the_shipped_files, test_the_vendored_files_are_stored_with_unix_line_endings, test_the_fixture_slice_records_the_release_it_came_from.

New coverage builds real throwaway git repositories rather than mocking git, including the CRLF case directly: a source whose working tree holds CRLF after the commit must still vendor LF bytes identical to the committed blob.

Limits, recorded in the docs rather than hidden

  • the narrative fields notes, prerelease and rules_source are not generated; the doc now says so
  • the tag is always v<version>, matching every existing index.json entry; there is no --ref override
  • the rule catalogue's pre-release exception, as in 1.0.0-rc.1, stays manual

Verification

Rebased onto main at v0.18.3 and re-verified there, since the first run measured against a main that has since moved by five commits:

  • full suite: 582 passed, 9 skipped, against a baseline of 565 on main
  • make check: clean
  • uv run oold validate tests/data/oold --offline: PASS, 380 ok, 21 warnings, unchanged
  • parity against fresh clones of both references: 6 passed
  • git status --porcelain -- src/oold/validation/meta tests/data/oold: empty, so no vendored byte or upstream fixture moved

The rebase produced no conflicts. #143 landed in the meantime and was the one to check, since it rewrote the remote-fetch half of meta_store.py. It touched fetch_remote, load_remote and _read_stamp; meta_dir() and load_index() are unchanged in both signature and semantics, and those are the two this command depends on.

  • the command was run end to end against a synthetic tagged repository, correctly excluding RULES.md and rules-baseline.json, and correctly refusing the second run without --force

@github-actions

github-actions Bot commented Aug 31, 2026

Copy link
Copy Markdown
Contributor

Release preview

Merging this PR would release v0.19.0 (current: v0.18.3).

Changelog preview (truncated)
## v0.19.0 (2026-08-31)

### Features

- **validation**: Add oold meta vendor command
  ([`8663489`](https://github.com/OO-LD/oold-python/commit/8663489d7b587e86bb04c0140b033eaf7e792de4))

### Testing

- **parity**: Compare against oold-js instead of oold-schema's scripts
  ([#144](https://github.com/OO-LD/oold-python/pull/144),
  [`42d0d74`](https://github.com/OO-LD/oold-python/commit/42d0d740fec4285ca6c3b9bd9c0c028a9368b601))

Preview via python-semantic-release and conventional commits.

@github-actions

Copy link
Copy Markdown
Contributor

📊 Benchmark Results

Click to see benchmark comparison
📊 Benchmark Comparison (threshold: 1.3x)
============================================================

➖ Unchanged (within threshold):
  ➖ test_simple_dict_document_store: 0.0016s → 0.0016s (+0.9%)
  ➖ test_sqlite_document_store: 0.0017s → 0.0017s (+0.8%)
  ➖ test_local_sparql_store: 0.0375s → 0.0371s (-1.2%)
  ➖ test_oneof_subschema: 0.0556s → 0.0565s (+1.8%)
  ➖ test_enum_docstrings: 0.0468s → 0.0475s (+1.5%)
  ➖ test_subclass_inheritance: 0.0500s → 0.0507s (+1.3%)
  ➖ test_class_hierarchy: 0.0474s → 0.0484s (+2.1%)
  ➖ test_core[v1]: 0.0355s → 0.0364s (+2.3%)
  ➖ test_core[v2]: 0.0408s → 0.0417s (+2.1%)
  ➖ test_schema_generation[v1]: 0.0015s → 0.0015s (+1.2%)
  ➖ test_schema_generation[v2]: 0.0026s → 0.0026s (+0.7%)
  ➖ test_simple_json: 0.0006s → 0.0006s (+0.6%)
  ➖ test_complex_graph: 0.0015s → 0.0015s (+1.1%)

============================================================
Summary: 0 regressions, 0 improvements, 13 unchanged
============================================================

✅ No significant performance regressions

Threshold: 1.3x (30% slower triggers a regression warning)

Note: Benchmarks are informational only and won't fail the build.

💡 Tip: Download the benchmark-results artifact for detailed JSON data

@codecov

codecov Bot commented Aug 31, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 93.00000% with 7 lines in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
src/oold/validation/meta_vendor.py 94.1% 3 Missing and 2 partials ⚠️
src/oold/validation/cli.py 85.7% 2 Missing ⚠️

📢 Thoughts on this report? Let us know!

- reads the file set a release tag actually ships instead of a hand-run
  bash loop, so the wrong-file-set trap cannot recur
- extracts with git cat-file blob and writes bytes verbatim, closing the
  CRLF-on-Windows trap by construction
- records tag, commit, commit date, id_base and sha256 per file in
  meta/index.json, refusing to overwrite a tracked version without --force
- refreshes tests/data/oold/ from the same tag and sets fixtures.tag in
  one call, so the two can no longer drift apart
- points docs/maintaining-meta-schemas.md at the command in place of the
  bash procedure it replaces
@LukasGold
LukasGold force-pushed the feat/meta-vendor-command branch from 57b9d05 to 8663489 Compare August 31, 2026 13:19
@github-actions

Copy link
Copy Markdown
Contributor

📊 Benchmark Results

Click to see benchmark comparison
📊 Benchmark Comparison (threshold: 1.3x)
============================================================

➖ Unchanged (within threshold):
  ➖ test_simple_dict_document_store: 0.0016s → 0.0016s (+0.2%)
  ➖ test_sqlite_document_store: 0.0017s → 0.0017s (-0.2%)
  ➖ test_local_sparql_store: 0.0382s → 0.0389s (+1.9%)
  ➖ test_oneof_subschema: 0.0583s → 0.0599s (+2.7%)
  ➖ test_enum_docstrings: 0.0502s → 0.0524s (+4.3%)
  ➖ test_subclass_inheritance: 0.0552s → 0.0542s (-1.8%)
  ➖ test_class_hierarchy: 0.0511s → 0.0510s (-0.2%)
  ➖ test_core[v1]: 0.0376s → 0.0385s (+2.5%)
  ➖ test_core[v2]: 0.0430s → 0.0439s (+2.1%)
  ➖ test_schema_generation[v1]: 0.0015s → 0.0015s (+0.9%)
  ➖ test_schema_generation[v2]: 0.0026s → 0.0027s (+3.2%)
  ➖ test_simple_json: 0.0006s → 0.0006s (+0.4%)
  ➖ test_complex_graph: 0.0015s → 0.0015s (-1.4%)

============================================================
Summary: 0 regressions, 0 improvements, 13 unchanged
============================================================

✅ No significant performance regressions

Threshold: 1.3x (30% slower triggers a regression warning)

Note: Benchmarks are informational only and won't fail the build.

💡 Tip: Download the benchmark-results artifact for detailed JSON data

@LukasGold
LukasGold requested a review from simontaurus August 31, 2026 15:03
@simontaurus
simontaurus merged commit f714002 into main Aug 31, 2026
21 checks passed
@simontaurus
simontaurus deleted the feat/meta-vendor-command branch August 31, 2026 18:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add an "oold meta vendor" command instead of a documented bash procedure

3 participants