@diplodoc/cli 5.46.1 → 5.47.0

package/tests/e2e/crawler-manifest.spec.ts

@@ -0,0 +1,129 @@
+import {describe, expect, test} from 'vitest';
+import {join} from 'node:path';
+import {access, readFile} from 'node:fs/promises';
+
+import {TestAdapter, getTestPaths} from '../fixtures';
+
+describe('Crawler manifest', () => {
+    test('generates crawler-manifest.json', async () => {
+        const {inputPath, outputPath} = getTestPaths('mocks/crawler-manifest/with-links');
+
+        await TestAdapter.testBuildPass(inputPath, outputPath, {
+            md2md: true,
+            md2html: false,
+            args: '--crawler-manifest',
+        });
+
+        const manifestContent = await readFile(join(outputPath, 'crawler-manifest.json'), 'utf-8');
+
+        expect(JSON.parse(manifestContent)).toMatchSnapshot();
+    });
+
+    test('does not generate manifest when --crawler-manifest flag is absent', async () => {
+        const {inputPath, outputPath} = getTestPaths('mocks/crawler-manifest/with-links');
+
+        await TestAdapter.testBuildPass(inputPath, outputPath, {
+            md2md: true,
+            md2html: false,
+        });
+
+        await expect(access(join(outputPath, 'crawler-manifest.json'))).rejects.toThrow();
+    });
+
+    test('does not generate manifest when there are no external links', async () => {
+        const {inputPath, outputPath} = getTestPaths('mocks/crawler-manifest/no-links');
+
+        await TestAdapter.testBuildPass(inputPath, outputPath, {
+            md2md: true,
+            md2html: false,
+            args: '--crawler-manifest',
+        });
+
+        await expect(access(join(outputPath, 'crawler-manifest.json'))).rejects.toThrow();
+    });
+
+    test('reads crawlerManifest setting from .yfm config file', async () => {
+        const {inputPath, outputPath} = getTestPaths('mocks/crawler-manifest/config');
+
+        await TestAdapter.testBuildPass(inputPath, outputPath, {
+            md2md: true,
+            md2html: false,
+        });
+
+        const manifestContent = await readFile(join(outputPath, 'crawler-manifest.json'), 'utf-8');
+        const manifest = JSON.parse(manifestContent);
+
+        expect(manifest.links['index.md']).toContain('https://config.example.com');
+    });
+
+    test('excludes urls by exact match and regexp from docs-viewer.crawler.exclude', async () => {
+        const {inputPath, outputPath} = getTestPaths('mocks/crawler-manifest/exclude');
+
+        await TestAdapter.testBuildPass(inputPath, outputPath, {
+            md2md: true,
+            md2html: false,
+        });
+
+        const manifestContent = await readFile(join(outputPath, 'crawler-manifest.json'), 'utf-8');
+        const manifest = JSON.parse(manifestContent);
+
+        expect(manifest.links['index.md']).toContain('https://kept.example.com');
+        expect(manifest.links['index.md']).not.toContain('https://excluded-exact.example.com');
+        expect(manifest.links['index.md']).not.toContain(
+            'https://excluded-regexp.example.com/some/path',
+        );
+    });
+
+    test('includes notifications from root crawler config with defaults applied', async () => {
+        const {inputPath, outputPath} = getTestPaths('mocks/crawler-manifest/notifications-root');
+
+        await TestAdapter.testBuildPass(inputPath, outputPath, {
+            md2md: true,
+            md2html: false,
+        });
+
+        const manifestContent = await readFile(join(outputPath, 'crawler-manifest.json'), 'utf-8');
+        const manifest = JSON.parse(manifestContent);
+
+        expect(manifest.notifications).toEqual({
+            interval: 'daily',
+            emailReceivers: ['user1', 'user2'],
+            messengerReceivers: ['user1', 'user2'],
+        });
+    });
+
+    test('includes notifications from docs-viewer.crawler config with default interval', async () => {
+        const {inputPath, outputPath} = getTestPaths(
+            'mocks/crawler-manifest/notifications-docs-viewer',
+        );
+
+        await TestAdapter.testBuildPass(inputPath, outputPath, {
+            md2md: true,
+            md2html: false,
+        });
+
+        const manifestContent = await readFile(join(outputPath, 'crawler-manifest.json'), 'utf-8');
+        const manifest = JSON.parse(manifestContent);
+
+        expect(manifest.notifications).toEqual({
+            interval: 'weekly',
+            emailReceivers: ['user3'],
+        });
+    });
+
+    test('omits notifications from manifest when receivers are not configured', async () => {
+        const {inputPath, outputPath} = getTestPaths(
+            'mocks/crawler-manifest/notifications-no-receivers',
+        );
+
+        await TestAdapter.testBuildPass(inputPath, outputPath, {
+            md2md: true,
+            md2html: false,
+        });
+
+        const manifestContent = await readFile(join(outputPath, 'crawler-manifest.json'), 'utf-8');
+        const manifest = JSON.parse(manifestContent);
+
+        expect(manifest.notifications).toBeUndefined();
+    });
+});

