@readme/cli 0.0.29 → 0.0.31

package/src/commands/oas-validate.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import OASNormalize from 'oas-normalize';
 import { findOasFiles, extractOperations } from './oas-sync.js';
 import * as styles from '../utils/styles.js';
+import { writeGithubActionsOutputs } from '../utils/gha-output.js';
 
 export const command = 'oas:validate';
 export const order = 3;
@@ -182,6 +183,13 @@ export async function run(options, _cmd, ctx) {
 
   if (!fs.existsSync(refDir)) {
     styles.error('No reference/ directory found.');
+    writeGithubActionsOutputs({
+      'has-errors': 'true',
+      'total-errors': '0',
+      'total-warnings': '0',
+      'total-valid': '0',
+      'file-count': '0',
+    });
     process.exit(1);
   }
 
@@ -189,11 +197,26 @@ export async function run(options, _cmd, ctx) {
 
   if (!result) {
     styles.info('No OpenAPI spec files found in reference/.');
+    writeGithubActionsOutputs({
+      'has-errors': 'false',
+      'total-errors': '0',
+      'total-warnings': '0',
+      'total-valid': '0',
+      'file-count': '0',
+    });
     return;
   }
 
   const { totalErrors, totalWarnings, totalValid, fileCount } = result;
 
+  writeGithubActionsOutputs({
+    'has-errors': String(totalErrors > 0),
+    'total-errors': String(totalErrors),
+    'total-warnings': String(totalWarnings),
+    'total-valid': String(totalValid),
+    'file-count': String(fileCount),
+  });
+
   console.log();
   if (totalErrors > 0) {
     const parts = [`${totalErrors} ${totalErrors === 1 ? 'error' : 'errors'}`];

package/src/gha-pre.js

@@ -0,0 +1,29 @@
+// Pre step for the readmeio/cli GitHub Action (see action.yml's runs.pre).
+//
+// dist-gha/index.js (built by the build:gha script) excludes @readme/markdown
+// from its bundle: it's a ~25MB package with 50+ dependencies (including
+// tailwindcss and postcss) pulled in for one narrow helper the "lint" command
+// uses, mdxishTags, and bundling it whole breaks on its embedded CSS/asset
+// references. Rather than vendoring that whole tree into this repo, this step
+// installs just that one package into the action's own directory immediately
+// before dist-gha/index.js runs, so plain Node module resolution finds it.
+//
+// GITHUB_ACTION_PATH looked like the natural way to find that directory (and
+// is what a version of this file first tried), but it came back undefined
+// when actually tested on a real Actions runner. import.meta.dirname doesn't
+// depend on the runner setting anything at all -- it's just "where is this
+// file" -- and it's the same approach readmeio/rdme's own pre-step
+// (bin/write-gha-pjson.js) already uses.
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+
+const actionPath = path.resolve(import.meta.dirname, '..');
+const pkg = JSON.parse(readFileSync(path.join(actionPath, 'package.json'), 'utf-8'));
+const range = pkg.dependencies['@readme/markdown'];
+
+execFileSync(
+  'npm',
+  ['install', '--no-save', '--no-audit', '--no-fund', '--prefix', actionPath, `@readme/markdown@${range}`],
+  { stdio: 'inherit' },
+);

package/src/gha.js

@@ -0,0 +1,104 @@
+// Entrypoint for the readmeio/cli GitHub Action. Deliberately does NOT go
+// through src/cli.js — that bootstraps the full CLI by scanning src/commands/
+// on disk at runtime (fs.readdirSync + dynamic import), which a bundler can't
+// follow statically. This file instead imports just the three commands the
+// Action exposes directly, so `ncc build` can produce one dependency-free
+// file with no runtime install step (see package.json's build:gha script).
+//
+// Takes one input, `readme` (env var INPUT_README per GitHub Actions'
+// convention), a plain command string such as "lint" or
+// "oas:validate --dereference". Split into a command name and flags; there's
+// no need for a full argument parser since each of these three commands only
+// ever takes simple boolean flags.
+//
+// Each command's own run() already writes its structured results (has-errors,
+// skipped-count, etc.) to GITHUB_OUTPUT itself, via utils/gha-output.js's
+// GITHUB_ACTIONS-detecting helper — so this file just needs to call run() and
+// let it do what it already does, exit code included.
+
+import * as lint from './commands/lint.js';
+import * as oasValidate from './commands/oas-validate.js';
+import * as oasSync from './commands/oas-sync.js';
+import { writeGithubActionsOutputs } from './utils/gha-output.js';
+
+// Each command's run(options, cmd, ctx) only ever reads specific boolean
+// flags off `options` (confirmed by reading all three) and never uses `cmd`
+// (the commander Command instance normal CLI invocation would pass) — so a
+// plain options object and a null cmd are enough here.
+const COMMANDS = {
+  'lint': { run: lint.run, flags: ['json', 'github', 'fix'] },
+  'validate': { run: lint.run, flags: ['json', 'github', 'fix'] }, // alias, matches src/commands/lint.js
+  'oas:validate': { run: oasValidate.run, flags: ['dereference'] },
+  'oas:sync': { run: oasSync.run, flags: [] },
+};
+
+function parseInput(input) {
+  const tokens = input.trim().split(/\s+/).filter(Boolean);
+  const [command, ...rest] = tokens;
+  return { command, rest };
+}
+
+export async function run() {
+  const input = process.env.INPUT_README || '';
+  const { command, rest } = parseInput(input);
+
+  const entry = COMMANDS[command];
+  if (!entry) {
+    console.error(
+      `::error::Unknown or unsupported command "${command || '(empty)'}" for the \`readme\` input. ` +
+        `Supported: ${[...new Set(Object.keys(COMMANDS).filter((k) => k !== 'validate'))].join(', ')}.`,
+    );
+    writeGithubActionsOutputs({ 'has-errors': 'true' });
+    process.exit(1);
+  }
+
+  // Every trailing token must be exactly "--<a supported flag>" — anything
+  // else (a short option like "-d", a malformed token, a misspelled flag)
+  // is rejected rather than silently dropped. An earlier version of this
+  // only checked tokens that already happened to start with "--", which let
+  // anything shaped differently (like "-d") skip validation entirely and
+  // run the command with default options with no indication anything was
+  // wrong.
+  const flags = new Set();
+  const badTokens = [];
+  for (const token of rest) {
+    const flag = token.startsWith('--') ? token.slice(2) : null;
+    if (flag && entry.flags.includes(flag)) {
+      flags.add(flag);
+    } else {
+      badTokens.push(token);
+    }
+  }
+
+  if (badTokens.length > 0) {
+    console.error(
+      `::error::Unknown option${badTokens.length > 1 ? 's' : ''} ${badTokens.map((t) => `"${t}"`).join(', ')} for "${command}". ` +
+        `Supported: ${entry.flags.length > 0 ? entry.flags.map((f) => `--${f}`).join(', ') : '(none)'}.`,
+    );
+    writeGithubActionsOutputs({ 'has-errors': 'true' });
+    process.exit(1);
+  }
+
+  const options = {};
+  for (const flag of entry.flags) options[flag] = flags.has(flag);
+
+  // The customer's repo, checked out by their own workflow before this
+  // action runs — not this action's own (separately checked-out) source.
+  const gitRoot = process.env.GITHUB_WORKSPACE || process.cwd();
+
+  await entry.run(options, null, { gitRoot });
+}
+
+run().catch((err) => {
+  console.error(err);
+  // A thrown error (as opposed to a command's own controlled process.exit)
+  // means whatever run() was doing never reached its own
+  // writeGithubActionsOutputs call, so this is the last chance to publish
+  // has-errors — without it, a downstream `if: always()` step would see an
+  // empty string, on exactly the failure path where that check matters
+  // most. Command-specific fields (skipped-count, results, etc.) aren't
+  // meaningful here since they were never computed, so has-errors is all
+  // this can honestly guarantee.
+  writeGithubActionsOutputs({ 'has-errors': 'true' });
+  process.exit(1);
+});

package/src/utils/gha-output.js

@@ -0,0 +1,32 @@
+import { randomUUID } from 'node:crypto';
+import fs from 'node:fs';
+
+/**
+ * Writes each field as a GitHub Actions step output, so a workflow can read
+ * e.g. `steps.sync.outputs.skipped-count` instead of scraping printed text.
+ * A no-op anywhere else (a plain local CLI run, or CI systems other than
+ * GitHub Actions), detected the same way GitHub's own `@actions/core`
+ * toolkit does: the `GITHUB_ACTIONS` env var GitHub sets on every runner,
+ * plus the `GITHUB_OUTPUT` file path it provides for the current step.
+ *
+ * @param {Record<string, string | object | Array<unknown>>} fields  Values are
+ *   written as-is if already a string, JSON-stringified otherwise.
+ */
+export function writeGithubActionsOutputs(fields) {
+  if (process.env.GITHUB_ACTIONS !== 'true') return;
+  const outputPath = process.env.GITHUB_OUTPUT;
+  if (!outputPath) return;
+
+  const lines = Object.entries(fields).map(([name, value]) => {
+    const text = typeof value === 'string' ? value : JSON.stringify(value);
+    // A random delimiter, rather than a fixed one like "EOF", matters here:
+    // `value` can echo back content from a customer's own docs/OAS files
+    // (an error message quoting their spec, say), and a guessable delimiter
+    // could let that content prematurely close the heredoc and inject extra
+    // key=value pairs into the outputs file.
+    const delimiter = `ghadelimiter_${randomUUID()}`;
+    return `${name}<<${delimiter}\n${text}\n${delimiter}`;
+  });
+
+  fs.appendFileSync(outputPath, `${lines.join('\n')}\n`);
+}

package/src/utils/lint.js

@@ -1,6 +1,15 @@
 import fs from 'node:fs'
 import path from 'node:path'
-import { pathToFileURL } from 'node:url'
+import * as componentsValidator from '../validators/components.js'
+import * as contentValidator from '../validators/content.js'
+import * as duplicatesValidator from '../validators/duplicates.js'
+import * as frontmatterValidator from '../validators/frontmatter.js'
+import * as linksValidator from '../validators/links.js'
+import * as nestingValidator from '../validators/nesting.js'
+import * as oasReferenceValidator from '../validators/oas-reference.js'
+import * as oasSchemaValidator from '../validators/oas-schema.js'
+import * as orderingValidator from '../validators/ordering.js'
+import * as recipesValidator from '../validators/recipes.js'
 
 const TARGET_PATTERNS = [
   { dir: 'custom_blocks', ext: ['.mdx', '.md'] },
@@ -32,24 +41,30 @@ export function collectFiles(gitRoot) {
   return files.sort()
 }
 
+// Every validator in src/validators/, imported statically (rather than
+// discovered via a runtime directory scan) so this file — and anything that
+// imports it, like the GitHub Action entrypoint in src/gha.js — can be
+// bundled into a single file by a tool like ncc. Add a new validator's
+// import above and its module here.
+const ALL_VALIDATORS = [
+  componentsValidator,
+  contentValidator,
+  duplicatesValidator,
+  frontmatterValidator,
+  linksValidator,
+  nestingValidator,
+  oasReferenceValidator,
+  oasSchemaValidator,
+  orderingValidator,
+  recipesValidator,
+]
+
 /**
- * Auto-discover all validators from src/validators/.
  * Validators can export `validate()` for per-file checks and/or
  * `validateAll()` for cross-file checks (like ordering).
  */
-async function loadValidators() {
-  const validatorsDir = path.join(path.dirname(new URL(import.meta.url).pathname), '..', 'validators')
-  const files = fs.readdirSync(validatorsDir).filter((f) => f.endsWith('.js'))
-  const validators = []
-
-  for (const file of files) {
-    const mod = await import(pathToFileURL(path.join(validatorsDir, file)).href)
-    if (mod.name && (mod.validate || mod.validateAll)) {
-      validators.push(mod)
-    }
-  }
-
-  return validators
+function loadValidators() {
+  return ALL_VALIDATORS.filter((mod) => mod.name && (mod.validate || mod.validateAll))
 }
 
 /**

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,14 @@
 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,
+  findIgnoredInternalExtensions,
+} from '../commands/oas-sync.js';
 
 export const name = 'oas-reference';
 
@@ -16,6 +23,17 @@ export function validateAll(files, gitRoot, { fix } = {}) {
   const oasMap = new Map();
   for (const { filename, spec } of oasFiles) {
     oasMap.set(filename, { spec, ops: extractOperations(spec) });
+
+    // Check: `x-readme.internal`, which ReadMe ignores for page visibility.
+    for (const location of findIgnoredInternalExtensions(spec)) {
+      results.push({
+        file: `reference/${filename}`,
+        rule: name,
+        severity: 'warning',
+        message: `"x-readme.internal" is ignored by ReadMe (${location}); use "x-internal" instead to hide pages`,
+        fixable: false,
+      });
+    }
   }
 
   // Collect all reference pages with api frontmatter.
@@ -34,6 +52,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 +69,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,23 +86,30 @@ 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,
         });
       }
     }
   }
 
-  // Apply fixes by running the full sync.
-  if (fix && results.length > 0) {
+  // Apply fixes by running the full sync — but only when something reported
+  // is actually fixable. The sync adds, deletes, moves, hides and reorders
+  // reference files, which is far too much to do on the strength of an
+  // unfixable warning (`x-readme.internal`, a page pointing at a missing spec).
+  if (fix && results.some((r) => r.fixable)) {
     const syncResults = syncOas(gitRoot);
     if (syncResults) {
       for (const r of results) {