@beltype/cli 0.1.3 → 0.1.5

package/dist/src/print.js

@@ -2,7 +2,7 @@
  * `beltype print`: a finished HTML document to a PDF, through Cicero and Caster, in Chromium's headless shell.
  *
  * @remarks
- * **One road.** Cicero paginates and Caster prints the pages Cicero presented. Chromium's own print (`page.pdf()`) is never called, which is why the bare headless shell is enough: where Cicero cuts is layout, the same Blink in the shell as in the full binary.
+ * **Two printers.** Cicero paginates, then Caster prints the pages Cicero presented (the default), or `--printer chromium` has Chromium's `page.pdf()` print them. Under Caster the bare headless shell is enough: where Cicero cuts is layout, the same Blink in the shell as in the full binary.
  *
  * **Every request is answered from disk, on one made-up origin.** The browser context's `route` answers the document at its own name, the document's folder at the root, and `/_beltype/` from the companions' built files. A request for anything else is refused and named, and a run that refused anything writes no file, because the print would not be the document.
  *
@@ -12,120 +12,127 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { chromium } from 'playwright-core';
-import { ciceroEngine } from '@beltype/cicero';
-import { BuildError } from '@beltype/common/errors';
-import { contentType } from '@beltype/common/mime';
-import { cutInPage, printInPage } from './in-page.js';
-/** `.invalid` is reserved (RFC 2606), so nothing on a network can ever answer it instead. */
-const ORIGIN = 'https://print.invalid';
-const VIEWPORT = { width: 1200, height: 1600 };
-/** Deterministic text and timers that run while nobody watches the page. */
-const ARGS = ['--font-render-hinting=none', '--force-device-scale-factor=1', '--disable-background-timer-throttling', '--disable-renderer-backgrounding', '--disable-backgrounding-occluded-windows'];
+import { ciceroFlags } from '@beltype/cicero/flags';
+import { cliFlags, tableOf } from './flags.js';
+import { checkPages } from './check.js';
+import { ARGS, VIEWPORT, documentAssets, servedHtml, routeCompanions, routeDocument, printOnPage, refusal } from './run.js';
+export { spliceHead } from './run.js';
+const round = (ms) => Math.round(ms * 10) / 10;
 /**
  * Print `input`, an HTML file, to `output`.
  *
  * @throws {BuildError} naming what the document asked for and could not be given, or the step that refused.
  */
