Skip to content

Commit 58bbc39

Browse files
estebanzimanyiestebanzimanyi
committed
chore(vendor): vendor MEOS-API artefacts (step 2 of the ingestion plan)
Brings copies of MEOS-API's published catalog + parity artefacts into `vendor/meos-api/`, with a `Makefile` target (`make vendor-meos-api`) to re-fetch. This is step 2 of `docs/MEOS_API_INGESTION_PLAN.md`: it lets MobilityAPI's dispatcher layer consume the catalog as a versioned, in-tree dependency, without a runtime libclang or a checked-out MEOS-source-tree dependency. What's vendored today (from MEOS-API `master`): * `meos-idl.json` — 2699 fns / 47 structs / 6 enums (simple parse) * `meos-coverage.json` — worklist of non-exposable fns by class * `meos-object-model-parity.json` — 29-pair portable-bare-name parity What's pending upstream (called out in `PROVENANCE.json` + `vendor/meos-api/README.md`): * enriched catalog with `network`/`wire`/`api` fields → MEOS-API PR #4 * `meos-openapi.json` (1790-operation 3.1 contract) → MEOS-API PR #5 * `meos-movfeat-openapi.json` (OGC MovFeat projection) → natural follow-up named in PR #5's body — the immediate dependency for MobilityAPI step 5 Two Makefile targets: * `make vendor-meos-api` — copies from MEOS-API master (today's state) * `make vendor-meos-api-from-prs` — checks out PR #4 + PR #5 branches and regenerates the enriched catalog + OpenAPI; lets MobilityAPI work against the open-PR baseline (no merge wait) The vendored files are committed verbatim so a downstream contributor doesn't need libclang. Refresh = re-run the make target and commit the diff. This sets the stage for step 3 (CI regenerate-and-diff gate), step 4 (dispatcher replacement for the 5 pure-MEOS endpoint modules), and step 5 (MovFeat-projection adoption once upstream ships it). See `docs/MEOS_API_INGESTION_PLAN.md`.
1 parent 726470b commit 58bbc39

6 files changed

Lines changed: 57740 additions & 0 deletions

File tree

‎Makefile‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# MobilityAPI build & vendoring targets
2+
3+
MEOS_API_REPO ?= https://github.com/MobilityDB/MEOS-API
4+
MEOS_API_REF ?= master
5+
MEOS_API_PR5 ?= refs/pull/5/head # MEOS-API PR #5 (OpenAPI projection)
6+
MEOS_API_PR4 ?= refs/pull/4/head # MEOS-API PR #4 (enrichment)
7+
VENDOR_DIR := vendor/meos-api
8+
9+
.PHONY: vendor-meos-api vendor-meos-api-from-prs
10+
11+
vendor-meos-api:
12+
@echo "[vendor] fetching meos-api artefacts from $(MEOS_API_REPO)@$(MEOS_API_REF)"
13+
@mkdir -p $(VENDOR_DIR)
14+
@tmpdir=$$(mktemp -d) && \
15+
git clone --depth 1 --branch $(MEOS_API_REF) $(MEOS_API_REPO) $$tmpdir && \
16+
cp -v $$tmpdir/output/meos-idl.json $(VENDOR_DIR)/ && \
17+
cp -v $$tmpdir/output/meos-coverage.json $(VENDOR_DIR)/ && \
18+
cp -v $$tmpdir/output/meos-object-model-parity.json $(VENDOR_DIR)/ && \
19+
rm -rf $$tmpdir
20+
@echo "[vendor] done — $(VENDOR_DIR) refreshed from $(MEOS_API_REF)"
21+
22+
# Fetch the enriched catalog + OpenAPI projection from the open PR branches
23+
# (PR #4 ships parser/enrich.py, PR #5 ships generate_openapi.py).
24+
vendor-meos-api-from-prs:
25+
@echo "[vendor] fetching from open PR branches (#4 enrichment + #5 OpenAPI)"
26+
@mkdir -p $(VENDOR_DIR)
27+
@tmpdir=$$(mktemp -d) && \
28+
git clone $(MEOS_API_REPO) $$tmpdir && \
29+
cd $$tmpdir && \
30+
git fetch origin $(MEOS_API_PR4):pr4 $(MEOS_API_PR5):pr5 && \
31+
git checkout pr5 && \
32+
git merge --no-edit pr4 || true && \
33+
pip install --quiet --user libclang || true && \
34+
python3 run.py && \
35+
python3 generate_openapi.py && \
36+
cp -v output/meos-idl.json $(CURDIR)/$(VENDOR_DIR)/ && \
37+
cp -v output/meos-coverage.json $(CURDIR)/$(VENDOR_DIR)/ && \
38+
cp -v output/meos-object-model-parity.json $(CURDIR)/$(VENDOR_DIR)/ && \
39+
cp -v output/meos-openapi.json $(CURDIR)/$(VENDOR_DIR)/ && \
40+
cd $(CURDIR) && rm -rf $$tmpdir
41+
@echo "[vendor] done — $(VENDOR_DIR) refreshed from PRs #4 + #5"
42+

