@readme/cli 0.0.26 → 0.0.27

package/src/commands/import.js

@@ -7,7 +7,7 @@ import { Option } from 'commander'
 import { query } from '@anthropic-ai/claude-agent-sdk'
 import matter from 'gray-matter'
 import * as styles from '../utils/styles.js'
-import { syncOas, extractOperations } from './oas-sync.js'
+import { syncOas } from './oas-sync.js'
 import OASNormalize from 'oas-normalize'
 import { slotOrphansPrompt, iconizeNavPrompt, organizeFromSectionsPrompt, organizeFromScratchPrompt, stripCodeFences } from '../prompts/index.js'
 
@@ -20,7 +20,7 @@ export const skipBootstrap = true
 export function args(cmd) {
   cmd.requiredOption('--source <url-or-file>', 'URL to import from, or path to a local OpenAPI spec (.json/.yaml/.yml)')
   cmd.option('-o, --output <path>', 'Output zip path (defaults to <basename>-readme.zip in cwd)')
-  cmd.option('--model <name>', 'Claude model alias: haiku, sonnet, opus', 'sonnet')
+  cmd.addOption(new Option('-m, --model <name>', 'Claude model alias: haiku, sonnet, opus').choices(['haiku', 'sonnet', 'opus']).default('sonnet'))
   cmd.option('--firecrawl-key <key>', 'Firecrawl API key (or set FIRECRAWL_API_KEY env var) — enables JS-rendered sidebar scraping')
   cmd.option('--skip-api-reference', 'Drop pages routed to the API Reference / reference dir. Use when uploading the OAS spec separately.')
   // Internal dev-only flag: skip the zip, keep staging, and boot the dev server
@@ -95,14 +95,42 @@ export async function importDocs(options) {
   })
   console.log()
 
+  let sitemapUrl = null
+  let sitemapKnownUrls = []
   if (!llms) {
-    styles.warning(`No llms.txt found at any probed path — falling back to sidebar discovery via scrape.`)
+    // Sitemap fallback: gives us a flat URL list to anchor the scrape (slot
+    // orphans by path) even though it lacks llms.txt's section structure.
+    // Scope is narrowed to the docs subtree of the source URL when possible
+    // so we don't pull in marketing/blog pages from a whole-site sitemap.
+    const sitemapCandidates = buildSitemapCandidates(sourceUrl)
+    const scopePrefix = deriveSitemapScope(sourceUrl)
+    styles.info(
+      `No llms.txt — checking for sitemap.xml (${sitemapCandidates.length} candidate${sitemapCandidates.length === 1 ? '' : 's'})${scopePrefix ? `, scoped to ${styles.bold(scopePrefix)}` : ''}...`,
+    )
+    const sitemapResult = await timePhase('fetch sitemap.xml', async () => {
+      for (const candidate of sitemapCandidates) {
+        const res = await fetchSitemap(candidate, scopePrefix)
+        if (res.ok && res.urls.length > 0) return { url: candidate, urls: res.urls }
+        const reason = res.ok ? '0 urls in scope' : res.status ? `HTTP ${res.status}` : res.error || 'failed'
+        styles.info(styles.dim(`  ${candidate} → ${reason}`))
+      }
+      return null
+    })
+    console.log()
+    if (sitemapResult) {
+      sitemapUrl = sitemapResult.url
+      sitemapKnownUrls = sitemapUrlsToKnownUrls(sitemapResult.urls)
+      styles.ok(`Found sitemap.xml at ${styles.bold(sitemapUrl)} — ${styles.bold(String(sitemapKnownUrls.length))} URL${sitemapKnownUrls.length === 1 ? '' : 's'} in scope.`)
+    } else {
+      styles.warning(`No llms.txt or sitemap.xml found — falling back to sidebar discovery via scrape.`)
+    }
   } else {
     styles.info(styles.dim(`Using ${llmsUrl}.`))
   }
 
   if (debugSnapshots) {
     debugSnapshots['01-llms-parsed.json'] = { llmsUrl, parsed: llms ? llms.parsed : null }
+    debugSnapshots['01b-sitemap.json'] = { sitemapUrl, urls: sitemapKnownUrls }
   }
 
   let knownUrls = []
