docs(catalog): list official and community AXIs in alphabetical order - #219
leecalcote wants to merge 1 commit into
Conversation
Signed-off-by: Lee Calcote <lee.calcote@layer5.io>
 |
|
Speaking as Kun's firstmate. I read the PR body, the Greptile summary, and the diff intent (alphabetical reorder of official + community catalogs, regenerated README/docs, CONTRIBUTING guidance). VISION.md per-rule verdict
contract-class: opt-in / docs-only for community sort, but the official-catalog edit blocks acceptance of this PR as filed. Decision: closing as out of VISION on the official-catalog rule. A follow-up that only alphabetizes the community list (plus CONTRIBUTING/catalog header guidance for community insertions) would be in scope; please leave No security concern in the diff. No captain flag beyond this close. |
2 participants
Intent
Reorder the Ecosystem AXI implementations in the catalog in README.md alphabetically, then push the feature branch to the fork (leecalcote/axi) and open a PR in upstream (kunchenguid/axi). Both the Official and Community tables are sorted A-Z by AXI name (catalog.yaml is the single source of truth; README.md and docs/index.html are regenerated via pnpm run docs:gen with no hand edits to generated regions). The two duplicate ado-axi community entries are ordered by author as tiebreak (dtabolich before jeffreyhaen). Admission-review comments travel with their superbee and vercel-axi entries. Contributor guidance in catalog.yaml header and CONTRIBUTING.md now asks for alphabetical insertion to keep the order stable.
What Changed
officialandcommunitylists incatalog.yamlA-Z by AXI name. All 90 entries are still there. The twoado-axicommunity entries are ordered by author (dtabolich, then jeffreyhaen), and the admission-review comment blocks moved with theirsuperbeeandvercel-axientries.README.mdanddocs/index.htmlwithpnpm run docs:gen. Nothing in the generated regions was edited by hand.catalog.yamlheader comment and inCONTRIBUTING.md: new entries now go in alphabetical order by name instead of being appended at the end.Risk Assessment
✅ Low: The change only reorders documentation. Parsing both versions shows the same entries before and after (4 official, 86 community, deep-equal). Both lists are strictly A-Z, with author tiebreaks for ado-axi and asana-axi. The superbee and vercel-axi admission comments sit directly above their entries. Every README and docs/index.html diff hunk falls inside the generated catalog regions, and those tables list entries in exactly the catalog.yaml order.
Testing
I ran the real docs generator (
docs:check, adocs:genpass that changed nothing, and its own test file) and a YAML-level check against origin/main. I served the axi.md site locally and loaded it in an isolated headless Chrome. The Official (4) and Community (86) tables render A-Z and match catalog.yaml row for row, with screenshots of the top, the bottom, and the full section. A GitHub-style rendering of the README catalog, captured as a screenshot, shows the same order. Two adversarial runs in a throwaway sandbox also passed: a new entry inserted alphabetically lands in the correct row with nothing else moving, and manually reordered generated rows are rejected bydocs:check. Three scenarios were checked only statically, so they are marked untested: entries preserved compared with origin/main, admission comments attached to their entries, and the contributor guidance text. Every scenario that ran live passed. Pushing to the fork and opening the upstream PR belong to later pipeline phases and were not run here.git diff e15f82d..HEAD -- CONTRIBUTING.md catalog.yaml). Th…~/.no-mistakes/evidence/01M3MZE1R43PF8V9XEYZWQ4X02/site-catalog-official-and-community-top.png)~/.no-mistakes/evidence/01M3MZE1R43PF8V9XEYZWQ4X02/site-catalog-community-bottom-superbee-vercel.png)~/.no-mistakes/evidence/01M3MZE1R43PF8V9XEYZWQ4X02/site-catalog-full-section.png)~/.no-mistakes/evidence/01M3MZE1R43PF8V9XEYZWQ4X02/site-catalog-full-section-middle-crop.png)~/.no-mistakes/evidence/01M3MZE1R43PF8V9XEYZWQ4X02/readme-catalog-rendered-top.png)Evidence: README.md catalog section rendered to HTML
Evidence: Live DOM row order compared with catalog.yaml
rendered official == catalog.yaml official order: true rendered community == catalog.yaml community order: true rendered official sorted: true | rendered community sorted: true | rows: 4 86Evidence: YAML-level verification against origin/main
PASS official: same 4 entries as base (4), every field byte-identical PASS community: same 86 entries as base (86), every field byte-identical PASS official: sorted A-Z by name PASS community: sorted A-Z by name PASS ado-axi duplicates ordered by author: dtabolich before jeffreyhaen PASS every leading comment is attached to the same entry with identical text PASS superbee admission-review comment directly precedes superbee PASS vercel-axi admission-review comment directly precedes vercel-axi PASS README catalog-official: 4 rows in catalog.yaml A-Z order PASS README catalog-community: 86 rows in catalog.yaml A-Z order ALL CHECKS PASSEDEvidence: Verification script used
Evidence: docs:check passes; docs:gen changes nothing
$ pnpm run docs:check docs:check ok — generated regions match their sources exit=0 $ pnpm run docs:gen generated regions already up to date exit=0 $ git status --porcelain README.md docs/index.html catalog.yaml (end)Evidence: Sandbox: new entry inserted alphabetically is rendered in the correct row
Evidence: Sandbox: docs:check rejects manually reordered generated rows
Pipeline
Updates from git push no-mistakes
✅ **intent** - passed
✅ No issues found.
🔧 **Rebase** - 2 issues found → auto-fixed ✅
README.md- merge conflict rebasing onto origin/maincatalog.yaml- merge conflict rebasing onto origin/main🔧 Fix applied.
✅ Re-checked - no issues remain.
catalog.yaml:3- Nothing enforces the new alphabetical order. It depends only on contributors reading the prose guidance. scripts/generate-docs.mjs renderscatalog.officialandcatalog.communityin file order (mdCatalogTable/htmlCatalogRows at lines 255-261), anddocs:checkonly compares the rendered output to catalog.yaml, not the order of entries. Concrete sequence: any community-catalog PR opened before this change follows the old guidance to 'append an entry below', just like docs(catalog): add bun-axi to the community catalog #214, docs(catalog): add gerrit-axi to the community catalog #215 and feat: add router-axi to AXI catalog #216 did. After rebasing, it adds its entry at the end ofcommunityand runspnpm run docs:gen.docs:checkstill passes and the README and axi.md tables quietly fall out of A-Z order. The same unenforced rule appears at CONTRIBUTING.md:41. Neither place states the author tiebreak for duplicate names, which already applies to ado-axi and asana-axi. A durable fix would be an order check inside generate-docs.mjs--check(next to checkTitles), with a behavioral test in scripts/generate-docs.test.mjs. That goes beyond the stated goal of contributor guidance only, so the maintainer should decide whether to add it.✅ **Test** - passed
✅ No issues found.
git diff e15f82d..HEAD -- CONTRIBUTING.md catalog.yaml). Th…pnpm run docs:checkon the branch (exit 0)pnpm run docs:genon the branch: reported 'already up to date';git status --porcelainstayed emptynode verify-catalog.mjs <worktree> catalog.base-origin-main.yaml catalog.yaml: compares the parsed YAML with origin/main (same entries, A-Z order, author tiebreak for duplicate names, comments attached to the same entries, README tables in the same order)Served docs/ atpython3 -m http.server 48717 --bind 127.0.0.1and loaded it withchrome-devtools-axi openin an isolated headless Chrome session; read row order from the live DOM withchrome-devtools-axi evaland compared it with catalog.yamlchrome-devtools-axi screenshotof the site's Official table plus the top of Community, the bottom of Community (superbee through wrangler-axi), and the whole catalog section at full heightRendered the README catalog section with marked and github-markdown-css (installed only in a throwaway temp sandbox), served it locally, checked the DOM order and took a screenshotSandbox: inserted a test entry, kafka-axi, between jj-axi and kubernetes-axi in catalog.yaml, then rannode scripts/generate-docs.mjs --check(expected failure),node scripts/generate-docs.mjs, and--checkagain; diffed the regenerated README.md and docs/index.html against the branchSandbox: swapped the two ado-axi rows in README.md and moved gh-axi above chrome-devtools-axi in docs/index.html, confirmed--checkfails with exit 1 in each case, then confirmed regenerating restores output identical to the branchpnpm run docs:test(generator test file only, 11/11 pass)✅ **Document** - passed
✅ No issues found.
✅ **Lint** - passed
✅ No issues found.
✅ **Push** - passed
✅ No issues found.