mirror of
https://github.com/videojs/video.js.git
synced 2026-11-20 06:29:27 +01:00
461 lines
17 KiB
TypeScript
461 lines
17 KiB
TypeScript
import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
|
|
import { tmpdir } from 'node:os';
|
|
import { join } from 'node:path';
|
|
|
|
import { afterEach, describe, expect, it } from 'vite-plus/test';
|
|
|
|
import {
|
|
getInstallationRoutePath,
|
|
INSTALLATION_ROUTES,
|
|
INSTALLATION_ROUTE_SEGMENTS,
|
|
} from '../../src/utils/installation/routes.ts';
|
|
import {
|
|
type PackageDocsTarget,
|
|
packageDocumentation,
|
|
rewriteIndexHeader,
|
|
rewriteLinks,
|
|
stripFooter,
|
|
synthesizeReadme,
|
|
} from '../copy-package-docs.ts';
|
|
|
|
const temporaryDirectories: string[] = [];
|
|
|
|
function createFixture() {
|
|
const root = mkdtempSync(join(tmpdir(), 'package-docs-'));
|
|
|
|
temporaryDirectories.push(root);
|
|
return {
|
|
root,
|
|
siteDist: join(root, 'site-dist'),
|
|
packagesDirectory: join(root, 'packages'),
|
|
};
|
|
}
|
|
|
|
function writeDoc(siteDist: string, framework: PackageDocsTarget, relativePath: string, content: string): void {
|
|
const path = join(siteDist, 'docs', 'framework', framework, relativePath);
|
|
|
|
mkdirSync(join(path, '..'), { recursive: true });
|
|
writeFileSync(path, content);
|
|
}
|
|
|
|
function writeInstallationDocs(siteDist: string, framework: PackageDocsTarget): number {
|
|
const routes = INSTALLATION_ROUTE_SEGMENTS.filter((route) =>
|
|
INSTALLATION_ROUTES[route].frameworks.some((candidate) => candidate === framework)
|
|
);
|
|
|
|
for (const route of routes) {
|
|
const path = join(siteDist, `${getInstallationRoutePath(route).slice(1)}.md`);
|
|
|
|
mkdirSync(join(path, '..'), { recursive: true });
|
|
writeFileSync(
|
|
path,
|
|
`# ${route} installation\n\n<!-- installation-plan:start -->\n\nDefault steps.\n\n<!-- installation-plan:end -->`
|
|
);
|
|
}
|
|
|
|
return routes.length;
|
|
}
|
|
|
|
afterEach(() => {
|
|
for (const directory of temporaryDirectories.splice(0)) rmSync(directory, { recursive: true, force: true });
|
|
});
|
|
|
|
describe('stripFooter', () => {
|
|
it('removes an index-style breadcrumb footer (no framework line)', () => {
|
|
const input = ['# Index', '- entry', '', '---', '', 'All documentation: https://videojs.org/llms.txt', ''].join(
|
|
'\n'
|
|
);
|
|
|
|
expect(stripFooter(input)).toBe(['# Index', '- entry'].join('\n'));
|
|
});
|
|
|
|
it('removes every framework line from a multi-framework page footer', () => {
|
|
const input = [
|
|
'# Shadcn Installation Guide',
|
|
'',
|
|
'Body content.',
|
|
'',
|
|
'---',
|
|
'',
|
|
'React documentation: https://videojs.org/docs/framework/react/llms.txt',
|
|
'HTML documentation: https://videojs.org/docs/framework/html/llms.txt',
|
|
'All documentation: https://videojs.org/llms.txt',
|
|
'',
|
|
].join('\n');
|
|
|
|
expect(stripFooter(input)).toBe(['# Shadcn Installation Guide', '', 'Body content.'].join('\n'));
|
|
});
|
|
|
|
it('leaves content without a footer unchanged', () => {
|
|
const input = '# Heading\n\nBody.';
|
|
|
|
expect(stripFooter(input)).toBe(input);
|
|
});
|
|
});
|
|
|
|
describe('rewriteLinks', () => {
|
|
it('rewrites an absolute same-framework .md link to a relative path', () => {
|
|
const input = '- [Installation](https://videojs.org/docs/framework/react/guides/installation.md): desc';
|
|
|
|
expect(rewriteLinks(input, 'llms', 'react')).toBe('- [Installation](./guides/installation.md): desc');
|
|
});
|
|
|
|
it('rewrites canonical installation links to their bundled guide paths', () => {
|
|
const input = [
|
|
'[Packaged](https://videojs.org/docs/guides/installation/react.md)',
|
|
'[Shadcn](/docs/guides/installation/shadcn)',
|
|
].join('\n');
|
|
|
|
expect(rewriteLinks(input, 'llms', 'react')).toBe(
|
|
['[Packaged](./guides/installation.md)', '[Shadcn](./guides/installation-shadcn.md)'].join('\n')
|
|
);
|
|
});
|
|
|
|
it('rewrites a root-relative same-framework link with a trailing slash', () => {
|
|
const input = 'See [Play Button](/docs/framework/react/components/play-button/) for details.';
|
|
|
|
expect(rewriteLinks(input, 'concepts/overview', 'react')).toBe(
|
|
'See [Play Button](../components/play-button.md) for details.'
|
|
);
|
|
});
|
|
|
|
it('rewrites a sibling-page link from inside a subdirectory', () => {
|
|
const input = '[Skins](https://videojs.org/docs/framework/html/concepts/skins.md)';
|
|
|
|
expect(rewriteLinks(input, 'concepts/overview', 'html')).toBe('[Skins](./skins.md)');
|
|
});
|
|
|
|
it('preserves a fragment when rewriting', () => {
|
|
const input = '[Section](https://videojs.org/docs/framework/react/components/play-button.md#props)';
|
|
|
|
expect(rewriteLinks(input, 'llms', 'react')).toBe('[Section](./components/play-button.md#props)');
|
|
});
|
|
|
|
it('does not touch links to a different framework', () => {
|
|
const input = '[HTML docs](https://videojs.org/docs/framework/html/guides/installation.md)';
|
|
|
|
expect(rewriteLinks(input, 'llms', 'react')).toBe(input);
|
|
});
|
|
|
|
it('does not touch links to non-docs site pages', () => {
|
|
const input = 'See the [blog](https://videojs.org/blog/post.md) for context.';
|
|
|
|
expect(rewriteLinks(input, 'llms', 'react')).toBe(input);
|
|
});
|
|
|
|
it('preserves the .txt extension when rewriting a link to llms.txt', () => {
|
|
const input = '[index](https://videojs.org/docs/framework/react/llms.txt)';
|
|
|
|
expect(rewriteLinks(input, 'guides/build-with-ai', 'react')).toBe('[index](../llms.txt)');
|
|
});
|
|
|
|
it('leaves bare framework-root URLs alone (empty slug)', () => {
|
|
const input = '[Docs](https://videojs.org/docs/framework/react/)';
|
|
|
|
expect(rewriteLinks(input, 'guides/build-with-ai', 'react')).toBe(input);
|
|
});
|
|
|
|
it('does not rewrite URLs that appear inside link text (e.g. code spans)', () => {
|
|
// The link text contains a URL-shaped string inside backticks; only the
|
|
// target inside `(...)` should be rewritten.
|
|
const input = '[`videojs.org/docs/framework/react/llms.txt`](https://videojs.org/docs/framework/react/llms.txt)';
|
|
|
|
expect(rewriteLinks(input, 'guides/build-with-ai', 'react')).toBe(
|
|
'[`videojs.org/docs/framework/react/llms.txt`](../llms.txt)'
|
|
);
|
|
});
|
|
});
|
|
|
|
describe('rewriteIndexHeader', () => {
|
|
const webIndex =
|
|
'# Video.js v10 — HTML Documentation\n\n' +
|
|
'> Every page below is also available as Markdown at its `.md` URL. The whole set in one file (about 240k tokens): https://videojs.org/docs/framework/html/llms-full.txt\n\n' +
|
|
'## Guides\n\n' +
|
|
'Section index: [guides/llms.txt](https://videojs.org/docs/framework/html/guides/llms.txt). This section in one file (about 90k tokens): https://videojs.org/docs/framework/html/guides/llms-full.txt\n';
|
|
|
|
it('names the package and version and drops the unbundled complete files', () => {
|
|
expect(rewriteIndexHeader(webIndex, { framework: 'html', version: '10.0.0-test' })).toBe(
|
|
'# Video.js v10 — HTML Documentation\n\n' +
|
|
'> Bundled with `@videojs/html` v10.0.0-test. Links are relative paths to files in this directory.\n\n' +
|
|
'## Guides\n\n' +
|
|
'Section index: [guides/llms.txt](https://videojs.org/docs/framework/html/guides/llms.txt).\n'
|
|
);
|
|
});
|
|
|
|
it('keeps a section description ahead of the package context and omits an unknown version', () => {
|
|
const section =
|
|
'# Guides\n\n> Guides for Video.js. Every page below is also available as Markdown at its `.md` URL. This section in one file (about 98k tokens): https://videojs.org/docs/framework/html/guides/llms-full.txt\n';
|
|
|
|
expect(rewriteIndexHeader(section, { framework: 'html', version: undefined })).toBe(
|
|
'# Guides\n\n> Guides for Video.js. Bundled with `@videojs/html`. Links are relative paths to files in this directory.\n'
|
|
);
|
|
});
|
|
});
|
|
|
|
describe('synthesizeReadme', () => {
|
|
it('renders the react cold-start file with a version', () => {
|
|
const out = synthesizeReadme({ framework: 'react', version: '10.0.0-beta.23' });
|
|
|
|
expect(out).toContain('# @videojs/react documentation');
|
|
expect(out).toContain('Bundled markdown documentation for `@videojs/react` v10.0.0-beta.23.');
|
|
expect(out).toContain('Start at [`./llms.txt`](./llms.txt)');
|
|
expect(out).toContain('Canonical online version: https://videojs.org/docs/framework/react');
|
|
});
|
|
|
|
it('renders the html cold-start file', () => {
|
|
const out = synthesizeReadme({ framework: 'html', version: '10.0.0-beta.23' });
|
|
|
|
expect(out).toContain('# @videojs/html documentation');
|
|
expect(out).toContain('Canonical online version: https://videojs.org/docs/framework/html');
|
|
});
|
|
|
|
it('omits the version suffix when version is unknown', () => {
|
|
const out = synthesizeReadme({ framework: 'react', version: undefined });
|
|
|
|
expect(out).toContain('Bundled markdown documentation for `@videojs/react`.');
|
|
expect(out).not.toContain('undefined');
|
|
});
|
|
|
|
it('throws on an unsupported framework', () => {
|
|
expect(() =>
|
|
synthesizeReadme({
|
|
// @ts-expect-error Verify the runtime guard for untyped callers.
|
|
framework: 'svelte',
|
|
version: '1.0.0',
|
|
})
|
|
).toThrow();
|
|
});
|
|
});
|
|
|
|
describe('packageDocumentation', () => {
|
|
const footer =
|
|
'\n\n---\n\nReact documentation: https://videojs.org/docs/framework/react/llms.txt\nAll documentation: https://videojs.org/llms.txt\n';
|
|
|
|
it('packages framework docs with local links and a README', () => {
|
|
const fixture = createFixture();
|
|
const installationCount = writeInstallationDocs(fixture.siteDist, 'react');
|
|
|
|
writeDoc(
|
|
fixture.siteDist,
|
|
'react',
|
|
'concepts/overview.md',
|
|
`[Install](https://videojs.org/docs/framework/react/guides/installation.md)${footer}`
|
|
);
|
|
|
|
expect(
|
|
packageDocumentation({
|
|
target: 'react',
|
|
siteDist: fixture.siteDist,
|
|
packagesDirectory: fixture.packagesDirectory,
|
|
version: '10.0.0-test',
|
|
})
|
|
).toBe(1 + installationCount);
|
|
expect(readFileSync(join(fixture.packagesDirectory, 'react/docs/concepts/overview.md'), 'utf-8')).toBe(
|
|
'[Install](../guides/installation.md)'
|
|
);
|
|
expect(readFileSync(join(fixture.packagesDirectory, 'react/docs/README.md'), 'utf-8')).toContain('v10.0.0-test');
|
|
});
|
|
|
|
it('places canonical installation Markdown at the package guide paths', () => {
|
|
const fixture = createFixture();
|
|
const installationCount = writeInstallationDocs(fixture.siteDist, 'react');
|
|
|
|
writeDoc(fixture.siteDist, 'react', 'llms.txt', '[Install](/docs/guides/installation/react.md)');
|
|
const installation = join(fixture.siteDist, 'docs/guides/installation/react.md');
|
|
|
|
writeFileSync(
|
|
installation,
|
|
'# React Installation Guide\n\n<!-- installation-plan:start -->\nDefault steps.\n<!-- installation-plan:end -->'
|
|
);
|
|
|
|
expect(
|
|
packageDocumentation({
|
|
target: 'react',
|
|
siteDist: fixture.siteDist,
|
|
packagesDirectory: fixture.packagesDirectory,
|
|
})
|
|
).toBe(1 + installationCount);
|
|
expect(readFileSync(join(fixture.packagesDirectory, 'react/docs/guides/installation.md'), 'utf-8')).toContain(
|
|
'- `framework`: `react`'
|
|
);
|
|
expect(readFileSync(join(fixture.packagesDirectory, 'react/docs/llms.txt'), 'utf-8')).toBe(
|
|
'[Install](./guides/installation.md)'
|
|
);
|
|
});
|
|
|
|
it('pins the reproduce command to the documented release', () => {
|
|
const fixture = createFixture();
|
|
|
|
writeInstallationDocs(fixture.siteDist, 'html');
|
|
writeDoc(fixture.siteDist, 'html', 'llms.txt', '# Docs');
|
|
|
|
packageDocumentation({
|
|
target: 'html',
|
|
siteDist: fixture.siteDist,
|
|
packagesDirectory: fixture.packagesDirectory,
|
|
version: '9.9.9',
|
|
});
|
|
|
|
const installation = readFileSync(join(fixture.packagesDirectory, 'html/docs/guides/installation.md'), 'utf-8');
|
|
|
|
expect(installation).toContain('npx @videojs/cli@9.9.9 agents init --method packaged --framework html ');
|
|
expect(installation).not.toContain('npx @videojs/cli agents init');
|
|
});
|
|
|
|
it('keeps the reproduce command unpinned without a release version', () => {
|
|
const fixture = createFixture();
|
|
|
|
writeInstallationDocs(fixture.siteDist, 'html');
|
|
writeDoc(fixture.siteDist, 'html', 'llms.txt', '# Docs');
|
|
|
|
packageDocumentation({
|
|
target: 'html',
|
|
siteDist: fixture.siteDist,
|
|
packagesDirectory: fixture.packagesDirectory,
|
|
});
|
|
|
|
expect(readFileSync(join(fixture.packagesDirectory, 'html/docs/guides/installation.md'), 'utf-8')).toContain(
|
|
'npx @videojs/cli agents init --method packaged --framework html '
|
|
);
|
|
});
|
|
|
|
it('preserves installed agent commands throughout the package documentation', () => {
|
|
const fixture = createFixture();
|
|
|
|
writeInstallationDocs(fixture.siteDist, 'react');
|
|
writeDoc(fixture.siteDist, 'react', 'llms.txt', 'Run `npx @videojs/cli agents init`.');
|
|
writeDoc(
|
|
fixture.siteDist,
|
|
'react',
|
|
'guides/build-with-ai.md',
|
|
'Use `npx @videojs/cli agents init --framework react --method shadcn` for version-matched instructions.'
|
|
);
|
|
|
|
packageDocumentation({
|
|
target: 'react',
|
|
siteDist: fixture.siteDist,
|
|
packagesDirectory: fixture.packagesDirectory,
|
|
});
|
|
|
|
const packageDocs = join(fixture.packagesDirectory, 'react/docs');
|
|
|
|
expect(readFileSync(join(packageDocs, 'llms.txt'), 'utf-8')).toContain('npx @videojs/cli agents init');
|
|
expect(readFileSync(join(packageDocs, 'guides/build-with-ai.md'), 'utf-8')).toContain(
|
|
'npx @videojs/cli agents init --framework react --method shadcn'
|
|
);
|
|
});
|
|
|
|
it('bundles pages and indexes but no complete files', () => {
|
|
const fixture = createFixture();
|
|
|
|
writeInstallationDocs(fixture.siteDist, 'html');
|
|
writeDoc(
|
|
fixture.siteDist,
|
|
'html',
|
|
'llms.txt',
|
|
'# Docs\n\n> Every page below is also available as Markdown at its `.md` URL. The whole set in one file: https://videojs.org/docs/framework/html/llms-full.txt\n'
|
|
);
|
|
writeDoc(fixture.siteDist, 'html', 'llms-full.txt', '# Docs\n\n> Header\n');
|
|
writeDoc(
|
|
fixture.siteDist,
|
|
'html',
|
|
'guides/llms.txt',
|
|
'# Guides\n\n> Every page below is also available as Markdown at its `.md` URL. This section in one file (about 9k tokens): https://videojs.org/docs/framework/html/guides/llms-full.txt\n'
|
|
);
|
|
writeDoc(fixture.siteDist, 'html', 'guides/llms-full.txt', '# Guides\n\n> Header\n');
|
|
|
|
packageDocumentation({
|
|
target: 'html',
|
|
siteDist: fixture.siteDist,
|
|
packagesDirectory: fixture.packagesDirectory,
|
|
version: '10.0.0-test',
|
|
});
|
|
|
|
expect(readFileSync(join(fixture.packagesDirectory, 'html/docs/llms.txt'), 'utf-8')).toBe(
|
|
'# Docs\n\n> Bundled with `@videojs/html` v10.0.0-test. Links are relative paths to files in this directory.\n'
|
|
);
|
|
expect(readFileSync(join(fixture.packagesDirectory, 'html/docs/guides/llms.txt'), 'utf-8')).toBe(
|
|
'# Guides\n\n> Bundled with `@videojs/html` v10.0.0-test. Links are relative paths to files in this directory.\n'
|
|
);
|
|
expect(existsSync(join(fixture.packagesDirectory, 'html/docs/llms-full.txt'))).toBe(false);
|
|
expect(existsSync(join(fixture.packagesDirectory, 'html/docs/guides/llms-full.txt'))).toBe(false);
|
|
});
|
|
|
|
it("keeps only the package's branch of the Shadcn guide and links it locally", () => {
|
|
const fixture = createFixture();
|
|
|
|
writeInstallationDocs(fixture.siteDist, 'html');
|
|
writeDoc(fixture.siteDist, 'html', 'llms.txt', '# Docs');
|
|
writeFileSync(
|
|
join(fixture.siteDist, 'docs/guides/installation/shadcn.md'),
|
|
[
|
|
'# Shadcn',
|
|
'<!-- installation-plan:start -->',
|
|
'Default React plan',
|
|
'<!-- installation-plan:end -->',
|
|
'<!-- installation:framework react -->',
|
|
'React steps',
|
|
'<!-- /installation:framework react -->',
|
|
'<!-- installation:framework html -->',
|
|
'HTML steps',
|
|
'<!-- /installation:framework html -->',
|
|
].join('\n\n')
|
|
);
|
|
writeFileSync(
|
|
join(fixture.siteDist, 'docs/guides/installation/vue.md'),
|
|
'# Vue\n\n<!-- installation-plan:start -->\nDefault steps.\n<!-- installation-plan:end -->\n\n[Shadcn](https://videojs.org/docs/guides/installation/shadcn?framework=html) or [React](https://videojs.org/docs/guides/installation/shadcn?framework=react)'
|
|
);
|
|
|
|
packageDocumentation({ target: 'html', siteDist: fixture.siteDist, packagesDirectory: fixture.packagesDirectory });
|
|
|
|
const guides = join(fixture.packagesDirectory, 'html/docs/guides');
|
|
|
|
const shadcn = readFileSync(join(guides, 'installation-shadcn.md'), 'utf-8');
|
|
|
|
expect(shadcn).toContain('- `framework`: `html`');
|
|
expect(shadcn).toContain('HTML steps');
|
|
expect(shadcn).not.toContain('React steps');
|
|
expect(shadcn).not.toContain('installation:framework');
|
|
const vue = readFileSync(join(guides, 'installation-vue.md'), 'utf-8');
|
|
|
|
expect(vue).toContain(
|
|
'[Shadcn](./installation-shadcn.md) or [React](https://videojs.org/docs/guides/installation/shadcn?framework=react)'
|
|
);
|
|
});
|
|
|
|
it('throws when a canonical installation document is missing', () => {
|
|
const fixture = createFixture();
|
|
|
|
writeDoc(fixture.siteDist, 'react', 'llms.txt', '# React');
|
|
writeInstallationDocs(fixture.siteDist, 'react');
|
|
rmSync(join(fixture.siteDist, 'docs/guides/installation/shadcn.md'));
|
|
|
|
expect(() =>
|
|
packageDocumentation({
|
|
target: 'react',
|
|
siteDist: fixture.siteDist,
|
|
packagesDirectory: fixture.packagesDirectory,
|
|
})
|
|
).toThrow(/installation\/shadcn\.md/);
|
|
});
|
|
|
|
it('validates every source before replacing existing output', () => {
|
|
const fixture = createFixture();
|
|
|
|
writeDoc(fixture.siteDist, 'html', 'llms.txt', '# HTML');
|
|
const sentinel = join(fixture.packagesDirectory, 'html/docs/sentinel.txt');
|
|
|
|
mkdirSync(join(sentinel, '..'), { recursive: true });
|
|
writeFileSync(sentinel, 'keep');
|
|
|
|
expect(() =>
|
|
packageDocumentation({
|
|
target: 'html',
|
|
siteDist: fixture.siteDist,
|
|
packagesDirectory: fixture.packagesDirectory,
|
|
})
|
|
).toThrow(/installation/);
|
|
expect(existsSync(sentinel)).toBe(true);
|
|
});
|
|
});
|