Chili Palmer
d08b59c9a9
Some checks failed
API and SemVer surface / api-surface (push) Failing after 13m8s
Native code generation / deterministic (push) Failing after 2m8s
Concurrency and resource soak audit / soak (push) Failing after 6m39s
Imaging and meshing gate / native (push) Has been cancelled
Release platform and feature matrix / audit (push) Has been cancelled
Release platform and feature matrix / matrix (false, linux-stable-minimal, x86_64-unknown-linux-gnu, stable) (push) Has been cancelled
Release platform and feature matrix / matrix (false, macos-stable-portable, x86_64-apple-darwin, stable) (push) Has been cancelled
Release platform and feature matrix / matrix (false, windows-stable-portable, x86_64-pc-windows-gnu, stable) (push) Has been cancelled
Release platform and feature matrix / matrix (true, linux-msrv-portable, x86_64-unknown-linux-gnu, 1.96.0) (push) Has been cancelled
Release platform and feature matrix / matrix (true, linux-stable-default, x86_64-unknown-linux-gnu, stable) (push) Has been cancelled
Release platform and feature matrix / matrix (true, linux-stable-features, x86_64-unknown-linux-gnu, stable) (push) Has been cancelled
Release platform and feature matrix / matrix (true, linux-stable-release-surface, x86_64-unknown-linux-gnu, stable) (push) Has been cancelled
Documentation / documentation (push) Has been cancelled
Native Rust workspace compile / compile (push) Has been cancelled
Dependency and supply-chain audit / audit (push) Has been cancelled
JPEG 2000 feature / linux (push) Successful in 2m46s
Skia feature / linux (push) Successful in 31m0s
85 lines
4.1 KiB
Markdown
85 lines
4.1 KiB
Markdown
# Public API catalog
|
|
|
|
`public-api.json` is the authoritative compiled-metadata inventory for the 13
|
|
LibreMetaverse library assemblies at the pinned upstream commit. It contains:
|
|
|
|
- stable C# documentation IDs and complete public type/member metadata;
|
|
- nullability, constraints, bases, interfaces, overload parameters, accessors,
|
|
constants, events, delegates, enum values, and public attributes;
|
|
- assembly identities and independent reflection/ECMA-335 count checks;
|
|
- hashes for the outputs of all six upstream source generators;
|
|
- `external_types`, the non-LibreMetaverse types used by public signatures and
|
|
every LibreMetaverse API that uses them.
|
|
|
|
External entries are replacement obligations, not copied dependency APIs.
|
|
`RUST-TYPES.tsv` resolves every entry to Rust core/std, an adopted
|
|
cross-platform crate, or a native MetaCrate type. Third-party API objects use
|
|
project-owned boundary types so their eventual backend can be replaced without
|
|
exposing SkiaSharp, SIPSorcery, MessagePack, CoreJ2K, or another foreign member
|
|
surface. `RUST-MAPPING.tsv` records one reviewed destination and full Rust
|
|
signature for every catalog member. `MAPPING-COVERAGE.md` is the readable gate
|
|
summary.
|
|
|
|
Regenerate from the clean pinned upstream checkout:
|
|
|
|
```sh
|
|
python3 tools/extract_public_api.py
|
|
```
|
|
|
|
The command builds the upstream libraries into a temporary directory, runs the
|
|
extractor twice against the same compiled metadata, rejects count mismatches or
|
|
duplicate documentation IDs, and writes the result only when both outputs are
|
|
byte-identical. The extractor is development-only and is absent from every
|
|
Cargo manifest and published Rust dependency graph.
|
|
|
|
Regenerate or validate the Rust mapping with only Python's standard library:
|
|
|
|
```sh
|
|
python3 tools/generate_rust_mapping.py
|
|
python3 tools/generate_rust_mapping.py --check
|
|
python3 tools/generate_api_shims.py
|
|
python3 tools/generate_api_shims.py --check
|
|
python3 tools/check_api_coverage.py
|
|
```
|
|
|
|
The checker rejects duplicate C# IDs, duplicate Rust destinations, invalid
|
|
statuses, stale or missing catalog entries, unresolved signature types,
|
|
assemblies without representative mappings, and platform-specific API targets.
|
|
It also rejects generated `Default` shims and plausible false/zero/empty/nil
|
|
fallbacks. Failure-only bodies must use the standardized
|
|
`Error::NotImplemented` result or `unimplemented_api!` panic; reviewed native
|
|
member hooks must call an explicitly registered hand-written implementation.
|
|
The two support traits in `RUST-TYPES.tsv` are included because compiled public
|
|
inheritance records reference them even though they are absent from the public
|
|
type table.
|
|
|
|
`generate_api_shims.py` consumes the catalog and reviewed mapping ledger,
|
|
formats all 13 generated Rust assemblies deterministically, and generates the
|
|
standalone `tests/api-compile` downstream fixture. `check_api_coverage.py`
|
|
compares catalog IDs, mapping rows, exported shim IDs, and fixture probes;
|
|
rejects stale, missing, duplicate, or erased entries; and verifies
|
|
`API-COVERAGE.md`. Regenerate that report with
|
|
`python3 tools/check_api_coverage.py --write`.
|
|
|
|
The reviewed first-release public surface is stored in
|
|
[`SEMVER-BASELINE.json`](SEMVER-BASELINE.json), with the decisions and migration
|
|
recipes rendered in [`SEMVER-AUDIT.md`](SEMVER-AUDIT.md). The audit compares
|
|
mapping/export coverage, normalized Rust declarations, feature sets, ownership,
|
|
async and error contracts, thread-safety boundaries, and public dependency
|
|
types. Record a deliberate baseline only after reviewing its SemVer impact,
|
|
then verify it and write reproducible evidence:
|
|
|
|
```sh
|
|
cargo run --locked -p metacrate-ci-matrix -- api-baseline-write
|
|
cargo run --locked -p metacrate-ci-matrix -- api-audit \
|
|
--evidence /tmp/metacrate-api-audit.json
|
|
cmp /tmp/metacrate-api-audit.json ci/evidence/api-audit.json
|
|
```
|
|
|
|
Native implementations replace whole generated types where practical. The
|
|
generated module retains the catalog markers and re-exports the hand-written
|
|
type; member-level implementations use an explicit generator registry. This
|
|
keeps regeneration deterministic without moving behavioral code into Python.
|
|
`SHIM-COVERAGE.md` reports native type/member totals separately from remaining
|
|
failure-only surfaces.
|