@diplodoc/cli 5.46.1 → 5.47.0

package/tests/e2e/vars-ignore.test.ts

@@ -0,0 +1,168 @@
+import {describe, expect, test} from 'vitest';
+import {resolve} from 'node:path';
+import {readFileSync} from 'node:fs';
+
+import {TestAdapter, getTestPaths} from '../fixtures';
+
+describe('VarsService ignore patterns', () => {
+    test('should ignore presets files based on ignore patterns', async () => {
+        const {inputPath, outputPath} = getTestPaths('mocks/vars-ignore');
+
+        // Test with ignore patterns via flags - should ignore ignored/ and data/ folders
+        await TestAdapter.testBuildPass(inputPath, outputPath, {
+            md2md: true,
+            args: '--ignore ignored/ --ignore data/',
+        });
+
+        // Check that variables from ignored presets are not resolved
+        const outputContent = readFileSync(resolve(outputPath, 'test.md'), 'utf8');
+        expect(outputContent).toContain('Root var: rootValue');
+        expect(outputContent).toContain('Common var: fromRoot');
+        expect(outputContent).toContain('Ignored var: {{ignoredVar}}'); // Should remain unresolved
+        expect(outputContent).toContain('Data var: {{dataVar}}'); // Should remain unresolved
+    });
+
+    test('should load all presets when no ignore patterns specified', async () => {
+        const {inputPath, outputPath} = getTestPaths('mocks/vars-ignore');
+
+        // Test without ignore patterns - should load all presets
+        await TestAdapter.testBuildPass(inputPath, outputPath + '-no-ignore', {
+            md2md: true,
+        });
+
+        // Check that variables in subdirectories are resolved
+        const ignoredContent = readFileSync(
+            resolve(outputPath + '-no-ignore', 'ignored/ignored-test.md'),
+            'utf8',
+        );
+        expect(ignoredContent).toContain('Root var: rootValue');
+        expect(ignoredContent).toContain('Ignored var: ignoredValue');
+
+        const dataContent = readFileSync(
+            resolve(outputPath + '-no-ignore', 'data/data-test.md'),
+            'utf8',
+        );
+        expect(dataContent).toContain('Root var: rootValue');
+        expect(dataContent).toContain('Data var: dataValue');
+    });
+
+    test('should handle partial ignore patterns', async () => {
+        const {inputPath, outputPath} = getTestPaths('mocks/vars-ignore');
+
+        // Test with partial ignore - should ignore only data/ folder
+        await TestAdapter.testBuildPass(inputPath, outputPath + '-partial', {
+            md2md: true,
+            args: '--ignore data/',
+        });
+
+        // Check that ignored/ presets are loaded but data/ presets are not
+        const ignoredContent = readFileSync(
+            resolve(outputPath + '-partial', 'ignored/ignored-test.md'),
+            'utf8',
+        );
+        expect(ignoredContent).toContain('Root var: rootValue');
+        expect(ignoredContent).toContain('Ignored var: ignoredValue'); // Should be resolved
+
+        const dataContent = readFileSync(
+            resolve(outputPath + '-partial', 'data/data-test.md'),
+            'utf8',
+        );
+        expect(dataContent).toContain('Root var: rootValue');
+        expect(dataContent).toContain('{{dataVar}}'); // Should remain unresolved
+    });
+
+    test('should handle ignore patterns with trailing slashes normalization', async () => {
+        const {inputPath, outputPath} = getTestPaths('mocks/vars-ignore');
+
+        // Test with various trailing slash patterns
+        await TestAdapter.testBuildPass(inputPath, outputPath + '-slashes', {
+            md2md: true,
+            args: '--ignore ignored// --ignore data/',
+        });
+
+        // Check that both folders are ignored despite different slash patterns
+        const outputContent = readFileSync(resolve(outputPath + '-slashes', 'test.md'), 'utf8');
+        expect(outputContent).toContain('Root var: rootValue');
+        expect(outputContent).toContain('Common var: fromRoot');
+        expect(outputContent).toContain('Ignored var: {{ignoredVar}}'); // Should remain unresolved
+        expect(outputContent).toContain('Data var: {{dataVar}}'); // Should remain unresolved
+    });
+
+    test('should ignore top-level presets when using custom config for nested docs', async () => {
+        const {inputPath, outputPath} = getTestPaths('mocks/nested-docs');
+
+        // Test nested docs scenario - use custom config that ignores everything except subdoc/
+        await TestAdapter.testBuildPass(inputPath, outputPath + '-nested', {
+            md2md: true,
+            args: '--config .yfm-subdoc',
+        });
+
+        // Check that subdoc files are processed and variables are resolved correctly
+        const subDocContent = readFileSync(
+            resolve(outputPath + '-nested', 'subdoc/index.md'),
+            'utf8',
+        );
+        expect(subDocContent).toContain('Sub var: subValue'); // Should be resolved from subdoc presets
+        expect(subDocContent).toContain('Common var: fromSub'); // Should use subdoc override
+        expect(subDocContent).toContain('{{topLevelVar}}'); // Should remain unresolved (top-level presets ignored)
+
+        // Verify that top-level presets.yaml was ignored by checking that top-level variables are not available
+        expect(subDocContent).not.toContain('topLevelValue');
+    });
+
+    test('should not load any presets when using custom config with disabled template vars', async () => {
+        const {inputPath, outputPath} = getTestPaths('mocks/nested-docs');
+
+        // Test with custom config and --no-template-vars - should not load any presets at all
+        await TestAdapter.testBuildPass(inputPath, outputPath + '-no-vars-config', {
+            md2md: true,
+            args: '--config .yfm-subdoc --no-template-vars',
+        });
+
+        // Check that ALL variables remain unresolved (no presets loaded at all)
+        const subDocContent = readFileSync(
+            resolve(outputPath + '-no-vars-config', 'subdoc/index.md'),
+            'utf8',
+        );
+        expect(subDocContent).toContain('{{subVar}}'); // Should remain unresolved
+        expect(subDocContent).toContain('{{commonVar}}'); // Should remain unresolved
+        expect(subDocContent).toContain('{{topLevelVar}}'); // Should remain unresolved
+
+        // Verify that no variables were resolved at all
+        expect(subDocContent).not.toContain('Sub var: subValue');
+        expect(subDocContent).not.toContain('Common var: fromSub');
+        expect(subDocContent).not.toContain('Top level var: topLevelValue');
+    });
+
+    test('should not load any presets when template vars are disabled', async () => {
+        const {inputPath, outputPath} = getTestPaths('mocks/vars-ignore');
+
+        // Test with --no-template-vars flag - should not load any presets
+        await TestAdapter.testBuildPass(inputPath, outputPath + '-no-vars', {
+            md2md: true,
+            args: '--no-template-vars',
+        });
+
+        // Check that ALL variables remain unresolved (no presets loaded)
+        const outputContent = readFileSync(resolve(outputPath + '-no-vars', 'test.md'), 'utf8');
+        expect(outputContent).toContain('{{rootVar}}'); // Should remain unresolved
+        expect(outputContent).toContain('{{commonVar}}'); // Should remain unresolved
+        expect(outputContent).toContain('{{ignoredVar}}'); // Should remain unresolved
+        expect(outputContent).toContain('{{dataVar}}'); // Should remain unresolved
+
+        // Check subdirectory files - variables should also remain unresolved
+        const ignoredContent = readFileSync(
+            resolve(outputPath + '-no-vars', 'ignored/ignored-test.md'),
+            'utf8',
+        );
+        expect(ignoredContent).toContain('{{rootVar}}'); // Should remain unresolved
+        expect(ignoredContent).toContain('{{ignoredVar}}'); // Should remain unresolved
+
+        const dataContent = readFileSync(
+            resolve(outputPath + '-no-vars', 'data/data-test.md'),
+            'utf8',
+        );
+        expect(dataContent).toContain('{{rootVar}}'); // Should remain unresolved
+        expect(dataContent).toContain('{{dataVar}}'); // Should remain unresolved
+    });
+});

