@readme/cli 0.0.26 → 0.0.29

package/src/commands/import.slug-planner.test.js

@@ -0,0 +1,86 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { ensureUniqueSlugs } from './import.js'
+
+function assignedSlug(categories, page) {
+  return ensureUniqueSlugs(categories).get(page)
+}
+
+test('ensureUniqueSlugs: generic docs terminal paths fall back to introduction', () => {
+  for (const segment of ['doc', 'docs', 'documentation', 'documentations']) {
+    const page = { title: segment, url: `https://example.com/${segment}` }
+    assert.equal(
+      assignedSlug([{ title: 'Documentation', pages: [page] }], page),
+      'introduction',
+    )
+  }
+})
+
+test('ensureUniqueSlugs: terminal generic docs paths use introduction under non-generic categories', () => {
+  const page = { title: 'Docs', url: 'https://example.com/docs' }
+
+  assert.equal(
+    assignedSlug([{ title: 'Guides', pages: [page] }], page),
+    'introduction',
+  )
+})
+
+test('ensureUniqueSlugs: category segment disambiguates introduction collisions', () => {
+  const guidesPage = { title: 'Docs', url: 'https://example.com/docs' }
+  const apiPage = { title: 'Docs', url: 'https://example.com/docs' }
+  const slugs = ensureUniqueSlugs([
+    { title: 'Guides', pages: [guidesPage] },
+    { title: 'API', pages: [apiPage] },
+  ])
+
+  assert.equal(slugs.get(guidesPage), 'guides-introduction')
+  assert.equal(slugs.get(apiPage), 'api-introduction')
+})
+
+test('ensureUniqueSlugs: generic docs category does not prefix an available page slug', () => {
+  const page = { title: 'Getting Started', url: 'https://example.com/docs/getting-started' }
+
+  assert.equal(
+    assignedSlug([{ title: 'Docs', pages: [page] }], page),
+    'getting-started',
+  )
+})
+
+test('ensureUniqueSlugs: generic docs categories use existing numeric suffix fallback for irreducible collisions', () => {
+  const first = { title: 'Getting Started', url: 'https://example.com/docs/getting-started' }
+  const second = { title: 'Getting Started', url: 'https://example.com/documentation/getting-started' }
+  const slugs = ensureUniqueSlugs([
+    { title: 'Docs', pages: [first] },
+    { title: 'Documentation', pages: [second] },
+  ])
+
+  assert.equal(slugs.get(first), 'getting-started')
+  assert.equal(slugs.get(second), 'getting-started-2')
+})
+
+test('ensureUniqueSlugs: generic docs category is assigned before non-generic categories', () => {
+  const docsPage = { title: 'Getting Started', url: 'https://example.com/docs/getting-started' }
+  const aiPage = { title: 'Getting Started', url: 'https://example.com/ai/getting-started' }
+  const slugs = ensureUniqueSlugs([
+    { title: 'AI', pages: [aiPage] },
+    { title: 'Docs', pages: [docsPage] },
+  ])
+
+  assert.equal(slugs.get(docsPage), 'getting-started')
+  assert.equal(slugs.get(aiPage), 'ai-getting-started')
+})
+
+test('ensureUniqueSlugs: non-generic docs paths keep current base slug behavior', () => {
+  const api = { title: 'API', url: 'https://example.com/docs/api' }
+  const gettingStarted = { title: 'Getting Started', url: 'https://example.com/docs/getting-started' }
+  const docsApi = { title: 'Docs API', url: 'https://example.com/docs-api' }
+  const documentationSettings = { title: 'Documentation Settings', url: 'https://example.com/documentation-settings' }
+  const slugs = ensureUniqueSlugs([
+    { title: 'Guides', pages: [api, gettingStarted, docsApi, documentationSettings] },
+  ])
+
+  assert.equal(slugs.get(api), 'api')
+  assert.equal(slugs.get(gettingStarted), 'getting-started')
+  assert.equal(slugs.get(docsApi), 'docs-api')
+  assert.equal(slugs.get(documentationSettings), 'documentation-settings')
+})