‎vendor/meos-api/PROVENANCE.json‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
{
2+
"$comment": "Vendored MEOS-API artefacts. Sources, regenerate with `make vendor-meos-api`.",
3+
"fetched_at": "2026-05-20",
4+
"artefacts": {
5+
"meos-idl.json": {
6+
"source_repo": "MobilityDB/MEOS-API",
7+
"source_branch": "master",
8+
"source_path": "output/meos-idl.json",
9+
"regenerate": "python3 run.py",
10+
"describes": "MEOS catalog: 2699 functions, 47 structs, 6 enums (simple parse). Enriched form (with `network`/`wire`/`api` fields) is delivered by open PR #4; once that PR's content reaches master, this artefact picks up the enriched form via the standard `make vendor-meos-api` fetch."
11+
},
12+
"meos-coverage.json": {
13+
"source_repo": "MobilityDB/MEOS-API",
14+
"source_branch": "master",
15+
"source_path": "output/meos-coverage.json",
16+
"regenerate": "python3 report.py",
17+
"describes": "Structural worklist of non-exposable functions, ranked by `byClass`."
18+
},
19+
"meos-object-model-parity.json": {
20+
"source_repo": "MobilityDB/MEOS-API",
21+
"source_branch": "master",
22+
"source_path": "output/meos-object-model-parity.json",
23+
"regenerate": "python3 portable_parity.py",
24+
"describes": "Object-model dispatch / portable bare-name parity (29-pair contract verbatim)."
25+
},
26+
"meos-openapi.json": {
27+
"source_repo": "MobilityDB/MEOS-API",
28+
"source_branch": "feat/openapi (PR #5)",
29+
"source_path": "output/meos-openapi.json (regenerated; not committed on the PR branch)",
30+
"regenerate": "python3 generate_openapi.py",
31+
"describes": "OpenAPI 3.1 projection: 1790 operations over 14 component schemas, every path a single POST with `x-meos-*` extensions. NOT YET vendored here — open PR #5's generator requires the enriched catalog from open PR #4. When both land on master, this artefact appears.",
32+
"status": "PENDING_PR4_PLUS_PR5"
33+
},
34+
"meos-movfeat-openapi.json": {
35+
"source_repo": "MobilityDB/MEOS-API",
36+
"source_branch": "MISSING — natural follow-up named in PR #5's body",
37+
"describes": "OGC API – Moving Features OpenAPI projection. The immediate dependency for MobilityAPI per `docs/MEOS_API_INGESTION_PLAN.md`.",
38+
"status": "MISSING_UPSTREAM"
39+
}
40+
}
41+
}

‎vendor/meos-api/README.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
# Vendored MEOS-API artefacts
2+
3+
This directory contains snapshots of the published catalog and projections
4+
from [`MobilityDB/MEOS-API`](https://github.com/MobilityDB/MEOS-API).
5+
MobilityAPI's [`docs/MEOS_API_INGESTION_PLAN.md`](../../docs/MEOS_API_INGESTION_PLAN.md)
6+
describes how these artefacts drive the ingestion pipeline; this file
7+
documents which artefact is fresh from where.
8+
9+
## Refresh
10+
11+
```bash
12+
# Current state — copies from MEOS-API master:
13+
make vendor-meos-api
14+
15+
# Once the open PR branches land — pulls from PR #4 + PR #5 and regenerates:
16+
make vendor-meos-api-from-prs
17+
```
18+
19+
The `Makefile` targets are idempotent; commit the resulting JSON files
20+
verbatim so a downstream contributor doesn't need libclang installed to
21+
run MobilityAPI.
22+
23+
## What lives here today
24+
25+
| File | Source | Size | Describes |
26+
|---|---|---:|---|
27+
| `meos-idl.json` | MEOS-API master, `output/` | ~1.2 MB | Catalog: 2699 functions, 47 structs, 6 enums (**simple parse**; enrichment via PR #4 not yet on master) |
28+
| `meos-coverage.json` | MEOS-API master, `output/` | ~37 KB | Worklist of non-exposable functions ranked by class |
29+
| `meos-object-model-parity.json` | MEOS-API master, `output/` | ~13 KB | 29-pair portable-bare-name parity (object-model dispatch) |
30+
| **`PROVENANCE.json`** | this file's companion | ~2 KB | Machine-readable source map + status of pending artefacts |
31+
32+
## What's NOT here yet (pending upstream)
33+
34+
| File | Pending | Why |
35+
|---|---|---|
36+
| `meos-idl.json` (enriched form, with `network` / `wire` / `api` fields) | MEOS-API PR #4 | The enrichment pass adds the projectability metadata MobilityAPI's dispatcher layer needs. Once #4's content reaches master, `make vendor-meos-api` picks it up automatically. |
37+
| `meos-openapi.json` | MEOS-API PR #5 | OpenAPI 3.1 projection: 1790 operations + `x-meos-*` extensions. Consumed by MobilityAPI's dispatcher generator (step 4 of the ingestion plan). |
38+
| `meos-movfeat-openapi.json` | MEOS-API session's natural-follow-up | OGC API – Moving Features resource projection. The immediate dependency for MobilityAPI step 5; until it lands, MobilityAPI's hand-written OGC endpoints stay. |
39+
40+
## Why we vendor instead of fetching at runtime
41+
42+
Three reasons:
43+
44+
1. **Reproducible builds** — a MobilityAPI checkout pinned to commit `X` always builds against the same MEOS-API artefact tree, not whatever MEOS-API's master happens to be at build time.
45+
2. **No libclang dependency at install time** — running MEOS-API's `run.py` (the enrichment pass) requires libclang and a checked-out MEOS source tree. Most MobilityAPI users don't need that.
46+
3. **Diff-able drift signal** — a `make vendor-meos-api` followed by `git status` immediately shows what changed upstream, surfacing breaking-changes as reviewable diffs.
47+
48+
See [`docs/MEOS_API_INGESTION_PLAN.md`](../../docs/MEOS_API_INGESTION_PLAN.md) for the full ingestion roadmap (steps 1–5).

0 commit comments

Comments
 (0)