package/tests/fixtures/cli.ts

@@ -0,0 +1,103 @@
+import runner from './runner';
+import {cleanupDirectory} from './file';
+
+export interface BuildRunArgs {
+    md2md?: boolean;
+    md2html?: boolean;
+    args?: string;
+    env?: Record<string, string>;
+}
+
+export interface TranslateRunArgs {
+    subcommand: 'extract' | 'compose';
+    source: string;
+    target: string;
+    additionalArgs?: string;
+}
+
+class Build {
+    run(input: string, output: string, args: string[], env?: Record<string, string>) {
+        return runner.runYfmDocs(
+            ['--input', input, '--output', output, '--quiet', '--allowHtml', ...args],
+            env,
+        );
+    }
+}
+
+class Extract {
+    run(input: string, output: string, args: string[], env?: Record<string, string>) {
+        return runner.runYfmDocs(
+            ['translate', 'extract', '--input', input, '--output', output, '--quiet', ...args],
+            env,
+        );
+    }
+}
+
+export class CliTestAdapter {
+    readonly runner = runner;
+
+    readonly build = new Build();
+
+    readonly extract = new Extract();
+
+    async testBuildPass(
+        inputPath: string,
+        outputPath: string,
+        {md2md = true, md2html = true, args = '', env}: BuildRunArgs = {},
+    ): Promise<void> {
+        await cleanupDirectory(outputPath);
+        await cleanupDirectory(`${outputPath}-md`);
+        await cleanupDirectory(`${outputPath}-html`);
+
+        const baseArgs = args.split(' ').filter(Boolean);
+
+        const tasks = [];
+
+        if (md2md && md2html) {
+            tasks.push(() => this.build.run(inputPath, outputPath, [...baseArgs, '-f', 'md'], env));
+            tasks.push(() =>
+                this.build.run(inputPath, `${outputPath}-html`, [...baseArgs, '-f', 'html'], env),
+            );
+        } else if (md2md) {
+            tasks.push(() => this.build.run(inputPath, outputPath, [...baseArgs, '-f', 'md'], env));
+        } else {
+            tasks.push(() =>
+                this.build.run(inputPath, outputPath, [...baseArgs, '-f', 'html'], env),
+            );
+        }
+
+        for (const task of tasks) {
+            const report = await task();
+            if (report.code > 0) {
+                throw report;
+            }
+        }
+    }
+
+    async testTranslatePass(
+        inputPath: string,
+        outputPath: string,
+        {subcommand, source, target, additionalArgs = ''}: TranslateRunArgs,
+    ): Promise<void> {
+        await cleanupDirectory(outputPath);
+
+        const baseArgs = [
+            'translate',
+            subcommand,
+            '--quiet',
+            '--input',
+            inputPath,
+            '--output',
+            outputPath,
+            '--source',
+            source,
+            '--target',
+            target,
+            ...additionalArgs.split(' ').filter(Boolean),
+        ];
+
+        await runner.runYfmDocs(baseArgs);
+    }
+}
+
+export const TestAdapter = new CliTestAdapter();

