@readme/cli 0.1.0 → 0.3.0

package/src/commands/import.landing.test.js

@@ -1,217 +0,0 @@
-import { afterEach, test } from 'node:test'
-import assert from 'node:assert/strict'
-import { __test__ } from './import.js'
-
-const {
-  injectSectionLandingPages,
-  parseMetaRefreshTarget,
-  parseHtmlCanonical,
-} = __test__
-
-const originalFetch = globalThis.fetch
-
-afterEach(() => {
-  globalThis.fetch = originalFetch
-})
-
-function mockLandingFetch(routes) {
-  globalThis.fetch = async (url) => {
-    const href = String(url)
-    const entry = routes[href]
-    if (!entry) return { ok: false, status: 404, url: href, text: async () => '' }
-    if (entry instanceof Error) throw entry
-    return {
-      ok: entry.ok !== false,
-      status: entry.status ?? 200,
-      url: entry.finalUrl || href,
-      text: async () => entry.body || '',
-    }
-  }
-}
-
-test('parseMetaRefreshTarget resolves relative, quoted, and entity-encoded targets', () => {
-  const base = 'https://example.com/docs/guides/'
-  assert.equal(
-    parseMetaRefreshTarget('<meta http-equiv="refresh" content="0;url=/docs/guides/intro">', base),
-    'https://example.com/docs/guides/intro',
-  )
-  assert.equal(
-    parseMetaRefreshTarget("<meta http-equiv='refresh' content='0; url=intro'>", base),
-    'https://example.com/docs/guides/intro',
-  )
-  assert.equal(
-    parseMetaRefreshTarget('<meta http-equiv="refresh" content="0;url=/docs/guides?tab=js&amp;x=1">', base),
-    'https://example.com/docs/guides?tab=js&x=1',
-  )
-  assert.equal(parseMetaRefreshTarget('<html><title>Guides</title></html>', base), null)
-  assert.equal(parseMetaRefreshTarget('', base), null)
-  assert.equal(parseMetaRefreshTarget('<meta http-equiv="refresh" content="5">', base), null)
-})
-
-test('parseHtmlCanonical resolves relative and entity-encoded hrefs', () => {
-  const base = 'https://example.com/docs/guides/'
-  assert.equal(
-    parseHtmlCanonical('<link rel="canonical" href="/docs/guides/intro">', base),
-    'https://example.com/docs/guides/intro',
-  )
-  assert.equal(
-    parseHtmlCanonical("<link rel='canonical' href='intro'>", base),
-    'https://example.com/docs/guides/intro',
-  )
-  assert.equal(
-    parseHtmlCanonical('<link rel="canonical" href="/docs/guides?tab=js&amp;x=1">', base),
-    'https://example.com/docs/guides?tab=js&x=1',
-  )
-  assert.equal(parseHtmlCanonical('<html></html>', base), null)
-  assert.equal(parseHtmlCanonical('', base), null)
-})
-
-test('injectSectionLandingPages prepends a real common-prefix landing page', async () => {
-  mockLandingFetch({
-    'https://example.com/docs/guides': { body: '<title>Guides</title>' },
-  })
-  const organized = {
-    categories: [
-      {
-        title: 'Guides',
-        pages: [
-          { title: 'Intro', url: 'https://example.com/docs/guides/intro' },
-          { title: 'Install', url: 'https://example.com/docs/guides/install' },
-        ],
-      },
-    ],
-  }
-
-  await injectSectionLandingPages(organized, 'https://example.com/docs')
-
-  assert.equal(organized.categories[0].pages[0].url, 'https://example.com/docs/guides')
-  assert.equal(organized.categories[0].pages[0].title, 'Guides')
-  assert.equal(organized.categories[0].pages.length, 3)
-})
-
-test('injectSectionLandingPages skips client-redirect stub landings via meta refresh', async () => {
-  mockLandingFetch({
-    'https://example.com/docs/guides': {
-      body: '<meta http-equiv="refresh" content="0;url=/docs/guides/intro">',
-    },
-  })
-  const organized = {
-    categories: [
-      {
-        title: 'Guides',
-        pages: [
-          { title: 'Intro', url: 'https://example.com/docs/guides/intro' },
-          { title: 'Install', url: 'https://example.com/docs/guides/install' },
-        ],
-      },
-    ],
-  }
-
-  await injectSectionLandingPages(organized, 'https://example.com/docs')
-  assert.deepEqual(
-    organized.categories[0].pages.map((p) => p.url),
-    ['https://example.com/docs/guides/intro', 'https://example.com/docs/guides/install'],
-  )
-})
-
-test('injectSectionLandingPages skips landings whose canonical points at a known child', async () => {
-  mockLandingFetch({
-    'https://example.com/docs/guides': {
-      body: '<link rel="canonical" href="/docs/guides/intro">',
-    },
-  })
-  const organized = {
-    categories: [
-      {
-        title: 'Guides',
-        pages: [
-          { title: 'Intro', url: 'https://example.com/docs/guides/intro' },
-          { title: 'Install', url: 'https://example.com/docs/guides/install' },
-        ],
-      },
-    ],
-  }
-
-  await injectSectionLandingPages(organized, 'https://example.com/docs')
-  assert.equal(organized.categories[0].pages.length, 2)
-})
-
-test('injectSectionLandingPages skips landings that HTTP-redirect onto a known child', async () => {
-  mockLandingFetch({
-    'https://example.com/docs/guides': {
-      finalUrl: 'https://example.com/docs/guides/intro',
-      body: '<title>Intro</title>',
-    },
-  })
-  const organized = {
-    categories: [
-      {
-        title: 'Guides',
-        pages: [
-          { title: 'Intro', url: 'https://example.com/docs/guides/intro' },
-          { title: 'Install', url: 'https://example.com/docs/guides/install' },
-        ],
-      },
-    ],
-  }
-
-  await injectSectionLandingPages(organized, 'https://example.com/docs')
-  assert.equal(organized.categories[0].pages.length, 2)
-})
-
-test('injectSectionLandingPages does not probe the import base or categories with a single child', async () => {
-  const seen = []
-  globalThis.fetch = async (url) => {
-    seen.push(String(url))
-    return { ok: true, status: 200, url: String(url), text: async () => '<title>Docs</title>' }
-  }
-  const organized = {
-    categories: [
-      {
-        title: 'Docs',
-        pages: [
-          { title: 'A', url: 'https://example.com/docs/a' },
-          { title: 'B', url: 'https://example.com/docs/b' },
-        ],
-      },
-      {
-        title: 'Lonely',
-        pages: [{ title: 'Only', url: 'https://example.com/docs/guides/only' }],
-      },
-    ],
-  }
-
-  await injectSectionLandingPages(organized, 'https://example.com/docs')
-  assert.deepEqual(seen, [])
-  assert.equal(organized.categories[0].pages.length, 2)
-  assert.equal(organized.categories[1].pages.length, 1)
-})
-
-test('injectSectionLandingPages ignores 404s and fetch failures', async () => {
-  mockLandingFetch({
-    'https://example.com/docs/guides': new Error('network down'),
-    'https://example.com/docs/api': { ok: false, status: 404, body: '' },
-  })
-  const organized = {
-    categories: [
-      {
-        title: 'Guides',
-        pages: [
-          { title: 'Intro', url: 'https://example.com/docs/guides/intro' },
-          { title: 'Install', url: 'https://example.com/docs/guides/install' },
-        ],
-      },
-      {
-        title: 'API',
-        pages: [
-          { title: 'Auth', url: 'https://example.com/docs/api/auth' },
-          { title: 'Errors', url: 'https://example.com/docs/api/errors' },
-        ],
-      },
-    ],
-  }
-
-  await injectSectionLandingPages(organized, 'https://example.com/docs')
-  assert.equal(organized.categories[0].pages.length, 2)
-  assert.equal(organized.categories[1].pages.length, 2)
-})

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