package/src/commands/import.test.js

@@ -0,0 +1,136 @@
+import { afterEach, test } from 'node:test'
+import assert from 'node:assert/strict'
+import { __test__ } from './import.js'
+
+const originalFetch = globalThis.fetch
+
+afterEach(() => {
+  globalThis.fetch = originalFetch
+})
+
+function mockLlmsFetch(files) {
+  const seen = []
+  globalThis.fetch = async (url) => {
+    const href = String(url)
+    seen.push(href)
+    if (!Object.hasOwn(files, href)) return new Response('', { status: 404 })
+    return new Response(files[href], {
+      status: 200,
+      headers: { 'content-type': 'text/plain' },
+    })
+  }
+  return seen
+}
+
+function mockRedirectFetch(files) {
+  globalThis.fetch = async (url) => {
+    const entry = files[String(url)]
+    if (!entry) return { ok: false, status: 404, url: String(url), text: async () => '' }
+    return { ok: true, status: 200, url: entry.finalUrl || String(url), text: async () => entry.body || '' }
+  }
+}
+
+function mergedItems(merged) {
+  return merged.parsed.sections.flatMap((section) => section.items.map((item) => ({ text: item.text, url: item.url })))
+}
+
+test('llms discovery and merge resolve nested files, dedupe canonical pages, and preserve distinct page states', async () => {
+  const seen = mockLlmsFetch({
+    'https://example.com/docs/llms.txt': `# Docs\n\n## Index\n- [Guide llms](guide/llms.txt)\n- [API llms](https://example.com/docs/api/llms.txt)\n`,
+    'https://example.com/docs/guide/llms.txt': `# Guide\n\n## Guides\n- [Rendered redirect](/getting-started)\n- [Rendered slash](/getting-started/)\n- [Rendered index](/getting-started/index.html)\n- [Markdown source](/getting-started.md)\n- [Search API](/search?product=api)\n- [Search SDK](/search?product=sdk)\n- [Search API Anchor](/search?product=api#overview)\n- [Hash only](#local)\n- [Mail](mailto:test@example.com)\n- [JS](javascript:alert(1))\n- [Malformed](http://%zz)\n`,
+    'https://example.com/docs/api/llms.txt': `# API\n\n## Reference\n- [Reference](/reference.md)\n- [OpenAPI](/openapi.yaml)\n`,
+  })
+
+  const discovery = await __test__.discoverLlmsTxt(new URL('https://example.com/docs/'))
+  const merged = __test__.mergeValidHits(discovery.hits)
+  const items = mergedItems(merged)
+  const urls = items.map((item) => item.url)
+
+  assert(seen.includes('https://example.com/docs/guide/llms.txt'))
+  assert(seen.includes('https://example.com/docs/api/llms.txt'))
+
+  assert.equal(urls.filter((url) => url.includes('/docs/guide/getting-started')).length, 1)
+  assert(urls.includes('https://example.com/docs/guide/getting-started.md'))
+
+  assert(urls.includes('https://example.com/docs/guide/search?product=api'))
+  assert(urls.includes('https://example.com/docs/guide/search?product=sdk'))
+  assert.equal(urls.filter((url) => url.includes('/docs/guide/search?product=api')).length, 1)
+
+  assert(urls.includes('https://example.com/docs/api/reference.md'))
+  assert(urls.includes('https://example.com/openapi.yaml'))
+
+  assert(!urls.some((url) => url.includes('%zz')))
+  assert(!urls.some((url) => url.startsWith('mailto:') || url.startsWith('javascript:')))
+})
+
+test('llms.txt fetched through a cross-origin redirect resolves links against the final URL', async () => {
+  mockRedirectFetch({
+    'https://docs.example.com/llms.txt': {
+      finalUrl: 'https://example.com/docs/llms.txt',
+      body: `# Docs\n\n## Guides\n- [Sample APIs](/docs/sample-apis.md)\n- [Policies](/policies.md)\n`,
+    },
+  })
+
+  const discovery = await __test__.discoverLlmsTxt(new URL('https://docs.example.com'))
+  const merged = __test__.mergeValidHits(discovery.hits)
+  const urls = mergedItems(merged).map((item) => item.url)
+
+  assert(urls.includes('https://example.com/docs/sample-apis.md'))
+  assert(urls.includes('https://example.com/docs/policies.md'))
+  assert(!urls.some((url) => url.startsWith('https://docs.example.com/')))
+})
+
+test('nested llms.txt with its own redirect resolves links on its final path', async () => {
+  mockRedirectFetch({
+    'https://example.com/llms.txt': {
+      body: `# Root\n\n## Index\n- [Guide llms](/guide/llms.txt)\n`,
+    },
+    'https://example.com/guide/llms.txt': {
+      finalUrl: 'https://example.com/docs/guide/llms.txt',
+      body: `# Guide\n\n## Guides\n- [Intro](intro.md)\n- [Setup](setup.md)\n`,
+    },
+  })
+
+  const discovery = await __test__.discoverLlmsTxt(new URL('https://example.com'))
+  const merged = __test__.mergeValidHits(discovery.hits)
+  const urls = mergedItems(merged).map((item) => item.url)
+
+  assert(urls.includes('https://example.com/docs/guide/intro.md'))
+  assert(urls.includes('https://example.com/docs/guide/setup.md'))
+  assert(!urls.includes('https://example.com/guide/intro.md'))
+  assert(!urls.includes('https://example.com/guide/setup.md'))
+})
+
+test('resolveRedirectedSourceUrl adopts cross-origin path redirects', async () => {
+  mockRedirectFetch({
+    'https://docs.example.com/': { finalUrl: 'https://example.com/docs' },
+  })
+  const final = await __test__.resolveRedirectedSourceUrl(new URL('https://docs.example.com/'))
+  assert.equal(final?.href, 'https://example.com/docs')
+})
+
+test('resolveRedirectedSourceUrl ignores trailing-slash redirects', async () => {
+  mockRedirectFetch({
+    'https://example.com/docs': { finalUrl: 'https://example.com/docs/' },
+  })
+  assert.equal(await __test__.resolveRedirectedSourceUrl(new URL('https://example.com/docs')), null)
+})
+
+test('resolveRedirectedSourceUrl ignores query and hash-only redirects', async () => {
+  mockRedirectFetch({
+    'https://example.com/docs': { finalUrl: 'https://example.com/docs?lang=en#top' },
+  })
+  assert.equal(await __test__.resolveRedirectedSourceUrl(new URL('https://example.com/docs')), null)
+})
+
+test('resolveRedirectedSourceUrl returns null on non-ok responses', async () => {
+  globalThis.fetch = async (url) => ({ ok: false, status: 500, url: String(url), text: async () => '' })
+  assert.equal(await __test__.resolveRedirectedSourceUrl(new URL('https://example.com/')), null)
+})
+
+test('resolveRedirectedSourceUrl returns null when fetch throws', async () => {
+  globalThis.fetch = async () => {
+    throw new Error('network down')
+  }
+  assert.equal(await __test__.resolveRedirectedSourceUrl(new URL('https://example.com/')), null)
+})