package/tests/fixtures/file.ts

@@ -0,0 +1,148 @@
+import type {BuildRunArgs} from './cli';
+
+import {readFileSync} from 'node:fs';
+import {rm} from 'node:fs/promises';
+import {join, resolve} from 'node:path';
+import {glob} from 'glob';
+import {expect, test} from 'vitest';
+
+import {TestAdapter} from './cli';
+import {bundleless, hashless, platformless} from './test';
+
+const SYSTEM_DIRS = ['_bundle/', '_search/'];
+
+// CLI-emitted build artifacts that aren't part of user content. Build-stats
+// and build-content default to on for md2md, so every md2md fixture would
+// otherwise need to list these in its snapshot.
+const SYSTEM_ARTIFACTS = [
+    'yfm-build-manifest.json',
+    'yfm-build-stats.json',
+    'yfm-build-content.json',
+];
+
+export function getFileContent(filePath: string) {
+    return platformless(bundleless(readFileSync(filePath, 'utf8')));
+}
+
+const uselessFile = (file: string, dirs: string[]) => !dirs.some((part) => file.includes(part));
+
+export function stripSystemLinks(content: string) {
+    const dirPattern = SYSTEM_DIRS.map((d) => d.replace('/', '\\/')).join('|');
+
+    content = content.replace(
+        new RegExp(`<script[^>]+src="(?:${dirPattern})[^"]*"[^>]*></script>`, 'g'),
+        '',
+    );
+
+    content = content.replace(
+        new RegExp(`<link[^>]+href="(?:${dirPattern})[^"]*"[^>]*\\/?>`, 'g'),
+        '',
+    );
+
+    content = content.replace(
+        new RegExp(
+            `<meta http-equiv="last-modified" content="\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z">`,
+            'g',
+        ),
+        '<meta http-equiv="last-modified" content="2025-10-15T00:00:00.000Z">',
+    );
+
+    content = content.replace(
+        new RegExp(
+            `<meta property="article:modified_time" content="\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z">`,
+            'g',
+        ),
+        '<meta property="article:modified_time" content="2025-10-15T00:00:00.000Z">',
+    );
+
+    content = content.replace(
+        new RegExp(`"updatedAt":"\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z"`, 'g'),
+        '"updatedAt":"2025-10-15T00:00:00.000Z"',
+    );
+
+    content = content.replace(/^[ \t]*\r?\n/gm, '');
+
+    return content;
+}
+
+export async function compareDirectories(
+    outputPath: string,
+    ignoreFileContent = false,
+    checkBundle = false,
+    ignoreFileList = false,
+) {
+    const filesFromOutput = (
+        await glob(`**/*`, {
+            cwd: outputPath,
+            dot: true,
+            follow: true,
+            nodir: true,
+            posix: true,
+        })
+    ).sort();
+
+    let filesForSnapshot;
+
+    if (checkBundle) {
+        filesForSnapshot = filesFromOutput;
+    } else {
+        filesForSnapshot = filesFromOutput.filter((file) =>
+            uselessFile(file, [...SYSTEM_DIRS, ...SYSTEM_ARTIFACTS]),
+        );
+    }
+
+    // Here we sort the order of the included files after all processing
+    // This is necessary for better test stability
+    // We do not care in what order these files were received and processed
+    // We sort only the final list and put it in the snapshot.
+    // `bundleless` strips dynamic (numeric-id) client chunks → drop the now-empty
+    // entries so they don't appear in the file list snapshot.
+    filesForSnapshot = filesForSnapshot.map(bundleless).map(hashless).filter(Boolean).sort();
+
+    if (!ignoreFileList) {
+        expect(JSON.stringify(filesForSnapshot, null, 2)).toMatchSnapshot('filelist');
+    }
+
+    if (!ignoreFileContent) {
+        filesFromOutput
+            .filter((file) => uselessFile(file, ['_assets/', ...SYSTEM_DIRS, ...SYSTEM_ARTIFACTS]))
+            .forEach((filePath) => {
+                let content = getFileContent(resolve(outputPath, filePath));
+
+                if (!checkBundle && filePath.endsWith('.html')) {
+                    content = stripSystemLinks(content);
+                }
+
+                expect(content).toMatchSnapshot();
+            });
+    }
+}
+
+type TestPaths = {
+    inputPath: string;
+    outputPath: string;
+};
+
+export function getTestPaths(testRootPath: string): TestPaths {
+    return {
+        inputPath: resolve(__dirname, '../', join(testRootPath, 'input')),
+        outputPath: resolve(__dirname, '../', join(testRootPath, 'output')),
+    };
+}
+
+export function cleanupDirectory(path: string) {
+    return rm(path, {recursive: true, force: true});
+}
+
+export function generateMapTestTemplate(
+    testTitle: string,
+    testRootPath: string,
+    options: BuildRunArgs = {},
+) {
+    test(testTitle, async () => {
+        const {inputPath, outputPath} = getTestPaths(testRootPath);
+
+        await TestAdapter.testBuildPass(inputPath, outputPath, options);
+        await compareDirectories(outputPath);
+    });
+}

