omni-viewer-core 0.1.0

package/dist/parsers/hdf5/node.js

@@ -0,0 +1,95 @@
+import * as fs from 'node:fs';
+import { Hdf5Parser, formatFileSize } from './index.js';
+const EMPTY = new Uint8Array(0);
+/**
+ * File-descriptor-backed random-access reader for Node hosts such as VS Code.
+ * A 4 MiB LRU page cache keeps metadata traversal cheap without loading HDF5
+ * dataset payloads or the complete file into memory.
+ */
+export class Hdf5FileReader {
+    fd;
+    size;
+    static PAGE_BYTES = 64 * 1024;
+    static MAX_PAGES = 64;
+    cache = new Map();
+    closed = false;
+    constructor(fd, size) {
+        this.fd = fd;
+        this.size = size;
+    }
+    static open(filePath) {
+        const fd = fs.openSync(filePath, 'r');
+        try {
+            return new Hdf5FileReader(fd, fs.fstatSync(fd).size);
+        }
+        catch (error) {
+            fs.closeSync(fd);
+            throw error;
+        }
+    }
+    read(offset, length) {
+        if (this.closed)
+            throw new Error('HDF5 reader is closed');
+        const start = Math.max(0, offset);
+        const end = Math.min(offset + length, this.size);
+        if (end <= start)
+            return EMPTY;
+        const out = new Uint8Array(end - start);
+        let position = start;
+        while (position < end) {
+            const pageIndex = Math.floor(position / Hdf5FileReader.PAGE_BYTES);
+            const page = this.getPage(pageIndex);
+            const inPage = position - pageIndex * Hdf5FileReader.PAGE_BYTES;
+            const copyLength = Math.min(page.byteLength - inPage, end - position);
+            if (copyLength <= 0)
+                break;
+            out.set(page.subarray(inPage, inPage + copyLength), position - start);
+            position += copyLength;
+        }
+        return out;
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.cache.clear();
+        try {
+            fs.closeSync(this.fd);
+        }
+        catch {
+            // Closing is best-effort and must not mask a parser failure.
+        }
+    }
+    getPage(pageIndex) {
+        const cached = this.cache.get(pageIndex);
+        if (cached) {
+            this.cache.delete(pageIndex);
+            this.cache.set(pageIndex, cached);
+            return cached;
+        }
+        const start = pageIndex * Hdf5FileReader.PAGE_BYTES;
+        const length = Math.min(Hdf5FileReader.PAGE_BYTES, this.size - start);
+        if (length <= 0)
+            return EMPTY;
+        const page = new Uint8Array(length);
+        const bytesRead = fs.readSync(this.fd, page, 0, length, start);
+        const value = bytesRead === length ? page : page.subarray(0, bytesRead);
+        if (this.cache.size >= Hdf5FileReader.MAX_PAGES) {
+            const oldest = this.cache.keys().next().value;
+            if (oldest !== undefined)
+                this.cache.delete(oldest);
+        }
+        this.cache.set(pageIndex, value);
+        return value;
+    }
+}
+/** Parse an HDF5 file without loading dataset payloads into memory. */
+export function parseHdf5File(filePath, fileSize) {
+    const reader = Hdf5FileReader.open(filePath);
+    try {
+        return Hdf5Parser.parseReader(reader, fileSize ?? formatFileSize(reader.size));
+    }
+    finally {
+        reader.close();
+    }
+}

package/dist/parsers/json/index.d.ts

