#!/usr/bin/env node
/**
* The example check: the live examples under `samples/`, compiled straight from here against the
* packages in this commit, without syncing them into a site or starting one.
*
* node scripts/samples.mjs every example; exit 1 on an error
* node scripts/samples.mjs search stage only the examples of these areas
* node scripts/samples.mjs viewer only the ready-made viewer's
* node scripts/samples.mjs --root
a site's synced copy instead (`src/samples`)
*
* Unlike a snippet, an example is a complete app that runs on its page, so every one must compile:
* nothing stands in for a missing helper, and an error fails the check. React examples compile
* with `tsc`, Angular ones with `ngc` (`strictTemplates`), Vue ones with `vue-tsc`
* (`strictTemplates`) and Svelte ones with `svelte-check`. Each run gets its own directory
* (`compile.mjs`), so several checks of different areas can run at the same time.
*
* The ready-made viewer's examples (`samples/viewer/`) compile as the snippet check compiles the
* viewer's snippets: against `@embedpdf/viewer` at its source, for the four frameworks and
* `vanilla`, a plain HTML page (`.vanilla.html`), whose module scripts are taken out of the
* page and checked as JavaScript, and whose elements are checked against the viewer's
* (`viewer.mjs`).
*
* By default it checks examples as they are written, for the local engine. A site checks what it
* ships with `--root src/samples` (its `check:samples`): the synced copy, the cloud form included,
* in every framework. A synced copy's `snippets/` belong to the snippet check.
*/
import fs from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import {
compile,
contentRoot,
FRAMEWORK_LABELS,
FRAMEWORKS,
removeRunDirectory,
runDirectory,
toPosix,
VIEWER_INTEGRATIONS,
walk,
writeTsconfig,
} from './compile.mjs';
import { ENGINES } from '../engines.mjs';
import { addMarkupErrors, stageVanilla } from './viewer.mjs';
/** Where the examples are: here, or a site's synced copy (`--root`). */
let samplesRoot = path.join(contentRoot, 'samples');
/** A synced copy's snippets: not examples. */
const NOT_EXAMPLES = new Set(['snippets']);
/** The ready-made viewer's examples, which compile against the viewer, in five integrations. */
const VIEWER = 'viewer';
/**
* How each framework's examples are named: one file, `..`, or a directory
* of them, `./` with `App.` first. A plain-HTML page is one file. The
* tsconfig compiles exactly those.
*/
const EXTENSIONS = { react: 'tsx', vue: 'vue', svelte: 'svelte', angular: 'ts', vanilla: 'html' };
const include = (framework) => [
`**/*.${framework}.${EXTENSIONS[framework]}`,
`**/*.${framework}/**/*`,
'samples-env.d.ts',
];
/** The example a file belongs to (`search/basic.vue`), or null if it isn't a `framework` one. */
function exampleOf(file, framework) {
const match = toPosix(path.relative(samplesRoot, file)).match(
new RegExp(`^(.+\\.${framework})(?:\\.${EXTENSIONS[framework]}$|/.+\\.[a-z]+$)`),
);
return match ? match[1] : null;
}
/** The areas to check: the ones named on the command line, or every one. */
function areasToCheck(argv) {
const all = fs
.readdirSync(samplesRoot, { withFileTypes: true })
.filter((entry) => entry.isDirectory() && !NOT_EXAMPLES.has(entry.name))
.map((entry) => entry.name);
const named = argv.filter((arg) => !arg.startsWith('-'));
const unknown = named.filter((area) => !all.includes(area));
if (unknown.length) {
throw new Error(`no examples in ${unknown.join(', ')}; the areas are ${all.join(', ')}`);
}
return named.length ? named : all;
}
/**
* Copy the areas a pass compiles (every headless area, or the viewer's) to `root`, so an
* example's relative imports work wherever they point, with a tsconfig for one framework. Only
* the areas being checked report errors.
*/
function stage(framework, root, { viewer = false } = {}) {
fs.cpSync(samplesRoot, root, {
recursive: true,
filter: (source) => {
const relative = path.relative(samplesRoot, source);
// The directory itself, and the files beside the areas (`samples-env.d.ts`).
if (!relative || (!relative.includes(path.sep) && fs.statSync(source).isFile())) return true;
const area = relative.split(path.sep)[0];
return !NOT_EXAMPLES.has(area) && (area === VIEWER) === viewer;
},
});
writeTsconfig(framework, root, include(framework), {}, { viewer });
}
/** Where a staged file came from, as the docs name it: `samples/search/search-box.react.tsx`. */
const sourceName = (root, file) => toPosix(path.join('samples', path.relative(root, file)));
/** One framework's compile: how many examples, its errors (`{ where, message }`), or why not. */
async function checkFramework(framework, areas, runRoot, { viewer }) {
const examples = new Set(
areas
.flatMap((area) => walk(path.join(samplesRoot, area)))
.map((file) => exampleOf(file, framework))
.filter(Boolean),
);
if (examples.size === 0) return null;
const root = path.join(runRoot, `${viewer ? 'viewer-' : ''}${framework}`);
const inArea = (file) => areas.includes(path.relative(root, file).split(path.sep)[0]);
stage(framework, root, { viewer });
const result = await compile(framework, root, inArea);
if (!result.tool) return { examples: examples.size, ...result };
// A compiler that can't narrow to the areas reports on every example: keep theirs.
const errors = result.diagnostics
.filter(({ file }) => !file || inArea(file))
.map(({ file, line, column, message }) => ({
where: file ? `${sourceName(root, file)}:${line}:${column}` : '(compiler options)',
message,
}));
return { examples: examples.size, tool: result.tool, errors };
}
/**
* The viewer's plain-HTML examples, compiled as the snippet check compiles the viewer's plain-HTML
* snippets (`viewer.mjs`): each module script on its own at the page's line numbers, and the
* elements and attributes the page uses, against its site's viewer. A per-site page
* (`.cloud.vanilla.html`) is its site's; the others are the site's whose copy this is
* (`viewer.mjs` tells), embedpdf.com's as written.
*/
async function checkVanilla(runRoot) {
const pages = walk(path.join(samplesRoot, VIEWER))
.map((file) => toPosix(path.relative(samplesRoot, file)))
.filter((file) => /\.vanilla(\.|\/)/.test(file));
if (pages.length === 0) return null;
const directories = pages.filter((file) => !file.endsWith('.vanilla.html'));
if (directories.length) {
return {
examples: pages.length,
tool: 'the example check',
errors: directories.map((file) => ({
where: `samples/${file}`,
message: 'a plain-HTML example is one page: `.vanilla.html`',
})),
};
}
const bySite = Map.groupBy(pages, (file) => {
const flavor = file.match(/\.(\w+)\.vanilla\.html$/)?.[1];
return flavor && ENGINES[flavor] ? flavor : null;
});
const errors = [];
let tool = null;
for (const [engine, files] of bySite) {
const examples = files.map((file) => ({
file,
name: file.replace(/\.vanilla\.html$/, ''),
framework: 'vanilla',
}));
const root = path.join(runRoot, `viewer-vanilla${engine ? `-${engine}` : ''}`);
const staged = stageVanilla(examples, new Map(), root, samplesRoot, engine ? { engine } : {});
writeTsconfig('vanilla', root, ['**/*.ts', '**/*.js'], {}, { viewer: true });
const result = await compile('vanilla', root);
if (!result.tool) return { examples: pages.length, ...result };
tool = result.tool;
for (const { file, line, column, message } of result.diagnostics) {
const origin = file && staged.origins.get(file);
const at = origin ? staged.locate.get(file)(line, column) : null;
if (at) errors.push({ where: `samples/${origin}:${at.line}:${at.column}`, message });
else {
const own = file ? `${toPosix(path.relative(root, file))}:${line}` : '(compiler options)';
errors.push({ where: `the check's own ${own}`, message });
}
}
const markup = { tool, bySnippet: new Map() };
addMarkupErrors(markup, staged.markup);
for (const [file, list] of markup.bySnippet) {
for (const { line, column, message } of list) {
errors.push({ where: `samples/${file}:${line}:${column}`, message });
}
}
}
return { examples: pages.length, tool, errors };
}
export async function checkSamples(argv = []) {
const started = performance.now();
const rootFlag = argv.indexOf('--root');
if (rootFlag !== -1) {
samplesRoot = path.resolve(argv[rootFlag + 1]);
argv = argv.filter((_, index) => index !== rootFlag && index !== rootFlag + 1);
}
const areas = areasToCheck(argv);
const headless = areas.filter((area) => area !== VIEWER);
const viewer = areas.includes(VIEWER) ? [VIEWER] : [];
const runRoot = runDirectory('embedpdf-samples');
let failed = false;
const report = (label, outcome) => {
if (!outcome) return;
if (!outcome.tool) {
failed = true;
console.error(` ${label} not checked: ${outcome.reason}`);
return;
}
const { examples, errors, tool } = outcome;
console.log(
` ${label} ${examples} examples, ${errors.length ? `${errors.length} errors` : 'all compile'} (${tool})`,
);
for (const { where, message } of errors) console.error(` ${where} ${message}`);
failed ||= errors.length > 0;
};
try {
if (headless.length) {
for (const framework of FRAMEWORKS) {
const outcome = await checkFramework(framework, headless, runRoot, { viewer: false });
report(FRAMEWORK_LABELS[framework].padEnd(8), outcome);
}
}
if (viewer.length) {
for (const integration of VIEWER_INTEGRATIONS) {
const outcome =
integration === 'vanilla'
? await checkVanilla(runRoot)
: await checkFramework(integration, viewer, runRoot, { viewer: true });
report(`Viewer, ${FRAMEWORK_LABELS[integration]}`.padEnd(18), outcome);
}
}
} finally {
removeRunDirectory(runRoot);
}
console.log(
`Examples in ${areas.join(', ')}: ${((performance.now() - started) / 1000).toFixed(1)}s`,
);
return !failed;
}
if (process.argv[1] && fileURLToPath(import.meta.url) === path.resolve(process.argv[1])) {
const ok = await checkSamples(process.argv.slice(2));
process.exit(ok ? 0 : 1);
}