package/tests/e2e/disable-csp.spec.ts

@@ -0,0 +1,55 @@
+import {readFileSync, readdirSync} from 'node:fs';
+import {join, sep} from 'node:path';
+import {describe, expect, test} from 'vitest';
+
+import {TestAdapter, getTestPaths} from '../fixtures';
+
+function findHtmlFiles(dir: string): string[] {
+    const results: string[] = [];
+
+    try {
+        for (const entry of readdirSync(dir, {withFileTypes: true})) {
+            const full = join(dir, entry.name);
+
+            if (entry.isDirectory()) {
+                results.push(...findHtmlFiles(full));
+            } else if (entry.name.endsWith('.html')) {
+                results.push(full);
+            }
+        }
+    } catch {
+        // ignore
+    }
+
+    return results;
+}
+
+describe('disableCsp', () => {
+    test('should not inject CSP meta tag when disableCsp is true with neuroExpert enabled', async () => {
+        const {inputPath, outputPath} = getTestPaths('mocks/disable-csp');
+
+        await TestAdapter.testBuildPass(inputPath, outputPath, {
+            md2md: false,
+            md2html: true,
+            args: '-j2',
+        });
+
+        const htmlFiles = findHtmlFiles(outputPath);
+        expect(htmlFiles.length).toBeGreaterThan(0);
+
+        // No HTML page should contain CSP meta tag
+        for (const htmlFile of htmlFiles) {
+            const html = readFileSync(htmlFile, 'utf8');
+            expect(html).not.toContain('Content-Security-Policy');
+        }
+
+        // Content pages (under en/) should still have the neuroExpert widget script
+        const contentPages = htmlFiles.filter((f) => f.includes(`${sep}en${sep}`));
+        expect(contentPages.length).toBeGreaterThan(0);
+
+        for (const htmlFile of contentPages) {
+            const html = readFileSync(htmlFile, 'utf8');
+            expect(html).toContain('neuroexpert-widget');
+        }
+    });
+});

package/tests/e2e/empty-presets.spec.ts

@@ -0,0 +1,32 @@
+import {describe, expect, test} from 'vitest';
+import {existsSync, readFileSync} from 'node:fs';
+import {resolve} from 'node:path';
+
+import {TestAdapter, getTestPaths} from '../fixtures';
+
+describe('Empty presets.yaml handling', () => {
+    test('should not create empty presets.yaml files in md output format when no variables are used', async () => {
+        const {inputPath, outputPath} = getTestPaths('mocks/empty-presets');
+
+        // Test with --output-format=md and disabled templating
+        await TestAdapter.testBuildPass(inputPath, outputPath, {
+            md2md: true,
+            args: '-f md --no-template',
+        });
+
+        // Check that presets.yaml file was NOT created in the output
+        const presetsPath = resolve(outputPath, 'presets.yaml');
+        expect(existsSync(presetsPath)).toBe(false);
+
+        // Check that subfolder presets.yaml file was NOT created in the output
+        const subfolderPresetsPath = resolve(outputPath, 'subfolder/presets.yaml');
+        expect(existsSync(subfolderPresetsPath)).toBe(false);
+
+        // Verify that the markdown files were still processed correctly
+        const indexContent = readFileSync(resolve(outputPath, 'index.md'), 'utf8');
+        expect(indexContent).toContain('Test Page');
+
+        const subpageContent = readFileSync(resolve(outputPath, 'subfolder/subpage.md'), 'utf8');
+        expect(subpageContent).toContain('Sub Page');
+    });
+});