@@ -0,0 +1,15 @@
+import type { ParseOptions, ParseOutcome } from '../types.js';
+import type { JsonDocument } from './model.js';
+export type { JsonDocument, JsonNode, JsonValueKind } from './model.js';
+export { appendPath, decodeJsonString, encodeJsonString } from './model.js';
+export { tokenizeJson } from './tokenizer.js';
+export type { JsonToken, JsonTokenKind } from './tokenizer.js';
+export { parseJsonDocument, JSON_DEFAULT_MAX_DEPTH } from './parse.js';
+export type { JsonParseTree, ParseTreeOptions } from './parse.js';
+export interface JsonParseOptions extends ParseOptions {
+    /** Nesting depth cap (default JSON_DEFAULT_MAX_DEPTH) — deep-nesting defense. */
+    maxDepth?: number;
+}
+/** Input ownership: borrows the input; the caller keeps the bytes (DESIGN §3-①). */
+export declare const JSON_INPUT_OWNERSHIP: "borrows";
+export declare function parseJson(input: Uint8Array | string, options?: JsonParseOptions): ParseOutcome<JsonDocument>;

package/dist/parsers/json/index.js

@@ -0,0 +1,102 @@
+// JSON parser entry — the core contract surface (DESIGN.md §3-①, J1 = 원문
+// 보존 토크나이저). parseJson(bytes or text) -> ParseOutcome<JsonDocument>.
+// Input-caused failures never throw; limits stop with `partial` + a diagnostic;
+// a syntax error yields the recovered prefix as `partial` (or `failed` if
+// nothing parsed) while the source text stays available for the verbatim view.
+import { DEFAULT_LIMITS, LimitTracker, decodeUtf8, utf8ByteLength } from '../types.js';
+import { JSON_DEFAULT_MAX_DEPTH, parseJsonDocument } from './parse.js';
+export { appendPath, decodeJsonString, encodeJsonString } from './model.js';
+export { tokenizeJson } from './tokenizer.js';
+export { parseJsonDocument, JSON_DEFAULT_MAX_DEPTH } from './parse.js';
+/** Input ownership: borrows the input; the caller keeps the bytes (DESIGN §3-①). */
+export const JSON_INPUT_OWNERSHIP = 'borrows';
+/** How often (in nodes) the cooperative abort/time checkpoint runs. */
+const CHECKPOINT_INTERVAL = 256;
+export function parseJson(input, options = {}) {
+    const started = Date.now();
+    const limits = { ...DEFAULT_LIMITS, ...options.limits };
+    const diagnostics = [];
+    const finish = (result) => ({
+        result,
+        execution: {
+            workerUsed: false,
+            hardLimitEnforced: false,
+            elapsedMillis: Date.now() - started
+        }
+    });
+    const inputBytes = typeof input === 'string' ? utf8ByteLength(input) : input.byteLength;
+    if (inputBytes > limits.maxInputBytes) {
+        return finish({
+            status: 'failed',
+            failure: {
+                code: 'limit-exceeded',
+                retryable: false,
+                messageKey: 'diag.limit-exceeded.input',
+                args: { maxBytes: limits.maxInputBytes }
+            },
+            diagnostics
+        });
+    }
+    if (options.signal?.aborted) {
+        return finish({
+            status: 'failed',
+            failure: { code: 'aborted', retryable: true, messageKey: 'diag.aborted' },
+            diagnostics
+        });
+    }
+    const text = typeof input === 'string' ? input : decodeUtf8(input);
+    const tracker = new LimitTracker(limits, options.signal);
+    const onNode = () => {
+        tracker.addEntries(1);
+        const count = tracker.entryCount;
+        // Amortize the abort/time checks; always enforce the node cap.
+        if (count % CHECKPOINT_INTERVAL !== 0 && count <= limits.maxEntries) {
+            return null;
+        }
+        const violation = tracker.checkpoint();
+        if (!violation)
+            return null;
+        return violation.kind === 'aborted' ? 'abort' : 'limit';
+    };
+    const tree = parseJsonDocument(text, {
+        maxDepth: options.maxDepth ?? JSON_DEFAULT_MAX_DEPTH,
+        onNode
+    });
+    diagnostics.push(...tree.diagnostics);
+    // Cancellation is a failure regardless of how much parsed (parity with csv).
+    if (tree.stopped && tree.stopReason === 'abort') {
+        return finish({
+            status: 'failed',
+            failure: { code: 'aborted', retryable: true, messageKey: 'diag.aborted' },
+            diagnostics
+        });
+    }
+    // Nothing recovered — the verbatim view falls back to the raw bytes (J20),
+    // so the viewer still shows the source; the model result is `failed`.
+    if (!tree.root) {
+        return finish({
+            status: 'failed',
+            failure: {
+                code: 'invalid-format',
+                retryable: false,
+                messageKey: 'diag.json.invalid'
+            },
+            diagnostics
+        });
+    }
+    const document = { root: tree.root, text };
+    if (tree.stopped && tree.stopReason === 'limit') {
+        diagnostics.push({
+            severity: 'warning',
+            code: 'limit-exceeded',
+            messageKey: 'diag.limit-exceeded.nodes',
+            args: { count: tracker.entryCount }
+        });
+        return finish({ status: 'partial', document, diagnostics });
+    }
+    // A syntax error or trailing content means we recovered only a prefix.
+    if (tree.errored || tree.trailing) {
+        return finish({ status: 'partial', document, diagnostics });
+    }
+    return finish({ status: 'ok', document, diagnostics });
+}

