@chengxianglibra/dsh-data-analysis 0.1.1 → 0.2.0

package/lib/presentation/build/index.js

@@ -0,0 +1,72 @@
+// src/presentation/build/index.ts
+import { createHash } from "node:crypto";
+import {
+  PRESENTATION_BUDGETS,
+  PresentationContractError,
+  parsePresentationDocument
+} from "../contracts/index.js";
+var escapeHtml = (value) => value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&#39;");
+var inlineJson = (value) => JSON.stringify(value).replaceAll("<", "\\u003c").replaceAll("\u2028", "\\u2028").replaceAll("\u2029", "\\u2029");
+async function buildPresentation(value, options = { html: true }) {
+  parsePresentationDocument(value);
+  const documentBytes = Buffer.from(JSON.stringify(value), "utf8");
+  const document = parsePresentationDocument(JSON.parse(documentBytes.toString("utf8")));
+  if (!options.html) return { document, documentBytes };
+  const [portable, staticAssets] = await Promise.all([
+    import(new URL("../../../lib/presentation/assets/portable.js", import.meta.url).href),
+    import(new URL("../../../lib/presentation/assets/static.js", import.meta.url).href)
+  ]);
+  const fallback = staticAssets.renderFallback(document);
+  const script = portable.script.replace(/<\/script/gi, "<\\/script");
+  const scriptHash = createHash("sha256").update(script).digest("base64");
+  const csp = [
+    "default-src 'none'",
+    `script-src 'sha256-${scriptHash}' 'wasm-unsafe-eval'`,
+    "script-src-attr 'none'",
+    "style-src 'unsafe-inline'",
+    "connect-src 'none'",
+    "img-src 'none'",
+    "font-src 'none'",
+    "media-src 'none'",
+    "frame-src 'none'",
+    "worker-src 'none'",
+    "object-src 'none'",
+    "base-uri 'none'",
+    "form-action 'none'"
+  ].join("; ");
+  const htmlBytes = Buffer.from(
+    `<!doctype html>
+<html lang="${escapeHtml(document.locale)}">
+<head>
+<meta charset="utf-8">
+<meta http-equiv="Content-Security-Policy" content="${escapeHtml(csp)}">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<meta name="color-scheme" content="light dark">
+<meta name="referrer" content="no-referrer">
+<title>${escapeHtml(document.title)}</title>
+<style>${portable.styles.replace(/<\/style/gi, "<\\/style")}</style>
+</head>
+<body data-presentation-portable="true">
+<div id="presentation-fallback">${fallback}</div>
+<div id="reader"></div>
+<script id="presentation-data" type="application/json">${inlineJson(document)}</script>
+<script id="third-party-notices" type="application/json">${inlineJson(portable.notices)}</script>
+<script id="presentation-runtime">${script}</script>
+</body>
+</html>
+`,
+    "utf8"
+  );
+  if (htmlBytes.length > PRESENTATION_BUDGETS.htmlBytes) {
+    throw new PresentationContractError(
+      "budget",
+      "/html",
+      `HTML exceeds the ${PRESENTATION_BUDGETS.htmlBytes} byte budget.`,
+      "Reduce repeated blocks, displayed rows, or text before building again."
+    );
+  }
+  return { document, documentBytes, htmlBytes };
+}
+export {
+  buildPresentation
+};

package/lib/presentation/commit.js