@@ -130,6 +158,8 @@ export async function importDocs(options) {
     if (dropped > 0) {
       styles.info(`${styles.dim(`Collapsed ${dropped} anchor/query duplicates → ${knownUrls.length} unique pages.`)}`)
     }
+  } else if (sitemapKnownUrls.length > 0) {
+    knownUrls = sitemapKnownUrls
   }
 
   console.log()
@@ -265,10 +295,12 @@ export async function importDocs(options) {
         )
       }
     }
-  } else if (!llms) {
-    throw new Error(`No llms.txt and the sidebar scrape found no usable structure — can't import ${sourceUrl.toString()}.`)
-  } else {
+  } else if (!llms && knownUrls.length === 0) {
+    throw new Error(`No llms.txt or sitemap.xml and the sidebar scrape found no usable structure — can't import ${sourceUrl.toString()}.`)
+  } else if (llms) {
     styles.warning(`Couldn't extract a useful nav — falling back to llms.txt-based organization.`)
+  } else {
+    styles.warning(`Couldn't extract a useful nav — falling back to sitemap URL clustering.`)
   }
   console.log()
 
@@ -281,11 +313,25 @@ export async function importDocs(options) {
       title: (llms && llms.parsed.title) || null,
       categories: scraped.categories.map((c) => ({ title: c.title, icon: null, pages: c.pages })),
     }
-  } else {
+  } else if (llms) {
     const fastPath = sectionsLookUsable(llms.parsed.sections)
     styles.info(`Organizing with Claude (${styles.bold(options.model)}, ${fastPath ? 'fast path: icons only' : 'full reorg'})...`)
     organized = await timePhase('claude organize', () => organizeWithClaude(llms.parsed, options.model))
+  } else {
+    // Sitemap-only fallback: synthesize categories by clustering the URL
+    // paths. clusterByUrlPath returns null when the URLs don't split cleanly,
+    // in which case everything lands in a single Documentation bucket.
+    const clustered = clusterByUrlPath(knownUrls) || [{ title: 'Documentation', pages: knownUrls }]
+    organized = {
+      title: null,
+      categories: clustered.map((c) => ({ title: c.title, icon: null, pages: c.pages })),
+    }
+  }
+  
+  for (const cat of organized.categories || []) {
+    cat.pages = nestByUrlHierarchy(cat.pages)
   }
+
   styles.ok(`Organized in ${styles.bold(formatDuration(Date.now() - organizeStart))}.`)
   if (debugSnapshots) {
     debugSnapshots['05-organized.json'] = organized
@@ -1573,6 +1619,73 @@ function collectFlat(page, out) {
   }
 }
 