package/dist/parsers/json/model.d.ts

@@ -0,0 +1,42 @@
+export type JsonValueKind = 'object' | 'array' | 'string' | 'number' | 'boolean' | 'null';
+export interface JsonNode {
+    kind: JsonValueKind;
+    /** Key within the parent object, array index as a string, or '$' for root. */
+    key: string;
+    /** JSONPath from the root, e.g. '$.a.b[0]' or '$["odd key"]'. */
+    path: string;
+    depth: number;
+    /** object/array only — ordered children; duplicate object keys are kept. */
+    children?: JsonNode[];
+    /** primitive value: decoded string, boolean, or null. Numbers use rawNumber. */
+    value?: string | boolean | null;
+    /** number only — the verbatim token (e.g. "1e400", big ints), no rounding. */
+    rawNumber?: string;
+    /** [start, end) char range in the source text (verbatim slice / error locus). */
+    span: {
+        start: number;
+        end: number;
+    };
+}
+export interface JsonDocument {
+    root: JsonNode;
+    /** Decoded source text; also lets a failed parse still show the source (J20). */
+    text: string;
+}
+/**
+ * Build a child JSONPath (parity with web JsonViewer.appendPath): identifier
+ * keys use dot notation, everything else uses bracket-quoted notation.
+ */
+export declare function appendPath(parent: string, key: string, isArrayItem: boolean): string;
+/**
+ * Encode a string as a JSON string literal (with surrounding quotes),
+ * deterministically and without JSON.stringify (ADR 41). Used for bracket
+ * path keys and, later, re-serialization.
+ */
+export declare function encodeJsonString(value: string): string;
+/**
+ * Decode a JSON string literal (including its surrounding quotes) to its text
+ * value. Deterministic, never throws — malformed escapes fall back to the
+ * literal characters so a recovered/partial parse still yields a usable value.
+ */
+export declare function decodeJsonString(raw: string): string;

package/dist/parsers/json/model.js

