@publisle/research 0.1.1 → 0.3.0

package/src/native-install.ts

@@ -0,0 +1,96 @@
+/** Locate a pinned, already installed native artifact. Never download at runtime. */
+import { createHash } from "node:crypto";
+import researchPackage from "../package.json" with { type: "json" };
+import { createRequire } from "node:module";
+import { readFile, realpath, stat } from "node:fs/promises";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import { parseJson, isPlainObject } from "@publisle/schema";
+const require = createRequire(import.meta.url);
+export const NATIVE_ARTIFACT_VERSION = researchPackage.version;
+export const NATIVE_PLATFORM_PACKAGES: Readonly<Record<string, string>> = {
+  "linux-x64": "@publisle/pdf-native-linux-x64",
+  "linux-arm64": "@publisle/pdf-native-linux-arm64",
+  "darwin-x64": "@publisle/pdf-native-darwin-x64",
+  "darwin-arm64": "@publisle/pdf-native-darwin-arm64",
+  "win32-x64": "@publisle/pdf-native-win32-x64",
+};
+export interface InstalledNativeCompiler {
+  readonly executable: string;
+  readonly fontManifest: string;
+  readonly compilerVersion: string;
+}
+export async function installedNativeCompiler(): Promise<InstalledNativeCompiler> {
+  const name = NATIVE_PLATFORM_PACKAGES[`${process.platform}-${process.arch}`];
+  if (!name)
+    throw new Error(
+      `Native PDF does not support ${process.platform}/${process.arch}. Configure an explicit compatible compiler and fonts.`,
+    );
+  let root: string;
+  try {
+    root = dirname(require.resolve(`${name}/package.json`));
+  } catch {
+    throw new Error(
+      `Missing ${name}@${NATIVE_ARTIFACT_VERSION}. Install that native package; optional dependencies may have been omitted. PDF compilation never downloads binaries.`,
+    );
+  }
+  const manifest = parseJson(await readFile(resolve(root, "package.json")));
+  if (
+    !isPlainObject(manifest) ||
+    manifest["name"] !== name ||
+    manifest["version"] !== NATIVE_ARTIFACT_VERSION
+  )
+    throw new Error(
+      "Installed native PDF package version does not match Research.",
+    );
+  const artifact = parseJson(await readFile(resolve(root, "artifact.json")), {
+    maxBytes: 65536,
+    maxDepth: 8,
+    maxNodes: 512,
+  });
+  if (
+    !isPlainObject(artifact) ||
+    artifact["schemaVersion"] !== 1 ||
+    artifact["inputSchemaVersion"] !== 1 ||
+    artifact["compilerVersion"] !== NATIVE_ARTIFACT_VERSION ||
+    artifact["platform"] !== process.platform ||
+    artifact["architecture"] !== process.arch ||
+    !isPlainObject(artifact["files"])
+  )
+    throw new Error("Native artifact metadata is invalid or incompatible.");
+  const executable =
+    process.platform === "win32" ? "bin/publisle-pdf.exe" : "bin/publisle-pdf";
+  const paths = Object.keys(artifact["files"]);
+  if (
+    !paths.includes(executable) ||
+    !paths.includes("fonts.json") ||
+    paths.length > 64
+  )
+    throw new Error("Native artifact inventory is incomplete.");
+  const base = await realpath(root);
+  for (const [file, digest] of Object.entries(artifact["files"])) {
+    if (
+      typeof digest !== "string" ||
+      !/^[a-f0-9]{64}$/u.test(digest) ||
+      isAbsolute(file) ||
+      file.split(/[\\/]/u).includes("..")
+    )
+      throw new Error("Invalid native artifact path or checksum.");
+    const path = await realpath(resolve(base, file));
+    const local = relative(base, path);
+    if (
+      isAbsolute(local) ||
+      local === ".." ||
+      local.startsWith(`..${sep}`) ||
+      !(await stat(path)).isFile()
+    )
+      throw new Error("Native artifact escapes its package.");
+    const bytes = await readFile(path);
+    if (createHash("sha256").update(bytes).digest("hex") !== digest)
+      throw new Error(`Native artifact checksum mismatch: ${file}`);
+  }
+  return {
+    executable: resolve(base, executable),
+    fontManifest: resolve(base, "fonts.json"),
+    compilerVersion: NATIVE_ARTIFACT_VERSION,
+  };
+}

