@open-press/core 0.3.0

package/engine/react/comment-marker.mjs

@@ -0,0 +1,306 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { loadConfig } from "../config.mjs";
+import { collectSourceTextFiles } from "../source-text-tools.mjs";
+
+const EDITABLE_COMMENT_SOURCE_PATTERNS = [
+  /^document\/index\.tsx$/,
+  /^document\/chapters\/[^/]+\/content\/[^/]+\.mdx$/,
+  /^document\/chapters\/[^/]+\/chapter\.tsx$/,
+  /^document\/chapters\/[^/]+\/components\/.+\.tsx$/,
+  /^document\/components\/.+\.tsx$/,
+];
+const COMMENT_MARKER_RE = /\{\/\*\s*@openpress-comment\b(?<attrs>[^*]*)\*\/\}/g;
+const COMMENT_LINE_RE = /^\s*\{\/\*\s*@openpress-comment\b[^*]*\*\/\}\s*$/;
+
+export async function insertCommentMarker({
+  root = ".",
+  path: sourcePath,
+  source,
+  note,
+  hint,
+  id = createCommentId(),
+  timestamp = new Date().toISOString(),
+} = {}) {
+  const workspaceRoot = path.resolve(root);
+  const relativePath = normalizeEditableSourcePath(sourcePath);
+  assertEditableCommentPath(relativePath);
+  const absolutePath = path.resolve(workspaceRoot, relativePath);
+  if (!absolutePath.startsWith(`${workspaceRoot}${path.sep}`)) {
+    throw new Error(`OpenPress comment target path escapes workspace: ${sourcePath}`);
+  }
+
+  const noteText = normalizedNote(note);
+  const marker = createCommentMarker({ id, timestamp, note: noteText, hint });
+  const line = normalizeLineNumber(source?.line);
+  const text = await fs.readFile(absolutePath, "utf8");
+  const nextText = insertLineBefore(text, line, marker);
+  await fs.writeFile(absolutePath, nextText, "utf8");
+
+  return {
+    id,
+    timestamp,
+    marker,
+    path: relativePath,
+    absolutePath,
+    line,
+  };
+}
+
+export function createCommentMarker({ id = createCommentId(), timestamp = new Date().toISOString(), note, hint } = {}) {
+  const payload = { note: normalizedNote(note), ...(typeof hint === "string" && hint.trim() ? { hint: hint.trim() } : {}) };
+  return `{/* @openpress-comment id="${escapeMarkerAttribute(id)}" ts="${escapeMarkerAttribute(timestamp)}" text="${encodeCommentPayload(payload)}" */}`;
+}
+
+export function decodeCommentMarkerText(marker) {
+  const match = String(marker ?? "").match(/\btext="([^"]+)"/);
+  if (!match) return null;
+  return JSON.parse(Buffer.from(match[1], "base64url").toString("utf8"));
+}
+
+export async function listCommentMarkers({ root = "." } = {}) {
+  const config = await loadConfig(root);
+  const files = await collectSourceTextFiles(config, { scope: "all" });
+  const comments = [];
+
+  for (const file of files) {
+    if (!isEditableCommentPath(file.path ?? file.relativePath)) continue;
+    comments.push(...extractCommentMarkers(file));
+  }
+
+  comments.sort((a, b) => a.path.localeCompare(b.path) || a.line - b.line || a.id.localeCompare(b.id));
+  return comments;
+}
+
+export async function clearCommentMarkers({ root = ".", id = null, all = false } = {}) {
+  if (!all && !(typeof id === "string" && id.trim())) {
+    throw new Error("OpenPress comment clear requires an `id` or `all: true`.");
+  }
+
+  const config = await loadConfig(root);
+  const files = await collectSourceTextFiles(config, { scope: "all" });
+  const removed = [];
+
+  for (const file of files) {
+    if (!isEditableCommentPath(file.path ?? file.relativePath)) continue;
+    const next = removeCommentMarkerLines(file.text, { id, all });
+    if (next.removed.length === 0) continue;
+    await fs.writeFile(file.absolutePath, next.text, "utf8");
+    for (const marker of next.removed) {
+      removed.push({
+        ...marker,
+        path: file.path ?? file.relativePath,
+        absolutePath: file.absolutePath,
+      });
+    }
+  }
+
+  return {
+    removedCount: removed.length,
+    comments: removed,
+  };
+}
+
+export async function updateCommentMarker({
+  root = ".",
+  id,
+  note,
+  hint,
+  timestamp = new Date().toISOString(),
+} = {}) {
+  if (!(typeof id === "string" && id.trim())) {
+    throw new Error("OpenPress comment update requires an `id`.");
+  }
+
+  const config = await loadConfig(root);
+  const files = await collectSourceTextFiles(config, { scope: "all" });
+  const noteText = normalizedNote(note);
+
+  for (const file of files) {
+    if (!isEditableCommentPath(file.path ?? file.relativePath)) continue;
+    const next = replaceCommentMarkerLine(file.text, { id, note: noteText, hint, timestamp });
+    if (!next.comment) continue;
+    await fs.writeFile(file.absolutePath, next.text, "utf8");
+    return {
+      ...next.comment,
+      path: file.path ?? file.relativePath,
+      absolutePath: file.absolutePath,
+    };
+  }
+
+  throw new Error(`OpenPress comment marker not found: ${id}`);
+}
+
+export function assertEditableCommentPath(relativePath) {
+  if (!isEditableCommentPath(relativePath)) {
+    throw new Error(`OpenPress comment target is not an editable OpenPress document source: ${relativePath}`);
+  }
+}
+
+export function isEditableCommentPath(relativePath) {
+  return EDITABLE_COMMENT_SOURCE_PATTERNS.some((pattern) => pattern.test(relativePath));
+}
+
+function normalizeEditableSourcePath(value) {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new Error("OpenPress comment target requires a source path.");
+  }
+  const normalized = value.trim().replaceAll("\\", "/").replace(/^\.\//, "");
+  if (path.posix.isAbsolute(normalized) || normalized.includes("\0") || normalized === "." || normalized.startsWith("../")) {
+    throw new Error(`OpenPress comment target path is invalid: ${value}`);
+  }
+  return path.posix.normalize(normalized);
+}
+
+function normalizeLineNumber(value) {
+  const line = Number(value);
+  if (!Number.isInteger(line) || line < 1) {
+    throw new Error("OpenPress comment target requires a 1-based source line.");
+  }
+  return line;
+}
+
+function normalizedNote(value) {
+  const note = typeof value === "string" ? value.trim() : "";
+  if (!note) throw new Error("OpenPress comment note must not be empty.");
+  return note;
+}
+
+function insertLineBefore(text, line, marker) {
+  const newline = text.includes("\r\n") ? "\r\n" : "\n";
+  const hasTrailingNewline = /\r?\n$/.test(text);
+  const lines = text.split(/\r?\n/);
+  if (hasTrailingNewline) lines.pop();
+  const index = Math.min(Math.max(line - 1, 0), lines.length);
+  lines.splice(index, 0, marker);
+  return `${lines.join(newline)}${hasTrailingNewline ? newline : ""}`;
+}
+
+function encodeCommentPayload(payload) {
+  return Buffer.from(JSON.stringify(payload), "utf8").toString("base64url");
+}
+
+function extractCommentMarkers(file) {
+  const comments = [];
+  const text = String(file.text ?? "");
+  const lineStarts = lineStartOffsets(text);
+  for (const match of text.matchAll(COMMENT_MARKER_RE)) {
+    const marker = match[0];
+    const attrs = parseMarkerAttributes(match.groups?.attrs ?? "");
+    const payload = decodeCommentMarkerText(marker) ?? {};
+    const line = lineNumberForOffset(lineStarts, match.index ?? 0);
+    comments.push({
+      id: attrs.id ?? "",
+      timestamp: attrs.ts,
+      path: file.path ?? file.relativePath,
+      absolutePath: file.absolutePath,
+      line,
+      marker,
+      note: typeof payload.note === "string" ? payload.note : "",
+      hint: typeof payload.hint === "string" ? payload.hint : undefined,
+    });
+  }
+  return comments;
+}
+
+function removeCommentMarkerLines(text, { id, all }) {
+  const newline = text.includes("\r\n") ? "\r\n" : "\n";
+  const hasTrailingNewline = /\r?\n$/.test(text);
+  const lines = text.split(/\r?\n/);
+  if (hasTrailingNewline) lines.pop();
+  const kept = [];
+  const removed = [];
+
+  for (const [index, line] of lines.entries()) {
+    if (!COMMENT_LINE_RE.test(line)) {
+      kept.push(line);
+      continue;
+    }
+    const attrs = parseMarkerAttributes(line);
+    if (all || attrs.id === id) {
+      removed.push({ id: attrs.id ?? "", timestamp: attrs.ts, line: index + 1, marker: line.trim() });
+      continue;
+    }
+    kept.push(line);
+  }
+
+  return {
+    text: `${kept.join(newline)}${hasTrailingNewline ? newline : ""}`,
+    removed,
+  };
+}
+
+function replaceCommentMarkerLine(text, { id, note, hint, timestamp }) {
+  const newline = text.includes("\r\n") ? "\r\n" : "\n";
+  const hasTrailingNewline = /\r?\n$/.test(text);
+  const lines = text.split(/\r?\n/);
+  if (hasTrailingNewline) lines.pop();
+
+  for (const [index, line] of lines.entries()) {
+    if (!COMMENT_LINE_RE.test(line)) continue;
+    const attrs = parseMarkerAttributes(line);
+    if (attrs.id !== id) continue;
+    const marker = createCommentMarker({ id, timestamp, note, hint });
+    lines[index] = `${line.match(/^\s*/)?.[0] ?? ""}${marker}`;
+    return {
+      text: `${lines.join(newline)}${hasTrailingNewline ? newline : ""}`,
+      comment: {
+        id,
+        timestamp,
+        line: index + 1,
+        marker,
+        note,
+        hint: typeof hint === "string" && hint.trim() ? hint.trim() : undefined,
+      },
+    };
+  }
+
+  return { text, comment: null };
+}
+
+function parseMarkerAttributes(value) {
+  const attrs = {};
+  for (const match of String(value ?? "").matchAll(/\b([A-Za-z_:][-A-Za-z0-9_:.]*)="([^"]*)"/g)) {
+    attrs[match[1]] = unescapeMarkerAttribute(match[2]);
+  }
+  return attrs;
+}
+
+function lineStartOffsets(text) {
+  const starts = [0];
+  for (let index = 0; index < text.length; index += 1) {
+    if (text[index] === "\n") starts.push(index + 1);
+  }
+  return starts;
+}
+
+function lineNumberForOffset(starts, offset) {
+  let line = 1;
+  for (const [index, start] of starts.entries()) {
+    if (start > offset) break;
+    line = index + 1;
+  }
+  return line;
+}
+
+function createCommentId() {
+  return `c-${crypto.randomBytes(4).toString("hex")}`;
+}
+
+function escapeMarkerAttribute(value) {
+  return String(value ?? "").replace(/["&<>]/g, (char) => ({
+    "\"": "&quot;",
+    "&": "&amp;",
+    "<": "&lt;",
+    ">": "&gt;",
+  }[char]));
+}
+
+function unescapeMarkerAttribute(value) {
+  return String(value ?? "")
+    .replace(/&quot;/g, "\"")
+    .replace(/&amp;/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">");
+}

