@readme/cli 0.0.30 → 0.1.0

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, fileURLToPath } 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(fileURLToPath(import.meta.url)), '..', '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/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, operationKey } 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.
@@ -87,8 +105,11 @@ export function validateAll(files, gitRoot, { fix } = {}) {
     }
   }
 
-  // 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) {