package/src/commands/lint.js

@@ -1,22 +1,22 @@
-import { createRequire } from 'node:module';
-import { collectFiles, runValidators } from '../utils/lint.js';
-import { createHumanReporter, createJsonReporter, createGithubReporter } from '../utils/reporter.js';
-import { printHeader, isAgenticCli } from '../utils/eyes.js';
-import * as styles from '../utils/styles.js';
+import { createRequire } from 'node:module'
+import { collectFiles, runValidators } from '../utils/lint.js'
+import { createHumanReporter, createJsonReporter, createGithubReporter } from '../utils/reporter.js'
+import { printHeader, isAgenticCli } from '../utils/eyes.js'
+import * as styles from '../utils/styles.js'
 
-const require = createRequire(import.meta.url);
-const pkg = require('../../package.json');
+const require = createRequire(import.meta.url)
+const pkg = require('../../package.json')
 
-export const command = 'lint';
-export const order = 1;
-export const aliases = ['validate'];
-export const category = 'Linting';
-export const description = 'Lint and validate your ReadMe docs';
+export const command = 'lint'
+export const order = 1
+export const aliases = ['validate']
+export const category = 'Linting'
+export const description = 'Lint and validate your ReadMe docs'
 
 export function args(cmd) {
-  cmd.option('--json', 'Output results as JSON (for CI and automation)');
-  cmd.option('--github', 'Output a GitHub PR comment body as markdown');
-  cmd.option('--fix', 'Automatically fix issues where possible');
+  cmd.option('--json', 'Output results as JSON (for CI and automation)')
+  cmd.option('--github', 'Output a GitHub PR comment body as markdown')
+  cmd.option('--fix', 'Automatically fix issues where possible')
 }
 
 /**
@@ -25,46 +25,43 @@ export function args(cmd) {
  * exit on their own terms.
  *
  * @param {object}  [opts]
- * @param {string}  [opts.cwd]   Repo root to lint (defaults to process.cwd()).
- * @param {boolean} [opts.fix]   Apply autofixes where validators support it.
+ * @param {string}  [opts.cwd]              Repo root to lint (defaults to process.cwd()).
+ * @param {boolean} [opts.fix]              Apply autofixes where validators support it.
+ * @param {boolean} [opts.nonInteractive]   Skip any interactive prompts (e.g. rename confirmation). Fixes that would normally prompt are not applied.
  * @param {(file: string) => void} [opts.onFile]            Called per file before validation.
  * @param {() => void}             [opts.onBeforeCrossFile] Called once before cross-file checks run.
  * @returns {Promise<{ gitRoot: string, files: string[], results: object[], hasErrors: boolean }>}
  */
