@chengxianglibra/dsh-data-analysis 0.1.1

package/lib/environment/subprocess.js

@@ -0,0 +1,178 @@
+import { spawn } from 'node:child_process';
+import process from 'node:process';
+import { SUBPROCESS_POLICY_VERSION } from "../compatibility.js";
+import { MarivoEnvironmentError } from "./errors.js";
+export const SUBPROCESS_POLICY_ID = SUBPROCESS_POLICY_VERSION;
+export const MARIVO_PERSIST_CREDENTIALS_ENV = 'MARIVO_PERSIST_CREDENTIALS';
+export const MARIVO_PERSIST_CREDENTIALS_DISABLED = '0';
+export const DEFAULT_SUBPROCESS_LIMITS = Object.freeze({
+    timeoutMs: 30_000,
+    stdoutMaxBytes: 1_048_576,
+    stderrMaxBytes: 65_536,
+    terminateGraceMs: 250,
+});
+function snapshotEnvironment(source) {
+    return Object.freeze({
+        ...Object.fromEntries(Object.entries(source).filter((entry) => entry[1] !== undefined)),
+        [MARIVO_PERSIST_CREDENTIALS_ENV]: MARIVO_PERSIST_CREDENTIALS_DISABLED,
+    });
+}
+function overlayEnvironment(snapshot, overlay) {
+    if (overlay === undefined)
+        return snapshot;
+    return Object.freeze({
+        ...snapshot,
+        ...Object.fromEntries(Object.entries(overlay).filter((entry) => entry[1] !== undefined)),
+        // This is plugin policy, not caller-controlled configuration.
+        [MARIVO_PERSIST_CREDENTIALS_ENV]: MARIVO_PERSIST_CREDENTIALS_DISABLED,
+    });
+}
+function positiveLimit(name, value) {
+    if (!Number.isSafeInteger(value) || value < 1) {
+        throw new TypeError(`${name} must be a positive safe integer`);
+    }
+    return value;
+}
+function resolveLimits(overrides) {
+    const merged = { ...DEFAULT_SUBPROCESS_LIMITS, ...overrides };
+    return {
+        timeoutMs: positiveLimit('timeoutMs', merged.timeoutMs),
+        stdoutMaxBytes: positiveLimit('stdoutMaxBytes', merged.stdoutMaxBytes),
+        stderrMaxBytes: positiveLimit('stderrMaxBytes', merged.stderrMaxBytes),
+        terminateGraceMs: positiveLimit('terminateGraceMs', merged.terminateGraceMs),
+    };
+}
+/**
+ * Direct-argv subprocess runner shared by doctor, inventory, and focused help.
+ *
+ * The policy captures cwd and the environment projection once. Calls never use a shell. On
+ * POSIX, detached children form a process group so timeout, cancellation, and output overflow
+ * terminate the whole group.
+ */
+export class FixedSubprocessPolicy {
+    id = SUBPROCESS_POLICY_ID;
+    cwd;
+    #environment;
+    constructor(cwd, environment = process.env) {
+        this.cwd = cwd;
+        this.#environment = snapshotEnvironment(environment);
+    }
+    run(request) {
+        const limits = resolveLimits(request.limits);
+        const startedAt = performance.now();
+        const environment = overlayEnvironment(this.#environment, request.environmentOverlay);
+        if (request.signal?.aborted) {
+            return Promise.reject(new MarivoEnvironmentError('subprocess-cancelled', 'Marivo subprocess was cancelled before it started'));
+        }
+        return new Promise((resolve, reject) => {
+            const spawnChild = () => spawn(request.executable, request.args, {
+                cwd: this.cwd,
+                env: environment,
+                shell: false,
+                windowsHide: true,
+                detached: process.platform !== 'win32',
+                stdio: ['ignore', 'pipe', 'pipe'],
+            });
+            let child;
+            try {
+                child = spawnChild();
+            }
+            catch (cause) {
+                reject(new MarivoEnvironmentError('subprocess-start-failed', 'Could not start Marivo subprocess', {
+                    executable: request.executable,
+                    errorCode: cause.code,
+                }));
+                return;
+            }
+            const stdout = [];
+            const stderr = [];
+            let stdoutBytes = 0;
+            let stderrBytes = 0;
+            let settled = false;
+            let failure;
+            let killTimer;
+            const killTree = (signal) => {
+                if (child.pid === undefined)
+                    return;
+                if (process.platform === 'win32') {
+                    const killer = spawn('taskkill', ['/pid', String(child.pid), '/t', '/f'], {
+                        cwd: this.cwd,
+                        env: environment,
+                        shell: false,
+                        windowsHide: true,
+                        stdio: 'ignore',
+                    });
+                    killer.once('error', () => child.kill(signal));
+                    killer.unref();
+                    return;
+                }
+                try {
+                    process.kill(-child.pid, signal);
+                }
+                catch (error) {
+                    const code = error.code;
+                    if (code !== 'ESRCH')
+                        child.kill(signal);
+                }
+            };
+            const terminate = (error) => {
+                if (failure !== undefined || settled)
+                    return;
+                failure = error;
+                killTree('SIGTERM');
+                killTimer = setTimeout(() => killTree('SIGKILL'), limits.terminateGraceMs);
+                killTimer.unref();
+            };
+            const timeout = setTimeout(() => terminate(new MarivoEnvironmentError('subprocess-timeout', `Marivo subprocess exceeded ${limits.timeoutMs} ms`, { timeoutMs: limits.timeoutMs })), limits.timeoutMs);
+            timeout.unref();
+            const onAbort = () => terminate(new MarivoEnvironmentError('subprocess-cancelled', 'Marivo subprocess was cancelled'));
+            request.signal?.addEventListener('abort', onAbort, { once: true });
+            child.stdout.on('data', (chunk) => {
+                stdoutBytes += chunk.byteLength;
+                if (stdoutBytes > limits.stdoutMaxBytes) {
+                    terminate(new MarivoEnvironmentError('subprocess-output-limit', `Marivo subprocess stdout exceeded ${limits.stdoutMaxBytes} bytes`, { stream: 'stdout', maxBytes: limits.stdoutMaxBytes, observedBytes: stdoutBytes }));
+                    return;
+                }
+                stdout.push(chunk);
+            });
+            child.stderr.on('data', (chunk) => {
+                stderrBytes += chunk.byteLength;
+                if (stderrBytes > limits.stderrMaxBytes) {
+                    terminate(new MarivoEnvironmentError('subprocess-output-limit', `Marivo subprocess stderr exceeded ${limits.stderrMaxBytes} bytes`, { stream: 'stderr', maxBytes: limits.stderrMaxBytes, observedBytes: stderrBytes }));
+                    return;
+                }
+                stderr.push(chunk);
+            });
+            child.once('error', (cause) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timeout);
+                if (killTimer !== undefined)
+                    clearTimeout(killTimer);
+                request.signal?.removeEventListener('abort', onAbort);
+                reject(new MarivoEnvironmentError('subprocess-start-failed', 'Could not start Marivo subprocess', { executable: request.executable, errorCode: cause.code }));
+            });
+            child.once('close', (exitCode, signal) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timeout);
+                if (killTimer !== undefined)
+                    clearTimeout(killTimer);
+                request.signal?.removeEventListener('abort', onAbort);
+                if (failure !== undefined) {
+                    reject(failure);
+                    return;
+                }
+                resolve({
+                    exitCode,
+                    signal,
+                    stdout: Buffer.concat(stdout, stdoutBytes),
+                    stderr: Buffer.concat(stderr, stderrBytes),
+                    durationMs: Math.max(0, Math.round(performance.now() - startedAt)),
+                });
+            });
+        });
+    }
+}