package/tests/fixtures/globals.d.ts

@@ -0,0 +1,4 @@
+declare module '@diplodoc/cli/manifest' {
+    const manifest: Record<string, Record<string, string[]>>;
+    export = manifest;
+}

package/tests/fixtures/index.ts

@@ -0,0 +1,4 @@
+export * from './cli';
+export * from './file';
+export * from './test';
+export * from './runner';

package/tests/fixtures/runner.ts

@@ -0,0 +1,49 @@
+import {resolve} from 'node:path';
+import {execa} from 'execa';
+import strip from 'strip-ansi';
+
+export type Report = {
+    code: number;
+    warns: string[];
+    errors: string[];
+};
+
+const bin = process.env.DIPLODOC_BINARY_PATH || resolve(__dirname, '../../build/index.js');
+
+export class Runner {
+    async runYfmDocs(argv: string[], env?: Record<string, string>) {
+        const {stderr, exitCode} = await execa(bin, argv, {
+            all: true,
+            reject: false,
+            env: {...process.env, ...env},
+        });
+        const report = {
+            code: exitCode || 0,
+            warns: fillLog(/^WARN/, stderr),
+            errors: fillLog(/^ERR/, stderr),
+        };
+
+        const restLog = fillLog(/^(?!INFO|WARN|ERR)/, stderr);
+        if (restLog.length) {
+            for (const line of restLog) {
+                // eslint-disable-next-line no-console
+                console.log(line);
+            }
+        } else if (report.code > 0) {
+            // eslint-disable-next-line no-console
+            console.error(stderr);
+        }
+
+        return report;
+    }
+}
+
+function fillLog(filter: RegExp, source: string) {
+    return source
+        .split('\n')
+        .map((line) => strip(line).trim())
+        .filter(Boolean)
+        .filter((line) => line.match(filter));
+}
+
+export default new Runner();

