@pterodoc/core 0.2.0

package/src/target/target.ts

@@ -0,0 +1,146 @@
+/**
+ * What a publishing target has to be able to do.
+ *
+ * WordPress is the only implementation today, but keeping the contract
+ * explicit is what stops target vocabulary leaking into the renderer and the
+ * reconciler.
+ */
+
+/** What a target can and cannot do. */
+export interface TargetCapabilities {
+  /** Page ids must exist before bodies can be rendered, as WordPress's page list needs. */
+  needsIdsBeforeRender: boolean;
+  /** Files can be uploaded and referenced. */
+  supportsMedia: boolean;
+  /** Pages with no source can be removed. */
+  supportsPrune: boolean;
+  /** Pages nest; a flat target gets its whole path as one name. */
+  supportsHierarchy: boolean;
+  /** There is a separate summary field. */
+  supportsExcerpt: boolean;
+  /** Arbitrary key/value metadata can be written. */
+  supportsMeta: boolean;
+  /** A page can be given a template. */
+  supportsTemplates: boolean;
+  /** A page can be created unpublished. */
+  supportsDrafts: boolean;
+}
+
+/** A page as it exists on the target. */
+export interface RemotePage {
+  id: number;
+  parent: number;
+  slug: string;
+  status: string;
+  link: string;
+  title: string;
+  content?: string;
+  excerpt?: string;
+  menuOrder: number;
+  template: string;
+  meta?: Record<string, unknown> | undefined;
+}
+
+/** A page as pterodoc would publish it. */
+export interface RenderedPage {
+  /** Path within the published tree. */
+  path: string;
+  /** Slug of the last path segment. */
+  slug: string;
+  /** Page title. */
+  title: string;
+  /** The composed body. */
+  content: string;
+  /** Short summary. */
+  excerpt: string;
+  /** Position among siblings. */
+  menuOrder: number;
+  /** Metadata to write, when the target supports it. */
+  meta: Record<string, string>;
+  /** Source file, for messages. */
+  file?: string | undefined;
+  /** Version this page belongs to. */
+  versionName?: string | undefined;
+}
+
+/** A file to upload. */
+export interface MediaUpload {
+  bytes: Uint8Array;
+  filename: string;
+  hash: string;
+  mime: string;
+  alt: string;
+  title: string;
+}
+
+/** An uploaded file. */
+export interface MediaRef {
+  id: number;
+  hash: string;
+  url: string;
+  filename: string;
+  mime: string;
+}
+
+/** Asking the target to make sure a page exists. */
+export interface EnsureRequest {
+  path: string;
+  slug: string;
+  parentId: number | null;
+  title: string;
+  menuOrder: number;
+  isRoot: boolean;
+}
+
+/** What came of that. */
+export interface EnsureResult {
+  id: number | null;
+  created: boolean;
+  warnings: string[];
+}
+
+/** An open connection to a target. */
+export interface TargetSession {
+  /** Every page under the target's namespace, fetched once. */
+  loadIndex(): Promise<RemotePage[]>;
+  /**
+   * Make sure everything above the documentation root exists.
+   *
+   * The target owns this because only it knows what a path is made of. Pages
+   * it has to create are reported so the plan can show them; pages that were
+   * already there are never touched.
+   */
+  ensureRootParent(): Promise<{ id: number | null; created: { path: string; id: number | null }[] }>;
+  /** Make sure a page exists at this position, and give back its id. */
+  ensurePage(request: EnsureRequest): Promise<EnsureResult>;
+  /** Fetch a page with the fields needed to compare it. */
+  fetchPage(id: number): Promise<RemotePage>;
+  /** Which fields of an existing page differ from the rendered one. */
+  diffPage(remote: RemotePage, rendered: RenderedPage, parentId: number): string[];
+  /** Write a rendered page, returning warnings for anything the target refused. */
+  writePage(id: number, page: RenderedPage, parentId: number): Promise<{ warnings: string[] }>;
+  /** Pages below a root that no rendered page accounts for, deepest first. */
+  computePrune(index: RemotePage[], rootId: number, keepIds: Set<number>): RemotePage[];
+  /** Remove a page. Never a permanent delete. */
+  removePage(page: RemotePage): Promise<void>;
+  /** Files already uploaded, by content hash. */
+  loadMediaIndex(): Promise<Map<string, MediaRef>>;
+  /** Upload one file. */
+  uploadMedia(upload: MediaUpload): Promise<MediaRef>;
+  /** How many requests this session has made. */
+  requestCount(): number;
+}
+
+/** A place documentation can be published. */
+export interface Target {
+  /** Name used in messages and in the plan. */
+  readonly name: string;
+  /** What this target can do. */
+  readonly capabilities: TargetCapabilities;
+  /** Absolute site path for a tree path: the target owns URL policy. */
+  hrefFor(treePath: string, context: { versionName: string; locale: string }): string;
+  /** The path pages are published under, for messages. */
+  readonly rootPath: string;
+  /** Open a session. */
+  open(context: { locale: string; dryRun: boolean }): Promise<TargetSession>;
+}