package/tests/e2e/errors.spec.ts

@@ -0,0 +1,158 @@
+import type {Report} from '../fixtures/runner';
+
+import {describe, expect, it} from 'vitest';
+
+import {TestAdapter, getTestPaths} from '../fixtures';
+
+type TestResult = {
+    md: Report;
+    html: Report;
+};
+
+function test(path: string, expect: Function, additionalArgs: string[] = []) {
+    it(path, async () => {
+        const {inputPath, outputPath} = getTestPaths(path);
+
+        const md = await TestAdapter.build.run(inputPath, outputPath, [
+            '-j2',
+            '-f',
+            'md',
+            ...additionalArgs,
+        ]);
+        const html = await TestAdapter.build.run(inputPath, outputPath + '-html', [
+            '-j2',
+            '-f',
+            'html',
+            ...additionalArgs,
+        ]);
+        return expect({md, html});
+    });
+}
+
+describe('Errors', () => {
+    test('mocks/errors/unreachable-link', ({html}: TestResult) => {
+        expectErrors(html, [
+            'ERR index.md: 1: YFM003 / unreachable-link Link is unreachable [Context: "Unreachable link: "exists.html"; Reason: File is not declared in toc; Line: 1"]',
+            'ERR index.md: 2: YFM003 / unreachable-link Link is unreachable [Context: "Unreachable link: "missed.html"; Reason: File is not declared in toc; Line: 2"]',
+        ]);
+    });
+
+    test('mocks/errors/object-validation', ({html}: TestResult) => {
+        expectErrors(html, [
+            'ERR Invalid toc structure in toc.yaml -> toc.yaml at items[1].name: found [object Object] value',
+            'ERR Invalid toc structure in toc.yaml -> toc.yaml at items[2].href: found [object Object] value',
+            'ERR Invalid toc structure in toc.yaml -> toc.yaml at items[3].items[0].name: found [object Object] value',
+            'ERR Invalid toc structure in toc.yaml -> toc.yaml at items[4].title: found [object Object] value',
+            'ERR Invalid toc structure in toc.yaml -> toc.yaml at items[5].label: found [object Object] value',
+            'ERR Invalid toc structure in toc.yaml -> toc.yaml at items[6].navigation: found [object Object] value',
+        ]);
+    });
+
+    test(
+        'mocks/errors/invalid-toc-root-array',
+        ({md, html}: TestResult) => {
+            expectErrors(md, [
+                'ERR Invalid TOC format in ru/toc.yaml: root value must be an object, got array. Wrap items into an object with the items field.',
+            ]);
+            expectErrors(html, [
+                'ERR Invalid TOC format in ru/toc.yaml: root value must be an object, got array. Wrap items into an object with the items field.',
+            ]);
+        },
+        ['-j1'],
+    );
+
+    test('mocks/errors/invalid-toc-root-array', ({md, html}: TestResult) => {
+        expectErrors(md, [
+            'ERR Invalid TOC format in ru/toc.yaml: root value must be an object, got array. Wrap items into an object with the items field.',
+        ]);
+        expectErrors(html, [
+            'ERR Invalid TOC format in ru/toc.yaml: root value must be an object, got array. Wrap items into an object with the items field.',
+        ]);
+    });
+
+    test(
+        'mocks/errors/max-asset-size',
+        ({md, html}: TestResult) => {
+            expectErrors(md, [
+                'ERR YFM013 _images/large-image.png: YFM013 / File asset limit exceeded: 3057 (limit is 2048)',
+            ]);
+            expectErrors(html, [
+                'ERR YFM013 _images/large-image.png: YFM013 / File asset limit exceeded: 3057 (limit is 2048)',
+            ]);
+        },
+        ['--max-asset-size', '2K'],
+    );
+
+    test('mocks/errors/invalid-frontmatter', ({md, html}: TestResult) => {
+        expectErrors(md, [
+            'ERR index.md: 2: YFM017 / invalid front matter format [Reason: "duplicated mapping key"; Line: 2; Key: "title"]',
+        ]);
+        expectErrors(html, [
+            'ERR index.md: 2: YFM017 / invalid front matter format [Reason: "duplicated mapping key"; Line: 2; Key: "title"]',
+        ]);
+    });
+
+    it('translate extract with filtered links', async () => {
+        const {inputPath, outputPath} = getTestPaths('mocks/errors/extract-filtered-link');
+
+        const result = await TestAdapter.extract.run(inputPath, outputPath, [
+            '--source',
+            'ru-RU',
+            '--target',
+            'es-ES',
+            '--filter',
+        ]);
+
+        expect(result.code).toEqual(1);
+
+        expect(result.errors).toEqual([
+            "ERR File index.md contains link to filtered.md, which was filtered from toc.yaml or it's not been included initially",
+            "ERR File index.md contains link to filtered2.md, which was filtered from toc.yaml or it's not been included initially",
+            "ERR File index.md contains link to filtered2.md, which was filtered from toc.yaml or it's not been included initially",
+            "ERR File index.md contains link to filtered3.md, which was filtered from toc.yaml or it's not been included initially",
+        ]);
+    });
+});
+
+describe('Include chain errors', () => {
+    test('mocks/errors/unreachable-link-in-include', ({html}: TestResult) => {
+        expectErrors(html, [
+            'ERR index.md: 5: YFM003 / unreachable-link Link is unreachable [Context: "index.md:5 → _includes/chapter.md:1 ↛ _includes/nonexistent.html; Reason: File is not declared in toc"]',
+        ]);
+    });
+
+    test('mocks/errors/unreachable-link-in-nested-include', ({html}: TestResult) => {
+        expectErrors(html, [
+            'ERR index.md: 3: YFM003 / unreachable-link Link is unreachable [Context: "index.md:3 → _includes/chapter.md:3 → _includes/details.md:1 ↛ _includes/nonexistent.html; Reason: File is not declared in toc"]',
+        ]);
+    });
+
+    test('mocks/errors/valid-link-in-include', ({html}: TestResult) => {
+        const yfm003 = html.errors.filter((e: string) => e.includes('YFM003'));
+        expect(yfm003).toEqual([]);
+    });
+});
+
+describe('Warnings', () => {
+    test('mocks/warning/unreachable-autotitle', ({html}: TestResult) => {
+        expectWarnings(html, [
+            'WARN index.md: 1: YFM010 / unreachable-autotitle-anchor Auto title anchor is unreachable [Context: "Unreachable autotitle anchor: "link.html#unknown_yfm010"; Line: 1"]',
+        ]);
+    });
+});
+
+function expectErrors(report: Report, errors: string[]) {
+    expect(report.code).toEqual(1);
+
+    for (const error of errors) {
+        expect(report.errors).toContain(error);
+    }
+}
+
+function expectWarnings(report: Report, warnings: string[]) {
+    expect(report.warns.length).toEqual(warnings.length);
+
+    for (const warn of warnings) {
+        expect(report.warns).toContain(warn);
+    }
+}