-export async function lint({ cwd, fix = false, onFile, onBeforeCrossFile } = {}) {
-  const gitRoot = cwd || process.cwd();
-  const files = collectFiles(gitRoot);
-  const results = await runValidators(files, gitRoot, { onFile, onBeforeCrossFile, fix });
-  const hasErrors = results.some((r) => r.severity !== 'warning');
-  return { gitRoot, files, results, hasErrors };
+export async function lint({ cwd, fix = false, nonInteractive = false, onFile, onBeforeCrossFile } = {}) {
+  const gitRoot = cwd || process.cwd()
+  const files = collectFiles(gitRoot)
+  const results = await runValidators(files, gitRoot, { onFile, onBeforeCrossFile, fix, nonInteractive })
+  const hasErrors = results.some((r) => r.severity !== 'warning')
+  return { gitRoot, files, results, hasErrors }
 }
 
 export async function run(options, _cmd, ctx) {
-  const { gitRoot } = ctx;
+  const { gitRoot } = ctx
 
   if (!options.json && !options.github && !isAgenticCli()) {
-    printHeader({ version: pkg.version, binName: styles.binName(), indent: '  ' });
-    console.log();
+    printHeader({ version: pkg.version, binName: styles.binName(), indent: '  ' })
+    console.log()
   }
 
-  const reporter = options.github
-    ? createGithubReporter()
-    : options.json
-      ? createJsonReporter()
-      : createHumanReporter();
+  const reporter = options.github ? createGithubReporter() : options.json ? createJsonReporter() : createHumanReporter()
 
   const { files, results, hasErrors } = await lint({
     cwd: gitRoot,
     fix: options.fix,
     onFile: (f) => reporter.onFile(f),
     onBeforeCrossFile: () => reporter.pause(),
-  });
+  })
 
-  reporter.finish(files.length, results, files, { fix: options.fix, gitRoot });
+  reporter.finish(files.length, results, files, { fix: options.fix, gitRoot })
 
   if (hasErrors) {
     // Wait for stdout to flush (important when piped to a file), then exit
-    await new Promise((resolve) => process.stdout.write('', resolve));
-    process.exit(1);
+    await new Promise((resolve) => process.stdout.write('', resolve))
+    process.exit(1)
   }
 }