package/src/util/hash.ts

@@ -0,0 +1,14 @@
+/** Content hashing, used to give an uploaded asset a stable identity. */
+
+import { createHash } from 'node:crypto';
+
+/**
+ * A short content hash.
+ *
+ * Sixteen hex characters of SHA-256: long enough that a collision across one
+ * site's assets is not a practical concern, short enough to sit inside a
+ * WordPress slug without dominating it.
+ */
+export function contentHash(bytes: Uint8Array | string): string {
+  return createHash('sha256').update(bytes).digest('hex').slice(0, 16);
+}

package/src/util/index.ts

@@ -0,0 +1,23 @@
+/**
+ * Shared helpers with no domain knowledge, and the errors every layer throws.
+ *
+ * Nothing here imports another layer, which is what makes it safe for all of
+ * them to import it.
+ */
+
+export { EXIT, PterodocError, ConfigError, TargetError, UnsupportedContentError } from '../errors';
+export { VERSION, USER_AGENT } from '../version';
+export { contentHash } from './hash';
+export { compareSeverity, formatIssue, IssueCollector } from './issues';
+export type { Issue, Severity } from './issues';
+export { mimeTypeFor, isBlockedByDefault } from './mime';
+export {
+  joinPath,
+  relativeToPrefix,
+  resolveAliasedPath,
+  segments,
+  slugify,
+  titleCase,
+  toPosix,
+  toSlugSegments,
+} from './paths';

package/src/util/issues.ts

@@ -0,0 +1,86 @@
+/**
+ * Structured diagnostics.
+ *
+ * Everything a run wants to tell the user goes through here rather than into
+ * free-form strings, so the CLI can group them, `--json` can emit them, and
+ * `--strict` can decide whether they should fail the run.
+ */
+
+/** How much a reader should care. */
+export type Severity = 'info' | 'warning' | 'error';
+
+const ORDER: Record<Severity, number> = { info: 0, warning: 1, error: 2 };
+
+/** One thing worth telling the user about. */
+export interface Issue {
+  /** Stable identifier, e.g. `mdx-unknown-component`. Never localised. */
+  code: string;
+  /** How much a reader should care. */
+  severity: Severity;
+  /** One sentence, in English, naming what happened. */
+  message: string;
+  /** Source file the issue came from, relative to the site directory. */
+  file?: string | undefined;
+  /** One-based line within `file`. */
+  line?: number | undefined;
+  /** One-based column within `line`. */
+  column?: number | undefined;
+  /** Document id, when the issue belongs to a document. */
+  docId?: string | undefined;
+  /** Page path within the target tree, when the issue belongs to a page. */
+  path?: string | undefined;
+}
+
+/** Accumulates issues during a run. */
+export class IssueCollector {
+  readonly issues: Issue[] = [];
+
+  /** Record an issue. */
+  add(issue: Issue): void {
+    this.issues.push(issue);
+  }
+
+  /** Record an issue that inherits a document's file and id. */
+  addFor(
+    doc: { id: string; sourceRelativePath?: string } | undefined,
+    issue: Omit<Issue, 'docId' | 'file'> & { file?: string },
+  ): void {
+    this.add({
+      ...issue,
+      docId: doc?.id,
+      file: issue.file ?? doc?.sourceRelativePath,
+    });
+  }
+
+  /** True when any issue is at least as severe as `severity`. */
+  hasAtLeast(severity: Severity): boolean {
+    return this.issues.some((issue) => ORDER[issue.severity] >= ORDER[severity]);
+  }
+
+  /** Issues at least as severe as `severity`. */
+  atLeast(severity: Severity): Issue[] {
+    return this.issues.filter((issue) => ORDER[issue.severity] >= ORDER[severity]);
+  }
+
+  /** How many issues carry each code, for a compact summary. */
+  countByCode(): Record<string, number> {
+    const counts: Record<string, number> = {};
+    for (const issue of this.issues) counts[issue.code] = (counts[issue.code] ?? 0) + 1;
+    return counts;
+  }
+}
+
+/** Compare two severities; positive when `a` is more severe than `b`. */
+export function compareSeverity(a: Severity, b: Severity): number {
+  return ORDER[a] - ORDER[b];
+}
+
+/** Render an issue as one line, with its position when it has one. */
+export function formatIssue(issue: Issue): string {
+  const where = issue.file
+    ? `${issue.file}${issue.line ? `:${issue.line}${issue.column ? `:${issue.column}` : ''}` : ''}: `
+    : issue.path
+      ? `${issue.path || '(root)'}: `
+      : '';
+  return `${where}${issue.message}`;
+}