package/tests/e2e/files.spec.ts

@@ -0,0 +1,21 @@
+import {describe, test} from 'vitest';
+
+import {TestAdapter, compareDirectories, getTestPaths} from '../fixtures';
+
+describe('Static files from _assets directory', () => {
+    test('Download link should be enabled', async () => {
+        const {inputPath, outputPath} = getTestPaths('mocks/files');
+
+        await TestAdapter.testBuildPass(inputPath, outputPath, {
+            md2md: true,
+            md2html: false,
+        });
+        await compareDirectories(outputPath);
+
+        await TestAdapter.testBuildPass(outputPath, outputPath + '-html', {
+            md2md: false,
+            md2html: true,
+        });
+        await compareDirectories(outputPath + '-html');
+    });
+});

package/tests/e2e/generate-map.spec.ts

@@ -0,0 +1,47 @@
+import {describe, expect, test} from 'vitest';
+import {join} from 'node:path';
+import {readFile} from 'node:fs/promises';
+
+import {TestAdapter, bundleless, getFileContent, getTestPaths} from '../fixtures';
+
+const generateMapTestTemplate = (
+    testTitle: string,
+    testRootPath: string,
+    md2md = true,
+    md2html = true,
+) => {
+    test(testTitle, async () => {
+        const {inputPath, outputPath} = getTestPaths(testRootPath);
+
+        await TestAdapter.testBuildPass(inputPath, outputPath, {
+            md2md,
+            md2html,
+            args: '--add-map-file --build-manifest',
+        });
+
+        const content = getFileContent(join(outputPath, 'files.json'));
+        const manifestContent = await readFile(
+            join(outputPath, 'yfm-build-manifest.json'),
+            'utf-8',
+        );
+
+        expect(bundleless(content)).toMatchSnapshot();
+        expect(JSON.parse(manifestContent)).toMatchSnapshot();
+    });
+};
+
+describe('Generate map for', () => {
+    generateMapTestTemplate(
+        'project with single language and toc include',
+        'mocks/generate-map/test1',
+    );
+
+    generateMapTestTemplate(
+        'project with single language and toc include - only md2html',
+        'mocks/generate-map/test1',
+    );
+
+    generateMapTestTemplate('project with multiple language', 'mocks/generate-map/test2');
+
+    generateMapTestTemplate('project with external links in toc', 'mocks/generate-map/test3');
+});