-export async function print(input, output) {
+export async function print(input, output, options = {}) {
     const started = performance.now();
-    const html = fs.readFileSync(input, 'utf8');
-    const root = path.dirname(path.resolve(input));
-    const docPath = `/${encodeURIComponent(path.basename(input))}`;
-    // Each companion's built folder, found from a module it exports: common exports no `package.json`.
-    const distOf = (specifier, up) => path.resolve(path.dirname(fileURLToPath(import.meta.resolve(specifier))), ...Array(up).fill('..'));
-    const cicero = ciceroEngine.vendorAssets();
-    const assets = {
-        files: cicero.files,
-        dirs: { ...cicero.dirs, caster: distOf('@beltype/caster', 1), common: distOf('@beltype/common/errors', 0) },
+    // Caster's own defaults are resolved in the page by `caster.print`, so the given values are all the page is handed; its table is loaded for the trace alone, at the end.
+    const flags = {
+        caster: options.given?.caster ?? {},
+        cicero: ciceroFlags.resolve(options.given?.cicero),
+        beltype: cliFlags.resolve(options.given?.beltype)
     };
-    // Caster's modules import common by its package names, which a page resolves only through an import map.
-    const imports = Object.fromEntries(['errors', 'data-beltype', 'mime'].map((m) => [`@beltype/common/${m}`, `/_beltype/common/${m}.js`]));
-    const served = spliceHead(html, `<script type="importmap">${JSON.stringify({ imports })}</script>\n  ${ciceroEngine.headHtml('/')}`);
-    const missing = new Set();
-    const browser = await chromium.launch({ headless: true, args: ARGS });
+    const trace = { process: {}, cicero: [], caster: null, versions: {}, flags: {} };
+    let mark = started;
+    const lap = (key) => {
+        const now = performance.now();
+        trace.process[key] = round(now - mark);
+        mark = now;
+    };
+    let step = 'launch';
+    let chromiumVersion = 'unknown';
     try {
-        const context = await browser.newContext({ viewport: VIEWPORT, serviceWorkers: 'block' });
-        await answerFromDisk(context, missing, { root, docPath, served, assets });
-        const page = await context.newPage();
-        page.on('pageerror', (error) => console.warn(`page error: ${error.message}`));
-        await page.goto(ORIGIN + docPath, { waitUntil: 'load' });
-        const cut = await page.evaluate(cutInPage);
-        if ('refused' in cut || missing.size)
-            throw refusal(missing, 'refused' in cut ? cut : null);
-        const printed = await page.evaluate(printInPage);
-        if ('refused' in printed)
-            throw refusal(missing, printed);
-        await browser.close();
-        if (missing.size)
-            throw refusal(missing, null);
-        for (const warning of printed.warnings)
-            console.warn(typeof warning === 'string' ? warning : JSON.stringify(warning));
-        fs.mkdirSync(path.dirname(path.resolve(output)), { recursive: true });
-        fs.writeFileSync(output, Buffer.from(printed.base64, 'base64'));
-        return { output, pages: printed.pages, words: printed.words, ms: performance.now() - started };
-    }
-    finally {
-        await browser.close();
-    }
-}
-/** The run's refusal: what it could not answer comes first, because a missing file's name says more than the step it broke. */
-function refusal(missing, answer) {
-    if (missing.size)
-        return new BuildError(`beltype print: the document asked for what the run cannot give it, so the print would not be the document:\n${[...missing].map((m) => `  ${m}`).join('\n')}`);
-    return new BuildError(`beltype print: the ${answer?.at ?? 'run'} step refused:\n${answer?.refused || '(the refusal carried no message)'}`);
-}
-/** `fragment` at the top of the document's `<head>`, ahead of the author's own sheets and scripts. */
-export function spliceHead(html, fragment) {
-    const head = /<head\b[^>]*>/i.exec(html);
-    if (head)
-        return html.slice(0, head.index + head[0].length) + `\n  ${fragment}` + html.slice(head.index + head[0].length);
-    const before = /^\s*(<!doctype[^>]*>\s*)?(<html\b[^>]*>)?/i.exec(html)?.[0] ?? '';
-    return `${before}<head>\n  ${fragment}\n</head>${html.slice(before.length)}`;
-}
-// ponytail: routes only. A dedicated or shared worker's WebSocket and fetches pass no route, so a document that opens one is not refused; the monorepo's `cast` closes that with a proxy the run owns (packages/cli/src/cast.js), to be brought over when a document needs it.
-async function answerFromDisk(context, missing, o) {
-    await context.routeWebSocket(/.*/, (ws) => {
-        missing.add(`${ws.url()} (a WebSocket; print opens none)`);
-        return ws.close({ code: 1008, reason: 'beltype print reaches no network' });
-    });
-    await context.route('**/*', async (route) => {
-        const url = new URL(route.request().url());
-        if (url.origin !== ORIGIN) {
-            missing.add(`${url.href} (another origin; print fetches nothing from a network)`);
-            return route.abort('blockedbyclient');
-        }
-        let pathname;
+        const html = fs.readFileSync(input, 'utf8');
+        const root = path.dirname(path.resolve(input));
+        const docPath = `/${encodeURIComponent(path.basename(input))}`;
+        const assets = documentAssets();
+        const served = servedHtml(html);
+        const missing = new Set();
+        const browser = await chromium.launch({ headless: true, args: ARGS });
+        chromiumVersion = browser.version();
+        lap('launch');
         try {
-            pathname = decodeURIComponent(url.pathname);
+            step = 'context';
+            const context = await browser.newContext({ viewport: VIEWPORT, serviceWorkers: 'block' });
+            await routeCompanions(context, missing, assets);
+            const page = await context.newPage();
+            await routeDocument(page, missing, { root, docPath, served });
+            lap('context');
+            const printed = await printOnPage(page, missing, flags, {
+                docPath,
+                measures: options.trace !== undefined,
+                ...(options.created !== undefined ? { created: options.created } : {}),
+                progress: { step: (name) => { step = name; }, lap, cicero: (measures) => { trace.cicero = measures; } }
+            });
+            if (printed.printMs !== undefined) {
+                trace.process['print'] = round(printed.printMs);
+                trace.process['transfer'] = round(performance.now() - mark - printed.printMs);
+                mark = performance.now();
+                trace.caster = printed.caster;
+                for (const warning of printed.warnings)
+                    console.warn(typeof warning === 'string' ? warning : JSON.stringify(warning));
+            }
+            else
+                lap('print');
+            const { bytes, pages, words, screens } = printed;
+            step = 'close';
+            await browser.close();
+            lap('close');
+            if (missing.size)
+                throw refusal(missing, null);
+            step = 'write';
+            fs.mkdirSync(path.dirname(path.resolve(output)), { recursive: true });
+            fs.writeFileSync(output, bytes);
+            lap('write');
+            let check;
+            if (flags.beltype.check) {
+                step = 'check';
+                check = await checkPages(screens, bytes, path.resolve(output).replace(/\.pdf$/i, '') + '.check', flags.beltype.printer);
+                lap('check');
+            }
+            return { output, pages, words, ms: performance.now() - started, ...(check ? { check } : {}) };
         }
-        catch {
-            missing.add(`${url.pathname} (a malformed percent escape, which names no file)`);
-            return route.fulfill({ status: 400, body: '' });
+        finally {
+            await browser.close();
+        }
+    }
+    catch (error) {
+        trace.refused = { step, message: error instanceof Error ? error.message : String(error) };
+        throw error;
+    }
+    finally {
+        if (options.trace !== undefined) {
+            trace.process['total'] = round(performance.now() - started);
+            trace.versions = versions(chromiumVersion);
+            // After the total: importing Caster's table here costs about 40 ms in Node, which is not the run's.
+            trace.flags = { ...flags, caster: (await tableOf('caster')).resolve(flags.caster) };
+            fs.mkdirSync(path.dirname(path.resolve(options.trace)), { recursive: true });
+            fs.writeFileSync(options.trace, JSON.stringify(trace, null, 2));
         }
-        if (url.pathname === o.docPath)
-            return route.fulfill({ status: 200, contentType: 'text/html; charset=utf-8', body: o.served });
-        const file = pathname.startsWith('/_beltype/') ? fromAssets(o.assets, pathname.slice('/_beltype/'.length)) : within(o.root, `.${pathname}`);
-        if (file)
-            return route.fulfill({ status: 200, path: file, contentType: contentType(file) });
-        if (pathname !== '/favicon.ico')
-            missing.add(pathname.startsWith('/_beltype/') ? `${pathname} (no companion holds it)` : `${pathname} (not in ${o.root})`);
-        return route.fulfill({ status: 404, body: '' });
-    });
-}
-function fromAssets(assets, assetPath) {
-    const file = assets.files[assetPath];
-    if (file)
-        return isFile(file) ? file : null;
-    for (const [prefix, dir] of Object.entries(assets.dirs)) {
-        if (assetPath.startsWith(prefix + '/'))
-            return within(dir, assetPath.slice(prefix.length + 1));
     }
-    return null;
 }
-/** `rel` under `dir`, if it is a file there and does not climb out. */
-function within(dir, rel) {
-    const file = path.resolve(dir, rel);
-    const inside = path.relative(dir, file);
-    return !inside.startsWith('..') && !path.isAbsolute(inside) && isFile(file) ? file : null;
+/** The version of each package the run used, read from the `package.json` above the module that `specifier` resolves to. */
+function versions(chromiumVersion) {
+    const of = (url, name) => {
+        let dir = path.dirname(fileURLToPath(url));
+        for (;;) {
+            const file = path.join(dir, 'package.json');
+            if (fs.existsSync(file)) {
+                const pkg = JSON.parse(fs.readFileSync(file, 'utf8'));
+                if (pkg.name === name)
+                    return pkg.version ?? 'unknown';
+            }
+            const up = path.dirname(dir);
+            if (up === dir)
+                return 'unknown';
+            dir = up;
+        }
+    };
+    return {
+        '@beltype/cli': of(import.meta.url, '@beltype/cli'),
+        '@beltype/cicero': of(import.meta.resolve('@beltype/cicero'), '@beltype/cicero'),
+        '@beltype/caster': of(import.meta.resolve('@beltype/caster'), '@beltype/caster'),
+        '@beltype/common': of(import.meta.resolve('@beltype/common/errors'), '@beltype/common'),
+        'playwright-core': of(import.meta.resolve('playwright-core'), 'playwright-core'),
+        chromium: chromiumVersion
+    };
 }
-const isFile = (file) => fs.existsSync(file) && fs.statSync(file).isFile();

package/dist/src/run.js

@@ -0,0 +1,157 @@
+/**
+ * The steps of a print as functions of a page, so `beltype print` and a server that keeps a browser alive print the same way.
+ *
+ * @remarks
+ * **Every request is answered from disk, on one made-up origin.** {@link routeCompanions} answers on the browser context what no document owns: a WebSocket and another origin are refused and named, `/_beltype/` is answered from the companions' built files. {@link routeDocument} answers on a page the document at its own name and its folder at the root, and lets everything else fall back to the context's routes (Playwright runs a page's routes before its context's). {@link printOnPage} then loads, cuts, screenshots when asked and prints, and throws the refusals `print` has always thrown.
+ *
+ * @packageDocumentation
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { ciceroEngine } from '@beltype/cicero/engine';
+import { BuildError } from '@beltype/common/errors';
+import { contentType } from '@beltype/common/mime';
+import { cutInPage, printInPage, pageSizesInPage, chromiumSheetInPage } from './in-page.js';
+import { chromiumSheet } from './chromium.js';
+import { screenshotPages } from './check.js';
+/** `.invalid` is reserved (RFC 2606), so nothing on a network can ever answer it instead. */
+export const ORIGIN = 'https://print.invalid';
+export const VIEWPORT = { width: 1200, height: 1600 };
+/** Deterministic text and timers that run while nobody watches the page. */
+export const ARGS = ['--font-render-hinting=none', '--force-device-scale-factor=1', '--disable-background-timer-throttling', '--disable-renderer-backgrounding', '--disable-backgrounding-occluded-windows'];
+/** The companions' built folders and files, each folder found from a module it exports: common exports no `package.json`. */
+export function documentAssets() {
+    const distOf = (specifier, up) => path.resolve(path.dirname(fileURLToPath(import.meta.resolve(specifier))), ...Array(up).fill('..'));
+    const cicero = ciceroEngine.vendorAssets();
+    return { files: cicero.files, dirs: { ...cicero.dirs, caster: distOf('@beltype/caster', 1), common: distOf('@beltype/common/errors', 0) } };
+}
+/** The document as the page is served it: Caster's import map and Cicero's head ahead of the author's own. */
+export function servedHtml(html) {
+    // Caster's modules import common by its package names, which a page resolves only through an import map.
+    const imports = Object.fromEntries(['errors', 'data-beltype', 'flags', 'mime'].map((m) => [`@beltype/common/${m}`, `/_beltype/common/${m}.js`]));
+    return spliceHead(html, `<script type="importmap">${JSON.stringify({ imports })}</script>\n  ${ciceroEngine.headHtml('/')}`);
+}
+/** `fragment` at the top of the document's `<head>`, ahead of the author's own sheets and scripts. */
+export function spliceHead(html, fragment) {
+    const head = /<head\b[^>]*>/i.exec(html);
+    if (head)
+        return html.slice(0, head.index + head[0].length) + `\n  ${fragment}` + html.slice(head.index + head[0].length);
+    const before = /^\s*(<!doctype[^>]*>\s*)?(<html\b[^>]*>)?/i.exec(html)?.[0] ?? '';
+    return `${before}<head>\n  ${fragment}\n</head>${html.slice(before.length)}`;
+}
+// ponytail: routes only. A dedicated or shared worker's WebSocket and fetches pass no route, so a document that opens one is not refused; the monorepo's `cast` closes that with a proxy the run owns (packages/cli/src/cast.js), to be brought over when a document needs it.
+/** What no document owns, on the context: refuse a WebSocket or another origin by name, and answer `/_beltype/` from the companions. */
+export async function routeCompanions(context, missing, assets = documentAssets()) {
+    await context.routeWebSocket(/.*/, (ws) => {
+        missing.add(`${ws.url()} (a WebSocket; print opens none)`);
+        return ws.close({ code: 1008, reason: 'beltype print reaches no network' });
+    });
+    await context.route('**/*', async (route) => {
+        const url = new URL(route.request().url());
+        if (url.origin !== ORIGIN) {
+            missing.add(`${url.href} (another origin; print fetches nothing from a network)`);
+            return route.abort('blockedbyclient');
+        }
+        const pathname = decoded(url, missing);
+        if (pathname === null)
+            return route.fulfill({ status: 400, body: '' });
+        const file = pathname.startsWith('/_beltype/') ? fromAssets(assets, pathname.slice('/_beltype/'.length)) : null;
+        if (file)
+            return route.fulfill({ status: 200, path: file, contentType: contentType(file) });
+        missing.add(`${pathname} (${pathname.startsWith('/_beltype/') ? 'no companion holds it' : 'no document answered it'})`);
+        return route.fulfill({ status: 404, body: '' });
+    });
+}
+/** The document's own files on a page: the document at `docPath`, its folder `root` at the root. Another origin and `/_beltype/` fall back to the context's routes. */
+export async function routeDocument(page, missing, o) {
+    await page.route('**/*', async (route) => {
+        const url = new URL(route.request().url());
+        if (url.origin !== ORIGIN)
+            return route.fallback();
+        const pathname = decoded(url, missing);
+        if (pathname === null)
+            return route.fulfill({ status: 400, body: '' });
+        if (pathname.startsWith('/_beltype/'))
+            return route.fallback();
+        if (url.pathname === o.docPath)
+            return route.fulfill({ status: 200, contentType: 'text/html; charset=utf-8', body: o.served });
+        const file = within(o.root, `.${pathname}`);
+        if (file)
+            return route.fulfill({ status: 200, path: file, contentType: contentType(file) });
+        if (pathname !== '/favicon.ico')
+            missing.add(`${pathname} (not in ${o.root})`);
+        return route.fulfill({ status: 404, body: '' });
+    });
+}
+/**
+ * Load the document on `page`, cut it, screenshot its pages when `--check` asks, and print it under the flags' printer.
+ *
+ * @remarks
+ * What the run could not answer after the print (`missing`) is the caller's to test with {@link refusal}: `print` tests it after closing the browser, as it always has.
+ * @throws {BuildError} where the cut or the print refused, or the document asked for what the run could not give it.
+ */
+export async function printOnPage(page, missing, flags, o) {
+    const { progress } = o;
+    page.on('pageerror', (error) => console.warn(`page error: ${error.message}`));
+    progress?.step('load');
+    await page.goto(ORIGIN + o.docPath, { waitUntil: 'load' });
+    progress?.lap('load');
+    progress?.step('cut');
+    const cut = await page.evaluate(cutInPage, { cicero: flags.cicero, measures: o.measures === true });
+    progress?.lap('cut');
+    const measures = 'refused' in cut ? [] : cut.measures;
+    progress?.cicero?.(measures);
+    if ('refused' in cut || missing.size)
+        throw refusal(missing, 'refused' in cut ? cut : null);
+    let screens = [];
+    if (flags.beltype.check) {
+        progress?.step('check');
+        screens = await screenshotPages(page);
+        progress?.lap('check');
+    }
+    progress?.step('print');
+    if (flags.beltype.printer === 'chromium') {
+        const sheet = chromiumSheet(await page.evaluate(pageSizesInPage));
+        await page.evaluate(chromiumSheetInPage, sheet);
+        const bytes = await page.pdf({ preferCSSPageSize: true, printBackground: true });
+        return { bytes, pages: await page.locator('beltype-page').count(), words: 0, warnings: [], caster: null, cicero: measures, screens };
+    }
+    const printed = await page.evaluate(printInPage, { options: flags.caster, ...(o.created !== undefined ? { created: o.created } : {}), ...(o.sharedWriter ? { sharedWriter: true } : {}) });
+    if ('refused' in printed)
+        throw refusal(missing, printed);
+    return { bytes: Buffer.from(printed.base64, 'base64'), pages: printed.pages, words: printed.words, warnings: printed.warnings, caster: printed.caster, cicero: measures, screens, printMs: printed.printMs };
+}
+/** The run's refusal: what it could not answer comes first, because a missing file's name says more than the step it broke. */
+export function refusal(missing, answer) {
+    if (missing.size)
+        return new BuildError(`beltype print: the document asked for what the run cannot give it, so the print would not be the document:\n${[...missing].map((m) => `  ${m}`).join('\n')}`);
+    return new BuildError(`beltype print: the ${answer?.at ?? 'run'} step refused:\n${answer?.refused || '(the refusal carried no message)'}`);
+}
+/** The percent-decoded path of `url`, or null (and the name of what it asked) where the escape is malformed. */
+function decoded(url, missing) {
+    try {
+        return decodeURIComponent(url.pathname);
+    }
+    catch {
+        missing.add(`${url.pathname} (a malformed percent escape, which names no file)`);
+        return null;
+    }
+}
+function fromAssets(assets, assetPath) {
+    const file = assets.files[assetPath];
+    if (file)
+        return isFile(file) ? file : null;
+    for (const [prefix, dir] of Object.entries(assets.dirs)) {
+        if (assetPath.startsWith(prefix + '/'))
+            return within(dir, assetPath.slice(prefix.length + 1));
+    }
+    return null;
+}
+/** `rel` under `dir`, if it is a file there and does not climb out. */
+function within(dir, rel) {
+    const file = path.resolve(dir, rel);
+    const inside = path.relative(dir, file);
+    return !inside.startsWith('..') && !path.isAbsolute(inside) && isFile(file) ? file : null;
+}
+const isFile = (file) => fs.existsSync(file) && fs.statSync(file).isFile();