@@ -0,0 +1,140 @@
+// JSON document model (docs/parsers/json.md, J1 = 원문 보존 토크나이저).
+//
+// Preserves the fidelity JSON.parse loses: raw number text (no float64
+// rounding), duplicate object keys (kept in order), and source char spans so
+// the verbatim source view and error loci can slice the original text.
+const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
+/**
+ * Build a child JSONPath (parity with web JsonViewer.appendPath): identifier
+ * keys use dot notation, everything else uses bracket-quoted notation.
+ */
+export function appendPath(parent, key, isArrayItem) {
+    if (isArrayItem)
+        return `${parent}[${key}]`;
+    return IDENTIFIER.test(key)
+        ? `${parent}.${key}`
+        : `${parent}[${encodeJsonString(key)}]`;
+}
+/**
+ * Encode a string as a JSON string literal (with surrounding quotes),
+ * deterministically and without JSON.stringify (ADR 41). Used for bracket
+ * path keys and, later, re-serialization.
+ */
+export function encodeJsonString(value) {
+    let out = '"';
+    for (let i = 0; i < value.length; i++) {
+        const ch = value.charCodeAt(i);
+        switch (ch) {
+            case 0x22:
+                out += '\\"';
+                break;
+            case 0x5c:
+                out += '\\\\';
+                break;
+            case 0x08:
+                out += '\\b';
+                break;
+            case 0x0c:
+                out += '\\f';
+                break;
+            case 0x0a:
+                out += '\\n';
+                break;
+            case 0x0d:
+                out += '\\r';
+                break;
+            case 0x09:
+                out += '\\t';
+                break;
+            default:
+                if (ch < 0x20) {
+                    out += '\\u' + ch.toString(16).padStart(4, '0');
+                }
+                else {
+                    out += value[i];
+                }
+        }
+    }
+    return out + '"';
+}
+/**
+ * Decode a JSON string literal (including its surrounding quotes) to its text
+ * value. Deterministic, never throws — malformed escapes fall back to the
+ * literal characters so a recovered/partial parse still yields a usable value.
+ */
+export function decodeJsonString(raw) {
+    // Strip surrounding quotes if present (the scanner may hand us an
+    // unterminated literal on recovery).
+    let start = 0;
+    let end = raw.length;
+    if (raw.charCodeAt(0) === 0x22)
+        start = 1;
+    if (end > start && raw.charCodeAt(end - 1) === 0x22)
+        end -= 1;
+    let out = '';
+    let i = start;
+    while (i < end) {
+        const ch = raw.charCodeAt(i);
+        if (ch !== 0x5c /* \ */) {
+            out += raw[i];
+            i++;
+            continue;
+        }
+        const next = raw[i + 1];
+        if (next === undefined) {
+            out += '\\';
+            break;
+        }
+        switch (next) {
+            case '"':
+                out += '"';
+                i += 2;
+                break;
+            case '\\':
+                out += '\\';
+                i += 2;
+                break;
+            case '/':
+                out += '/';
+                i += 2;
+                break;
+            case 'b':
+                out += '\b';
+                i += 2;
+                break;
+            case 'f':
+                out += '\f';
+                i += 2;
+                break;
+            case 'n':
+                out += '\n';
+                i += 2;
+                break;
+            case 'r':
+                out += '\r';
+                i += 2;
+                break;
+            case 't':
+                out += '\t';
+                i += 2;
+                break;
+            case 'u': {
+                const hex = raw.slice(i + 2, i + 6);
+                if (/^[0-9a-fA-F]{4}$/.test(hex)) {
+                    out += String.fromCharCode(parseInt(hex, 16));
+                    i += 6;
+                }
+                else {
+                    out += '\\u';
+                    i += 2;
+                }
+                break;
+            }
+            default:
+                // Unknown escape — keep it literal (lossless for recovery).
+                out += next;
+                i += 2;
+        }
+    }
+    return out;
+}

package/dist/parsers/json/parse.d.ts

@@ -0,0 +1,22 @@
+import type { Diagnostic } from '../types.js';
+import { type JsonNode } from './model.js';
+/** Reason a checkpoint asked the parser to stop. */
+export type StopReason = 'abort' | 'limit';
+export interface ParseTreeOptions {
+    maxDepth?: number;
+    /** Called once per node; return a stop reason to halt, or null to continue. */
+    onNode?: () => StopReason | null;
+}
+export interface JsonParseTree {
+    root: JsonNode | null;
+    diagnostics: Diagnostic[];
+    /** A checkpoint (abort/limit) halted parsing. */
+    stopped: boolean;
+    stopReason: StopReason | null;
+    /** A syntax error prevented a complete parse. */
+    errored: boolean;
+    /** Non-whitespace content followed the top-level value. */
+    trailing: boolean;
+}
+export declare const JSON_DEFAULT_MAX_DEPTH = 500;
+export declare function parseJsonDocument(text: string, options?: ParseTreeOptions): JsonParseTree;