@@ -0,0 +1,163 @@
+import { constants } from 'node:fs';
+import { lstat, mkdir, mkdtemp, open, realpath, rename, rm } from 'node:fs/promises';
+import path from 'node:path';
+import { PRESENTATION_BUDGETS, parsePresentationDocument, parsePresentationReceipt, } from "./contracts/index.js";
+import { presentationAssetPath, presentationSha256, readPresentationAsset } from "./files.js";
+async function directory(filename) {
+    const stat = await lstat(filename);
+    if (!stat.isDirectory() || stat.isSymbolicLink() || (await realpath(filename)) !== filename)
+        throw new Error('presentation-directory-mismatch');
+    return stat;
+}
+async function syncDirectory(filename) {
+    const handle = await open(filename, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function sameDirectory(filename, expected) {
+    const actual = await directory(filename);
+    if (actual.dev !== expected.dev || actual.ino !== expected.ino)
+        throw new Error('presentation-directory-changed');
+}
+/** Owns only one newly-created build. A single directory rename publishes all requested complete files. */
+export async function commitPresentation(workspaceRoot, input, assertOwner, signal) {
+    signal?.throwIfAborted();
+    const document = parsePresentationDocument(structuredClone(input.document));
+    const built = {
+        document,
+        documentBytes: Buffer.from(input.documentBytes),
+        htmlBytes: input.htmlBytes && Buffer.from(input.htmlBytes),
+    };
+    if (built.documentBytes.length > PRESENTATION_BUDGETS.documentBytes ||
+        (built.htmlBytes !== undefined &&
+            (built.htmlBytes.length === 0 || built.htmlBytes.length > PRESENTATION_BUDGETS.htmlBytes)))
+        throw new Error('presentation-build-budget');
+    if (!built.documentBytes.equals(Buffer.from(JSON.stringify(document))))
+        throw new Error('presentation-build-document-mismatch');
+    const root = await realpath(workspaceRoot);
+    if (root !== path.resolve(workspaceRoot))
+        throw new Error('presentation-workspace-mismatch');
+    const paths = [
+        root,
+        path.join(root, '.dsh-data-analysis'),
+        path.join(root, '.dsh-data-analysis', 'presentations'),
+        path.join(root, '.dsh-data-analysis', 'presentations', document.reportId),
+        path.join(root, '.dsh-data-analysis', 'presentations', document.reportId, 'builds'),
+    ];
+    const identities = [];
+    for (const [index, filename] of paths.entries()) {
+        if (index > 0) {
+            await sameDirectory(paths[index - 1], identities[index - 1]);
+            try {
+                await mkdir(filename, { mode: 0o700 });
+                await syncDirectory(paths[index - 1]);
+            }
+            catch (error) {
+                if (error.code !== 'EEXIST')
+                    throw error;
+            }
+        }
+        identities.push(await directory(filename));
+    }
+    const check = async () => {
+        signal?.throwIfAborted();
+        await assertOwner();
+        for (const [index, filename] of paths.entries())
+            await sameDirectory(filename, identities[index]);
+        signal?.throwIfAborted();
+    };
+    await check();
+    const parent = paths.at(-1);
+    const temporary = await mkdtemp(path.join(parent, '.pending-'));
+    const ownedIdentity = await directory(temporary);
+    const final = path.dirname(presentationAssetPath(root, built.document.reportId, built.document.buildId, 'presentation.json'));
+    let owned = temporary;
+    try {
+        await check();
+        for (const [asset, bytes] of [
+            ['presentation.json', built.documentBytes],
+            ['index.html', built.htmlBytes],
+        ]) {
+            if (!bytes)
+                continue;
+            await sameDirectory(temporary, ownedIdentity);
+            signal?.throwIfAborted();
+            const file = await open(path.join(temporary, asset), constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+            try {
+                await file.writeFile(bytes, { signal });
+                await file.sync();
+            }
+            finally {
+                await file.close();
+            }
+        }
+        await check();
+        await sameDirectory(temporary, ownedIdentity);
+        await syncDirectory(temporary);
+        // Never overwrite a completed build (the caller creates an unpredictable build UUID).
+        try {
+            await lstat(final);
+            throw new Error('presentation-build-exists');
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        await rename(temporary, final);
+        owned = final;
+        for (const filename of [...paths].reverse())
+            await syncDirectory(filename);
+        await check();
+        await sameDirectory(final, ownedIdentity);
+        const document = await readPresentationAsset(root, built.document.reportId, built.document.buildId, 'presentation.json', signal);
+        const html = built.htmlBytes &&
+            (await readPresentationAsset(root, built.document.reportId, built.document.buildId, 'index.html', signal));
+        if (!document.equals(built.documentBytes) || (html && !html.equals(built.htmlBytes)))
+            throw new Error('presentation-build-changed');
+        await check();
+        return parsePresentationReceipt({
+            schemaVersion: 2,
+            reportId: built.document.reportId,
+            kind: 'marivo.presentation',
+            workspaceId: built.document.workspaceId,
+            buildId: built.document.buildId,
+            title: built.document.title,
+            summary: `${built.document.blocks.length} 个区块 · ${built.document.datasets.length} 份数据集 · ${built.document.sources.length} 个声明来源 · ${built.document.diagnostics.length} 条诊断`,
+            files: {
+                document: {
+                    asset: 'presentation.json',
+                    path: path.join(final, 'presentation.json'),
+                    sha256: presentationSha256(document),
+                    bytes: document.length,
+                },
+                ...(html
+                    ? {
+                        html: {
+                            asset: 'index.html',
+                            path: path.join(final, 'index.html'),
+                            sha256: presentationSha256(html),
+                            bytes: html.length,
+                        },
+                    }
+                    : {}),
+            },
+        });
+    }
+    catch (error) {
+        // Cleanup only this invocation's unchanged directory; never follow a replaced parent.
+        try {
+            for (const [index, filename] of paths.entries())
+                await sameDirectory(filename, identities[index]);
+            await sameDirectory(owned, ownedIdentity);
+            await rm(owned, { recursive: true, force: true });
+        }
+        catch {
+            /* Failure cleanup must not hide the original cancellation/write error. */
+        }
+        throw error;
+    }
+}

package/lib/presentation/contracts/asset-path.js

@@ -0,0 +1,9 @@
+/** Fixed Build locator shared by the browser and Workspace storage. */
+import { parsePresentationBuildId } from "./index.js";
+export function presentationAssetRelativePath(reportId, buildId, asset) {
+    parsePresentationBuildId(reportId, '/reportId');
+    parsePresentationBuildId(buildId);
+    if (asset !== 'presentation.json' && asset !== 'index.html')
+        throw new Error('invalid-asset');
+    return `.dsh-data-analysis/presentations/${reportId}/builds/${buildId}/${asset}`;
+}

package/lib/presentation/contracts/catalog.js

@@ -0,0 +1,62 @@
+import { parsePresentationReceipt } from "./index.js";
+export const REPORT_HISTORY_BYTES = 16 * 1024 * 1024;
+export const REPORT_HISTORY_LIMIT = 4096;
+export function parseReportVersion(value) {
+    const entry = value;
+    if (!entry ||
+        Object.keys(entry).sort().join(',') !== 'publishedAt,receipt,source' ||
+        !(entry.publishedAt === null ||
+            (typeof entry.publishedAt === 'string' &&
+                Number.isFinite(Date.parse(entry.publishedAt)) &&
+                new Date(entry.publishedAt).toISOString() === entry.publishedAt)) ||
+        !(entry.source === null ||
+            (entry.source &&
+                Object.keys(entry.source).sort().join(',') === 'kind,sessionId' &&
+                ['agent', 'reader'].includes(entry.source.kind) &&
+                (entry.source.sessionId === null ||
+                    (typeof entry.source.sessionId === 'string' &&
+                        !!entry.source.sessionId.trim() &&
+                        entry.source.sessionId.length <= 512)))))
+        throw new Error('invalid-report-history');
+    parsePresentationReceipt(entry.receipt);
+    return entry;
+}
+export function parseReportHistory(value) {
+    const history = value;
+    if (!history ||
+        !Array.isArray(history.versions) ||
+        !history.versions.length ||
+        history.versions.length > REPORT_HISTORY_LIMIT ||
+        typeof history.legacyHistoryUnavailable !== 'boolean')
+        throw new Error('invalid-report-history');
+    const ids = new Set();
+    for (const entry of history.versions) {
+        const { receipt } = parseReportVersion(entry);
+        if (receipt.workspaceId !== history.workspaceId ||
+            receipt.reportId !== history.reportId ||
+            ids.has(receipt.buildId))
+            throw new Error('invalid-report-history');
+        ids.add(receipt.buildId);
+    }
+    if (history.currentBuildId !== history.versions[0].receipt.buildId)
+        throw new Error('invalid-report-history');
+    return history;
+}
+export function parseReportCatalog(value) {
+    const catalog = value;
+    if (!catalog ||
+        typeof catalog.workspaceId !== 'string' ||
+        !Array.isArray(catalog.reports) ||
+        catalog.reports.length > 4096 ||
+        !Number.isInteger(catalog.unavailable) ||
+        catalog.unavailable < 0)
+        throw new Error('invalid-report-catalog');
+    const ids = new Set();
+    for (const item of catalog.reports) {
+        const { receipt } = parseReportVersion(item);
+        if (receipt.workspaceId !== catalog.workspaceId || ids.has(receipt.reportId))
+            throw new Error('invalid-report-catalog');
+        ids.add(receipt.reportId);
+    }
+    return catalog;
+}