package/tests/e2e/include-toc.test.ts

@@ -0,0 +1,73 @@
+import {describe, test} from 'vitest';
+
+import {TestAdapter, compareDirectories, getTestPaths} from '../fixtures';
+
+describe('Include toc', () => {
+    test('Toc is included in link mode', async () => {
+        const {inputPath, outputPath} = getTestPaths('mocks/include-toc/test1');
+        await TestAdapter.testBuildPass(inputPath, outputPath);
+        await compareDirectories(outputPath);
+    });
+
+    test('Toc is included inline, not as a new section', async () => {
+        const {inputPath, outputPath} = getTestPaths('mocks/include-toc/test2');
+        await TestAdapter.testBuildPass(inputPath, outputPath);
+        await compareDirectories(outputPath);
+    });
+
+    test('Nested toc inclusions with mixed including modes', async () => {
+        const {inputPath, outputPath} = getTestPaths('mocks/include-toc/test3');
+        await TestAdapter.testBuildPass(inputPath, outputPath);
+        await compareDirectories(outputPath);
+    });
+
+    test('Nested toc inclusions with mixed including modes 2', async () => {
+        const {inputPath, outputPath} = getTestPaths('mocks/include-toc/test5');
+        await TestAdapter.testBuildPass(inputPath, outputPath);
+        await compareDirectories(outputPath);
+    });
+
+    test('Toc with expressions', async () => {
+        const {inputPath, outputPath} = getTestPaths('mocks/include-toc/test4');
+        const vars = {
+            type: 'a',
+            a: 'A',
+            b: 'B',
+        };
+
+        await TestAdapter.testBuildPass(inputPath, outputPath, {
+            args: `--vars=${JSON.stringify(vars)}`,
+        });
+        await compareDirectories(outputPath);
+    });
+
+    test('Toc with generic includer', async () => {
+        const {inputPath, outputPath} = getTestPaths('mocks/include-toc/test6');
+        await TestAdapter.testBuildPass(inputPath, outputPath);
+        await compareDirectories(outputPath);
+    });
+
+    test('Toc root merge on non root dir', async () => {
+        const {inputPath, outputPath} = getTestPaths('mocks/include-toc/test7');
+        await TestAdapter.testBuildPass(inputPath, outputPath);
+        await compareDirectories(outputPath);
+    });
+
+    test('Toc with generic includer and linkIndex option', async () => {
+        const {inputPath, outputPath} = getTestPaths('mocks/include-toc/test8');
+        await TestAdapter.testBuildPass(inputPath, outputPath);
+        await compareDirectories(outputPath);
+    });
+
+    test('Toc with generic includer keeps index.md as child item by default', async () => {
+        const {inputPath, outputPath} = getTestPaths('mocks/include-toc/test9');
+        await TestAdapter.testBuildPass(inputPath, outputPath);
+        await compareDirectories(outputPath);
+    });
+
+    test('Toc with generic includer linkIndexAutotitle uses index.md heading for directory', async () => {
+        const {inputPath, outputPath} = getTestPaths('mocks/include-toc/test10');
+        await TestAdapter.testBuildPass(inputPath, outputPath);
+        await compareDirectories(outputPath);
+    });
+});

