fix(oas:sync): match the platform's OAS-upload output (tag index pages, root ordering, slug casing)

[rossrdme]

Problem

oas:sync produced a different tree than uploading the same OAS spec to ReadMe, so a repo initialized by upload drifted after a local sync:

• Tag category pages (<tag>/index.md) were never generated — the tag's description from the spec's top-level tags array was silently dropped.
• The root reference/_order.yaml was never written, losing top-level ordering.
• Slugs kept operationId casing (getUserById.md) where the platform lowercases (getuserbyid.md), diverging page URLs.

Changes

Tag category pages. Generate <tag>/index.md (title = tag name, excerpt = tag description) for every tag in the spec, in its own pass — so it's created even when a tag's operation pages already exist. This backfills category pages for references first synced by an older CLI that didn't generate them, and recreates a deleted one. Never overwrites an existing index.md (hand-written categories are safe); idempotent.

Root ordering + slug casing. Maintain reference/_order.yaml; lowercase generated slugs to match upload output.

Page visibility (hidden). Generated pages are written hidden: false, matching the platform's OAS upload, which always stamps hidden and forces false on a new endpoint even when its tag/siblings are hidden — so the backend default can't be relied on to omit it. A @todo tracks honoring the x-internal extension (gitto#2095 / RM-4616 / CX-3303) once released; the resync-side of that (re-applying x-internal to existing pages, parent hide-ratchet) is intentionally out of scope for this create-only command.

Reference-wide, folder-aware slug uniqueness. Reference page slugs share one flat namespace (docs/ is a separate namespace and is never consulted). A generated slug is uniquified against every slug already in reference/ — both <slug>.md files and category folders (<slug>/index.md) — appending -1, -2, … until free. index is reserved for the tag category page, so an operation whose slug normalizes to index always gets a numbered page (index-1, index-2, …).

Verification

• Clean-room parity: wiped a real ReadMe Git Sync repo's reference/ to just the spec, ran the patched sync, diffed against the platform's actual upload output — identical file trees, byte-identical _order.yaml, matching frontmatter.
• Behavior matrix (empirical): add endpoint to existing tag ✅; add new tag ✅; remove endpoint ✅; upload of an operationId: index spec confirmed the platform itself produces index-1/index-2, matching this PR.
• Backfill: a repo with op pages but no index.md gets the category page on next sync; re-run reports "already in sync".
• Tests: 93/93 (tag index w/ description; root _order.yaml; existing index never overwritten; lowercased slugs; index collision; reference-wide cross-tag uniqueness; category-folder-taken slug; missing-index backfill).

Known follow-ups (out of scope, tracked)

• x-internal visibility resolution (create + resync) — @todo in buildPageContent.
• Empty-tag cleanup (orphaned index.md / stale _order.yaml entry when a tag loses its last operation).

🤖 Generated with Claude Code

[coderabbitai]

Walkthrough

OpenAPI synchronization now generates visible operation pages and per-tag index.md pages with optional tag descriptions. Generated operation slugs are lowercased and allocated uniquely across the reference tree, existing tag indexes are preserved, and root reference ordering includes the specification title. Tests cover frontmatter, tag index generation, ordering behavior, operation collisions, and preservation of existing pages.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

src/commands/oas-sync.js (1)

253-253: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Consider generating tag index pages even when operation pages already exist.

Because this continue skips the rest of the loop for already-synced operations, missing tag category pages (index.md) and their corresponding _order.yaml updates won't be backfilled for tags whose operation pages were generated in previous runs.

If the goal is to fully align with the platform and ensure all tags have an index.md regardless of their operations' page status, consider moving the tag index generation logic (lines 268-277) and the relevant _order.yaml updates above this check.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/commands/oas-sync.js` at line 253, Update the operation-processing loop
so tag index generation and its corresponding _order.yaml updates execute before
the pagesByOpId.has(opId) early continue. Preserve the continue for
already-existing operation pages, while still backfilling missing tag index.md
pages and ordering entries.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/commands/oas-sync.js`:
- Line 257: Update the slug derivation in the operation-page generation flow
around safeSegment to reserve the "index" slug: when the normalized operation
slug equals "index", append a distinct suffix before constructing pagePath,
while preserving existing slugs for all other operations.

---

Nitpick comments:
In `@src/commands/oas-sync.js`:
- Line 253: Update the operation-processing loop so tag index generation and its
corresponding _order.yaml updates execute before the pagesByOpId.has(opId) early
continue. Preserve the continue for already-existing operation pages, while
still backfilling missing tag index.md pages and ordering entries.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: dc454943-2f4a-4b94-9bcc-52610b01a54c

📥 Commits

Reviewing files that changed from the base of the PR and between 7c5c920 and 2c738b2.

📒 Files selected for processing (2)

• src/commands/oas-sync.js
• test/oas-sync.test.js

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

• readmeio/ai (manual)
• readmeio/gitto (manual)
• readmeio/markdown (manual)
• readmeio/readme (manual)

[erunion]

Why do we need to add this in here? Can we rely on the defaults in our backend?

[rossrdme]

Good call — dropped it. Removed the explicit hidden: false from both the generated operation pages and the tag index.md, relying on the backend default. (86bd1b4)

[rossrdme]

Correction on my earlier reply here — I'd said we'd drop this, but after testing the actual UI upload I put hidden: false back (363d3de). The upload always stamps hidden and forces false on a newly-added endpoint even when its tag and all siblings are hidden: true, so the backend isn't inferring false from a missing field that we could safely omit — omitting it would make a synced endpoint diverge from an uploaded one. Kept on both operation pages and the tag index.md. Added an @todo to honor the x-internal extension (gitto#2095 / RM-4616 / CX-3303) once it's out, at which point we can derive visibility from the spec instead of hardcoding false.

[rossrdme]

not ready yet, pushed an update too quickly, standby

[coderabbitai]

🧹 Nitpick comments (1)

src/commands/oas-sync.js (1)

263-297: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Backfill tag index pages and root order entries for existing operations.

Currently, the check if (pagesByOpId.has(opId)) continue; at the beginning of the loop skips the generation of the tag's index.md and updates to the root _order.yaml if the operation page already exists. This means users upgrading to this version won't have tag index pages generated for their existing APIs unless they also add a new operation to that tag.

Consider moving the tag index and root order generation logic above the continue statement. This ensures the directory structure and metadata are fully synchronized for all tags in the specification on the next sync.

♻️ Proposed refactor

   for (const [opId, op] of specOps) {
-    if (pagesByOpId.has(opId)) continue;
-
     const rawTag = op.tag || 'Other';
     const tag = safeSegment(rawTag, 'Other');
     const pageDir = path.join(refDir, infoTitle, tag);
+
+    // Ensure the directory exists so index.md and _order.yaml can be safely written
+    fs.mkdirSync(pageDir, { recursive: true });
+
+    // Generate the tag's category landing page (index.md) if it doesn't exist
+    const indexPath = path.join(pageDir, 'index.md');
+    if (!fs.existsSync(indexPath)) {
+      fs.writeFileSync(indexPath, buildTagIndexContent(rawTag, tagDescriptions.get(rawTag)));
+      changes.added.push(path.relative(refDir, indexPath));
+    }
+
+    // Maintain root and infoTitle order entries for the tag
+    addToOrder(path.join(refDir, infoTitle, '_order.yaml'), tag);
+    addToOrder(path.join(refDir, '_order.yaml'), infoTitle);
+
+    if (pagesByOpId.has(opId)) continue;
+
     const slug = reserveOperationSlug(pageDir, safeSegment(opId, 'operation').toLowerCase());
     const pagePath = path.join(pageDir, `${slug}.md`);

     // Never overwrite an existing file: it belongs to a manual page, another
     // spec, or a different operation whose sanitized name collides with this
     // one. Skipping (rather than clobbering) keeps repeated syncs stable.
     if (!isWithin(refDir, pagePath) || fs.existsSync(pagePath)) {
       changes.skipped.push({ path: path.relative(refDir, pagePath), operationId: opId });
       continue;
     }
-    fs.mkdirSync(pageDir, { recursive: true });

-    // The tag's category landing page (index.md), like the platform generates
-    // on upload. Never overwrite one that already exists.
-    const indexPath = path.join(pageDir, 'index.md');
-    if (!fs.existsSync(indexPath)) {
-      fs.writeFileSync(indexPath, buildTagIndexContent(rawTag, tagDescriptions.get(rawTag)));
-      changes.added.push(path.relative(refDir, indexPath));
-    }
-
     const content = buildPageContent({ oasFilename, operationId: opId });
     fs.writeFileSync(pagePath, content);

     addToOrder(path.join(pageDir, '_order.yaml'), slug);
-    addToOrder(path.join(refDir, infoTitle, '_order.yaml'), tag);
-    addToOrder(path.join(refDir, '_order.yaml'), infoTitle);

     changes.added.push(path.relative(refDir, pagePath));
   }

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/commands/oas-sync.js` around lines 263 - 297, Update the specOps loop so
tag directory/index generation and root/tag _order.yaml updates run for every
operation, including entries already present in pagesByOpId. Move the existing
metadata synchronization around pageDir, indexPath, and addToOrder above the
pagesByOpId continue, while keeping new page creation and changes.added/skipped
handling limited to missing operation pages.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@src/commands/oas-sync.js`:
- Around line 263-297: Update the specOps loop so tag directory/index generation
and root/tag _order.yaml updates run for every operation, including entries
already present in pagesByOpId. Move the existing metadata synchronization
around pageDir, indexPath, and addToOrder above the pagesByOpId continue, while
keeping new page creation and changes.added/skipped handling limited to missing
operation pages.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: cdf1de0c-d18f-4089-822c-1d255e906488

📥 Commits

Reviewing files that changed from the base of the PR and between 2c738b2 and 86bd1b4.

📒 Files selected for processing (2)

• src/commands/oas-sync.js
• test/oas-sync.test.js

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

• readmeio/ai (manual)
• readmeio/gitto (manual)
• readmeio/markdown (manual)
• readmeio/readme (manual)

[rossrdme]

Pushed 363d3de addressing the review. Summary of changes since the last review:

1. hidden: false — kept (not dropped). Testing the UI upload shows it always writes hidden and forces false on a new endpoint regardless of its tag/siblings being hidden, so we can't rely on a backend default here. @todo added to honor x-internal (gitto#2095) when available.
2. Index-slug clobbering — fixed and broadened. Reference-wide, folder-aware slug uniqueness with numeric suffixes; index reserved for the category page. Verified against a real UI upload (index-1/index-2 matches the platform).
3. Tag category index.md backfill. Category-page generation now runs in its own pass over every tag, so references synced by an older CLI (op pages, no index.md) get their category pages on the next sync. Idempotent; never overwrites an existing index.

Out of scope, tracked as follow-ups: full x-internal visibility resolution, and empty-tag cleanup. 93/93 tests; verified end-to-end against a real Git Sync repo.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/commands/oas-sync.js`:
- Around line 227-251: Replace the Set-based slug tracking in
collectReferenceSlugs with lowercase-slug reference counts so duplicate
pages/categories retain their ownership. Update the deletion logic around the
slug release at line 311 to decrement the count and remove the slug only when it
reaches zero. Add a regression covering two existing pages with the same slug
where deleting one leaves that slug reserved by the retained page.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 0688a58f-cab2-4e97-9d5e-5cdfaf317478

📥 Commits

Reviewing files that changed from the base of the PR and between 86bd1b4 and 363d3de.

📒 Files selected for processing (2)

• src/commands/oas-sync.js
• test/oas-sync.test.js

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

• readmeio/ai (manual)
• readmeio/gitto (manual)
• readmeio/markdown (manual)
• readmeio/readme (manual)

[rossrdme]

ok @erunion I believe I have addressed your concerns and coderabbit's concern. Please let me know if anything else persists. Also, I added a new PR, #37 since I noticed some issues when working on that.

Lastly, we're about to ship support for the custom extension that hides endpoints, but I didn't want to address that here since it means some medium-sized changes.

Thanks for all you've done thus far, I'm excited, and please let me know if this PR or #37 still needs work.

[rossrdme]

@erunion this never got merged. I went back over it last night and made some improvements on the oas-sync-upload-parity branch. I'm not sure how to proceed to get proper review.

[erunion]

@greptileai

[greptile-apps]

Confidence Score: 4/5

The PR is not yet safe to merge because deleting a legacy index.md operation can leave an invalid entry in the folder's _order.yaml.

The global slug-release fix correctly frees the folder slug, but it reuses that folder name when cleaning the local order file, whose corresponding operation entry is index; the stale entry therefore survives deletion.

Files Needing Attention: src/commands/oas-sync.js, test/oas-sync.test.js

_{Reviews (5): Last reviewed commit: "fix(oas:sync): release a deleted legacy ..." | Re-trigger Greptile}

[greptile-apps]

Legacy index order stays stale

When a deleted legacy operation is stored as <folder>/index.md, this branch passes the folder name to removeFromOrder, even though the folder's _order.yaml records the operation as index. The page is deleted, but - index remains as a dangling order entry or incorrectly orders a subsequently recreated category page.

Suggested change

	const slug =
	path.basename(page.filePath) === 'index.md'
	? path.basename(pageDir)
	: path.basename(page.filePath, '.md');
	removeFromOrder(path.join(pageDir, '_order.yaml'), slug);
	releaseSlug(takenSlugs, slug);
	const isIndexPage = path.basename(page.filePath) === 'index.md';
	const pageSlug = path.basename(page.filePath, '.md');
	const referenceSlug = isIndexPage ? path.basename(pageDir) : pageSlug;
	removeFromOrder(path.join(pageDir, '_order.yaml'), pageSlug);
	releaseSlug(takenSlugs, referenceSlug);