package/src/util/mime.ts

@@ -0,0 +1,47 @@
+/**
+ * Extension to media type.
+ *
+ * A twenty-entry table rather than a dependency: these are the types a
+ * documentation site actually embeds, and WordPress rejects most others.
+ */
+
+const TYPES: Record<string, string> = {
+  '.apng': 'image/apng',
+  '.avif': 'image/avif',
+  '.bmp': 'image/bmp',
+  '.gif': 'image/gif',
+  '.ico': 'image/x-icon',
+  '.jpeg': 'image/jpeg',
+  '.jpg': 'image/jpeg',
+  '.png': 'image/png',
+  '.svg': 'image/svg+xml',
+  '.tif': 'image/tiff',
+  '.tiff': 'image/tiff',
+  '.webp': 'image/webp',
+  '.mp4': 'video/mp4',
+  '.webm': 'video/webm',
+  '.ogv': 'video/ogg',
+  '.mp3': 'audio/mpeg',
+  '.wav': 'audio/wav',
+  '.pdf': 'application/pdf',
+  '.zip': 'application/zip',
+  '.json': 'application/json',
+  '.txt': 'text/plain',
+};
+
+/** The media type for a file name, or undefined when we do not recognise it. */
+export function mimeTypeFor(fileName: string): string | undefined {
+  const dot = fileName.lastIndexOf('.');
+  if (dot === -1) return undefined;
+  return TYPES[fileName.slice(dot).toLowerCase()];
+}
+
+/**
+ * True for types WordPress refuses by default.
+ *
+ * SVG is the one that surprises people: it is blocked unless a plugin allows
+ * it, because an SVG can carry script.
+ */
+export function isBlockedByDefault(mime: string): boolean {
+  return mime === 'image/svg+xml';
+}

package/src/util/paths.ts