package/tests/e2e/include-with-meta.test.ts

@@ -0,0 +1,20 @@
+import {describe, test} from 'vitest';
+
+import {TestAdapter, compareDirectories, getTestPaths} from '../fixtures';
+
+describe('Include with Meta', () => {
+    test('Build with PAGE_PROCESS_CONCURRENCY=1 should preserve meta information in includes', async () => {
+        const {inputPath, outputPath} = getTestPaths('mocks/include-with-meta');
+
+        await TestAdapter.testBuildPass(inputPath, outputPath, {
+            md2md: true,
+            md2html: false,
+            args: '-j 2',
+            env: {
+                PAGE_PROCESS_CONCURRENCY: '1',
+            },
+        });
+
+        await compareDirectories(outputPath);
+    });
+});

package/tests/e2e/includes-conditions.test.ts

@@ -0,0 +1,23 @@
+import {describe, test} from 'vitest';
+
+import {TestAdapter, compareDirectories, getTestPaths} from '../fixtures';
+
+describe('Includes with conditions', () => {
+    test('Consecutive includes with false condition in the middle', async () => {
+        const {inputPath, outputPath} = getTestPaths('mocks/includes-conditions');
+
+        // Test md2md transformation
+        await TestAdapter.testBuildPass(inputPath, outputPath, {
+            md2md: true,
+            md2html: false,
+        });
+        await compareDirectories(outputPath);
+
+        // Test md2html transformation
+        await TestAdapter.testBuildPass(outputPath, outputPath + '-html', {
+            md2md: false,
+            md2html: true,
+        });
+        await compareDirectories(outputPath + '-html');
+    });
+});

package/tests/e2e/includes.test.ts

@@ -0,0 +1,52 @@
+import {describe, expect, test} from 'vitest';
+
+import {TestAdapter, compareDirectories, getTestPaths} from '../fixtures';
+
+describe('Includes', () => {
+    test('Various include scenarios', async () => {
+        const {inputPath, outputPath} = getTestPaths('mocks/includes');
+
+        // Test md2md transformation
+        await TestAdapter.testBuildPass(inputPath, outputPath, {
+            md2md: true,
+            md2html: false,
+        });
+        await compareDirectories(outputPath);
+
+        // Test md2html transformation
+        await TestAdapter.testBuildPass(outputPath, outputPath + '-html', {
+            md2md: false,
+            md2html: true,
+        });
+        await compareDirectories(outputPath + '-html');
+    });
+
+    // TODO: This test was disabled because missing include files no longer cause
+    // a build failure in either md2md or md2html mode. The include is simply skipped.
+    // Re-enable when the expected error behavior is clarified.
+    test.todo('Include with missing file should fail');
+
+    test('Check filename and line in logs for skipped include', async () => {
+        const {inputPath, outputPath} = getTestPaths('mocks/include-skip/test1');
+
+        const mdReport = await TestAdapter.build.run(inputPath, outputPath, ['-f', 'html']);
+        expect(mdReport.code).toBeGreaterThan(0);
+        const mdLogs = mdReport.errors.join('\n');
+
+        expect(mdLogs).toContain(
+            'ERR Include skipped in (index.md:3). Include source for includes/missing.md not found',
+        );
+    });
+
+    test('Check filename and line in logs for skipped nested include', async () => {
+        const {inputPath, outputPath} = getTestPaths('mocks/include-skip/test2');
+
+        const mdReport = await TestAdapter.build.run(inputPath, outputPath, ['-f', 'html']);
+        expect(mdReport.code).toBeGreaterThan(0);
+        const mdLogs = mdReport.errors.join('\n');
+
+        expect(mdLogs).toContain(
+            'ERR Include skipped in (includes/valid.md:3). Include source for includes/missing.md not found',
+        );
+    });
+});