package/src/commands/oas-sync.js

@@ -14,12 +14,6 @@ export const description = 'Sync reference pages with OpenAPI specs';
 
 const HTTP_METHODS = new Set(['get', 'post', 'put', 'patch', 'delete', 'options', 'head', 'trace']);
 
-/**
- * Check if this is a ReadMeConfig spec (internal ReadMe pages — skip title/excerpt updates).
- */
-function isReadMeConfig(spec) {
-  return spec.info?.title === 'ReadMeConfig';
-}
 
 /**
  * Find OAS files at the root of reference/ (JSON or YAML).
@@ -168,19 +162,31 @@ function removeFromOrder(orderPath, slug) {
   }
 }
 
-function buildPageContent({ oasFilename, operationId, summary, description }) {
+/**
+ * Spec-derived values (info.title, tags, operationIds) become directory and
+ * file names. Collapse path separators and dot-only names into a single safe
+ * segment so a crafted spec can't write outside reference/.
+ */
+function safeSegment(value, fallback) {
+  const segment = String(value).replace(/[/\\]/g, '-').trim();
+  return !segment || segment === '.' || segment === '..' ? fallback : segment;
+}
+
+function isWithin(baseDir, target) {
+  const rel = path.relative(baseDir, target);
+  return (
+    rel !== '' && rel !== '..' && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel)
+  );
+}
+
+function buildPageContent({ oasFilename, operationId }) {
   const frontmatter = {
-    title: summary || operationId,
     api: {
       file: oasFilename,
       operationId,
     },
   };
 
-  if (description) {
-    frontmatter.excerpt = description;
-  }
-
   return matter.stringify('', frontmatter);
 }
 
@@ -189,8 +195,10 @@ function buildPageContent({ oasFilename, operationId, summary, description }) {
  */
 function syncOneOas(refDir, oasFilename, spec) {
   const specOps = extractOperations(spec);
-  const infoTitle = spec.info?.title || path.basename(oasFilename, path.extname(oasFilename));
-  const skipUpdates = isReadMeConfig(spec);
+  const infoTitle = safeSegment(
+    spec.info?.title || path.basename(oasFilename, path.extname(oasFilename)),
+    'api',
+  );
 
   const existingPages = collectExistingPages(refDir).filter(
     (p) => p.data.api.file === oasFilename,
@@ -201,7 +209,7 @@ function syncOneOas(refDir, oasFilename, spec) {
     pagesByOpId.set(page.data.api.operationId, page);
   }
 
-  const changes = { added: [], deleted: [], updated: [] };
+  const changes = { added: [], deleted: [], skipped: [] };
 
   // Deletes: pages referencing operations that no longer exist.
   for (const [opId, page] of pagesByOpId) {
@@ -216,61 +224,32 @@ function syncOneOas(refDir, oasFilename, spec) {
     }
   }
 
-  // Adds + Updates.
+  // 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) {
-    const existing = pagesByOpId.get(opId);
-    const tag = op.tag || 'Other';
-
-    if (!existing) {
-      const pageDir = path.join(refDir, infoTitle, tag);
-      fs.mkdirSync(pageDir, { recursive: true });
-
-      const pagePath = path.join(pageDir, `${opId}.md`);
-      const content = buildPageContent({
-        oasFilename,
-        operationId: opId,
-        summary: op.summary,
-        description: op.description,
-      });
-      fs.writeFileSync(pagePath, content);
-
-      addToOrder(path.join(pageDir, '_order.yaml'), opId);
-      addToOrder(path.join(refDir, infoTitle, '_order.yaml'), tag);
-
-      changes.added.push(path.relative(refDir, pagePath));
-    } else if (!skipUpdates) {
-      const expectedTitle = op.summary || opId;
-      const expectedExcerpt = op.description || null;
-      const currentTitle = existing.data.title;
-      const currentExcerpt = existing.data.excerpt || null;
-
-      const titleChanged = currentTitle !== expectedTitle;
-      const excerptChanged = currentExcerpt !== expectedExcerpt;
-
-      if (titleChanged || excerptChanged) {
-        const updated = { ...existing.data };
-        const updateDetails = [];
+    if (pagesByOpId.has(opId)) continue;
+
+    const tag = safeSegment(op.tag || 'Other', 'Other');
+    const slug = safeSegment(opId, 'operation');
+    const pageDir = path.join(refDir, infoTitle, tag);
+    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 });
 
-        if (titleChanged) {
-          updated.title = expectedTitle;
-          updateDetails.push('title');
-        }
-        if (excerptChanged) {
-          if (expectedExcerpt) {
-            updated.excerpt = expectedExcerpt;
-          } else {
-            delete updated.excerpt;
-          }
-          updateDetails.push('excerpt');
-        }
+    const content = buildPageContent({ oasFilename, operationId: opId });
+    fs.writeFileSync(pagePath, content);
 
-        const body = matter(existing.content).content;
-        const newContent = matter.stringify(body, updated);
-        fs.writeFileSync(existing.filePath, newContent);
+    addToOrder(path.join(pageDir, '_order.yaml'), slug);
+    addToOrder(path.join(refDir, infoTitle, '_order.yaml'), tag);
 
-        changes.updated.push(`${existing.relativePath} (${updateDetails.join(', ')})`);
-      }
-    }
+    changes.added.push(path.relative(refDir, pagePath));
   }
 
   return changes;