+/**
+ * Re-parent URL-bearing siblings by URL path so a page like `/foo/bar`
+ * becomes a child of `/foo` when both appear in the same list.
+ *
+ * @example
+ *   nestByUrlHierarchy([
+ *     { title: 'CLI',      url: 'https://x.com/getting-started/cli' },
+ *     { title: 'Overview', url: 'https://x.com/getting-started/cli/overview' },
+ *   ])
+ *   // [
+ *   //   { title: 'CLI', url: '…/cli', pages: [
+ *   //     { title: 'Overview', url: '…/cli/overview' },
+ *   //   ]},
+ *   // ]
+ */
+function nestByUrlHierarchy(pages) {
+  if (!pages || pages.length === 0) return pages
+
+  // Recurse first so group-only / already-nested subtrees get re-nested too.
+  for (const p of pages) {
+    if (p.pages && p.pages.length > 0) p.pages = nestByUrlHierarchy(p.pages)
+  }
+
+  // Need at least two URL-bearing siblings to form a parent/child pair.
+  const byPath = new Map()
+  for (const p of pages) {
+    if (!p.url) continue
+    const k = normalizePath(p.url)
+    if (!byPath.has(k)) byPath.set(k, p)
+  }
+  if (byPath.size < 2) return pages
+
+  const result = []
+  for (const p of pages) {
+    if (!p.url) {
+      result.push(p)
+      continue
+    }
+    let segs
+    try {
+      segs = new URL(p.url).pathname.split('/').filter(Boolean)
+    } catch {
+      result.push(p)
+      continue
+    }
+    let parent = null
+    for (let depth = segs.length - 1; depth >= 1; depth--) {
+      const key = ('/' + segs.slice(0, depth).join('/'))
+        .toLowerCase()
+        .replace(/\.(md|mdx|html?)$/i, '')
+        .replace(/\/$/, '')
+      const candidate = byPath.get(key)
+      if (candidate && candidate !== p) {
+        parent = candidate
+        break
+      }
+    }
+    if (parent) {
+      if (!parent.pages) parent.pages = []
+      parent.pages.push(p)
+    } else {
+      result.push(p)
+    }
+  }
+  return result
+}
+
 /**
  * The scraped nav only contains top-level items; subcategory pages sit behind
  * `>` chevrons and don't render on a cold fetch. For each llms.txt URL not
@@ -2262,6 +2375,185 @@ function parseLlmsTxt(body) {
   return { title, sections }
 }
 
+// Path segments that mark a docs scope. Used to find the right "base" for
+// filtering sitemap URLs: walking up from the source URL, the first segment
+// that matches becomes the scope prefix. Hits should stay narrow — `blog`
+// or `pricing` would over-include marketing pages.
+const WELL_KNOWN_DOC_SEGMENTS = new Set([
+  'docs',
+  'doc',
+  'documentation',
+  'guides',
+  'guide',
+  'references',
+  'reference',
+  'api',
+  'apis',
+  'api-reference',
+  'api-docs',
+  'learn',
+  'tutorials',
+  'tutorial',
+  'developers',
+  'developer',
+])
+
+/**
+ * Decide which path prefix to use when filtering sitemap URLs to "the docs
+ * portion of the site." Walk up the source URL's path looking for the first
+ * well-known docs segment (`/docs/`, `/guides/`, `/api-reference/`, …) and
+ * use the prefix up to and including it. Returns null when nothing matches —
+ * in that case we accept any URL on the same origin (no path filter).
+ */
+function deriveSitemapScope(sourceUrl) {
+  const segs = sourceUrl.pathname.split('/').filter(Boolean)
+  for (let i = segs.length - 1; i >= 0; i--) {
+    if (WELL_KNOWN_DOC_SEGMENTS.has(segs[i].toLowerCase())) {
+      return '/' + segs.slice(0, i + 1).join('/') + '/'
+    }
+  }
+  return null
+}
+
+/**
+ * Mirror buildLlmsCandidates but for sitemap.xml: walk up the source path
+ * appending `/sitemap.xml` at each level, ending at origin root.
+ */
+function buildSitemapCandidates(sourceUrl) {
+  const out = []
+  const seen = new Set()
+  const add = (url) => {
+    if (!seen.has(url)) {
+      seen.add(url)
+      out.push(url)
+    }
+  }
+  const origin = sourceUrl.origin
+  const segs = sourceUrl.pathname.split('/').filter(Boolean)
+  for (let i = segs.length; i >= 0; i--) {
+    const prefix = segs.slice(0, i).join('/')
+    add(`${origin}${prefix ? '/' + prefix : ''}/sitemap.xml`)
+  }
+  return out
+}
+
+/**
+ * Best-effort fetch of a sitemap. Handles both `<urlset>` (a flat list of
+ * page URLs) and `<sitemapindex>` (which references child sitemaps — we
+ * recurse one level, capped at 10 children to avoid runaway fetches).
+ *
+ * `scopePrefix` is a path string ending in `/`, or null. When set, only URLs
+ * whose pathname starts with the prefix and share the sitemap's origin are
+ * returned. Returns { ok, urls } on success.
+ */
+async function fetchSitemap(sitemapUrl, scopePrefix, depth = 0) {
+  try {
+    const res = await fetch(sitemapUrl, {
+      redirect: 'follow',
+      headers: { 'User-Agent': 'readme-cli-import' },
+    })
+    if (!res.ok) return { ok: false, status: res.status }
+    const text = await res.text()
+    const parsed = parseSitemapXml(text)
+    if (!parsed) return { ok: false, error: 'not a sitemap' }
+
+    if (parsed.kind === 'urlset') {
+      const urls = parsed.locs.filter((u) => urlInScope(u, sitemapUrl, scopePrefix))
+      return { ok: true, urls }
+    }
+
+    if (depth >= 1) return { ok: true, urls: [] }
+    const children = parsed.locs.slice(0, 10)
+    const all = []
+    for (const childUrl of children) {
+      const child = await fetchSitemap(childUrl, scopePrefix, depth + 1)
+      if (child.ok) all.push(...child.urls)
+    }
+    return { ok: true, urls: all }
+  } catch (e) {
+    return { ok: false, error: e.message }
+  }
+}
+
+/**
+ * Parse a sitemap with a regex — the format is small and well-defined enough
+ * that a dedicated XML parser would be overkill. Returns
+ * { kind: 'urlset' | 'sitemapindex', locs: string[] } or null when the body
+ * doesn't look like a sitemap (e.g. server returned a 200 HTML 404 page).
+ */
+function parseSitemapXml(body) {
+  const isIndex = /<sitemapindex[\s>]/i.test(body)
+  const isUrlset = /<urlset[\s>]/i.test(body)
+  if (!isIndex && !isUrlset) return null
+  const locs = []
+  const re = /<loc>\s*([^<]+?)\s*<\/loc>/gi
+  let m
+  while ((m = re.exec(body)) !== null) {
+    const url = decodeXmlEntities(m[1].trim())
+    if (url) locs.push(url)
+  }
+  return { kind: isIndex ? 'sitemapindex' : 'urlset', locs }
+}
+
+function decodeXmlEntities(s) {
+  return s
+    .replace(/&amp;/g, '&')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&apos;/g, "'")
+}
+
+function urlInScope(urlStr, sitemapUrl, scopePrefix) {
+  let u
+  try {
+    u = new URL(urlStr)
+  } catch {
+    return false
+  }
+  let sm
+  try {
+    sm = new URL(sitemapUrl)
+  } catch {
+    return false
+  }
+  if (u.origin !== sm.origin) return false
+  if (scopePrefix && !u.pathname.startsWith(scopePrefix)) return false
+  return true
+}
+
+/**
+ * Convert a flat sitemap URL list into the `{title, url, description}` shape
+ * the rest of the pipeline expects for knownUrls. Title is derived from the
+ * last non-empty path segment, with file extensions stripped. Index-style
+ * URLs that resolve to the scope root itself are dropped.
+ */
+function sitemapUrlsToKnownUrls(urls) {
+  const out = []
+  const seen = new Set()
+  for (const url of urls) {
+    let pathname
+    try {
+      pathname = new URL(url).pathname
+    } catch {
+      continue
+    }
+    const norm = normalizePath(url)
+    if (seen.has(norm)) continue
+    seen.add(norm)
+    const segs = pathname.split('/').filter(Boolean)
+    const last = segs[segs.length - 1] || ''
+    const slug = last.replace(/\.[a-z0-9]+$/i, '')
+    if (!slug) continue
+    out.push({
+      title: titleCase(slug),
+      url,
+      description: null,
+    })
+  }
+  return out
+}
+
 /**
  * Write the organized hierarchy to disk as git-format markdown stubs — just
  * frontmatter, no body yet. docs/ pages go under docs/<Category>/<slug>.md;
@@ -2287,12 +2579,27 @@ function printPagesTree(pages, indentLevel) {
 
 function stageOrganized(organized, stagingDir, opts = {}) {
   const pickIcon = makeIconPicker()
-  const usedSlugs = new Set() // cross-dir: duplicates validator is global
   const byDir = new Map()
   const subDirsByTopDir = new Map()
   const counts = { fileCount: 0, skippedApiRef: 0 }
   const skipApiReference = !!opts.skipApiReference
 
+  const eligibleCategories = (organized.categories || []).filter((cat) => {
+    if (skipApiReference && routeCategory(cat.title).topDir === 'reference') {
+      counts.skippedApiRef += countPagesDeep(cat.pages || [])
+      return false
+    }
+    return true
+  })
+
+  // Slug names must be unique
+  const slugFor = ensureUniqueSlugs(eligibleCategories)
+
+  const urlWidth = Math.max(...[...slugFor.keys()].map((p) => (p.url || '(group-only)').length))
+  for (const [page, slug] of slugFor) {
+    console.log(`${(page.url || '(group-only)').padEnd(urlWidth)} → ${slug}`)
+  }
+
   /**
    * Write a page (and its descendants) into `dir`. A page with children gets
    * its own subfolder named after its slug; the parent page lives at
@@ -2300,8 +2607,7 @@ function stageOrganized(organized, stagingDir, opts = {}) {
    * This matches git-format's on-disk convention for nested sidebars.
    */
   function writePage(page, dir, topDir, isSubPage = false) {
-    const slug = resolveSlug(deriveSlug(page.url, page.title), usedSlugs)
-    usedSlugs.add(slug)
+    const slug = slugFor.get(page)
 
     // Group-only nodes (e.g. a resource sub-group within API Reference) have
     // no backing page on the source site — they're pure sidebar containers.
@@ -2318,7 +2624,7 @@ function stageOrganized(organized, stagingDir, opts = {}) {
       // git-format convention for metadata the schema doesn't know about.
       frontmatter['x-import'] = toBrowsableUrl(page.url)
       // hide pages that need import
-      frontmatter.hidden = true
+      frontmatter.hidden = 'true'
 
       const absPath = path.join(stagingDir, relFilePath)
       fs.mkdirSync(path.dirname(absPath), { recursive: true })
@@ -2336,12 +2642,8 @@ function stageOrganized(organized, stagingDir, opts = {}) {
     }
   }
 
-  for (const cat of organized.categories || []) {
+  for (const cat of eligibleCategories) {
     const { topDir, subDir } = routeCategory(cat.title)
-    if (skipApiReference && topDir === 'reference') {
-      counts.skippedApiRef += countPagesDeep(cat.pages || [])
-      continue
-    }
     const dir = subDir ? `${topDir}/${subDir}` : topDir
     if (subDir) {
       if (!subDirsByTopDir.has(topDir)) subDirsByTopDir.set(topDir, [])
@@ -2420,30 +2722,104 @@ function buildFrontmatter(topDir, page, slug, pickIcon, opts = {}) {
 }
 
 /**
- * Turn a URL's trailing segment into a filename-safe slug. Strips `.md`, kebabs
- * the result, drops any leading numeric prefix (common in imports).
+ * Extract URL path segments for slug planning. Strips file extensions and
+ * leading numeric prefixes (e.g. `01-intro` → `intro`) the same way the
+ * legacy deriveSlug did, so the depth-1 result is byte-for-byte compatible.
  */
-function deriveSlug(url, fallbackTitle) {
-  let raw = ''
+function extractUrlPathSegments(url) {
+  if (!url) return []
   try {
-    const segs = new URL(url).pathname.split('/').filter(Boolean)
-    raw = segs[segs.length - 1] || ''
-  } catch {}
-  raw = raw.replace(/\.(md|mdx|html?)$/i, '').replace(/^\d+[-_.]/, '')
-  const slug = kebabCase(raw || fallbackTitle || 'page')
-  return slug || 'page'
+    return new URL(url).pathname
+      .split('/')
+      .filter(Boolean)
+      .map((s) => s.replace(/\.(md|mdx|html?)$/i, '').replace(/^\d+[-_.]/, ''))
+      .filter(Boolean)
+  } catch {
+    return []
+  }
 }
 
 /**
- * If `slug` is already in use anywhere in the staging tree, try `slug-2`,
- * `slug-3`, etc. The duplicates validator flags same-slug collisions across
- * directories, not just within a directory, so uniqueness must be global.
+ * Compute a globally-unique slug for every page in the tree.
+ *
+ * Base slug is the last URL segment (kebab-cased). When two or more pages
+ * share a base, we prepend the next-up URL segment to every member of the
+ * colliding group and recheck
+ * 
+ * @example
+ * ensureUniqueSlugs([
+ *   { title: 'Getting Started', pages: [
+ *     { title: 'Overview', url: 'https://acme.dev/getting-started/overview' },
+ *     { title: 'Install',  url: 'https://acme.dev/getting-started/install' },
+ *   ]},
+ *   { title: 'Guides', pages: [
+ *     { title: 'Overview', url: 'https://acme.dev/guides/overview' },
+ *   ]},
+ * ])
+ * // Map {
+ * //   <Overview (Getting Started)> => 'getting-started-overview',  // expanded (collides)
+ * //   <Install>                    => 'install',                   // unique, no expansion
+ * //   <Overview (Guides)>          => 'guides-overview',            // expanded (collides)
+ * // }
  */
-function resolveSlug(slug, usedSlugs) {
-  if (!usedSlugs.has(slug)) return slug
-  let n = 2
-  while (usedSlugs.has(`${slug}-${n}`)) n++
-  return `${slug}-${n}`
+function ensureUniqueSlugs(categories) {
+  const entries = []
+  const walk = (pages) => {
+    for (const p of pages || []) {
+      entries.push({ page: p, segments: extractUrlPathSegments(p.url), fallback: p.title, depth: 1 })
+      if (p.pages) walk(p.pages)
+    }
+  }
+  for (const c of categories || []) walk(c.pages)
+
+  const slugFor = (e) => {
+    if (e.segments.length === 0) return kebabCase(e.fallback || 'page') || 'page'
+    const start = Math.max(0, e.segments.length - e.depth)
+    return kebabCase(e.segments.slice(start).join('-')) || 'page'
+  }
+
+  // Iteratively grow any colliding group by one segment until stable. Each
+  // pass only grows pages that still have headroom (depth < segments.length);
+  // a page stuck at full depth stays put while its peers keep expanding.
+  while (true) {
+    const groups = new Map()
+    for (const e of entries) {
+      const s = slugFor(e)
+      if (!groups.has(s)) groups.set(s, [])
+      groups.get(s).push(e)
+    }
+    let grew = false
+    for (const group of groups.values()) {
+      if (group.length < 2) continue
+      for (const e of group) {
+        if (e.depth < e.segments.length) {
+          e.depth++
+          grew = true
+        }
+      }
+    }
+    if (!grew) break
+  }
+
+  const describe = (x) => `"${x.page.title || '(untitled)'}"${x.page.url ? ` <${x.page.url}>` : ' (group-only)'}`
+  const used = new Set()
+  const result = new Map()
+  for (const e of entries) {
+    const base = slugFor(e)
+    let slug = base
+    if (used.has(slug)) {
+      let n = 2
+      while (used.has(`${slug}-${n}`)) n++
+      slug = `${base}-${n}`
+      styles.error(
+        `Slug collision after segment expansion: ${base} — falling back to ${slug} for ${describe(e)}. ` +
+          `Pages were deduped by path before organize, so this indicates the organize step produced duplicates.`,
+      )
+    }
+    used.add(slug)
+    result.set(e.page, slug)
+  }
+  return result
 }
 
 // Values YAML interprets as non-strings need quoting when used as _order entries.

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)
   }
 }