Build the TEA specification from upstream source into ECMA HTML/PDF - #31

Open

taleodor wants to merge 3 commits into

Ecma-TC54:mainfrom

relizaio:2026-06-import-tea-source

taleodor commented Jun 3, 2026

Summary

Wires this repository up to render the Transparency Exchange API specification while keeping CycloneDX/transparency-exchange-api as the single source of truth for content.

That repo keeps owning the content sources — the OpenAPI document (spec/openapi.yaml) and the narrative Markdown chapters. This repo owns the ECMA publication pipeline (Markdown + OpenAPI → Ecmarkup → HTML → PDF) and the hand-authored ECMA front/back matter in excerpts/ (header, scope, conformance, normative references, terms, bibliography, colophon) — using the same toolchain as ECMA-424.

Before this PR, spec.html here was a hand-authored stub with TODO bodies. After it, spec.html is generated from upstream and the build produces full single-page HTML, multipage HTML, and a watermark-free PDF via the existing ghcr.io/ecma-tc54/princexml CI container.

The pipeline, the inputs pulled from upstream (the curated Markdown allowlist with ordering/stable-ID rules, and exactly what's extracted from spec/openapi.yaml), and local build steps are all documented in the updated README — see How this specification is built and What gets pulled from the TEA source.

Changes

index.js, lib/, excerpts/ — new build pipeline (see README Layout table).
package.json — generator deps + generate-spec; build-head/build-for-pdf now generate first. Default build-head runs --lint-spec without --strict (matching ECMA-424); strict kept as build-head-strict.
.github/workflows/build.yml — all actions pinned by commit digest (version in comment); Node read from .nvmrc. No job-topology changes.
README.md — replaced the stale PURL placeholder with TEA content + build docs.
.gitignore — ignores the tea-source/ fetch cache.

Notes for reviewers

Source tracks upstream main, not a pinned ref — reproducibility-unsafe for a real publication build. TODO in index.js to pin a tag/SHA before the first edition; on main for now so drafts stay current.
--strict is off by default — parenthesised narrative headings (e.g. "TEA Collection object (TCO)") trip ecmarkup's header-format rule, surfacing as 14 non-fatal warnings. Reason is commented at the emission site in lib/md-to-emu.js.
CI Node moved 18 → 20.14.0 as a side effect of reading .nvmrc. Code runs on both.
spec.html is committed as a generated artefact for diff-ability; CI regenerates it each build.

Test plan

npm run build — single + multipage HTML, clean (14 lint warnings)
npm run build-for-pdf + prince-books — renders PDF locally, exit 0
CI green (licensed Prince container produces the PDF artifact)

taleodor-claude added 3 commits

June 2, 2026 22:38


          Build TEA spec from CycloneDX source into ECMA Ecmarkup HTML/PDF

742177e

Adds the publication pipeline so this repository renders the Transparency
Exchange API specification from its upstream source of truth
(CycloneDX/transparency-exchange-api) without that repository owning any
ECMA tooling.

- index.js fetches spec/openapi.yaml and the narrative Markdown files from
  the TEA source repo (tracking main for now; see TODO to pin before the
  first publication build) and assembles spec.html.
- lib/md-to-emu.js converts narrative Markdown to nested emu-clauses;
  lib/openapi-to-emu.js generates the API surface (grouped by tag) and the
  data model from components.schemas.
- excerpts/ carries the hand-authored front/back matter (header, scope,
  conformance, normative references, terms, bibliography, colophon),
  mirroring the ECMA-424 excerpt layout.
- package.json gains generate-spec and mirrors ECMA-424 by defaulting
  build-head to --lint-spec (non-strict); --strict is kept as
  build-head-strict. Parenthesised narrative headings imported from
  Markdown otherwise trip ecmarkup's header-format rule.
- build.yml pins all actions by commit digest with the version in a
  comment, and reads the Node version from .nvmrc.

spec.html is committed as a generated artefact for reviewer diff-ability;
CI regenerates it on every build.


          Document the non-strict lint default next to its cause

81f4843

The default build runs --lint-spec without --strict because parenthesised
narrative headings imported from Markdown trip ecmarkup's header-format
rule. Add a comment at the heading-emission site so the reason lives with
the code, complementing the TEA_SOURCE_REF pin TODO already in index.js.


          Document source selection and OpenAPI extraction in README

a2eceb4

Explain how inputs are pulled from the TEA source repo: the curated,
ordered NARRATIVE_DOCS allowlist (why it is a list and not a glob,
ordering significance, idPrefix-based stable clause IDs, graceful skip on
404), exactly what lib/openapi-to-emu.js extracts from spec/openapi.yaml
(API surface by tag, operation tables, data model from components.schemas,
stable IDs and cross-references), and that only the README Introduction
section is used.

oej self-assigned this

oej requested a review from stevespringett

August 12, 2026 14:45

oej commented Aug 12, 2026

Contributor

After updating dependanot stuff, there's conflicts in this branch. I can't resolve them, sorry.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet