Skip to content

Commit 4d5098f

Browse files
estebanzimanyiestebanzimanyi
committed
chore(vendor): vendor MEOS-API artefacts (step 2 of the ingestion plan)
Vendor MobilityAPI's read-only copy of MEOS-API's published catalog + projection artefacts under `vendor/meos-api/`, plus a Makefile target `make vendor-meos-api` that regenerates them from upstream. Files added: vendor/meos-api/ PROVENANCE.json -- per-artefact source URLs + regenerate cmd README.md -- refresh procedure meos-idl.json -- 3546 fns / 70 structs / 16 enums (generated by MEOS-API run.py over MobilityDB master meos/include headers) meos-coverage.json -- structural worklist (from open PR #4) meos-object-model-parity.json -- 29-pair portable-parity (from open PR #10) The Makefile target clones MEOS-API + MobilityDB shallowly, installs libclang, runs MEOS-API's `run.py` against MobilityDB's MEOS headers, and copies the produced JSON artefacts into `vendor/meos-api/`. Two of the four artefacts (`meos-coverage.json`, `meos-object-model-parity.json`) currently come from open MEOS-API PR branches because their generators are not yet on master; PROVENANCE.json makes that explicit. The Makefile gracefully skips them if absent. Step 2 of `docs/MEOS_API_INGESTION_PLAN.md`. The drift gate workflow that fails on stale artefacts is step 3 (separate stacked PR).
1 parent 726470b commit 4d5098f

6 files changed

Lines changed: 78858 additions & 0 deletions

File tree

‎Makefile‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
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+
MOBILITYDB_REPO ?= https://github.com/MobilityDB/MobilityDB
8+
MOBILITYDB_REF ?= master
9+
VENDOR_DIR := vendor/meos-api
10+
11+
.PHONY: vendor-meos-api vendor-meos-api-from-prs
12+
13+
# Regenerate vendored MEOS-API artefacts from MEOS-API + MobilityDB headers.
14+
#
15+
# `output/*.json` is .gitignore'd in MEOS-API (generated by `python3 run.py
16+
# <path-to-meos-include>`), so we have to:
17+
# 1. clone MEOS-API at the requested ref,
18+
# 2. clone MobilityDB at the requested ref so MEOS-API's parser can read its
19+
# headers (`meos/include/`),
20+
# 3. install libclang,
21+
# 4. run `python3 run.py <MobilityDB-headers-path>` to produce output/*.json,
22+
# 5. copy the JSON artefacts into $(VENDOR_DIR).
23+
vendor-meos-api:
24+
@echo "[vendor] regenerating meos-api artefacts from"
25+
@echo " MEOS-API: $(MEOS_API_REPO)@$(MEOS_API_REF)"
26+
@echo " MobilityDB: $(MOBILITYDB_REPO)@$(MOBILITYDB_REF) (headers source)"
27+
@mkdir -p $(VENDOR_DIR)
28+
@tmpdir=$$(mktemp -d) && \
29+
git clone --depth 1 --branch $(MEOS_API_REF) $(MEOS_API_REPO) $$tmpdir/meos-api && \
30+
git clone --depth 1 --branch $(MOBILITYDB_REF) $(MOBILITYDB_REPO) $$tmpdir/mobilitydb && \
31+
cd $$tmpdir/meos-api && \
32+
pip install --quiet --user -r requirements.txt && \
33+
python3 run.py $$tmpdir/mobilitydb/meos/include && \
34+
if [ -f report.py ]; then python3 report.py $$tmpdir/mobilitydb/meos/include || true; fi && \
35+
if [ -f object_model_parity.py ]; then python3 object_model_parity.py || true; fi && \
36+
cp -v output/meos-idl.json $(CURDIR)/$(VENDOR_DIR)/ && \
37+
( [ -f output/meos-coverage.json ] && cp -v output/meos-coverage.json $(CURDIR)/$(VENDOR_DIR)/ || true ) && \
38+
( [ -f output/meos-object-model-parity.json ] && cp -v output/meos-object-model-parity.json $(CURDIR)/$(VENDOR_DIR)/ || true ) && \
39+
cd $(CURDIR) && rm -rf $$tmpdir
40+
@echo "[vendor] done — $(VENDOR_DIR) refreshed"
41+
42+
# Fetch the enriched catalog + OpenAPI projection from the open PR branches
43+
# (PR #4 ships parser/enrich.py, PR #5 ships generate_openapi.py).
44+
vendor-meos-api-from-prs:
45+
@echo "[vendor] fetching from open PR branches (#4 enrichment + #5 OpenAPI)"
46+
@mkdir -p $(VENDOR_DIR)
47+
@tmpdir=$$(mktemp -d) && \
48+
git clone $(MEOS_API_REPO) $$tmpdir/meos-api && \
49+
git clone --depth 1 --branch $(MOBILITYDB_REF) $(MOBILITYDB_REPO) $$tmpdir/mobilitydb && \
50+
cd $$tmpdir/meos-api && \
51+
git fetch origin $(MEOS_API_PR4):pr4 $(MEOS_API_PR5):pr5 && \
52+
git checkout pr5 && \
53+
git merge --no-edit pr4 || true && \
54+
pip install --quiet --user -r requirements.txt && \
55+
python3 run.py $$tmpdir/mobilitydb/meos/include && \
56+
python3 generate_openapi.py && \
57+
cp -v output/meos-idl.json $(CURDIR)/$(VENDOR_DIR)/ && \
58+
( [ -f output/meos-coverage.json ] && cp -v output/meos-coverage.json $(CURDIR)/$(VENDOR_DIR)/ || true ) && \
59+
( [ -f output/meos-object-model-parity.json ] && cp -v output/meos-object-model-parity.json $(CURDIR)/$(VENDOR_DIR)/ || true ) && \
60+
( [ -f output/meos-openapi.json ] && cp -v output/meos-openapi.json $(CURDIR)/$(VENDOR_DIR)/ || true ) && \
61+
cd $(CURDIR) && rm -rf $$tmpdir
62+
@echo "[vendor] done — $(VENDOR_DIR) refreshed from PRs #4 + #5"

‎vendor/meos-api/PROVENANCE.json‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
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 (generated, not committed)",
9+
"regenerate": "python3 run.py <path-to-MobilityDB/meos/include>",
10+
"describes": "MEOS catalog: 3546 functions, 70 structs, 16 enums (simple parse over MobilityDB master headers). 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": "feat/service-enrichment (PR #4) — `report.py` is not yet on master",
15+
"source_path": "output/meos-coverage.json (generated, not committed)",
16+
"regenerate": "python3 report.py <path-to-MobilityDB/meos/include>",
17+
"describes": "Structural worklist of non-exposable functions, ranked by `byClass`.",
18+
"status": "FROM_OPEN_PR4"
19+
},
20+
"meos-object-model-parity.json": {
21+
"source_repo": "MobilityDB/MEOS-API",
22+
"source_branch": "feat/object-model (PR #10) — `object_model_parity.py` is not yet on master",
23+
"source_path": "output/meos-object-model-parity.json (generated, not committed)",
24+
"regenerate": "python3 object_model_parity.py",
25+
"describes": "Object-model dispatch / portable bare-name parity (29-pair contract verbatim).",
26+
"status": "FROM_OPEN_PR10"
27+
},
28+
"meos-openapi.json": {
29+
"source_repo": "MobilityDB/MEOS-API",
30+
"source_branch": "feat/openapi (PR #5)",
31+
"source_path": "output/meos-openapi.json (regenerated; not committed on the PR branch)",
32+
"regenerate": "python3 generate_openapi.py",
33+
"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.",
34+
"status": "PENDING_PR4_PLUS_PR5"
35+
},
36+
"meos-movfeat-openapi.json": {
37+
"source_repo": "MobilityDB/MEOS-API",
38+
"source_branch": "MISSING — natural follow-up named in PR #5's body",
39+
"describes": "OGC API – Moving Features OpenAPI projection. The immediate dependency for MobilityAPI per `docs/MEOS_API_INGESTION_PLAN.md`.",
40+
"status": "MISSING_UPSTREAM"
41+
}
42+
}
43+
}

‎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)