package/src/native-node.ts

@@ -0,0 +1,236 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import {
+  mkdtemp,
+  readFile,
+  realpath,
+  rm,
+  stat,
+  writeFile,
+} from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import {
+  parseJson,
+  isPlainObject,
+  type Block,
+  type BlockType,
+  type Document,
+} from "@publisle/schema";
+import {
+  createNativePdfPackage,
+  type NativeFont,
+  type NativePdfOptions,
+} from "./native.ts";
+import { projectArticle, type ResearchLoss } from "./article.ts";
+
+import { installedNativeCompiler } from "./native-install.ts";
+const execute = promisify(execFile);
+export interface NativeCompileOptions extends Omit<
+  NativePdfOptions,
+  "fonts" | "assets"
+> {
+  readonly sourceDirectory: string;
+  readonly fonts?: readonly NativeFont[];
+  readonly executable?: string;
+  readonly fontManifest?: string;
+  readonly timeoutMs?: number;
+  readonly signal?: AbortSignal;
+}
+export interface NativeCompilerDiagnostic extends ResearchLoss {
+  readonly blockId?: string;
+}
+export interface NativeCompileResult {
+  readonly pdf: Uint8Array;
+  readonly diagnostics: readonly NativeCompilerDiagnostic[];
+  readonly timings: Readonly<Record<string, number>>;
+  readonly pages: number;
+  readonly compilerVersion: string;
+}
+
+/** Explicit native compiler invocation. Automatic selection remains gated on parity. */
+export async function compileNativePdf(
+  document: Document<Block<BlockType, unknown>>,
+  options: NativeCompileOptions,
+): Promise<NativeCompileResult> {
+  const timeout = options.timeoutMs ?? 180_000;
+  if (!Number.isSafeInteger(timeout) || timeout <= 0)
+    throw new Error("Compilation timeout must be a positive integer.");
+  const explicitExecutable =
+    options.executable ?? process.env["PUBLISLE_NATIVE_COMPILER"];
+  const explicitManifest =
+    options.fontManifest ?? process.env["PUBLISLE_NATIVE_FONTS"];
+  const installed =
+    !explicitExecutable || (!options.fonts && !explicitManifest)
+      ? await installedNativeCompiler()
+      : undefined;
+  const executable = explicitExecutable ?? installed?.executable;
+  if (!executable) throw new Error("A pinned native PDF compiler is required.");
+  let fonts = options.fonts;
+  if (!fonts) {
+    const manifest = explicitManifest ?? installed?.fontManifest;
+    if (!manifest)
+      throw new Error(
+        "Set PUBLISLE_NATIVE_FONTS to the pinned font manifest JSON file.",
+      );
+    const bytes = await readFile(manifest);
+    const raw = parseJson(bytes, {
+      maxBytes: 65536,
+      maxDepth: 8,
+      maxNodes: 256,
+    });
+    if (!Array.isArray(raw))
+      throw new Error("Native font manifest must be an array.");
+    fonts = raw.map((entry: unknown) => {
+      if (
+        !isPlainObject(entry) ||
+        typeof entry["path"] !== "string" ||
+        !["regular", "bold", "italic", "mono", "fallback"].includes(
+          String(entry["role"]),
+        ) ||
+        (entry["index"] !== undefined &&
+          (!Number.isSafeInteger(entry["index"]) || Number(entry["index"]) < 0))
+      )
+        throw new Error("Invalid native font manifest entry.");
+      return {
+        path: resolve(dirname(manifest), entry["path"]),
+        role: entry["role"] as NativeFont["role"],
+        ...(entry["index"] === undefined
+          ? {}
+          : { index: Number(entry["index"]) }),
+      };
+    });
+  }
+  const base = await realpath(options.sourceDirectory);
+  const assets = await Promise.all(
+    [
+      ...new Set(
+        projectArticle(document).blocks.flatMap((block) =>
+          block.kind === "figure" ? [block.src] : [],
+        ),
+      ),
+    ].map(async (source) => {
+      if (/^[a-z][a-z0-9+.-]*:/iu.test(source))
+        throw new Error("Native CLI figures must be validated local files.");
+      const path = await realpath(resolve(base, source));
+      const local = relative(base, path);
+      if (isAbsolute(local) || local === ".." || local.startsWith(`..${sep}`))
+        throw new Error(`Figure asset escapes manuscript directory: ${source}`);
+      if ((await stat(path)).size > 16 * 1024 * 1024)
+        throw new Error(`Figure asset exceeds 16 MiB: ${source}`);
+      return { source, path };
+    }),
+  );
+  const source = createNativePdfPackage(document, {
+    ...options,
+    fonts,
+    assets,
+  });
+  const directory = await mkdtemp(join(tmpdir(), "publisle-native-"));
+  try {
+    const input = join(directory, "input.json");
+    const output = join(directory, "manuscript.pdf");
+    await writeFile(input, JSON.stringify(source.input), { flag: "wx" });
+    let stdout: string;
+    try {
+      stdout = (
+        await execute(executable, [input, output], {
+          timeout,
+          signal: options.signal,
+          maxBuffer: 65536,
+        })
+      ).stdout;
+    } catch (cause) {
+      const stdout =
+        cause && typeof cause === "object" && "stdout" in cause
+          ? String(cause.stdout)
+          : "";
+      let message = "Native PDF compilation failed.";
+      try {
+        const error = JSON.parse(stdout) as {
+          diagnostics?: {
+            code: string;
+            message: string;
+            blockIndex?: number;
+          }[];
+        };
+        const detail = error.diagnostics
+          ?.map(
+            (entry) =>
+              `${entry.code}${entry.blockIndex === undefined ? "" : ` (${source.blockIds[entry.blockIndex] ?? "unknown block"})`}: ${entry.message}`,
+          )
+          .join("\n");
+        if (detail) message = detail;
+      } catch {
+        /* Preserve the bounded process failure when no structured result exists. */
+      }
+      throw new Error(message, { cause });
+    }
+    const report = JSON.parse(stdout) as {
+      ok?: boolean;
+      compilerVersion?: string;
+      pages?: number;
+      diagnostics?: unknown;
+      timings?: unknown;
+    };
+    if (
+      report.ok !== true ||
+      typeof report.pages !== "number" ||
+      !Number.isSafeInteger(report.pages) ||
+      report.pages < 1 ||
+      report.pages > 300 ||
+      typeof report.compilerVersion !== "string" ||
+      report.compilerVersion.length === 0 ||
+      report.compilerVersion.length > 64 ||
+      (installed !== undefined &&
+        report.compilerVersion !== installed.compilerVersion) ||
+      (report.diagnostics !== undefined &&
+        (!Array.isArray(report.diagnostics) ||
+          report.diagnostics.length > 100 ||
+          report.diagnostics.some(
+            (entry) =>
+              !isPlainObject(entry) ||
+              typeof entry["code"] !== "string" ||
+              typeof entry["message"] !== "string",
+          ))) ||
+      (report.timings !== undefined &&
+        (!isPlainObject(report.timings) ||
+          Object.values(report.timings).some(
+            (value) =>
+              typeof value !== "number" || !Number.isFinite(value) || value < 0,
+          )))
+    )
+      throw new Error("Invalid native compiler report.");
+    const outputInfo = await stat(output);
+    if (outputInfo.size > 16 * 1024 * 1024)
+      throw new Error("Native PDF exceeds 16 MiB.");
+    const pdf = new Uint8Array(await readFile(output));
+    if (new TextDecoder().decode(pdf.subarray(0, 5)) !== "%PDF-")
+      throw new Error("Native compiler returned an invalid PDF.");
+    const expectedHeader =
+      source.input.pdfStandard === "ua-1"
+        ? "%PDF-1.7"
+        : source.input.pdfStandard === "ua-2"
+          ? "%PDF-2.0"
+          : undefined;
+    if (
+      expectedHeader &&
+      new TextDecoder().decode(pdf.subarray(0, 8)) !== expectedHeader
+    )
+      throw new Error(
+        "Native compiler returned the wrong PDF version for the requested standard.",
+      );
+    return {
+      pdf,
+      diagnostics: [
+        ...source.diagnostics,
+        ...((report.diagnostics ?? []) as ResearchLoss[]),
+      ],
+      timings: (report.timings ?? {}) as Record<string, number>,
+      pages: report.pages,
+      compilerVersion: report.compilerVersion,
+    };
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+}

package/src/native.ts

@@ -0,0 +1,184 @@
+import {
+  isPlainObject,
+  type Block,
+  type BlockType,
+  type Document,
+} from "@publisle/schema";
+import { citationClusters, projectArticle } from "./article.ts";
+import { resolveDocument, type ResolvedDocument } from "./resolve.ts";
+import type { ArticleBlock, ArticleInline } from "./article.ts";
+
+export const NATIVE_PDF_INPUT_VERSION = 1 as const;
+export const NATIVE_PDF_TEMPLATES = [
+  "article",
+  "article-arabic",
+  "ieee-journal",
+  "acm-journal",
+  "springer-journal",
+  "elsevier-numeric",
+  "elsevier-author-date",
+] as const;
+export type NativePdfTemplate = (typeof NATIVE_PDF_TEMPLATES)[number];
+export interface NativeFont {
+  readonly path: string;
+  readonly role: "regular" | "bold" | "italic" | "mono" | "fallback";
+  readonly index?: number;
+}
+export interface NativePdfInput {
+  readonly schemaVersion: typeof NATIVE_PDF_INPUT_VERSION;
+  readonly template: NativePdfTemplate;
+  readonly templateVersion: string;
+  readonly pdfStandard: "ua-1" | "ua-2" | null;
+  readonly article: ResolvedDocument["article"] & { readonly title: string };
+  readonly citations: readonly string[];
+  readonly bibliography: ResolvedDocument["bibliography"];
+  readonly assets: readonly {
+    readonly source: string;
+    readonly path: string;
+  }[];
+  readonly fonts: readonly NativeFont[];
+  readonly templateData: { readonly country?: string };
+}
+export interface NativePdfOptions {
+  readonly template?: NativePdfTemplate;
+  readonly style?: string;
+  readonly pdfUa?: "ua-1" | "ua-2" | false;
+  readonly fonts: readonly NativeFont[];
+  readonly assets?: NativePdfInput["assets"];
+  readonly data?: { readonly country?: string };
+}
+export interface NativePdfPackage {
+  readonly input: NativePdfInput;
+  /** Maps bounded compiler block indices back to authored source IDs. */
+  readonly blockIds: readonly string[];
+  readonly diagnostics: ResolvedDocument["losses"];
+}
+
+/** Pure lowering shared by the website worker and Research CLI. No filesystem or network access. */
+export function createNativePdfPackage(
+  document: Document<Block<BlockType, unknown>>,
+  options: NativePdfOptions,
+): NativePdfPackage {
+  const template = options.template ?? "article";
+  if (!NATIVE_PDF_TEMPLATES.includes(template))
+    throw new Error(`Unsupported native PDF template: ${template}`);
+  const resolved = resolveDocument(
+    document,
+    options.style ??
+      (template === "elsevier-author-date" ? "author-date" : "numeric"),
+  );
+  if (resolved.unresolved.length)
+    throw new Error(`Unresolved citations: ${resolved.unresolved.join(", ")}`);
+  if (
+    ["ieee-journal", "springer-journal"].includes(template) &&
+    resolved.form !== "numeric"
+  )
+    throw new Error("This journal profile requires numeric citations.");
+  if (template === "elsevier-author-date" && resolved.form !== "author-date")
+    throw new Error("This journal profile requires author-date citations.");
+  if (
+    options.data !== undefined &&
+    (!isPlainObject(options.data) ||
+      Object.keys(options.data).some((key) => key !== "country") ||
+      (options.data.country !== undefined &&
+        (typeof options.data.country !== "string" ||
+          options.data.country.length > 100)))
+  )
+    throw new Error("Unsupported native template metadata.");
+  if (
+    template === "acm-journal" &&
+    resolved.article.authorDetails?.some((author) => author.affiliation) &&
+    !options.data?.country?.trim()
+  )
+    throw new Error("ACM affiliations require template data: country.");
+  if (!resolved.article.title?.trim() || !resolved.article.authors.length)
+    throw new Error("PDF export requires a title and at least one author.");
+  if (options.fonts.length === 0 || options.fonts.length > 16)
+    throw new Error("Native PDF export requires one to sixteen pinned fonts.");
+  const article = structuredClone(resolved.article);
+  // CSL resolves cited footnotes at their first reference, rather than at the
+  // definition's physical position. Bind results before the native layout runs.
+  const notes = new Map(
+    article.blocks
+      .filter((block) => block.kind === "footnote")
+      .map((block) => [block.id, block]),
+  );
+  const visited = new Set<string>();
+  let cursor = 0;
+  const bind = (inlines: readonly ArticleInline[]): void => {
+    for (const inline of inlines) {
+      if (inline.type === "citation") {
+        const value = resolved.citations[cursor++];
+        if (value === undefined)
+          throw new Error(
+            "Resolved citation count does not match the article.",
+          );
+        Object.assign(inline, { text: value });
+      } else if (
+        inline.type === "text" &&
+        inline.reference?.kind === "footnote" &&
+        !visited.has(inline.reference.target)
+      ) {
+        visited.add(inline.reference.target);
+        notes.get(inline.reference.target)?.paragraphs.forEach(bind);
+      }
+    }
+  };
+  for (const block of article.blocks) visitInlines(block, bind);
+  if (cursor !== resolved.citations.length)
+    throw new Error("Resolved citation count does not match the article.");
+  // Each projection may emit multiple printable blocks (for example callouts).
+  const blockIds = document.blocks.flatMap((block) =>
+    projectArticle({ ...document, blocks: [block] }).blocks.map(() => block.id),
+  );
+  if (blockIds.length !== article.blocks.length)
+    throw new Error("Native projection source mapping is inconsistent.");
+  const clusters = citationClusters(resolved.article);
+  if (clusters.length !== resolved.citations.length)
+    throw new Error("Resolved citation clusters are inconsistent.");
+  return {
+    input: {
+      schemaVersion: NATIVE_PDF_INPUT_VERSION,
+      template,
+      templateVersion: "0.1.0-experimental",
+      pdfStandard: options.pdfUa === false ? null : (options.pdfUa ?? "ua-2"),
+      article: { ...article, title: resolved.article.title },
+      citations: resolved.citations,
+      bibliography: resolved.bibliography,
+      assets: options.assets ?? [],
+      fonts: options.fonts,
+      templateData: options.data ?? {},
+    },
+    blockIds,
+    diagnostics: resolved.losses,
+  };
+}
+
+function visitInlines(
+  block: ArticleBlock,
+  visit: (inlines: readonly ArticleInline[]) => void,
+): void {
+  switch (block.kind) {
+    case "heading":
+    case "paragraph":
+      visit(block.inlines);
+      break;
+    case "list":
+      block.items.forEach(visit);
+      break;
+    case "quote":
+      block.paragraphs.forEach(visit);
+      break;
+    case "figure":
+      visit(block.caption);
+      break;
+    case "table":
+      if (block.caption) visit(block.caption);
+      block.rows.forEach((row) => {
+        row.forEach(visit);
+      });
+      break;
+    default:
+      break;
+  }
+}