@@ -1,86 +0,0 @@
-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.staging.test.js

@@ -1,230 +0,0 @@
-import { afterEach, test } from 'node:test'
-import assert from 'node:assert/strict'
-import fs from 'node:fs'
-import os from 'node:os'
-import path from 'node:path'
-import matter from 'gray-matter'
-import { Command } from 'commander'
-import { args, __test__ } from './import.js'
-
-const { stageOrganized, finalizeChangelogs, allocateChangelogFilenames } = __test__
-
-const originalLog = console.log
-afterEach(() => {
-  console.log = originalLog
-})
-
-function withStaging(fn) {
-  const stagingDir = fs.mkdtempSync(path.join(os.tmpdir(), 'import-staging-'))
-  console.log = () => {}
-  try {
-    return fn(stagingDir)
-  } finally {
-    fs.rmSync(stagingDir, { recursive: true, force: true })
-  }
-}
-
-function readFm(filePath) {
-  return matter(fs.readFileSync(filePath, 'utf8')).data
-}
-
-test('stageOrganized writes parent pages as index.md and leaves as slug.md', () => {
-  withStaging((stagingDir) => {
-    const parent = {
-      title: 'Getting Started',
-      url: 'https://example.com/docs/getting-started',
-      pages: [{ title: 'Install', url: 'https://example.com/docs/getting-started/install' }],
-    }
-    const leaf = { title: 'Pricing', url: 'https://example.com/docs/pricing' }
-
-    const result = stageOrganized(
-      { categories: [{ title: 'Guides', pages: [parent, leaf] }] },
-      stagingDir,
-    )
-
-    const parentIndex = path.join(stagingDir, 'docs', 'Guides', 'getting-started', 'index.md')
-    const child = path.join(stagingDir, 'docs', 'Guides', 'getting-started', 'install.md')
-    const leafFile = path.join(stagingDir, 'docs', 'Guides', 'pricing.md')
-    const siblingParent = path.join(stagingDir, 'docs', 'Guides', 'getting-started.md')
-
-    assert.equal(fs.existsSync(parentIndex), true)
-    assert.equal(fs.existsSync(child), true)
-    assert.equal(fs.existsSync(leafFile), true)
-    assert.equal(fs.existsSync(siblingParent), false)
-
-    assert.equal(readFm(parentIndex).title, 'Getting Started')
-    assert.equal(readFm(parentIndex)['x-import'], 'https://example.com/docs/getting-started')
-    assert.equal(readFm(child).title, 'Install')
-    assert.equal(readFm(leafFile).title, 'Pricing')
-
-    const guidesOrder = fs.readFileSync(path.join(stagingDir, 'docs', 'Guides', '_order.yaml'), 'utf8')
-    assert.match(guidesOrder, /^- getting-started$/m)
-    assert.match(guidesOrder, /^- pricing$/m)
-    assert.doesNotMatch(guidesOrder, /^- index$/m)
-
-    const nestedOrder = fs.readFileSync(
-      path.join(stagingDir, 'docs', 'Guides', 'getting-started', '_order.yaml'),
-      'utf8',
-    )
-    assert.match(nestedOrder, /^- install$/m)
-    assert.equal(result.fileCount, 3)
-  })
-})
-
-test('stageOrganized rescues /api/docs pages when skipping API reference categories', () => {
-  withStaging((stagingDir) => {
-    const result = stageOrganized(
-      {
-        categories: [
-          {
-            title: 'API Reference',
-            pages: [
-              { title: 'List pets', url: 'https://example.com/api/reference/pets' },
-              { title: 'Guides', url: 'https://example.com/api/docs/guides/intro' },
-              {
-                title: 'Mixed',
-                pages: [{ title: 'Pricing', url: 'https://example.com/api/docs/pricing' }],
-              },
-            ],
-          },
-        ],
-      },
-      stagingDir,
-      { skipApiReference: true },
-    )
-
-    assert.equal(result.skippedApiRef, 1)
-    assert.equal(fs.existsSync(path.join(stagingDir, 'reference')), false)
-
-    const rescuedDir = path.join(stagingDir, 'docs', 'API Docs')
-    const guides = path.join(rescuedDir, 'intro.md')
-    const pricing = path.join(rescuedDir, 'introduction', 'pricing.md')
-    assert.equal(fs.existsSync(guides), true)
-    assert.equal(fs.existsSync(pricing), true)
-    assert.equal(readFm(guides)['x-import'], 'https://example.com/api/docs/guides/intro')
-    assert.equal(readFm(pricing)['x-import'], 'https://example.com/api/docs/pricing')
-  })
-})
-
-test('stageOrganized namespaces nested category folders that would otherwise share a basename', () => {
-  withStaging((stagingDir) => {
-    stageOrganized(
-      {
-        categories: [
-          { title: 'Fundamentals', pages: [{ title: 'Hello', url: 'https://example.com/docs/hello' }] },
-          { title: 'cockroach/Fundamentals', pages: [{ title: 'SQL', url: 'https://example.com/docs/sql' }] },
-        ],
-      },
-      stagingDir,
-    )
-
-    const topLevel = path.join(stagingDir, 'docs', 'Fundamentals', 'hello.md')
-    const nestedDir = path.join(stagingDir, 'docs', 'cockroach', 'cockroach-fundamentals')
-    const nestedPage = path.join(nestedDir, 'sql.md')
-    const nestedIndex = path.join(nestedDir, 'index.md')
-
-    assert.equal(fs.existsSync(topLevel), true)
-    assert.equal(fs.existsSync(nestedPage), true)
-    assert.equal(fs.existsSync(nestedIndex), true)
-    assert.equal(readFm(nestedIndex).title, 'Fundamentals')
-    assert.equal('x-import' in readFm(nestedIndex), false)
-
-    const docsOrder = fs.readFileSync(path.join(stagingDir, 'docs', '_order.yaml'), 'utf8')
-    assert.match(docsOrder, /^- Fundamentals$/m)
-    assert.match(docsOrder, /^- cockroach\/cockroach-fundamentals$/m)
-  })
-})
-
-test('finalizeChangelogs emits flat canonical changelogs without an order file and suffixes case-insensitive collisions', () => {
-  withStaging((stagingDir) => {
-    const changelogDir = path.join(stagingDir, 'docs', 'Changelog')
-    fs.mkdirSync(path.join(changelogDir, 'foo'), { recursive: true })
-    fs.writeFileSync(
-      path.join(changelogDir, 'foo', 'Bar.md'),
-      matter.stringify('', { title: 'Nested', icon: 'fa-book', 'x-import': 'https://example.com/nested' }),
-    )
-    fs.writeFileSync(
-      path.join(changelogDir, 'foo-bar.md'),
-      matter.stringify('', { title: 'Root', icon: 'fa-book', 'x-import': 'https://example.com/root' }),
-    )
-    fs.writeFileSync(
-      path.join(changelogDir, 'unchanged.md'),
-      matter.stringify('', { title: 'Unchanged', icon: 'fa-book', 'x-import': 'https://example.com/unchanged' }),
-    )
-    fs.writeFileSync(path.join(stagingDir, 'docs', '_order.yaml'), '- Changelog\n')
-
-    assert.equal(finalizeChangelogs(stagingDir), 3)
-
-    const outputDir = path.join(stagingDir, 'changelogs')
-    assert.deepEqual(fs.readdirSync(outputDir).sort(), ['foo-Bar.md', 'foo-bar-2.md', 'unchanged.md'])
-    assert.equal(fs.existsSync(path.join(outputDir, '_order.yaml')), false)
-    assert.equal(fs.existsSync(path.join(stagingDir, 'changelog')), false)
-    assert.equal(fs.existsSync(path.join(stagingDir, 'docs', 'Changelog')), false)
-    assert.equal(fs.existsSync(path.join(stagingDir, 'docs', '_order.yaml')), false)
-    assert.equal(readFm(path.join(outputDir, 'foo-Bar.md')).icon, undefined)
-    assert.equal(readFm(path.join(outputDir, 'foo-Bar.md'))['x-import'], 'https://example.com/nested')
-    assert.equal(readFm(path.join(outputDir, 'foo-bar-2.md'))['x-import'], 'https://example.com/root')
-    assert.equal(readFm(path.join(outputDir, 'unchanged.md'))['x-import'], 'https://example.com/unchanged')
-  })
-})
-
-test('stageOrganized retains case-only changelog names before finalization', () => {
-  withStaging((stagingDir) => {
-    const upper = { title: 'Upper A', url: 'https://example.com/A' }
-    const lower = { title: 'Lower a', url: 'https://example.com/a' }
-    const independent = { title: 'Independent a-2', url: 'https://example.com/a-2' }
-    stageOrganized(
-      { categories: [{ title: 'Changelog', pages: [upper, lower, independent] }] },
-      stagingDir,
-      { slugFor: new Map([[upper, 'A'], [lower, 'a'], [independent, 'a-2']]) },
-    )
-    assert.equal(finalizeChangelogs(stagingDir), 3)
-
-    const outputDir = path.join(stagingDir, 'changelogs')
-    assert.deepEqual(fs.readdirSync(outputDir).sort(), ['A.md', 'a-2.md', 'a-3.md'])
-    assert.equal(readFm(path.join(outputDir, 'A.md')).title, 'Upper A')
-    assert.equal(readFm(path.join(outputDir, 'a-3.md')).title, 'Lower a')
-    assert.equal(readFm(path.join(outputDir, 'a-2.md')).title, 'Independent a-2')
-  })
-})
-
-test('allocateChangelogFilenames preserves an independent numeric-suffix filename', () => {
-  assert.deepEqual(
-    allocateChangelogFilenames([
-      { ancestors: [], slug: 'A' },
-      { ancestors: [], slug: 'a' },
-      { ancestors: [], slug: 'a-2' },
-    ]),
-    ['A', 'a-3', 'a-2'],
-  )
-})
-
-test('import command has no conditional changelog layout option', () => {
-  const cmd = new Command()
-  args(cmd)
-
-  assert.equal(cmd.options.some((option) => option.long === '--separate-changelog'), false)
-})
-
-test('stageOrganized quotes YAML-unsafe slugs in _order.yaml', () => {
-  withStaging((stagingDir) => {
-    stageOrganized(
-      {
-        categories: [
-          {
-            title: 'Guides',
-            pages: [
-              { title: 'True', url: 'https://example.com/docs/true' },
-              { title: 'Null', url: 'https://example.com/docs/null' },
-            ],
-          },
-        ],
-      },
-      stagingDir,
-    )
-
-    const order = fs.readFileSync(path.join(stagingDir, 'docs', 'Guides', '_order.yaml'), 'utf8')
-    assert.match(order, /^- "true"$/m)
-    assert.match(order, /^- "null"$/m)
-  })
-})