package/tests/fixtures/test.ts

@@ -0,0 +1,210 @@
+import assets from '@diplodoc/cli/manifest';
+
+export function platformless(text: string): string {
+    let index = 1;
+
+    return (
+        hashless(text)
+            .replace(/\r\n/g, '\n')
+            // Fix for XML equiv-text attributes in Windows - handle various patterns
+            .replace(/equiv-text="[\r\n]+
"/g, 'equiv-text="
"')
+            .replace(/equiv-text="[\r\n]+
"/g, 'equiv-text="
"')
+            // Also normalize any other attributes that might have line ending issues
+            .replace(/(ctype|id)="[\r\n]+(.*?)"/g, '$1="$2"')
+            .replace(/\w{8}-\w{4}-\w{4}-\w{4}-\w{12}/g, 'UUID')
+            .replace(
+                /(content"?[:=]{1}[" ]{1}Diplodoc.*? )v\d+\.\d+\.\d+(?:-[\w-]+)?/g,
+                `$1vDIPLODOC-VERSION`,
+            )
+            .replace(
+                /(aria-controls=\\":term_element\\" tabindex=\\"\d\\" id=\\")[a-zA-Z0-9]{1,10}/g,
+                `$1vTERM-ID`,
+            )
+            .replace(/(\\(?![/"'])){1,2}/g, '/')
+            .replace(
+                /id=\\"inline-code-id-[a-zA-Z0-9]{8}\\"/g,
+                () => `id="inline-code-id-${index++}"`,
+            )
+    );
+}
+
+export function hashless(text: string): string {
+    return text
+        .replace(/-[a-z0-9]{12,16}\./g, '-hash.')
+        .replace(/(rnd|svg)-[a-z0-9]{3,8}__/g, 'rnd-hash__')
+        .replace(/(\/|\\)[a-z0-9]{12,16}-(index|registry|resources)\./g, '/hash-$2.');
+}
+
+/**
+ * Replaces hashed bundle filenames from the client manifest with stable labels
+ * and sorts bundle references to normalize platform-dependent ordering.
+ *
+ * Examples: "app-3ff8bc0b40bc2914.js" → "app-js",
+ *           "vendor-00121562c7b7d3b5.rtl.css" → "vendor-rtl-css",
+ *           "976-40cbc1d2518eb8ea.js" → "chunk-js" (numeric webpack chunk ID).
+ */
+// Matches a dynamic client chunk reference: a numeric (webpack/rspack id) base
+// with a content hash, e.g. `_bundle/572-d105b8fc819aff93.rtl.css`,
+// `_bundle/189-ab12cd34ef56.js`.
+const DYNAMIC_CHUNK = String.raw`_bundle\/\d+-[a-f0-9]{12,16}(?:\.[a-z0-9]+)*\.[a-z0-9]+`;
+
+/**
+ * Removes dynamic (numeric-id) client chunks from both the file list and any
+ * references inside content.
+ *
+ * These chunks are an internal detail of the client bundler: their count,
+ * extensions and even existence change between `@diplodoc/client` releases
+ * (e.g. 5.7.11 → 5.7.13 added `572-*.css` / `572-*.rtl.css`). Asserting them
+ * makes snapshots depend on the exact client version, so a floating
+ * `npm install` (Arcadia) diverges from a locked `npm ci` (GitHub). Stripping
+ * them keeps snapshots stable across client patch releases while still
+ * asserting the named bundles (app/vendor/search/extensions).
+ */
+function stripDynamicChunks(text: string): string {
+    // Fast path. Besides being cheaper, this guard is essential: `bundleless` is
+    // also applied to binary asset content (fonts, images), and the punctuation
+    // cleanup below would otherwise corrupt random `,,`/`[,`/`,]` byte sequences.
+    // Binary content never contains a literal `_bundle/<id>-<hash>` reference.
+    if (!new RegExp(DYNAMIC_CHUNK).test(text)) {
+        return text;
+    }
+
+    // <script ... src="_bundle/572-hash.js"></script>
+    text = text.replace(
+        new RegExp(`<script\\b[^>]*?${DYNAMIC_CHUNK}[^>]*?>\\s*<\\/script>`, 'g'),
+        '',
+    );
+    // <link ... href="_bundle/572-hash.css" ...>
+    text = text.replace(new RegExp(`<link\\b[^>]*?${DYNAMIC_CHUNK}[^>]*?\\/?>`, 'g'), '');
+    // JSON/array string element: "_bundle/572-hash.css" (optionally escaped as \"...\").
+    text = text.replace(new RegExp(`\\\\?"${DYNAMIC_CHUNK}\\\\?",?`, 'g'), '');
+    // Any remaining bare reference (e.g. a file-list entry that is exactly the chunk).
+    text = text.replace(new RegExp(DYNAMIC_CHUNK, 'g'), '');
+    // Tidy up array punctuation left behind by removed elements.
+    return text
+        .replace(/\[\s*,/g, '[')
+        .replace(/,\s*\]/g, ']')
+        .replace(/,\s*,/g, ',');
+}
+
+export function bundleless(text: string): string {
+    // On Windows the CLI may emit `_bundle\file` or JSON-escaped `_bundle\\/file`.
+    // Collapse any mix of backslashes and forward slashes after `_bundle` into `/`.
+    text = text.replace(/_bundle[/\\]+/g, '_bundle/');
+
+    // Drop nondeterministic dynamic chunks before mapping named bundles.
+    text = stripDynamicChunks(text);
+
+    for (const entry of Object.values(assets)) {
+        for (const files of Object.values(entry)) {
+            for (const filename of files) {
+                const match = filename.match(
+                    /^([a-z0-9]+)-[a-f0-9]{12,16}((?:\.[a-z]+)*)\.([a-z]+)$/,
+                );
+                if (!match) continue;
+
+                const [, rawBase, suffixes, ext] = match;
+                // Numeric (dynamic) chunks are handled by stripDynamicChunks above.
+                if (/^\d+$/.test(rawBase)) continue;
+
+                const suffixPart = suffixes.replace(/\./g, '-').slice(1); // ".rtl" → "rtl"
+                const label = suffixPart ? `${rawBase}-${suffixPart}-${ext}` : `${rawBase}-${ext}`;
+                const escapedSuffixes = suffixes.replace(/\./g, '\\.');
+                const pattern = new RegExp(
+                    `${rawBase}-[a-f0-9]{12,16}${escapedSuffixes}\\.${ext}`,
+                    'g',
+                );
+                text = text.replace(pattern, label);
+            }
+        }
+    }
+
+    return sortBundleTokens(text);
+}
+
+/**
+ * Sorts contiguous runs of `_bundle/` references so snapshots stay stable
+ * regardless of manifest ordering or platform.
+ *
+ * Pass 1 (line-level): sorts groups of consecutive lines containing `_bundle/`
+ * — handles HTML `<link>` / `<script>` tags on separate lines.
+ *
+ * Pass 2 (inline): sorts groups of `_bundle/` tokens on the same line separated
+ * only by punctuation — handles JSON arrays like `"cssLink":["_bundle/b","_bundle/a"]`.
+ */
+function sortBundleTokens(text: string): string {
+    const bundleRe = /_bundle\/[a-z0-9][-a-z0-9]*/;
+
+    // --- Pass 1: line-level sort ---
+    const lines = text.split('\n');
+    let i = 0;
+    while (i < lines.length) {
+        if (!bundleRe.test(lines[i])) {
+            i++;
+            continue;
+        }
+        const start = i;
+        while (i < lines.length && bundleRe.test(lines[i])) {
+            i++;
+        }
+        if (i - start < 2) continue;
+
+        const slice = lines.slice(start, i);
+        const sorted = [...slice].sort((a, b) => {
+            const ka = a.match(bundleRe)?.[0] ?? '';
+            const kb = b.match(bundleRe)?.[0] ?? '';
+            if (ka < kb) {
+                return -1;
+            }
+            if (ka > kb) {
+                return 1;
+            }
+            return 0;
+        });
+        for (let j = 0; j < sorted.length; j++) {
+            lines[start + j] = sorted[j];
+        }
+    }
+    text = lines.join('\n');
+
+    // --- Pass 2: inline sort (JSON arrays, etc.) ---
+    const tokenRe = /_bundle\/[a-z0-9][-a-z0-9]*/g;
+    const hits: {start: number; end: number; value: string}[] = [];
+    let m;
+    while ((m = tokenRe.exec(text)) !== null) {
+        hits.push({start: m.index, end: m.index + m[0].length, value: m[0]});
+    }
+    if (hits.length < 2) return text;
+
+    // Gap between two tokens is "glue" when it contains no alphanumeric chars
+    // (ignoring `_bundle` substrings that may appear in the gap).
+    const isGlue = (gap: string) => !/[a-zA-Z0-9]/.test(gap.replace(/_bundle/g, ''));
+
+    // Group consecutive same-line tokens into runs.
+    const runs: number[][] = [[0]];
+    for (let idx = 1; idx < hits.length; idx++) {
+        const gap = text.slice(hits[idx - 1].end, hits[idx].start);
+        if (!gap.includes('\n') && isGlue(gap)) {
+            runs[runs.length - 1].push(idx);
+        } else {
+            runs.push([idx]);
+        }
+    }
+
+    // Sort each run with 2+ tokens, rewriting from the end to preserve offsets.
+    for (let r = runs.length - 1; r >= 0; r--) {
+        const run = runs[r];
+        if (run.length < 2) continue;
+
+        const values = run.map((idx) => hits[idx].value);
+        const sorted = [...values].sort();
+        if (values.every((v, idx) => v === sorted[idx])) continue;
+
+        for (let k = run.length - 1; k >= 0; k--) {
+            const {start: s, end: e} = hits[run[k]];
+            text = text.slice(0, s) + sorted[k] + text.slice(e);
+        }
+    }
+
+    return text;
+}