@@ -0,0 +1,101 @@
+/**
+ * Path helpers shared by the source reader and the targets.
+ *
+ * Everything here is POSIX-shaped: a documentation tree is addressed by URL
+ * paths, not by the host's separators.
+ */
+
+import path from 'node:path';
+import { ConfigError } from '../errors';
+
+/** Prefix Docusaurus uses for paths relative to the site directory. */
+const SITE_ALIAS = '@site/';
+
+/**
+ * Resolve a Docusaurus `@site/...` path to an absolute one.
+ *
+ * @param aliased The path as Docusaurus records it, e.g. `@site/docs/intro.md`.
+ * @param siteDir Absolute path of the Docusaurus site directory.
+ */
+export function resolveAliasedPath(aliased: string, siteDir: string): string {
+  if (!aliased.startsWith(SITE_ALIAS)) {
+    throw new ConfigError(
+      `Expected a "@site/"-relative path from Docusaurus but got "${aliased}". This usually means an unsupported Docusaurus version.`,
+    );
+  }
+  return path.resolve(siteDir, aliased.slice(SITE_ALIAS.length));
+}
+
+/** Turn a host path into the POSIX form used for ids and messages. */
+export function toPosix(value: string): string {
+  return value.split(path.sep).join('/');
+}
+
+/** Split a URL-ish path into its non-empty segments. */
+export function segments(value: string): string[] {
+  return value.split('/').filter(Boolean);
+}
+
+/**
+ * Split a configured path into slug segments, rejecting anything WordPress
+ * would not accept as a page slug.
+ *
+ * @param value A path such as `/products/docstack`.
+ * @param label The setting's name, used in the error message.
+ */
+export function toSlugSegments(value: string, label: string): string[] {
+  const parts = segments(String(value ?? '').trim());
+  for (const part of parts) {
+    if (!/^[a-z0-9]+(?:[-_][a-z0-9]+)*$/.test(part)) {
+      throw new ConfigError(
+        `${label} segment "${part}" is not a slug. Use lowercase letters, digits, hyphens and underscores.`,
+      );
+    }
+  }
+  return parts;
+}
+
+/**
+ * Make a slug out of arbitrary text, for path segments we derive ourselves
+ * (a version name, for instance) rather than receive from Docusaurus.
+ */
+export function slugify(value: string): string {
+  return String(value)
+    .normalize('NFKD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '') || 'untitled';
+}
+
+/** Title-case a slug, for a page that has no better label available. */
+export function titleCase(slug: string): string {
+  return segments(slug.replace(/[-_]/g, ' ').replace(/\s+/g, ' '))
+    .join(' ')
+    .split(' ')
+    .filter(Boolean)
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(' ');
+}
+
+/**
+ * The path a URL points at below a prefix.
+ *
+ * Returns undefined when `url` is not under `prefix`, which is how the link
+ * resolver decides whether a link belongs to the documentation at all.
+ */
+export function relativeToPrefix(url: string, prefix: string): string | undefined {
+  const normalisedPrefix = `/${segments(prefix).join('/')}`;
+  const normalisedUrl = `/${segments(url).join('/')}`;
+  if (normalisedPrefix === '/') return segments(normalisedUrl).join('/');
+  if (normalisedUrl === normalisedPrefix) return '';
+  if (!normalisedUrl.startsWith(`${normalisedPrefix}/`)) return undefined;
+  return normalisedUrl.slice(normalisedPrefix.length + 1);
+}
+
+/** Join path segments into an absolute URL path with a trailing slash. */
+export function joinPath(parts: string[], trailingSlash = true): string {
+  const joined = parts.flatMap((part) => segments(part)).join('/');
+  if (joined === '') return '/';
+  return trailingSlash ? `/${joined}/` : `/${joined}`;
+}

package/src/version.ts

@@ -0,0 +1,31 @@
+/** The tool's own version, stamped into the build. */
+
+import fs from 'node:fs';
+
+/**
+ * Read the version.
+ *
+ * The build replaces the token, so a built artefact never touches the disk and
+ * does not care how deeply it is nested. Running from source — tsx, the test
+ * suite, an editor — there is no token, and the manifest sits exactly one
+ * directory above this file.
+ *
+ * `typeof` on an undeclared identifier is the one expression that does not
+ * throw, so the ambient declaration costs nothing at runtime.
+ */
+function readVersion(): string {
+  if (typeof __PTERODOC_VERSION__ === 'string') return __PTERODOC_VERSION__;
+  try {
+    const manifest = new URL('../package.json', import.meta.url);
+    const parsed = JSON.parse(fs.readFileSync(manifest, 'utf8')) as { version?: string };
+    return parsed.version ?? '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+}
+
+/** Semantic version of this package. */
+export const VERSION = readVersion();
+
+/** The User-Agent every outbound request identifies itself with. */
+export const USER_AGENT = `pterodoc/${VERSION} (+https://github.com/onyx-ac/pterodoc)`;