package/engine/react/document-entry.mjs

@@ -0,0 +1,253 @@
+import fs from "node:fs/promises";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import react from "@vitejs/plugin-react";
+import ts from "typescript";
+import { createServer as createViteServer } from "vite";
+import { normalizeConfig } from "../config.mjs";
+
+const ENGINE_REACT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const FRAMEWORK_ROOT = path.resolve(ENGINE_REACT_DIR, "..", "..");
+const CORE_ENTRY = path.join(FRAMEWORK_ROOT, "src", "openpress", "core", "index.tsx");
+const REACT_PACKAGE_ROOT = path.join(FRAMEWORK_ROOT, "node_modules", "react");
+const require = createRequire(import.meta.url);
+const REACT_EXPORT_NAMES = Object.keys(require("react")).filter((name) => /^[A-Za-z_$][\w$]*$/.test(name));
+
+export async function loadReactDocumentEntry(root = ".") {
+  const workspaceRoot = path.resolve(root);
+  const entryPath = path.join(workspaceRoot, "document", "index.tsx");
+  if (!(await fileExists(entryPath))) return null;
+
+  const source = await fs.readFile(entryPath, "utf8");
+  assertNoObviousTopLevelSideEffects(source, entryPath);
+
+  const server = await createReactSsrServer(workspaceRoot);
+
+  try {
+    const mod = await server.ssrLoadModule(entryPath);
+    const config = normalizeReactDocumentConfig(workspaceRoot, entryPath, mod.config);
+    return {
+      entryPath,
+      config,
+      shell: {
+        cover: mod.cover ?? null,
+        toc: mod.toc ?? null,
+        backCover: mod.backCover ?? null,
+      },
+    };
+  } finally {
+    await server.close();
+  }
+}
+
+export async function createReactSsrServer(workspaceRoot = ".") {
+  const resolvedWorkspaceRoot = path.resolve(workspaceRoot);
+  return createViteServer({
+    configFile: false,
+    root: FRAMEWORK_ROOT,
+    appType: "custom",
+    logLevel: "silent",
+    plugins: [reactRuntimePlugin(), react()],
+    resolve: {
+      alias: [
+        { find: "@openpress/core", replacement: CORE_ENTRY },
+        { find: "@/components", replacement: path.join(resolvedWorkspaceRoot, "document", "components") },
+      ],
+    },
+    server: {
+      middlewareMode: true,
+      fs: {
+        allow: [FRAMEWORK_ROOT, resolvedWorkspaceRoot],
+      },
+    },
+  });
+}
+
+function normalizeReactDocumentConfig(workspaceRoot, entryPath, config) {
+  if (config != null && (typeof config !== "object" || Array.isArray(config))) {
+    throw new Error("OpenPress React document entry `config` export must be an object when provided.");
+  }
+  const rawConfig = config ?? {};
+  const paths = rawConfig.paths ?? {};
+  return normalizeConfig(workspaceRoot, {
+    ...rawConfig,
+    documentDir: rawConfig.documentDir ?? paths.documentDir ?? "document",
+    sourceDir: rawConfig.sourceDir ?? paths.chaptersDir ?? paths.sourceDir ?? "chapters",
+    componentsDir: rawConfig.componentsDir ?? paths.componentsDir ?? "components",
+    mediaDir: rawConfig.mediaDir ?? paths.mediaDir ?? "media",
+    themeDir: rawConfig.themeDir ?? paths.themeDir ?? "theme",
+    designDoc: rawConfig.designDoc ?? paths.designDoc ?? "design.md",
+  }, entryPath);
+}
+
+function assertNoObviousTopLevelSideEffects(source, entryPath) {
+  const sourceFile = ts.createSourceFile(entryPath, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+  for (const statement of sourceFile.statements) {
+    if (ts.isImportDeclaration(statement)) {
+      assertPureImport(statement, entryPath);
+      continue;
+    }
+
+    if (ts.isInterfaceDeclaration(statement) || ts.isTypeAliasDeclaration(statement)) {
+      continue;
+    }
+
+    if (ts.isExportDeclaration(statement) && statement.isTypeOnly) {
+      continue;
+    }
+
+    if (ts.isVariableStatement(statement)) {
+      assertExportedConstStatement(statement, entryPath);
+      continue;
+    }
+
+    if (ts.isExpressionStatement(statement)) {
+      assertPureTopLevelInitializer(statement.expression, entryPath);
+    }
+
+    throw new Error(`OpenPress React document entry has unsupported top-level code in ${entryPath}: ${statementKindName(statement)}`);
+  }
+}
+
+function assertPureImport(statement, entryPath) {
+  if (!statement.importClause) {
+    throw new Error(`OpenPress React document entry has an unsupported side-effect import in ${entryPath}`);
+  }
+  const moduleName = stringLiteralText(statement.moduleSpecifier);
+  if (!statement.importClause.isTypeOnly && isFileSystemModule(moduleName)) {
+    throw new Error(`OpenPress React document entry imports filesystem APIs at top level in ${entryPath}`);
+  }
+}
+
+function assertExportedConstStatement(statement, entryPath) {
+  if (!hasModifier(statement, ts.SyntaxKind.ExportKeyword)) {
+    throw new Error(`OpenPress React document entry only allows exported const declarations at top level in ${entryPath}`);
+  }
+  if ((statement.declarationList.flags & ts.NodeFlags.Const) === 0) {
+    throw new Error(`OpenPress React document entry only allows exported const declarations at top level in ${entryPath}`);
+  }
+
+  for (const declaration of statement.declarationList.declarations) {
+    if (declaration.initializer) assertPureTopLevelInitializer(declaration.initializer, entryPath);
+  }
+}
+
+function assertPureTopLevelInitializer(node, entryPath) {
+  visitNode(node, (child) => {
+    if (ts.isAwaitExpression(child)) {
+      throw new Error(`OpenPress React document entry has an unsupported top-level side effect: await in ${entryPath}`);
+    }
+
+    if (ts.isCallExpression(child)) {
+      const callee = skipExpressionWrappers(child.expression);
+      if (ts.isIdentifier(callee) && callee.text === "fetch") {
+        throw new Error(`OpenPress React document entry has an unsupported top-level side effect: fetch(...) in ${entryPath}`);
+      }
+      if (ts.isPropertyAccessExpression(callee) && isIdentifierText(callee.expression, "console")) {
+        throw new Error(`OpenPress React document entry has an unsupported top-level side effect: console.${callee.name.text}(...) in ${entryPath}`);
+      }
+      if (ts.isPropertyAccessExpression(callee) && isIdentifierText(callee.expression, "fs")) {
+        throw new Error(`OpenPress React document entry has an unsupported top-level side effect: fs.${callee.name.text}(...) in ${entryPath}`);
+      }
+      throw new Error(`OpenPress React document entry cannot execute top-level function calls in exported config or shell JSX in ${entryPath}`);
+    }
+
+    if (ts.isPropertyAccessExpression(child) && isProcessEnvAccess(child)) {
+      throw new Error(`OpenPress React document entry cannot read process.env in exported config or shell JSX in ${entryPath}`);
+    }
+  });
+}
+
+function visitNode(node, visitor) {
+  visitor(node);
+  ts.forEachChild(node, (child) => visitNode(child, visitor));
+}
+
+function skipExpressionWrappers(node) {
+  let current = node;
+  while (ts.isParenthesizedExpression(current) || ts.isAsExpression(current) || ts.isTypeAssertionExpression(current)) {
+    current = current.expression;
+  }
+  return current;
+}
+
+function isProcessEnvAccess(node) {
+  return node.name.text === "env" && isIdentifierText(skipExpressionWrappers(node.expression), "process");
+}
+
+function isIdentifierText(node, text) {
+  return ts.isIdentifier(node) && node.text === text;
+}
+
+function hasModifier(node, kind) {
+  return ts.canHaveModifiers(node) && (ts.getModifiers(node) ?? []).some((modifier) => modifier.kind === kind);
+}
+
+function statementKindName(node) {
+  return ts.SyntaxKind[node.kind] ?? String(node.kind);
+}
+
+function stringLiteralText(node) {
+  return ts.isStringLiteral(node) ? node.text : "";
+}
+
+function isFileSystemModule(moduleName) {
+  return moduleName === "fs" || moduleName === "node:fs" || moduleName === "fs/promises" || moduleName === "node:fs/promises";
+}
+
+async function fileExists(filePath) {
+  try {
+    const stat = await fs.stat(filePath);
+    return stat.isFile();
+  } catch (error) {
+    if (error?.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+function reactRuntimePlugin() {
+  const modules = {
+    react: "\0openpress-react",
+    "react/jsx-runtime": "\0openpress-react-jsx-runtime",
+    "react/jsx-dev-runtime": "\0openpress-react-jsx-dev-runtime",
+  };
+  return {
+    name: "openpress-react-runtime",
+    enforce: "pre",
+    resolveId(id) {
+      return modules[id] ?? null;
+    },
+    load(id) {
+      if (id === modules.react) return reactModuleShim();
+      if (id === modules["react/jsx-runtime"]) {
+        return runtimeModuleShim(path.join(REACT_PACKAGE_ROOT, "jsx-runtime.js"), ["Fragment", "jsx", "jsxs"]);
+      }
+      if (id === modules["react/jsx-dev-runtime"]) {
+        return runtimeModuleShim(path.join(REACT_PACKAGE_ROOT, "jsx-dev-runtime.js"), ["Fragment", "jsxDEV"]);
+      }
+      return null;
+    },
+  };
+}
+
+function runtimeModuleShim(modulePath, names) {
+  const exports = names.map((name) => `export const ${name} = runtime.${name};`).join("\n");
+  return `import { createRequire } from "node:module";
+const require = createRequire(${JSON.stringify(import.meta.url)});
+const runtime = require(${JSON.stringify(modulePath)});
+${exports}
+export default runtime;
+`;
+}
+
+function reactModuleShim() {
+  const reactPath = require.resolve("react");
+  const exports = REACT_EXPORT_NAMES.map((name) => `export const ${name} = React.${name};`).join("\n");
+  return `import { createRequire } from "node:module";
+const require = createRequire(${JSON.stringify(import.meta.url)});
+const React = require(${JSON.stringify(reactPath)});
+${exports}
+export default React;
+`;
+}