@@ -285,7 +264,7 @@ function syncOneOas(refDir, oasFilename, spec) {
  *
  * @param {string | { cwd?: string }} input  Repo root path, or `{ cwd }` object.
  * @returns {null | Array<{ filename: string, spec: object, opCount: number,
- *   changes: { added: string[], deleted: string[], updated: string[] } }>}
+ *   changes: { added: string[], deleted: string[] } }>}
  *   Returns null if there's no reference/ dir or no specs.
  */
 export function syncOas(input) {
@@ -325,11 +304,12 @@ export async function run(_options, _cmd, ctx) {
 
   let totalAdded = 0;
   let totalDeleted = 0;
-  let totalUpdated = 0;
+  let totalSkipped = 0;
 
   for (const { filename, spec, opCount, changes } of results) {
     const title = spec.info?.title || filename;
-    const hasChanges = changes.added.length + changes.deleted.length + changes.updated.length > 0;
+    const hasChanges =
+      changes.added.length + changes.deleted.length + changes.skipped.length > 0;
 
     const dot = hasChanges ? styles.warn('●') : styles.success('●');
     console.log();
@@ -345,20 +325,25 @@ export async function run(_options, _cmd, ctx) {
     for (const file of changes.deleted) {
       console.log(`    ${styles.err('−')} Deleted ${file}`);
     }
-    for (const file of changes.updated) {
-      console.log(`    ${styles.warn('~')} Updated ${file}`);
+    for (const { path: file, operationId } of changes.skipped) {
+      console.log(
+        `    ${styles.warn('!')} Skipped ${file} for "${operationId}" (destination already exists)`,
+      );
     }
 
     totalAdded += changes.added.length;
     totalDeleted += changes.deleted.length;
-    totalUpdated += changes.updated.length;
+    totalSkipped += changes.skipped.length;
   }
 
   console.log();
-  const total = totalAdded + totalDeleted + totalUpdated;
-  if (total === 0) {
+  const total = totalAdded + totalDeleted;
+  const skippedNote = totalSkipped > 0 ? `, ${totalSkipped} skipped` : '';
+  if (total === 0 && totalSkipped === 0) {
     styles.ok('Reference pages are already in sync.');
+  } else if (total === 0) {
+    styles.warning(`No pages synced; ${totalSkipped} skipped (destination already exists).`);
   } else {
-    styles.ok(`Synced: ${totalAdded} added, ${totalDeleted} deleted, ${totalUpdated} updated.`);
+    styles.ok(`Synced: ${totalAdded} added, ${totalDeleted} deleted${skippedNote}.`);
   }
 }