Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 50 additions & 9 deletions src/commands/import.js
Original file line number Diff line number Diff line change
Expand Up @@ -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();
Expand Down Expand Up @@ -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 (`<slug>.md`) and parents
Expand All @@ -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';
Expand All @@ -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('/');
Expand Down Expand Up @@ -5062,25 +5084,25 @@ 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++;
}

// Per-directory _order.yaml preserves input order in the sidebar.
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 };
Expand Down Expand Up @@ -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.
Expand Down
172 changes: 171 additions & 1 deletion test/commands/import/staging.test.js
Original file line number Diff line number Diff line change
Expand Up @@ -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__;
Expand All @@ -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 = {
Expand Down Expand Up @@ -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(
Expand Down
Loading