@chengxianglibra/dsh-data-analysis 0.1.1 → 0.1.2

package/lib/presentation/contracts/interaction.js

@@ -0,0 +1,62 @@
+export function defaultSelection(interaction) {
+    return Object.fromEntries(interaction.filters.map((filter) => [filter.id, filter.allOptionId]));
+}
+export function selectedSlice(interaction, selection) {
+    const slice = interaction.slices.find((slice) => interaction.filters.every((filter) => Object.hasOwn(selection, filter.id) && slice.selection[filter.id] === selection[filter.id]));
+    if (!slice)
+        throw new Error('Unknown presentation filter combination.');
+    return slice;
+}
+export function interactionRows(interaction, selection, block) {
+    if (!interaction?.blockIds.includes(block.id) || !('datasetId' in block))
+        return undefined;
+    const binding = selectedSlice(interaction, selection).datasets.find((entry) => entry.datasetId === block.datasetId);
+    if (!binding)
+        throw new Error('Missing presentation slice binding.');
+    return binding.rowIndices;
+}
+export function filterSummary(interaction, selection) {
+    return interaction.filters
+        .map((filter) => {
+        const option = filter.options.find((option) => option.id === selection[filter.id]);
+        if (!option)
+            throw new Error('Unknown presentation filter option.');
+        return `${filter.label}：${option.label}`;
+    })
+        .join(' · ');
+}
+/** Preserve the authored before / interactive / after boundary during host edits. */
+export function blockRegion(document, id) {
+    if (!document.interaction)
+        return 0;
+    if (document.interaction.blockIds.includes(id))
+        return 1;
+    return document.blocks.findIndex((block) => block.id === id) <
+        document.blocks.findIndex((block) => block.id === document.interaction.blockIds[0])
+        ? 0
+        : 2;
+}
+export function editedInteraction(document, blocks) {
+    if (!document.interaction)
+        return undefined;
+    const original = document.interaction;
+    const targets = blocks.filter((block) => original.blockIds.includes(block.id));
+    if (!targets.length)
+        return undefined;
+    const datasets = new Set(targets.flatMap((block) => 'datasetId' in block
+        ? [
+            block.datasetId,
+            ...(block.kind === 'chart'
+                ? (block.preparedViews ?? []).map((view) => view.datasetId)
+                : []),
+        ]
+        : []));
+    return {
+        ...original,
+        blockIds: targets.map((block) => block.id),
+        slices: original.slices.map((slice) => ({
+            ...slice,
+            datasets: slice.datasets.filter((entry) => datasets.has(entry.datasetId)),
+        })),
+    };
+}

package/lib/presentation/contracts/types.js

@@ -0,0 +1,15 @@
+export const PRESENTATION_SCHEMA_VERSION = 2;
+export const PRESENTATION_BUDGETS = {
+    documentBytes: 4 * 1024 * 1024,
+    draftBytes: 256 * 1024,
+    datasetBytes: 2 * 1024 * 1024,
+    htmlBytes: 8 * 1024 * 1024,
+    datasets: 16,
+    columns: 64,
+    rows: 5_000,
+    cells: 100_000,
+    sources: 64,
+    codeSnippets: 32,
+    blocks: 64,
+    text: 32_768,
+};

package/lib/presentation/contracts/values.js

@@ -0,0 +1,28 @@
+export class PresentationContractError extends Error {
+    code;
+    path;
+    hint;
+    reason;
+    constructor(code, path, message, hint = 'Correct the value at this path.') {
+        super(`${path || '/'}: ${message}`);
+        this.name = 'PresentationContractError';
+        this.reason = message;
+        this.code = code;
+        this.path = path;
+        this.hint = hint;
+    }
+}
+export function chartNumber(value, column, mode, path = '') {
+    if (value === null)
+        return null;
+    if (!['float64', 'int64', 'decimal'].includes(column.type))
+        throw new PresentationContractError('invalid_value', path, 'Chart series must be numeric.');
+    if (mode === 'exact' &&
+        (column.type === 'decimal' || (column.type === 'int64' && !Number.isSafeInteger(Number(value))))) {
+        throw new PresentationContractError('numeric_precision', path, 'Exact chart encoding cannot represent this value.', 'Set numericMode to approximate explicitly, or show the exact value in a table.');
+    }
+    const number = Number(value);
+    if (!Number.isFinite(number))
+        throw new PresentationContractError('numeric_precision', path, 'Chart encoding must remain finite.');
+    return number;
+}