package/lib/environment/summary.js

@@ -0,0 +1,19 @@
+/** Serialize only stable Runtime and admitted Environment identity for the operator CLI. */
+export function environmentPayload(runtime, environment) {
+    return {
+        status: environment.status,
+        runtimeRoot: runtime.runtimeRoot,
+        skillsRoot: runtime.skillsRoot,
+        projectRoot: environment.binding.projectRoot,
+        pythonExecutable: environment.binding.pythonExecutable,
+        marivo: {
+            version: environment.binding.marivoVersion,
+            packagePath: environment.binding.packagePath,
+        },
+        reportKit: {
+            version: runtime.reportKitVersion,
+            packagePath: runtime.reportKitPackagePath,
+        },
+        fingerprint: environment.binding.fingerprint,
+    };
+}

package/lib/environment/workspace.js

@@ -0,0 +1,49 @@
+import { realpath, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { bindMarivoEnvironment } from "./binding.js";
+import { MarivoEnvironmentError } from "./errors.js";
+async function assertDirectory(target, label) {
+    try {
+        if (!(await stat(target)).isDirectory())
+            throw new Error('not a directory');
+    }
+    catch (cause) {
+        throw new MarivoEnvironmentError('project-root-invalid', `Marivo Workspace ${label} path is not a directory: ${target}`, { path: target, label }, { cause });
+    }
+}
+async function canonicalWorkspaceRoot(projectRoot) {
+    let canonicalRoot;
+    try {
+        canonicalRoot = await realpath(path.resolve(projectRoot));
+        await assertDirectory(canonicalRoot, 'root');
+    }
+    catch (cause) {
+        if (cause instanceof MarivoEnvironmentError)
+            throw cause;
+        throw new MarivoEnvironmentError('project-root-invalid', `Marivo project root is not an existing directory: ${path.resolve(projectRoot)}`, { projectRoot: path.resolve(projectRoot) }, { cause });
+    }
+    return canonicalRoot;
+}
+/** Cache one zero-init Workspace binding while retaining project-specific doctor state. */
+export class MarivoWorkspaceEnvironmentManager {
+    runtime;
+    #bindings = new Map();
+    constructor(runtime) {
+        this.runtime = runtime;
+    }
+    async resolve(projectRoot) {
+        const canonicalRoot = await canonicalWorkspaceRoot(projectRoot);
+        let binding = this.#bindings.get(canonicalRoot);
+        if (binding === undefined) {
+            binding = bindMarivoEnvironment({
+                projectRoot: canonicalRoot,
+                pythonExecutable: this.runtime.pythonExecutable,
+            });
+            this.#bindings.set(canonicalRoot, binding);
+        }
+        return binding;
+    }
+    dispose() {
+        this.#bindings.clear();
+    }
+}

package/lib/evidence/bridge-program.js

@@ -0,0 +1,153 @@
+export const MARIVO_EVIDENCE_FINDINGS_PROGRAM = String.raw `
+import json
+import sys
+import marivo.analysis as mv
+from marivo.analysis.errors import ArtifactNotFoundError, FindingNotFoundError
+
+
+session_id = sys.argv[1]
+selections = json.loads(sys.argv[2])
+try:
+    session = mv.session.resume(session_id, use_datasources=False)
+except Exception as exc:
+    print(json.dumps({
+        "kind": "evidence-session-read-failed",
+        "exception_type": type(exc).__name__,
+    }, sort_keys=True), file=sys.stderr)
+    raise SystemExit(70)
+
+
+def revalidation_projection(artifact):
+    try:
+        result = session.revalidate(artifact.ref)
+    except ArtifactNotFoundError:
+        return {
+            "status": "unavailable",
+            "semantic_status": None,
+            "evidence_status": None,
+            "dependency_status": None,
+        }
+    return {
+        "status": result.status,
+        "semantic_status": result.semantic_status,
+        "evidence_status": result.evidence_status,
+        "dependency_status": result.dependency_status,
+    }
+
+
+sources = []
+for selection in selections:
+    artifact_ref = selection["artifactRef"]
+    finding_id = selection["findingId"]
+    locator = f"marivo://session/{session.id}/artifact/{artifact_ref}/finding/{finding_id}"
+    try:
+        artifact = session.artifact(artifact_ref)
+    except Exception:
+        sources.append({
+            "status": "missing",
+            "title": f"Missing Marivo Finding {finding_id}",
+            "locator": locator,
+            "excerpt": None,
+            "truncated": False,
+            "finding_id": finding_id,
+            "finding_type": None,
+            "epistemic_kind": None,
+            "artifact_ref": artifact_ref,
+            "session_id": session.id,
+            "canonical_item_key": None,
+            "committed_at": None,
+            "source_refs": [],
+            "revalidation": None,
+        })
+        continue
+    except Exception:
+        sources.append({
+            "status": "unsupported",
+            "title": f"Unavailable Marivo Finding {finding_id}",
+            "locator": locator,
+            "excerpt": None,
+            "truncated": False,
+            "finding_id": finding_id,
+            "finding_type": None,
+            "epistemic_kind": None,
+            "artifact_ref": artifact_ref,
+            "session_id": session.id,
+            "canonical_item_key": None,
+            "committed_at": None,
+            "source_refs": [],
+            "revalidation": None,
+        })
+        continue
+
+    revalidation = revalidation_projection(artifact)
+    try:
+        finding = artifact.finding(finding_id)
+    except FindingNotFoundError:
+        sources.append({
+            "status": "missing",
+            "title": f"Missing Marivo Finding {finding_id}",
+            "locator": locator,
+            "excerpt": None,
+            "truncated": False,
+            "finding_id": finding_id,
+            "finding_type": None,
+            "epistemic_kind": None,
+            "artifact_ref": artifact.ref,
+            "session_id": session.id,
+            "canonical_item_key": None,
+            "committed_at": None,
+            "source_refs": [],
+            "revalidation": revalidation,
+        })
+        continue
+    except Exception:
+        sources.append({
+            "status": "unsupported",
+            "title": f"Unavailable Marivo Finding {finding_id}",
+            "locator": locator,
+            "excerpt": None,
+            "truncated": False,
+            "finding_id": finding_id,
+            "finding_type": None,
+            "epistemic_kind": None,
+            "artifact_ref": artifact.ref,
+            "session_id": session.id,
+            "canonical_item_key": None,
+            "committed_at": None,
+            "source_refs": [],
+            "revalidation": revalidation,
+        })
+        continue
+
+    if finding.session_id != session.id or finding.artifact_ref != artifact.ref:
+        print(json.dumps({"kind": "evidence-identity-mismatch"}, sort_keys=True), file=sys.stderr)
+        raise SystemExit(70)
+
+    try:
+        excerpt = finding.render(max_output_bytes=4096)
+        status = "available"
+    except Exception:
+        excerpt = None
+        status = "unsupported"
+    sources.append({
+        "status": status,
+        "title": f"{finding.finding_type} Finding: {finding.canonical_item_key}",
+        "locator": locator,
+        "excerpt": excerpt,
+        "truncated": excerpt is not None and "output truncated at " in excerpt,
+        "finding_id": finding.finding_id,
+        "finding_type": finding.finding_type,
+        "epistemic_kind": finding.epistemic_kind,
+        "artifact_ref": finding.artifact_ref,
+        "session_id": finding.session_id,
+        "canonical_item_key": finding.canonical_item_key,
+        "committed_at": finding.committed_at.isoformat(),
+        "source_refs": list(finding.source_refs),
+        "revalidation": revalidation,
+    })
+
+print(json.dumps({
+    "session_id": session.id,
+    "sources": sources,
+}, sort_keys=True))
+`.trim();

package/lib/evidence/bridge.js

@@ -0,0 +1,166 @@
+import { MarivoEnvironmentError } from "../environment/errors.js";
+import { resolveMarivoBridgeSource } from "../environment/source.js";
+import { MARIVO_EVIDENCE_FINDINGS_PROGRAM } from "./bridge-program.js";
+const EVIDENCE_LIMITS = Object.freeze({
+    timeoutMs: 30_000,
+    stdoutMaxBytes: 1_048_576,
+    stderrMaxBytes: 65_536,
+});
+function nonEmptyString(value, field, maxChars = 2_048) {
+    if (typeof value !== 'string' || value.trim() === '' || value.length > maxChars) {
+        throw new TypeError(`${field} must be a bounded non-empty string`);
+    }
+    return value;
+}
+function boundedText(value, field, maxBytes = 4_096) {
+    const result = nonEmptyString(value, field, maxBytes);
+    if (Buffer.byteLength(result, 'utf8') > maxBytes) {
+        throw new TypeError(`${field} must be at most ${maxBytes} UTF-8 bytes`);
+    }
+    return result;
+}
+function nullableString(value, field, maxChars = 2_048) {
+    return value === null ? null : nonEmptyString(value, field, maxChars);
+}
+function parseRevalidation(value) {
+    if (value === null)
+        return null;
+    const item = jsonObject(value);
+    if (item === undefined)
+        throw new TypeError('revalidation must be an object or null');
+    exactKeys(item, ['status', 'semantic_status', 'evidence_status', 'dependency_status'], 'revalidation');
+    return {
+        status: nonEmptyString(item.status, 'revalidation.status', 128),
+        semanticStatus: nullableString(item.semantic_status, 'revalidation.semantic_status', 128),
+        evidenceStatus: nullableString(item.evidence_status, 'revalidation.evidence_status', 128),
+        dependencyStatus: nullableString(item.dependency_status, 'revalidation.dependency_status', 128),
+    };
+}
+function jsonObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function exactKeys(value, keys, field) {
+    const expected = new Set(keys);
+    if (Object.keys(value).some((key) => !expected.has(key)) || keys.some((key) => !(key in value))) {
+        throw new TypeError(`${field} must contain exactly the expected fields`);
+    }
+}
+function parseFinding(value) {
+    const item = jsonObject(value);
+    if (item === undefined)
+        throw new TypeError('finding must be an object');
+    exactKeys(item, [
+        'finding_id',
+        'status',
+        'title',
+        'locator',
+        'excerpt',
+        'truncated',
+        'finding_type',
+        'epistemic_kind',
+        'artifact_ref',
+        'session_id',
+        'canonical_item_key',
+        'committed_at',
+        'source_refs',
+        'revalidation',
+    ], 'finding');
+    if (!['available', 'missing', 'unsupported'].includes(String(item.status))) {
+        throw new TypeError('status must be available, missing, or unsupported');
+    }
+    if (typeof item.truncated !== 'boolean')
+        throw new TypeError('truncated must be boolean');
+    if (!Array.isArray(item.source_refs) || item.source_refs.length > 100) {
+        throw new TypeError('source_refs must be a bounded array');
+    }
+    const parsed = {
+        status: item.status,
+        title: boundedText(item.title, 'title', 2_048),
+        locator: boundedText(item.locator, 'locator', 2_048),
+        excerpt: item.excerpt === null ? null : boundedText(item.excerpt, 'excerpt'),
+        truncated: item.truncated,
+        findingId: nonEmptyString(item.finding_id, 'finding_id'),
+        findingType: nullableString(item.finding_type, 'finding_type'),
+        epistemicKind: nullableString(item.epistemic_kind, 'epistemic_kind'),
+        artifactRef: nonEmptyString(item.artifact_ref, 'artifact_ref'),
+        sessionId: nonEmptyString(item.session_id, 'finding session_id'),
+        canonicalItemKey: nullableString(item.canonical_item_key, 'canonical_item_key'),
+        committedAt: nullableString(item.committed_at, 'committed_at'),
+        sourceRefs: item.source_refs.map((ref, index) => nonEmptyString(ref, `source_refs[${index}]`, 2_048)),
+        revalidation: parseRevalidation(item.revalidation),
+    };
+    if ((parsed.status === 'available' &&
+        (parsed.excerpt === null ||
+            parsed.findingType === null ||
+            parsed.epistemicKind === null ||
+            parsed.canonicalItemKey === null ||
+            parsed.committedAt === null)) ||
+        (parsed.status === 'missing' &&
+            (parsed.excerpt !== null ||
+                parsed.truncated ||
+                parsed.findingType !== null ||
+                parsed.epistemicKind !== null ||
+                parsed.canonicalItemKey !== null ||
+                parsed.committedAt !== null)) ||
+        (parsed.status === 'unsupported' && parsed.excerpt !== null) ||
+        (parsed.truncated && parsed.excerpt === null)) {
+        throw new TypeError('finding status fields are inconsistent');
+    }
+    return parsed;
+}
+function parseFindingsPayload(stdout, expectedSessionId, expectedSelections) {
+    try {
+        const root = jsonObject(JSON.parse(stdout.toString('utf8')));
+        if (root !== undefined)
+            exactKeys(root, ['session_id', 'sources'], 'root');
+        if (root === undefined ||
+            root.session_id !== expectedSessionId ||
+            !Array.isArray(root.sources)) {
+            throw new TypeError('root fields are invalid');
+        }
+        const findings = root.sources.map(parseFinding);
+        if (findings.length !== expectedSelections.length)
+            throw new TypeError('finding count differs');
+        for (let index = 0; index < findings.length; index++) {
+            const finding = findings[index];
+            const selection = expectedSelections[index];
+            if (finding === undefined ||
+                selection === undefined ||
+                finding.findingId !== selection.findingId ||
+                finding.artifactRef !== selection.artifactRef ||
+                finding.sessionId !== expectedSessionId) {
+                throw new TypeError('finding identity or order differs');
+            }
+        }
+        return findings;
+    }
+    catch (cause) {
+        throw new MarivoEnvironmentError('subprocess-output-invalid', 'Marivo Evidence reader returned an invalid Finding payload', { stdoutBytes: stdout.byteLength }, { cause });
+    }
+}
+/** Identity-checked adapter for exact persisted Marivo Findings. */
+export class MarivoEvidenceBridge {
+    binding;
+    #runner;
+    constructor(runner) {
+        this.#runner = runner;
+        this.binding = runner.binding;
+    }
+    async findings(sessionId, selections, signal) {
+        const result = await this.#runner.runChecked({
+            program: MARIVO_EVIDENCE_FINDINGS_PROGRAM,
+            args: [sessionId, JSON.stringify(selections)],
+            limits: EVIDENCE_LIMITS,
+            signal,
+        });
+        if (result.exitCode !== 0) {
+            throw new MarivoEnvironmentError('subprocess-failed', `Marivo Evidence read failed with exit code ${String(result.exitCode)}`, { exitCode: result.exitCode, stderr: result.stderr.toString('utf8').slice(0, 2_000) });
+        }
+        return parseFindingsPayload(result.stdout, sessionId, selections);
+    }
+}
+export function resolveMarivoEvidenceBridge(source) {
+    return resolveMarivoBridgeSource(source);
+}

package/lib/evidence/index.js

@@ -0,0 +1,2 @@
+export { MarivoEvidenceBridge, resolveMarivoEvidenceBridge, } from "./bridge.js";
+export { createMarivoEvidenceSourcesTool, evidenceSourcesMeta, installMarivoEvidenceSourcesCodeDelivery, MARIVO_EVIDENCE_SOURCES_DURABLE_CONTENT_KIND, MARIVO_EVIDENCE_SOURCES_MAX_PER_CALL, MARIVO_EVIDENCE_SOURCES_META_KIND, MARIVO_EVIDENCE_SOURCES_META_VERSION, MARIVO_EVIDENCE_SOURCES_TOOL_NAME, registerMarivoEvidenceSourcesTool, } from "./sources.js";