diff --git a/src/commands/import.js b/src/commands/import.js index dc20b04..afd9068 100644 --- a/src/commands/import.js +++ b/src/commands/import.js @@ -4898,6 +4898,14 @@ function filterUrlPagesTree(pages, predicate) { * Writes _order.yaml per directory so sidebar order matches input order. */ function stageOrganized(organized, stagingDir, opts = {}) { + // Category titles become directory names. Reject any resolved path that leaves + // this temp dir (Windows `path.join` treats `\` as a separator and collapses `..`). + const assertContained = makeContainment(stagingDir, { label: 'staging directory' }); + const writeContained = (absPath, contents) => { + assertContained(absPath); + fs.mkdirSync(path.dirname(absPath), { recursive: true }); + fs.writeFileSync(absPath, contents); + }; const pickIcon = makeIconPicker(); const byDir = new Map(); const subDirsByTopDir = new Map(); @@ -4988,8 +4996,7 @@ function stageOrganized(organized, stagingDir, opts = {}) { } const absPath = path.join(stagingDir, relFilePath); - fs.mkdirSync(path.dirname(absPath), { recursive: true }); - fs.writeFileSync(absPath, toFrontmatter(frontmatter)); + writeContained(absPath, toFrontmatter(frontmatter)); counts.fileCount++; // The sidebar entry is `slug` for both leaves (`.md`) and parents @@ -5011,9 +5018,11 @@ function stageOrganized(organized, stagingDir, opts = {}) { // Namespace every NESTED category folder by its ancestor path so its basename // (and thus slug) is globally unique, and back it with an `index.md` so it's a // real titled parent. Top-level categories are matched by title, not slug, so - // their folders are left untouched. + // a safe display title is left untouched. A segment Windows would treat as + // `..` or as a separator is rewritten first, or a raw `..\` title would + // resolve outside this staging directory. const usedContainerSlugs = new Set(slugFor.values()); - const segRename = new Map(); // original path prefix -> unique folder name + const segRename = new Map(); // original path prefix -> folder name const nestedContainers = new Map(); // renamed dir (rel to stagingDir) -> display title const uniqueContainerName = base => { let name = base || 'section'; @@ -5030,7 +5039,20 @@ function stageOrganized(organized, stagingDir, opts = {}) { const out = []; for (let i = 0; i < segs.length; i++) { if (i === 0) { - out.push(segs[0]); + // Same original root must stay one folder. `SDK: Java/Setup/Windows` + // and `SDK: Java/Setup/Linux` both rewrite to `sdk-java`; allocating + // the second call would split the tree and reuse the child slug. + let name = segRename.get(segs[0]); + if (!name) { + const folder = safeCategorySegment(segs[0]); + // Equality with the raw segment means "display title, unchanged". + // Two categories may share that spelling. A rewritten name is + // suffixed when it collides with a different title or a page slug. + name = folder === segs[0] ? folder : uniqueContainerName(folder); + if (name === segs[0]) usedContainerSlugs.add(name); + segRename.set(segs[0], name); + } + out.push(name); continue; } const origPrefix = segs.slice(0, i + 1).join('/'); @@ -5062,10 +5084,10 @@ function stageOrganized(organized, stagingDir, opts = {}) { // these are pure nav containers, so the body stays empty and format skips them. for (const [relDir, title] of nestedContainers) { const idxPath = path.join(stagingDir, relDir, 'index.md'); + assertContained(idxPath); if (fs.existsSync(idxPath)) continue; - fs.mkdirSync(path.dirname(idxPath), { recursive: true }); const fm = { title, icon: formatIconClass(pickIcon(path.basename(relDir), title)) }; - fs.writeFileSync(idxPath, toFrontmatter(fm)); + writeContained(idxPath, toFrontmatter(fm)); counts.fileCount++; } @@ -5073,14 +5095,14 @@ function stageOrganized(organized, stagingDir, opts = {}) { for (const [dir, slugs] of byDir) { const orderPath = path.join(stagingDir, dir, '_order.yaml'); const body = `${slugs.map(s => `- ${yamlSafeSlug(s)}`).join('\n')}\n`; - fs.writeFileSync(orderPath, body); + writeContained(orderPath, body); } // Top-level _order.yaml (e.g. docs/_order.yaml) lists category subfolders. for (const [topDir, subs] of subDirsByTopDir) { const orderPath = path.join(stagingDir, topDir, '_order.yaml'); const body = `${subs.map(s => `- ${yamlSafeSlug(s)}`).join('\n')}\n`; - fs.writeFileSync(orderPath, body); + writeContained(orderPath, body); } return { fileCount: counts.fileCount, dirCount: byDir.size, skippedApiRef: counts.skippedApiRef }; @@ -5407,6 +5429,25 @@ function kebabCase(s) { ); } +/** + * Folder name for one category-title segment. + * + * Returns `segment` unchanged when it is safe to use as a path segment, so + * callers can treat equality with the input as "display title, not rewritten". + * Windows drops trailing dots and spaces, so `.`, `..`, and `.. ` all trim to + * empty and are rewritten. `path.win32` also treats `\`, `/`, and `:` as + * separators. `Guides` and `API Docs` stay as authored. + * + * @param {string} segment A single `/`-separated piece of a category title. + * @returns {string} + */ +function safeCategorySegment(segment) { + const seg = String(segment); + const trimmed = seg.replace(/[.\s]+$/g, ''); + const escapes = trimmed === '' || /[\\/\0-\x1f:]/.test(seg); + return escapes ? kebabCase(seg) : seg; +} + // Keyword → FontAwesome icon. Ported from v1 (most-specific entries first). // Each rule maps to an ordered list of candidates; the first unused-in-this-dir // icon wins so sibling pages don't all share the same icon. diff --git a/test/commands/import/staging.test.js b/test/commands/import/staging.test.js index c4ec7bf..ed3f702 100644 --- a/test/commands/import/staging.test.js +++ b/test/commands/import/staging.test.js @@ -3,9 +3,10 @@ import os from 'node:os'; import path from 'node:path'; import { Command } from 'commander'; -import { afterEach, test, expect } from 'vitest'; +import { afterEach, expect, test, vi } from 'vitest'; import { args, __test__ } from '../../../src/commands/import.js'; +import { PathEscapeError } from '../../../src/utils/containment.js'; import { parseFrontmatter, toFrontmatter } from '../../../src/utils/markdown.js'; const { stageOrganized, finalizeChangelogs, allocateChangelogFilenames } = __test__; @@ -29,6 +30,38 @@ function readFm(filePath) { return parseFrontmatter(fs.readFileSync(filePath, 'utf8')).data; } +function listFiles(dir) { + const out = []; + for (const entry of fs.readdirSync(dir, { withFileTypes: true })) { + const full = path.join(dir, entry.name); + if (entry.isDirectory()) out.push(...listFiles(full)); + else out.push(full); + } + return out; +} + +/** Re-join staged paths with Windows path semantics and require they stay put. */ +// oxlint-disable vitest/no-standalone-expect -- expects belong to the helper's caller +const expectContainedOnWin32 = vi.defineHelper(stagingDir => { + const winRoot = 'C:\\Users\\dev\\AppData\\Local\\Temp\\readme-import-abc123'; + const rootReal = fs.realpathSync(stagingDir); + const files = listFiles(stagingDir); + expect(files.length).toBeGreaterThan(0); + for (const file of files) { + const rel = path.relative(rootReal, fs.realpathSync(file)); + expect(rel === '..' || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)).toBe(false); + for (const part of rel.split(path.sep)) { + expect(part).not.toBe('..'); + expect(part).not.toBe('.'); + expect(part).not.toContain('\\'); + } + const winAbs = path.win32.join(winRoot, rel.split(path.sep).join(path.win32.sep)); + const winRel = path.win32.relative(winRoot, winAbs); + expect(winRel === '..' || winRel.startsWith(`..${path.win32.sep}`) || path.win32.isAbsolute(winRel)).toBe(false); + } +}); +// oxlint-enable vitest/no-standalone-expect + test('stageOrganized writes parent pages as index.md and leaves as slug.md', () => { withStaging(stagingDir => { const parent = { @@ -205,6 +238,143 @@ test('import command has no conditional changelog layout option', () => { expect(cmd.options.some(option => option.long === '--separate-changelog')).toBe(false); }); +test('stageOrganized keeps hostile category titles inside staging on win32', () => { + withStaging(stagingDir => { + const backslash = '..\\..\\..\\..\\..\\..\\..\\Users\\Public\\poc'; + const pages = n => + Array.from({ length: n }, (_, i) => ({ + title: `Page ${i + 1}`, + url: `https://example.com/docs/bs-${i + 1}`, + })); + + stageOrganized( + { + categories: [ + { title: 'Guides', pages: [{ title: 'Pricing', url: 'https://example.com/docs/pricing' }] }, + { title: backslash, pages: pages(5) }, + { title: '..\\poc', pages: [{ title: 'Near', url: 'https://example.com/docs/near' }] }, + { title: '..\\..\\poc', pages: [{ title: 'Far', url: 'https://example.com/docs/far' }] }, + { + title: 'C:\\Users\\Public\\poc-drive', + pages: [{ title: 'Drive', url: 'https://example.com/docs/drive' }], + }, + { + title: '\\\\server\\share\\poc', + pages: [{ title: 'Unc', url: 'https://example.com/docs/unc' }], + }, + { + title: '../../../../../../../../tmp/rm19530-slash-escape', + pages: [ + { title: 'Slash', url: 'https://example.com/docs/slash-1' }, + { title: 'Slash 2', url: 'https://example.com/docs/slash-2' }, + ], + }, + { + title: '..\\..\\..\\outside/Nested group', + pages: [{ title: 'Mixed', url: 'https://example.com/docs/mixed' }], + }, + { title: 'v2.', pages: [{ title: 'Release', url: 'https://example.com/docs/v2-notes' }] }, + ], + }, + stagingDir, + ); + + expect(fs.existsSync(path.join(stagingDir, 'docs', 'Guides', 'pricing.md'))).toBe(true); + expect(fs.existsSync(path.join(stagingDir, 'docs', 'users-public-poc', 'bs-1.md'))).toBe(true); + expect(fs.existsSync(path.join(stagingDir, 'docs', 'users-public-poc', 'bs-5.md'))).toBe(true); + expect(fs.existsSync(path.join(stagingDir, 'docs', 'users-public-poc', '_order.yaml'))).toBe(true); + expect(fs.existsSync(path.join(stagingDir, 'docs', 'poc', 'near.md'))).toBe(true); + expect(fs.existsSync(path.join(stagingDir, 'docs', 'poc-2', 'far.md'))).toBe(true); + expect(fs.existsSync(path.join(stagingDir, 'docs', 'c-users-public-poc-drive', 'drive.md'))).toBe(true); + expect(fs.existsSync(path.join(stagingDir, 'docs', 'server-share-poc', 'unc.md'))).toBe(true); + expect(fs.existsSync(path.join(stagingDir, 'docs', 'outside', 'outside-nested-group', 'mixed.md'))).toBe(true); + expect(fs.existsSync(path.join(stagingDir, 'docs', 'v2.', 'v2-notes.md'))).toBe(true); + expect(fs.existsSync(path.join(stagingDir, 'docs', 'page'))).toBe(true); + + const names = fs.readdirSync(path.join(stagingDir, 'docs')); + expect(names.some(name => name.includes('\\') || name === '..' || name === '.')).toBe(false); + expect(fs.readFileSync(path.join(stagingDir, 'docs', '_order.yaml'), 'utf8')).toContain('users-public-poc'); + expect(readFm(path.join(stagingDir, 'docs', 'users-public-poc', 'bs-1.md'))['x-import']).toBe( + 'https://example.com/docs/bs-1', + ); + + expectContainedOnWin32(stagingDir); + }); +}); + +test('stageOrganized rewrites a parent segment that trims to empty', () => { + withStaging(stagingDir => { + stageOrganized( + { + categories: [ + { title: '.', pages: [{ title: 'Dot', url: 'https://example.com/docs/dot' }] }, + { title: '..', pages: [{ title: 'Up', url: 'https://example.com/docs/up' }] }, + // routeCategory trims the whole title, so the trailing space has to + // sit on an earlier segment to survive until the folder name. + { title: '.. /Notes', pages: [{ title: 'Note', url: 'https://example.com/docs/note' }] }, + ], + }, + stagingDir, + ); + + expect(fs.existsSync(path.join(stagingDir, 'docs', 'page', 'dot.md'))).toBe(true); + expect(fs.existsSync(path.join(stagingDir, 'docs', 'page-2', 'up.md'))).toBe(true); + expect(fs.existsSync(path.join(stagingDir, 'docs', 'page-3', 'notes', 'note.md'))).toBe(true); + const names = fs.readdirSync(path.join(stagingDir, 'docs')); + expect(names).not.toContain('.'); + expect(names).not.toContain('..'); + expect(names).not.toContain('.. '); + expectContainedOnWin32(stagingDir); + }); +}); + +test('stageOrganized keeps one folder for a shared rewritten category root', () => { + withStaging(stagingDir => { + stageOrganized( + { + categories: [ + { + title: 'SDK: Java/Setup/Windows', + pages: [{ title: 'Win', url: 'https://example.com/docs/sdk-win' }], + }, + { + title: 'SDK: Java/Setup/Linux', + pages: [{ title: 'Lin', url: 'https://example.com/docs/sdk-lin' }], + }, + ], + }, + stagingDir, + ); + + const setup = path.join(stagingDir, 'docs', 'sdk-java', 'sdk-java-setup'); + expect(fs.existsSync(path.join(setup, 'sdk-java-setup-windows', 'sdk-win.md'))).toBe(true); + expect(fs.existsSync(path.join(setup, 'sdk-java-setup-linux', 'sdk-lin.md'))).toBe(true); + expect(fs.existsSync(path.join(stagingDir, 'docs', 'sdk-java-2'))).toBe(false); + expect(readFm(path.join(setup, 'index.md')).title).toBe('Setup'); + expect(readFm(path.join(setup, 'sdk-java-setup-windows', 'index.md')).title).toBe('Windows'); + expect(readFm(path.join(setup, 'sdk-java-setup-linux', 'index.md')).title).toBe('Linux'); + expectContainedOnWin32(stagingDir); + }); +}); + +test('stageOrganized refuses a slug that resolves outside staging', () => { + withStaging(stagingDir => { + const probe = path.join(path.dirname(stagingDir), 'rm19530-escape-probe.md'); + fs.rmSync(probe, { force: true }); + const page = { title: 'Escape', url: 'https://example.com/docs/escape' }; + try { + expect(() => + stageOrganized({ categories: [{ title: 'Guides', pages: [page] }] }, stagingDir, { + slugFor: new Map([[page, '../../../rm19530-escape-probe']]), + }), + ).toThrow(PathEscapeError); + expect(fs.existsSync(probe)).toBe(false); + } finally { + fs.rmSync(probe, { force: true }); + } + }); +}); + test('stageOrganized quotes YAML-unsafe slugs in _order.yaml', () => { withStaging(stagingDir => { stageOrganized(