package/lib/presentation/delivery.js

@@ -0,0 +1,56 @@
+import { MARIVO_PRESENT_TOOL_NAME, MARIVO_PRESENTATION_DELIVERY_KIND, parsePresentationDelivery, } from "./receipt.js";
+/** Persist the same envelope on nested Code dispatch even when code discards the return value. */
+export function installMarivoPresentationCodeDelivery(ctx) {
+    const pending = new Map();
+    const stopResult = ctx.on('tools/result', (exec, result) => {
+        if (exec.name !== MARIVO_PRESENT_TOOL_NAME || exec.parent === undefined || result.isError)
+            return;
+        try {
+            const value = result.value;
+            const delivery = parsePresentationDelivery(JSON.parse(value.deliveryJson));
+            if (delivery.dshSessionId !== String(exec.agent?.session.id))
+                return;
+            pending.set(String(exec.callId), { rootCallId: String(exec.rootCallId), delivery });
+            // Bounded transient dispatch rendezvous; receipts remain in Host events, never this map.
+            if (pending.size > 256)
+                pending.delete(pending.keys().next().value);
+        }
+        catch {
+            /* Invalid output cannot create a success card. */
+        }
+    });
+    const stopLog = ctx.on('tools/code-dispatch-log', async (dispatch, next) => {
+        const content = await next();
+        if (dispatch.name !== MARIVO_PRESENT_TOOL_NAME)
+            return content;
+        const key = String(dispatch.subCallId);
+        const item = pending.get(key);
+        pending.delete(key);
+        if (dispatch.isError ||
+            !item ||
+            item.delivery.dshSessionId !== String(dispatch.agent?.session.id) ||
+            item.rootCallId !== String(dispatch.exec.rootCallId))
+            return content;
+        const root = [...(dispatch.agent?.session.events ?? [])]
+            .reverse()
+            .find((event) => event.type === 'tool/call' && String(event.data.callId) === item.rootCallId);
+        if (root?.type !== 'tool/call' || root.data.turn !== item.delivery.turn)
+            return content;
+        return [
+            ...content,
+            {
+                type: MARIVO_PRESENTATION_DELIVERY_KIND,
+                delivery: item.delivery,
+            },
+        ];
+    }, { prepend: true });
+    let active = true;
+    return () => {
+        if (!active)
+            return;
+        active = false;
+        stopLog();
+        stopResult();
+        pending.clear();
+    };
+}

package/lib/presentation/files.js

