@readme/cli 0.0.29 → 0.0.30

package/src/commands/oas-sync.js

@@ -56,29 +56,104 @@ function generateOperationId(method, pathStr) {
 }
 
 /**
- * Extract operations from an OAS spec.
- * Returns a Map of operationId -> { summary, description, tag, operationId }.
- * For operations without an operationId, a synthetic one is generated from the method and path.
+ * Identity key for an operation record (or an existing page's frontmatter),
+ * used everywhere operations/pages are looked up by operationId. `paths` and
+ * `webhooks` are separate namespaces in an OAS document, but both can have
+ * operationId omitted, so their synthetic `<method>_<name>` ids can
+ * legitimately collide (e.g. `POST /orders` and webhook `POST orders` both
+ * synthesize to `post_orders`) — the isWebhook flag disambiguates them so
+ * neither silently overwrites the other in an operationId-only Map.
+ */
+export function operationKey({ operationId, isWebhook }) {
+  return `${isWebhook ? 'webhook' : 'path'}:${operationId}`;
+}
+
+/**
+ * Resolve a `paths`/`webhooks` entry that's a Reference Object (OAS 3.1,
+ * `{ $ref: '#/components/pathItems/Name' }`) against the spec's own
+ * `components.pathItems`, following chained refs (a pathItem that is itself
+ * a $ref to another) until a literal Path Item is reached. Only same-document
+ * refs in that exact form are supported; anything else (external files,
+ * other pointer shapes, an unresolvable name, or a cycle) is left unresolved
+ * and quietly skipped by the caller, same as before this existed.
+ */
+function resolveLocalPathItemRef(entry, spec) {
+  const seen = new Set();
+  let current = entry;
+  // Sibling fields (e.g. an inline operation) alongside a $ref are explicitly
+  // allowed in an OAS 3.1 Path Item Object — accumulate them from every hop
+  // in the chain so they aren't discarded once $ref is followed. A field
+  // declared at an outer/earlier hop wins over the same field found deeper
+  // in the chain (OAS itself leaves this "undefined" when both define it).
+  let overrides = {};
+  const finish = () => ({ ...current, ...overrides });
+
+  while (current && typeof current.$ref === 'string') {
+    const { $ref, ...siblings } = current;
+    overrides = { ...siblings, ...overrides };
+
+    if (seen.has(current.$ref)) return finish();
+    seen.add(current.$ref);
+
+    const match = current.$ref.match(/^#\/components\/pathItems\/(.+)$/);
+    if (!match) return finish();
+
+    let name;
+    try {
+      name = decodeURIComponent(match[1]).replace(/~1/g, '/').replace(/~0/g, '~');
+    } catch {
+      // Malformed percent-escape — leave unresolved rather than throwing and
+      // aborting the whole sync/lint run over one bad $ref.
+      return finish();
+    }
+    const resolved = spec.components?.pathItems?.[name];
+    if (!resolved) return finish();
+
+    current = resolved;
+  }
+
+  return finish();
+}
+
+/**
+ * Extract operations from an OAS spec's `paths`, plus its OAS 3.1 `webhooks`
+ * (callouts the API itself makes to a client-registered URL, not endpoints the
+ * API exposes — a separate top-level sibling of `paths` with the same
+ * Operation Object shape). The platform pages a webhook the same way it pages
+ * a path operation: a synthetic `post_<name>` operationId when none is given,
+ * grouped by its own tag or, absent one, its own category keyed by its raw
+ * name — never merged with `paths` operations of the same name.
+ * Returns a Map keyed by `operationKey()` -> { summary, description, tag,
+ * path, operationId, isWebhook }. For operations without an operationId, a
+ * synthetic one is generated from the method and path (or webhook name).
  */
 export function extractOperations(spec) {
   const ops = new Map();
-  const paths = spec.paths || {};
 
-  for (const [pathStr, methods] of Object.entries(paths)) {
-    for (const [method, operation] of Object.entries(methods)) {
-      if (!HTTP_METHODS.has(method)) continue;
+  function collect(entries, isWebhook) {
+    for (const [pathStr, rawItem] of Object.entries(entries)) {
+      const methods = resolveLocalPathItemRef(rawItem, spec);
+
+      for (const [method, operation] of Object.entries(methods)) {
+        if (!HTTP_METHODS.has(method)) continue;
 
-      const operationId = operation.operationId || generateOperationId(method, pathStr);
+        const operationId = operation.operationId || generateOperationId(method, pathStr);
 
-      ops.set(operationId, {
-        operationId,
-        summary: operation.summary || null,
-        description: operation.description || null,
-        tag: (operation.tags && operation.tags[0]) || null,
-      });
+        ops.set(operationKey({ operationId, isWebhook }), {
+          operationId,
+          summary: operation.summary || null,
+          description: operation.description || null,
+          tag: (operation.tags && operation.tags[0]) || null,
+          path: pathStr,
+          isWebhook,
+        });
+      }
     }
   }
 
+  collect(spec.paths || {}, false);
+  collect(spec.webhooks || {}, true);
+
   return ops;
 }
 
@@ -179,21 +254,156 @@ function isWithin(baseDir, target) {
   );
 }
 
-function buildPageContent({ oasFilename, operationId }) {
+/**
+ * Render a frontmatter-only page. `matter.stringify` always appends a blank
+ * body after the closing fence (even for an empty body); the platform's own
+ * generated pages end immediately after the fence with no trailing newline,
+ * so trim it to match.
+ */
+function stringifyFrontmatter(frontmatter) {
+  return matter.stringify('', frontmatter).replace(/\n+$/, '');
+}
+
+function buildPageContent({ oasFilename, operationId, isWebhook }) {
   const frontmatter = {
     api: {
       file: oasFilename,
       operationId,
+      // Marks the page as a webhook (the API calling out to the client)
+      // rather than a path operation (the client calling the API), matching
+      // what the platform stamps on a page generated from `webhooks`.
+      ...(isWebhook ? { webhook: true } : {}),
     },
+    // Mirror the platform's OAS-upload behavior: a newly added endpoint is
+    // always written `hidden: false`, even when its tag and siblings are
+    // `hidden: true`. The backend does not infer this from a missing field, so
+    // it must be written explicitly.
+    //
+    // @todo Honor the `x-internal` OpenAPI extension for page visibility, to
+    // match gitto#2095 (RM-4616 / CX-3303): resolve `hidden` from operation-level
+    // `x-internal`, falling back to root-level, else false; and hide a tag's
+    // index page when all of its operations are `x-internal: true`. Deferred to
+    // keep oas:sync create-only — the resync-side rules (re-applying x-internal
+    // to existing pages, parent hide-ratchet) would require mutating existing
+    // pages, which this command intentionally never does.
+    hidden: false,
   };
 
-  return matter.stringify('', frontmatter);
+  return stringifyFrontmatter(frontmatter);
+}
+
+/**
+ * Build a category landing page (mirrors what the ReadMe platform generates on
+ * OAS upload): `title` is the tag name for a tagged group, or the raw path for
+ * an untagged path-derived group (see `operationGroup`); `excerpt`, when given,
+ * is the tag's description from the spec's top-level `tags` array.
+ */
+function buildTagIndexContent(title, description) {
+  const frontmatter = { title };
+  if (description) frontmatter.excerpt = description;
+  // As with operation pages, upload always stamps hidden: false on new pages.
+  frontmatter.hidden = false;
+
+  return stringifyFrontmatter(frontmatter);
+}
+
+/**
+ * The category-folder grouping for an operation. A tagged operation groups
+ * under its own tag, as before. An untagged operation groups under a folder
+ * derived from its path, with the raw path as the category page's title — one
+ * folder per unique path, not a single shared bucket. This mirrors the
+ * platform's own OAS-upload output: untagged operations are never lumped into
+ * one "Other" folder.
+ */
+function operationGroup(op) {
+  if (op.tag) return { folder: safeSegment(op.tag, 'Other').toLowerCase(), title: op.tag };
+  const folder = safeSegment(op.path.replace(/[/{}]/g, ''), 'operation').toLowerCase();
+  return { folder, title: op.path };
+}
+
+/**
+ * Collect every slug already used across the entire reference/ tree, as a
+ * lowercase-slug -> owner-count map. Reference page slugs share one flat
+ * namespace (docs/ is a separate namespace and is not consulted), so a
+ * generated operation slug must be unique against all of them. A page's slug
+ * is its filename without `.md`; a category page's slug (a folder containing
+ * `index.md`) is the folder name.
+ *
+ * A count, not a Set, because two existing pages or folders can already share
+ * a slug (hand-authored content, or content that predates this uniqueness
+ * logic) — a Set would collapse them to one entry, and releasing one owner
+ * (see `releaseSlug`) would incorrectly free the slug while the other owner
+ * still holds it.
+ */
+function collectReferenceSlugs(refDir) {
+  const counts = new Map();
+
+  function walk(dir) {
+    for (const entry of fs.readdirSync(dir)) {
+      const full = path.join(dir, entry);
+      let stat;
+      try {
+        stat = fs.statSync(full);
+      } catch {
+        continue;
+      }
+      if (stat.isDirectory()) {
+        walk(full);
+      } else if (entry.endsWith('.md')) {
+        // A folder's index.md contributes the folder name as a slug; any other
+        // page contributes its own filename.
+        const slug = entry === 'index.md' ? path.basename(dir) : path.basename(entry, '.md');
+        takeSlug(counts, slug);
+      }
+    }
+  }
+
+  walk(refDir);
+  return counts;
+}
+
+function isSlugTaken(takenSlugs, slug) {
+  return (takenSlugs.get(slug.toLowerCase()) || 0) > 0;
+}
+
+/** Record one more owner of `slug`. */
+function takeSlug(takenSlugs, slug) {
+  const key = slug.toLowerCase();
+  takenSlugs.set(key, (takenSlugs.get(key) || 0) + 1);
+}
+
+/** Record one fewer owner of `slug`; only fully frees it once every owner is gone. */
+function releaseSlug(takenSlugs, slug) {
+  const key = slug.toLowerCase();
+  const remaining = (takenSlugs.get(key) || 0) - 1;
+  if (remaining > 0) takenSlugs.set(key, remaining);
+  else takenSlugs.delete(key);
+}
+
+/**
+ * Reserve a unique reference slug. `index` is never usable by an operation (it's
+ * reserved for the tag category page), and any slug already present in the
+ * reference namespace gets a numeric suffix (`-1`, `-2`, ...) until it's free.
+ * The chosen slug gains an owner in `takenSlugs` so later operations see it.
+ */
+function reserveSlug(takenSlugs, base) {
+  let chosen = base;
+  if (base === 'index' || isSlugTaken(takenSlugs, base)) {
+    let n = 1;
+    while (isSlugTaken(takenSlugs, `${base}-${n}`)) n += 1;
+    chosen = `${base}-${n}`;
+  }
+  takeSlug(takenSlugs, chosen);
+  return chosen;
 }
 
 /**
  * Run the sync for a single OAS file. Returns changes for that file.
+ *
+ * `takenSlugs` is the reference-wide set of slugs already in use; it is read and
+ * mutated so slugs stay unique across every spec processed in one sync run.
  */
-function syncOneOas(refDir, oasFilename, spec) {
+function syncOneOas(refDir, oasFilename, spec, takenSlugs) {
   const specOps = extractOperations(spec);
   const infoTitle = safeSegment(
     spec.info?.title || path.basename(oasFilename, path.extname(oasFilename)),
@@ -206,48 +416,120 @@ function syncOneOas(refDir, oasFilename, spec) {
 
   const pagesByOpId = new Map();
   for (const page of existingPages) {
-    pagesByOpId.set(page.data.api.operationId, page);
+    pagesByOpId.set(
+      operationKey({ operationId: page.data.api.operationId, isWebhook: !!page.data.api.webhook }),
+      page,
+    );
   }
 
   const changes = { added: [], deleted: [], skipped: [] };
 
+  // Tag descriptions from the spec's top-level `tags` array, used for the
+  // per-tag category landing page (index.md).
+  const tagDescriptions = new Map(
+    (Array.isArray(spec.tags) ? spec.tags : [])
+      .filter((t) => t && t.name)
+      .map((t) => [t.name, t.description || null]),
+  );
+
   // Deletes: pages referencing operations that no longer exist.
   for (const [opId, page] of pagesByOpId) {
     if (!specOps.has(opId)) {
       fs.unlinkSync(page.filePath);
 
       const pageDir = path.dirname(page.filePath);
-      const slug = path.basename(page.filePath, '.md');
-      removeFromOrder(path.join(pageDir, '_order.yaml'), slug);
+      // A legacy operation page can be literally named index.md (predating
+      // the "index is reserved for the category page" convention). Two
+      // different things need two different values here: pageSlug is what a
+      // pre-refactor tool would have actually written into pageDir's own
+      // _order.yaml ("index", the filename) — that's what removeFromOrder
+      // must remove. referenceSlug is what the reference-wide slug map
+      // reserved for it (its folder name, like any index.md — see
+      // collectReferenceSlugs) — that's what releaseSlug must free.
+      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);
 
       changes.deleted.push(page.relativePath);
     }
   }
 
-  // Adds: operations with no page yet. Title/excerpt are owned by the OAS spec
-  // at render time, so generated pages carry only the api reference.
-  for (const [opId, op] of specOps) {
-    if (pagesByOpId.has(opId)) continue;
+  // Ensure every group (a tag, or a path-derived bucket for untagged
+  // operations) present in the spec has its category landing page (index.md)
+  // and is ordered — independent of whether its operation pages are new. Doing
+  // this as its own pass (rather than only when creating a new op page) backfills
+  // category pages for references first synced by a CLI version that didn't
+  // generate them, and recreates one that was deleted.
+  const groupsByFolder = new Map();
+  for (const op of specOps.values()) {
+    const { folder, title } = operationGroup(op);
+    if (!groupsByFolder.has(folder)) {
+      groupsByFolder.set(folder, { title, description: op.tag ? tagDescriptions.get(op.tag) : null });
+    }
+  }
+
+  // Order groups the way the platform does: a tag keeps the position it's
+  // declared in the spec's own top-level `tags` array, not the order its
+  // operations happen to appear in `paths`. A group with no declared position
+  // (an untagged path-derived group, or a tag used by an operation but never
+  // listed in `tags`) keeps its natural encounter order, appended after every
+  // declared tag.
+  const declaredOrder = (Array.isArray(spec.tags) ? spec.tags : [])
+    .filter((t) => t && t.name)
+    .map((t) => safeSegment(t.name, 'Other').toLowerCase());
+  const orderedFolders = [
+    ...declaredOrder.filter((folder) => groupsByFolder.has(folder)),
+    ...[...groupsByFolder.keys()].filter((folder) => !declaredOrder.includes(folder)),
+  ];
+
+  for (const folder of orderedFolders) {
+    const { title, description } = groupsByFolder.get(folder);
+    const pageDir = path.join(refDir, infoTitle, folder);
+    if (!isWithin(refDir, pageDir)) continue;
+
+    const indexPath = path.join(pageDir, 'index.md');
+    if (!fs.existsSync(indexPath)) {
+      // Never overwrite an existing index.md — it may be a hand-written category.
+      fs.mkdirSync(pageDir, { recursive: true });
+      fs.writeFileSync(indexPath, buildTagIndexContent(title, description));
+      changes.added.push(path.relative(refDir, indexPath));
+      // The category page's slug is the folder name; reserve it so no operation
+      // takes it. Only when just-created — an existing index.md was already
+      // counted by collectReferenceSlugs's initial disk walk.
+      takeSlug(takenSlugs, folder);
+    }
+    addToOrder(path.join(refDir, infoTitle, '_order.yaml'), folder);
+    addToOrder(path.join(refDir, '_order.yaml'), infoTitle);
+  }
 
-    const tag = safeSegment(op.tag || 'Other', 'Other');
-    const slug = safeSegment(opId, 'operation');
-    const pageDir = path.join(refDir, infoTitle, tag);
+  // Adds: operation pages with no page yet. Title/excerpt are owned by the OAS
+  // spec at render time, so generated pages carry only the api reference. Slugs
+  // are lowercased to match the platform's OAS-upload output.
+  for (const [key, op] of specOps) {
+    if (pagesByOpId.has(key)) continue;
+
+    const { folder } = operationGroup(op);
+    const pageDir = path.join(refDir, infoTitle, folder);
+    // Reference slugs share one flat namespace, so uniquify against every slug
+    // already in reference/ — a collision (or the reserved `index` slug) gets a
+    // numeric suffix rather than being skipped.
+    const slug = reserveSlug(takenSlugs, safeSegment(op.operationId, '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.
+    // Guard against a spec-crafted name escaping reference/, or a stale slug set
+    // vs. disk. reserveSlug already prevents slug collisions.
     if (!isWithin(refDir, pagePath) || fs.existsSync(pagePath)) {
-      changes.skipped.push({ path: path.relative(refDir, pagePath), operationId: opId });
+      changes.skipped.push({ path: path.relative(refDir, pagePath), operationId: op.operationId });
       continue;
     }
     fs.mkdirSync(pageDir, { recursive: true });
 
-    const content = buildPageContent({ oasFilename, operationId: opId });
+    const content = buildPageContent({ oasFilename, operationId: op.operationId, isWebhook: op.isWebhook });
     fs.writeFileSync(pagePath, content);
 
     addToOrder(path.join(pageDir, '_order.yaml'), slug);
-    addToOrder(path.join(refDir, infoTitle, '_order.yaml'), tag);
 
     changes.added.push(path.relative(refDir, pagePath));
   }
@@ -275,11 +557,14 @@ export function syncOas(input) {
   const oasFiles = findOasFiles(refDir);
   if (oasFiles.length === 0) return null;
 
+  // Reference slugs share one flat namespace across every spec, so build the set
+  // of in-use slugs once and let each spec read/extend it.
+  const takenSlugs = collectReferenceSlugs(refDir);
   const allChanges = [];
 
   for (const { filename, spec } of oasFiles) {
     const ops = extractOperations(spec);
-    const changes = syncOneOas(refDir, filename, spec);
+    const changes = syncOneOas(refDir, filename, spec, takenSlugs);
     allChanges.push({ filename, spec, opCount: ops.size, changes });
   }
 

package/src/utils/lint.js

@@ -1,6 +1,6 @@
 import fs from 'node:fs'
 import path from 'node:path'
-import { pathToFileURL } from 'node:url'
+import { pathToFileURL, fileURLToPath } from 'node:url'
 
 const TARGET_PATTERNS = [
   { dir: 'custom_blocks', ext: ['.mdx', '.md'] },
@@ -38,7 +38,7 @@ export function collectFiles(gitRoot) {
  * `validateAll()` for cross-file checks (like ordering).
  */
 async function loadValidators() {
-  const validatorsDir = path.join(path.dirname(new URL(import.meta.url).pathname), '..', 'validators')
+  const validatorsDir = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'validators')
   const files = fs.readdirSync(validatorsDir).filter((f) => f.endsWith('.js'))
   const validators = []
 

package/src/utils/llms.test.js

@@ -140,6 +140,51 @@ test('parseLlmsTxt: items with no H2 fall into implicit Resources section', () =
   assert.equal(result.sections[0].title, 'Resources')
 })
 
+test('parseLlmsTxt: strips trailing (section) markers from H2 titles', () => {
+  const body = [
+    '# My Docs',
+    '',
+    '## getting-started (section)',
+    '- [Overview](https://docs.example.com/overview)',
+    '',
+    '## API Reference (SECTION)',
+    '- [Pets](https://docs.example.com/pets)',
+    '',
+    '## Guides (section) extra',
+    '- [Install](https://docs.example.com/install)',
+  ].join('\n')
+
+  const result = parseLlmsTxt(body, BASE)
+  assert.deepEqual(
+    result.sections.map((s) => s.title),
+    ['getting-started', 'API Reference', 'Guides (section) extra'],
+  )
+})
+
+test('parseLlmsTxt: strips (section) markers when falling back to H3 headings', () => {
+  const manyItems = Array.from({ length: 201 }, (_, i) => `- [Page ${i}](https://docs.example.com/page-${i})`).join('\n')
+  const body = [
+    '# Big Site',
+    '',
+    '## Docs',
+    manyItems,
+    '',
+    '### getting-started (section)',
+    '- [A1](https://docs.example.com/a1)',
+    '',
+    '### Reference (section)',
+    '- [B1](https://docs.example.com/b1)',
+  ].join('\n')
+
+  const result = parseLlmsTxt(body, BASE)
+  assert.equal(result.h3Fallback, true)
+  const titles = result.sections.map((s) => s.title)
+  assert.ok(titles.includes('getting-started'))
+  assert.ok(titles.includes('Reference'))
+  assert.ok(!titles.includes('getting-started (section)'))
+  assert.ok(!titles.includes('Reference (section)'))
+})
+
 // ---------------------------------------------------------------------------
 // parseLlmsTxt — H3 fallback
 // ---------------------------------------------------------------------------

package/src/utils/reporter.js

@@ -2,6 +2,7 @@ import { execSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
 import ora from "ora";
 import * as styles from "./styles.js";
 import { hasClaude } from "./claude.js";
@@ -177,7 +178,7 @@ export function createHumanReporter() {
       // When running inside Claude, output instructions and structured issue list.
       if (isRunningInClaude && unfixed.length > 0) {
         const cliRoot = path.join(
-          path.dirname(new URL(import.meta.url).pathname),
+          path.dirname(fileURLToPath(import.meta.url)),
           "../..",
         );
 

package/src/utils/slug-for-entry.js

@@ -0,0 +1,16 @@
+import path from 'node:path';
+
+/**
+ * Canonical slug for a git-format page path. `index.md`/`index.mdx` carries
+ * its parent folder's slug (e.g. `docs/a/setup/index.md` → "setup", matching
+ * how gitto slugs a folder from its index page); any other file is its
+ * filename minus the extension. A root-level index file falls back to "index".
+ */
+export function slugForEntry(relPath) {
+  const filename = path.basename(relPath);
+  if (filename === 'index.md' || filename === 'index.mdx') {
+    const parentDir = path.basename(path.dirname(relPath));
+    return parentDir && parentDir !== '.' && parentDir !== path.sep ? parentDir : 'index';
+  }
+  return filename.replace(/\.(md|mdx)$/, '');
+}

package/src/validators/components.js

@@ -135,19 +135,22 @@ export function validate({ content, relativePath }) {
 
   const results = [];
 
-  // .md snippet files: filename must be PascalCase (it becomes the component tag).
+  // .md snippet files: the filename becomes a component tag <Name />, so it must
+  // be a valid JS identifier starting with an uppercase letter. Underscores and
+  // digits are fine (<Helm_v4_error /> is valid); hyphens and a lowercase initial
+  // are not.
   if (isMd) {
     const slug = filename.replace(/\.md$/, "");
-    const pascalCase = slug
-      .split(/[-_]/)
-      .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
-      .join("");
-    if (slug !== pascalCase) {
+    if (!/^[A-Z][A-Za-z0-9_$]*$/.test(slug)) {
+      const suggestion = slug
+        .split(/[-_]/)
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join("");
       results.push({
         file: relativePath,
         rule: name,
         severity: "warning",
-        message: `Bad filename: should be PascalCase — rename to "${pascalCase}.md" so it can be used as <${pascalCase} />`,
+        message: `Bad filename: "${slug}" can't be used as a component tag — rename to "${suggestion}.md" so it can be used as <${suggestion} />`,
       });
     }
     return results.length > 0 ? results : null;

package/src/validators/duplicates.js

@@ -1,4 +1,5 @@
 import path from 'node:path';
+import { slugForEntry } from '../utils/slug-for-entry.js';
 
 export const name = 'duplicates';
 
@@ -14,10 +15,7 @@ export function validateAll(files) {
     const topDir = relPath.split('/')[0];
     if (!CHECKED_DIRS.includes(topDir)) continue;
 
-    const filename = path.basename(relPath);
-    if (filename === 'index.md' || filename === 'index.mdx') continue;
-
-    const slug = filename.replace(/\.(md|mdx)$/, '');
+    const slug = slugForEntry(relPath);
     const key = `${topDir}:${slug}`;
     if (!slugMap.has(key)) slugMap.set(key, []);
     slugMap.get(key).push(relPath);

package/src/validators/links.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import matter from 'gray-matter';
+import { slugForEntry } from '../utils/slug-for-entry.js';
 
 export const name = 'links';
 
@@ -19,14 +20,7 @@ function collectSlugs(gitRoot) {
     const entries = fs.readdirSync(dirPath, { recursive: true });
     for (const entry of entries) {
       if (!/\.(md|mdx)$/.test(entry)) continue;
-      const filename = path.basename(entry);
-      if (filename === 'index.md' || filename === 'index.mdx') {
-        // index.md represents the parent directory, e.g. plans-and-pricing/index.md -> slug "plans-and-pricing"
-        const parentDir = path.basename(path.dirname(entry));
-        if (parentDir && parentDir !== '.') slugs.add(parentDir);
-      } else {
-        slugs.add(filename.replace(/\.(md|mdx)$/, ''));
-      }
+      slugs.add(slugForEntry(entry));
     }
   }
 

package/src/validators/oas-reference.js

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import matter from 'gray-matter';
-import { findOasFiles, extractOperations, collectExistingPages, syncOas } from '../commands/oas-sync.js';
+import { findOasFiles, extractOperations, collectExistingPages, syncOas, operationKey } from '../commands/oas-sync.js';
 
 export const name = 'oas-reference';
 
@@ -34,6 +34,7 @@ export function validateAll(files, gitRoot, { fix } = {}) {
 
     const oasFilename = data.api.file;
     const operationId = data.api.operationId;
+    const isWebhook = !!data.api.webhook;
     const oas = oasMap.get(oasFilename);
 
     // Check: OAS file doesn't exist.
@@ -50,7 +51,7 @@ export function validateAll(files, gitRoot, { fix } = {}) {
     if (!operationId) continue;
 
     // Check: operationId doesn't exist in the spec.
-    if (!oas.ops.has(operationId)) {
+    if (!oas.ops.has(operationKey({ operationId, isWebhook }))) {
       results.push({
         file: relPath,
         rule: name,
@@ -67,15 +68,19 @@ export function validateAll(files, gitRoot, { fix } = {}) {
   const existingPages = collectExistingPages(refDir);
   for (const [oasFilename, { ops }] of oasMap) {
     const pagesForOas = existingPages.filter((p) => p.data.api.file === oasFilename);
-    const coveredOps = new Set(pagesForOas.map((p) => p.data.api.operationId));
-
-    for (const [opId] of ops) {
-      if (!coveredOps.has(opId)) {
+    const coveredOps = new Set(
+      pagesForOas.map((p) =>
+        operationKey({ operationId: p.data.api.operationId, isWebhook: !!p.data.api.webhook }),
+      ),
+    );
+
+    for (const op of ops.values()) {
+      if (!coveredOps.has(operationKey(op))) {
         results.push({
           file: `reference/${oasFilename}`,
           rule: name,
           severity: 'warning',
-          message: `Missing page: no reference page found for operation "${opId}"`,
+          message: `Missing page: no reference page found for operation "${op.operationId}"`,
           fixable: true,
         });
       }