@@ -0,0 +1,83 @@
+import { createHash } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, open, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { PRESENTATION_BUDGETS, parsePresentationBuildId, } from "./contracts/index.js";
+export function presentationReportPath(root, reportId) {
+    parsePresentationBuildId(reportId, '/reportId');
+    return path.join(root, '.dsh-data-analysis', 'presentations', reportId);
+}
+export function presentationAssetPath(root, reportId, buildId, asset) {
+    parsePresentationBuildId(buildId);
+    if (asset !== 'presentation.json' && asset !== 'index.html')
+        throw new Error('invalid-asset');
+    return path.join(presentationReportPath(root, reportId), 'builds', buildId, asset);
+}
+export function presentationSha256(bytes) {
+    return createHash('sha256').update(bytes).digest('hex');
+}
+/** Bounded raw-byte reader with no symbolic links and stable directory/file identity. */
+export async function readPresentationAsset(workspaceRoot, reportId, buildId, asset, signal) {
+    const filename = presentationAssetPath(workspaceRoot, reportId, buildId, asset);
+    return readReportFile(workspaceRoot, filename, asset === 'presentation.json'
+        ? PRESENTATION_BUDGETS.documentBytes
+        : PRESENTATION_BUDGETS.htmlBytes, signal);
+}
+export async function readReportFile(workspaceRoot, filename, maximum, signal) {
+    signal?.throwIfAborted();
+    const root = await realpath(workspaceRoot);
+    if (root !== path.resolve(workspaceRoot) || !filename.startsWith(`${root}${path.sep}`))
+        throw new Error('asset-path-mismatch');
+    const parents = [root];
+    for (const segment of path.relative(root, path.dirname(filename)).split(path.sep)) {
+        if (!segment || segment === '..' || segment === '.')
+            throw new Error('asset-path-mismatch');
+        parents.push(path.join(parents.at(-1), segment));
+    }
+    const beforeParents = await Promise.all(parents.map((parent) => lstat(parent)));
+    if (beforeParents.some((stat) => !stat.isDirectory() || stat.isSymbolicLink()))
+        throw new Error('asset-path-mismatch');
+    if ((await realpath(filename)) !== filename)
+        throw new Error('asset-path-mismatch');
+    const file = await open(filename, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    try {
+        const before = await file.stat();
+        if (!before.isFile())
+            throw new Error('asset-not-file');
+        if (before.size > maximum)
+            throw new Error('asset-too-large');
+        const bytes = Buffer.alloc(maximum + 1);
+        let length = 0;
+        while (length < bytes.length) {
+            signal?.throwIfAborted();
+            const read = await file.read(bytes, length, bytes.length - length, null);
+            if (read.bytesRead === 0)
+                break;
+            length += read.bytesRead;
+        }
+        if (length > maximum)
+            throw new Error('asset-too-large');
+        const after = await file.stat();
+        const current = await lstat(filename);
+        const afterParents = await Promise.all(parents.map((parent) => lstat(parent)));
+        if (afterParents.some((stat, index) => !stat.isDirectory() ||
+            stat.isSymbolicLink() ||
+            stat.dev !== beforeParents[index].dev ||
+            stat.ino !== beforeParents[index].ino) ||
+            (await realpath(workspaceRoot)) !== root ||
+            (await realpath(filename)) !== filename)
+            throw new Error('asset-path-mismatch');
+        if (current.dev !== after.dev ||
+            current.ino !== after.ino ||
+            before.size !== after.size ||
+            before.mtimeMs !== after.mtimeMs ||
+            before.ctimeMs !== after.ctimeMs ||
+            length !== after.size)
+            throw new Error('asset-changed');
+        signal?.throwIfAborted();
+        return bytes.subarray(0, length);
+    }
+    finally {
+        await file.close();
+    }
+}

package/lib/presentation/index.js

@@ -0,0 +1,6 @@
+export * from "./contracts/index.js";
+export * from "./delivery.js";
+export * from "./projection/index.js";
+export * from "./receipt.js";
+export * from "./rpc.js";
+export * from "./tool.js";

package/lib/presentation/lint.js

@@ -0,0 +1,46 @@
+import { PRESENTATION_BUDGETS, PresentationContractError, parsePresentationDraft, parseTypedDataset, } from "./contracts/index.js";
+import { readWorkspaceJson } from "./projection/files.js";
+/** Static preflight only: never starts a Runtime or publishes presentation assets. */
+export async function lintPresentationDraft(workspaceRoot, draftPath) {
+    const diagnostics = [];
+    let checkedComputedDatasets = 0;
+    const record = (error) => {
+        if (!(error instanceof PresentationContractError))
+            throw error;
+        diagnostics.push({
+            code: error.code,
+            path: error.path,
+            message: error.message,
+            hint: error.hint,
+        });
+    };
+    try {
+        const draft = parsePresentationDraft(await readWorkspaceJson(workspaceRoot, draftPath, PRESENTATION_BUDGETS.draftBytes, '/draft_path'));
+        for (const [index, dataset] of draft.datasets.entries()) {
+            if (dataset.kind !== 'computed')
+                continue;
+            try {
+                const data = await readWorkspaceJson(workspaceRoot, dataset.path, PRESENTATION_BUDGETS.datasetBytes, `/datasets/${index}/path`);
+                parseTypedDataset(data, `/datasets/${index}/data`);
+                checkedComputedDatasets++;
+            }
+            catch (error) {
+                record(error);
+            }
+        }
+    }
+    catch (error) {
+        record(error);
+    }
+    return {
+        ok: diagnostics.length === 0,
+        scope: 'draft-structure-and-computed-data',
+        checkedComputedDatasets,
+        diagnostics,
+        deferredChecks: [
+            'artifact-availability-and-data',
+            'codeRefs',
+            'projected-document-and-rendering',
+        ],
+    };
+}

package/lib/presentation/projection/files.js

@@ -0,0 +1,85 @@
+import { constants } from 'node:fs';
+import { lstat, open, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { PresentationContractError } from "../contracts/index.js";
+function boundary(location) {
+    throw new PresentationContractError('file_boundary', location, 'Expected an unchanged regular file inside the bound Workspace without symbolic links.');
+}
+/** Read raw bytes under a strict budget before JSON parsing, including concurrent growth. */
+export async function readWorkspaceJson(workspaceRoot, relativePath, maximum, location, signal) {
+    signal?.throwIfAborted();
+    if (path.isAbsolute(relativePath) ||
+        relativePath.includes('\\') ||
+        relativePath.includes('\0') ||
+        relativePath.split('/').some((part) => !part || part === '.' || part === '..'))
+        boundary(location);
+    try {
+        const root = await realpath(workspaceRoot);
+        if (root !== path.resolve(workspaceRoot))
+            boundary(location);
+        const segments = relativePath.split('/');
+        const filename = path.join(root, ...segments);
+        const parents = [
+            root,
+            ...segments.slice(0, -1).map((_, index) => path.join(root, ...segments.slice(0, index + 1))),
+        ];
+        const beforeParents = await Promise.all(parents.map((parent) => lstat(parent)));
+        if (beforeParents.some((stat) => !stat.isDirectory() || stat.isSymbolicLink()))
+            boundary(location);
+        if ((await realpath(filename)) !== filename)
+            boundary(location);
+        if (!(await lstat(filename)).isFile())
+            boundary(location);
+        const file = await open(filename, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        try {
+            const before = await file.stat();
+            if (!before.isFile())
+                boundary(location);
+            if (before.size > maximum)
+                throw new PresentationContractError('budget', location, 'Input file exceeds the presentation byte budget.');
+            const bytes = Buffer.alloc(maximum + 1);
+            let length = 0;
+            while (length < bytes.length) {
+                signal?.throwIfAborted();
+                const { bytesRead } = await file.read(bytes, length, bytes.length - length, null);
+                if (bytesRead === 0)
+                    break;
+                length += bytesRead;
+            }
+            if (length > maximum)
+                throw new PresentationContractError('budget', location, 'Input file exceeds the presentation byte budget.');
+            const after = await file.stat();
+            const current = await lstat(filename);
+            const afterParents = await Promise.all(parents.map((parent) => lstat(parent)));
+            if (afterParents.some((stat, index) => !stat.isDirectory() ||
+                stat.isSymbolicLink() ||
+                stat.dev !== beforeParents[index].dev ||
+                stat.ino !== beforeParents[index].ino) ||
+                (await realpath(workspaceRoot)) !== root ||
+                (await realpath(filename)) !== filename ||
+                current.dev !== after.dev ||
+                current.ino !== after.ino ||
+                before.size !== after.size ||
+                before.mtimeMs !== after.mtimeMs ||
+                before.ctimeMs !== after.ctimeMs ||
+                length !== after.size)
+                boundary(location);
+            signal?.throwIfAborted();
+            try {
+                return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes.subarray(0, length)));
+            }
+            catch {
+                throw new PresentationContractError('invalid_json', location, 'Expected valid UTF-8 JSON.');
+            }
+        }
+        finally {
+            await file.close();
+        }
+    }
+    catch (error) {
+        signal?.throwIfAborted();
+        if (error instanceof PresentationContractError)
+            throw error;
+        boundary(location);
+    }
+}

package/lib/presentation/projection/index.js

@@ -0,0 +1,195 @@
+import { MarivoEnvironmentError } from "../../environment/errors.js";
+import { readPythonExecution } from "../../python-execution.js";
+import { PRESENTATION_BUDGETS, PresentationContractError, parsePresentationDocument, parsePresentationDraft, parseTypedDataset, } from "../contracts/index.js";
+import { readWorkspaceJson } from "./files.js";
+import { MARIVO_PRESENTATION_READ_PROGRAM } from "./program.js";
+export { readWorkspaceJson } from "./files.js";
+function invalidOutput() {
+    throw new MarivoEnvironmentError('subprocess-output-invalid', 'Marivo presentation reader returned an invalid projection.');
+}
+function record(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        invalidOutput();
+    return value;
+}
+function exactKeys(value, keys) {
+    if (Object.keys(value).sort().join(',') !== keys.sort().join(','))
+        invalidOutput();
+}
+/** Internal S2 bridge: restores public data without observe, revalidation or credential admission. */
+export class MarivoPresentationProjection {
+    #runner;
+    constructor(runner) {
+        this.#runner = runner;
+    }
+    get status() {
+        return this.#runner.status;
+    }
+    get binding() {
+        return this.#runner.binding;
+    }
+    async readDraft(relativePath, signal) {
+        this.#assertReady(signal);
+        return parsePresentationDraft(await readWorkspaceJson(this.binding.projectRoot, relativePath, PRESENTATION_BUDGETS.draftBytes, '/draft_path', signal));
+    }
+    #assertReady(signal) {
+        signal?.throwIfAborted();
+        if (this.#runner.status !== 'ready')
+            throw new MarivoEnvironmentError('binding-failed', 'Presentation projection requires a ready bound Runtime.');
+        if (!this.binding.presentationKit)
+            throw new MarivoEnvironmentError('binding-identity-mismatch', 'Presentation projection requires the checked presentation helper identity.');
+    }
+    async project(value, options) {
+        this.#assertReady(options.signal);
+        // Snapshot caller-owned input before awaiting IO.
+        const draft = structuredClone(parsePresentationDraft(value));
+        const datasets = [];
+        const artifactSelections = draft.datasets.flatMap((dataset, index) => dataset.kind === 'artifact'
+            ? [
+                {
+                    id: dataset.id,
+                    kind: dataset.kind,
+                    sourceId: dataset.sourceId,
+                    rowLimit: dataset.rowLimit,
+                    ...(dataset.columns ? { columns: dataset.columns } : {}),
+                    index,
+                },
+            ]
+            : []);
+        let sources = [];
+        let diagnostics = [];
+        const artifactData = new Map();
+        if (draft.sources.length > 0) {
+            const result = await this.#runner.runChecked({
+                program: MARIVO_PRESENTATION_READ_PROGRAM,
+                args: [JSON.stringify({ sources: draft.sources, datasets: artifactSelections })],
+                limits: {
+                    timeoutMs: 30_000,
+                    stdoutMaxBytes: PRESENTATION_BUDGETS.documentBytes,
+                    stderrMaxBytes: 65_536,
+                },
+                signal: options.signal,
+            });
+            this.#assertReady(options.signal);
+            if (result.exitCode !== 0)
+                throw new MarivoEnvironmentError('subprocess-failed', 'The bound Marivo presentation read failed.', { exitCode: result.exitCode });
+            let payload;
+            try {
+                payload = record(JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(result.stdout)));
+            }
+            catch {
+                invalidOutput();
+            }
+            if (payload.ok === false) {
+                exactKeys(payload, ['ok', 'error']);
+                const error = record(payload.error);
+                exactKeys(error, ['code', 'path', 'message']);
+                if (typeof error.code !== 'string' ||
+                    !/^[a-z_]{1,128}$/.test(error.code) ||
+                    typeof error.path !== 'string' ||
+                    error.path.length > 1024 ||
+                    !/^(?:\/(?:[^~]|~[01])*)*$/.test(error.path) ||
+                    typeof error.message !== 'string' ||
+                    error.message.length > 1024)
+                    invalidOutput();
+                throw new PresentationContractError(error.code, error.path, error.message);
+            }
+            exactKeys(payload, ['ok', 'sources', 'datasets', 'diagnostics']);
+            if (payload.ok !== true ||
+                !Array.isArray(payload.sources) ||
+                !Array.isArray(payload.datasets) ||
+                !Array.isArray(payload.diagnostics))
+                invalidOutput();
+            if (payload.sources.length !== draft.sources.length ||
+                payload.datasets.length !== artifactSelections.length)
+                invalidOutput();
+            for (const [index, source] of payload.sources.entries()) {
+                const actual = record(source);
+                const ref = record(actual.ref);
+                const expected = draft.sources[index];
+                if (actual.id !== expected.id ||
+                    ref.sessionId !== expected.ref.sessionId ||
+                    ref.artifactRef !== expected.ref.artifactRef ||
+                    ref.findingId !== expected.ref.findingId)
+                    invalidOutput();
+            }
+            for (const [index, entry] of payload.datasets.entries()) {
+                const dataset = record(entry);
+                exactKeys(dataset, ['id', 'data']);
+                if (dataset.id !== artifactSelections[index].id)
+                    invalidOutput();
+                artifactData.set(artifactSelections[index].id, dataset.data);
+            }
+            sources = payload.sources;
+            diagnostics = payload.diagnostics;
+        }
+        for (const [index, dataset] of draft.datasets.entries()) {
+            this.#assertReady(options.signal);
+            const location = `/datasets/${index}`;
+            let data;
+            if (dataset.kind === 'computed') {
+                data = await readWorkspaceJson(this.binding.projectRoot, dataset.path, PRESENTATION_BUDGETS.datasetBytes, `${location}/path`, options.signal);
+            }
+            else
+                data = artifactData.get(dataset.id);
+            data = parseTypedDataset(data, `${location}/data`);
+            if (dataset.kind === 'artifact') {
+                const typed = data;
+                if (typed.limit > dataset.rowLimit ||
+                    (dataset.columns !== undefined &&
+                        (typed.columns.length !== dataset.columns.length ||
+                            typed.columns.some((column, index) => column.id !== dataset.columns[index]))))
+                    invalidOutput();
+            }
+            const code = [];
+            for (const [codeIndex, ref] of (dataset.codeRefs ?? []).entries()) {
+                this.#assertReady(options.signal);
+                try {
+                    code.push(await readPythonExecution(this.binding.projectRoot, ref, options.signal));
+                }
+                catch {
+                    options.signal?.throwIfAborted();
+                    throw new PresentationContractError('code_unavailable', `${location}/codeRefs/${codeIndex}`, 'The captured Python execution cannot be read with its exact Workspace identity and digest.', 'Check the codeRef returned by the successful marivo_python call; do not rerun analysis to repair presentation.');
+                }
+            }
+            this.#assertReady(options.signal);
+            datasets.push({
+                id: dataset.id,
+                origin: dataset.kind,
+                data: data,
+                sourceIds: dataset.kind === 'artifact' ? [dataset.sourceId] : dataset.sourceIds,
+                ...(dataset.codeRefs !== undefined ? { code } : {}),
+            });
+        }
+        for (const [index, dataset] of datasets.entries()) {
+            if (dataset.data.truncated)
+                diagnostics.push({
+                    code: 'truncated',
+                    path: `/datasets/${index}/data/rows`,
+                    message: `Showing ${dataset.data.rows.length} of ${dataset.data.rowCount} rows; truncated data must not imply full totals or rankings.`,
+                });
+        }
+        for (const [index, source] of sources.entries()) {
+            if (source.status === 'unavailable')
+                diagnostics.push({
+                    code: 'source_unavailable',
+                    path: `/sources/${index}`,
+                    message: 'The declared Artifact source cannot be restored in the bound Workspace.',
+                });
+        }
+        this.#assertReady(options.signal);
+        return parsePresentationDocument({
+            schemaVersion: 2,
+            reportId: options.reportId,
+            workspaceId: options.workspaceId,
+            buildId: options.buildId,
+            title: draft.title,
+            generatedAt: options.generatedAt ?? new Date().toISOString(),
+            datasets,
+            sources,
+            blocks: draft.blocks,
+            ...(draft.interaction ? { interaction: draft.interaction } : {}),
+            diagnostics,
+        });
+    }
+}