worldorbit 2.5.2

package/packages/core/dist/draft-parse.js

@@ -0,0 +1,642 @@
+import { WorldOrbitError } from "./errors.js";
+import { normalizeDocument } from "./normalize.js";
+import { getFieldSchema, isKnownFieldKey, WORLDORBIT_OBJECT_TYPES } from "./schema.js";
+import { getIndent, tokenizeLineDetailed } from "./tokenize.js";
+import { validateDocument } from "./validate.js";
+export function parseWorldOrbitAtlas(source) {
+    return parseAtlasSource(source, "2.0");
+}
+export function parseWorldOrbitDraft(source) {
+    return parseAtlasSource(source, "2.0-draft");
+}
+function parseAtlasSource(source, outputVersion) {
+    const lines = source.split(/\r?\n/);
+    let sawSchemaHeader = false;
+    let schemaVersion = "2.0";
+    let system = null;
+    let section = null;
+    const objectNodes = [];
+    let sawDefaults = false;
+    let sawAtlas = false;
+    const viewpointIds = new Set();
+    const annotationIds = new Set();
+    for (let index = 0; index < lines.length; index++) {
+        const rawLine = lines[index];
+        const lineNumber = index + 1;
+        if (!rawLine.trim()) {
+            continue;
+        }
+        const indent = getIndent(rawLine);
+        const tokens = tokenizeLineDetailed(rawLine.slice(indent), {
+            line: lineNumber,
+            columnOffset: indent,
+        });
+        if (tokens.length === 0) {
+            continue;
+        }
+        if (!sawSchemaHeader) {
+            schemaVersion = assertDraftSchemaHeader(tokens, lineNumber);
+            sawSchemaHeader = true;
+            continue;
+        }
+        if (indent === 0) {
+            section = startTopLevelSection(tokens, lineNumber, system, objectNodes, viewpointIds, annotationIds, {
+                sawDefaults,
+                sawAtlas,
+            });
+            if (section.kind === "system") {
+                system = section.system;
+            }
+            else if (section.kind === "defaults") {
+                sawDefaults = true;
+            }
+            else if (section.kind === "atlas") {
+                sawAtlas = true;
+            }
+            continue;
+        }
+        if (!section) {
+            throw new WorldOrbitError("Indented line without parent atlas section", lineNumber, indent + 1);
+        }
+        handleSectionLine(section, indent, tokens, lineNumber);
+    }
+    if (!sawSchemaHeader) {
+        throw new WorldOrbitError('Missing required atlas schema header "schema 2.0"');
+    }
+    const ast = {
+        type: "document",
+        objects: objectNodes,
+    };
+    const normalizedObjects = normalizeDocument(ast).objects;
+    validateDocument({
+        format: "worldorbit",
+        version: "1.0",
+        system: null,
+        objects: normalizedObjects,
+    });
+    const diagnostics = schemaVersion === "2.0-draft" && outputVersion === "2.0"
+        ? [
+            {
+                code: "load.schema.deprecatedDraft",
+                severity: "warning",
+                source: "upgrade",
+                message: 'Source header "schema 2.0-draft" is deprecated; canonical v2 documents now use "schema 2.0".',
+            },
+        ]
+        : [];
+    return {
+        format: "worldorbit",
+        version: outputVersion,
+        sourceVersion: "1.0",
+        system,
+        objects: normalizedObjects,
+        diagnostics,
+    };
+}
+function assertDraftSchemaHeader(tokens, line) {
+    if (tokens.length !== 2 ||
+        tokens[0].value.toLowerCase() !== "schema" ||
+        (tokens[1].value.toLowerCase() !== "2.0-draft" &&
+            tokens[1].value.toLowerCase() !== "2.0")) {
+        throw new WorldOrbitError('Expected atlas header "schema 2.0" or legacy "schema 2.0-draft"', line, tokens[0]?.column ?? 1);
+    }
+    return tokens[1].value.toLowerCase() === "2.0-draft" ? "2.0-draft" : "2.0";
+}
+function startTopLevelSection(tokens, line, system, objectNodes, viewpointIds, annotationIds, flags) {
+    const keyword = tokens[0]?.value.toLowerCase();
+    switch (keyword) {
+        case "system":
+            if (system) {
+                throw new WorldOrbitError('Atlas section "system" may only appear once', line, tokens[0].column);
+            }
+            return startSystemSection(tokens, line);
+        case "defaults":
+            if (!system) {
+                throw new WorldOrbitError('Atlas section "defaults" requires a preceding system declaration', line, tokens[0].column);
+            }
+            if (flags.sawDefaults) {
+                throw new WorldOrbitError('Atlas section "defaults" may only appear once', line, tokens[0].column);
+            }
+            return {
+                kind: "defaults",
+                system,
+                seenFields: new Set(),
+            };
+        case "atlas":
+            if (!system) {
+                throw new WorldOrbitError('Atlas section "atlas" requires a preceding system declaration', line, tokens[0].column);
+            }
+            if (flags.sawAtlas) {
+                throw new WorldOrbitError('Atlas section "atlas" may only appear once', line, tokens[0].column);
+            }
+            return {
+                kind: "atlas",
+                system,
+                inMetadata: false,
+                metadataIndent: null,
+            };
+        case "viewpoint":
+            if (!system) {
+                throw new WorldOrbitError('Atlas section "viewpoint" requires a preceding system declaration', line, tokens[0].column);
+            }
+            return startViewpointSection(tokens, line, system, viewpointIds);
+        case "annotation":
+            if (!system) {
+                throw new WorldOrbitError('Atlas section "annotation" requires a preceding system declaration', line, tokens[0].column);
+            }
+            return startAnnotationSection(tokens, line, system, annotationIds);
+        case "object":
+            return startObjectSection(tokens, line, objectNodes);
+        default:
+            throw new WorldOrbitError(`Unknown atlas section "${tokens[0]?.value ?? ""}"`, line, tokens[0]?.column ?? 1);
+    }
+}
+function startSystemSection(tokens, line) {
+    if (tokens.length !== 2) {
+        throw new WorldOrbitError("Invalid atlas system declaration", line, tokens[0]?.column ?? 1);
+    }
+    const system = {
+        type: "system",
+        id: tokens[1].value,
+        title: null,
+        defaults: {
+            view: "topdown",
+            scale: null,
+            units: null,
+            preset: null,
+            theme: null,
+        },
+        atlasMetadata: {},
+        viewpoints: [],
+        annotations: [],
+    };
+    return {
+        kind: "system",
+        system,
+        seenFields: new Set(),
+    };
+}
+function startViewpointSection(tokens, line, system, viewpointIds) {
+    if (tokens.length !== 2) {
+        throw new WorldOrbitError("Invalid viewpoint declaration", line, tokens[0]?.column ?? 1);
+    }
+    const id = normalizeIdentifier(tokens[1].value);
+    if (!id) {
+        throw new WorldOrbitError("Viewpoint id must not be empty", line, tokens[1].column);
+    }
+    if (viewpointIds.has(id)) {
+        throw new WorldOrbitError(`Duplicate viewpoint id "${id}"`, line, tokens[1].column);
+    }
+    const viewpoint = {
+        id,
+        label: humanizeIdentifier(id),
+        summary: "",
+        focusObjectId: null,
+        selectedObjectId: null,
+        projection: system.defaults.view,
+        preset: system.defaults.preset,
+        zoom: null,
+        rotationDeg: 0,
+        layers: {},
+        filter: null,
+    };
+    system.viewpoints.push(viewpoint);
+    viewpointIds.add(id);
+    return {
+        kind: "viewpoint",
+        viewpoint,
+        seenFields: new Set(),
+        inFilter: false,
+        filterIndent: null,
+        seenFilterFields: new Set(),
+    };
+}
+function startAnnotationSection(tokens, line, system, annotationIds) {
+    if (tokens.length !== 2) {
+        throw new WorldOrbitError("Invalid annotation declaration", line, tokens[0]?.column ?? 1);
+    }
+    const id = normalizeIdentifier(tokens[1].value);
+    if (!id) {
+        throw new WorldOrbitError("Annotation id must not be empty", line, tokens[1].column);
+    }
+    if (annotationIds.has(id)) {
+        throw new WorldOrbitError(`Duplicate annotation id "${id}"`, line, tokens[1].column);
+    }
+    const annotation = {
+        id,
+        label: humanizeIdentifier(id),
+        targetObjectId: null,
+        body: "",
+        tags: [],
+        sourceObjectId: null,
+    };
+    system.annotations.push(annotation);
+    annotationIds.add(id);
+    return {
+        kind: "annotation",
+        annotation,
+        seenFields: new Set(),
+    };
+}
+function startObjectSection(tokens, line, objectNodes) {
+    if (tokens.length < 3) {
+        throw new WorldOrbitError("Invalid atlas object declaration", line, tokens[0]?.column ?? 1);
+    }
+    const objectTypeToken = tokens[1];
+    const idToken = tokens[2];
+    const objectType = objectTypeToken.value;
+    if (!WORLDORBIT_OBJECT_TYPES.has(objectType) ||
+        objectType === "system") {
+        throw new WorldOrbitError(`Unknown object type "${objectTypeToken.value}"`, line, objectTypeToken.column);
+    }
+    const objectNode = {
+        type: "object",
+        objectType,
+        name: idToken.value,
+        inlineFields: parseInlineFields(tokens.slice(3), line),
+        blockFields: [],
+        infoEntries: [],
+        location: {
+            line,
+            column: objectTypeToken.column,
+        },
+    };
+    objectNodes.push(objectNode);
+    return {
+        kind: "object",
+        objectNode,
+        inInfoBlock: false,
+        infoIndent: null,
+    };
+}
+function handleSectionLine(section, indent, tokens, line) {
+    switch (section.kind) {
+        case "system":
+            applySystemField(section, tokens, line);
+            return;
+        case "defaults":
+            applyDefaultsField(section, tokens, line);
+            return;
+        case "atlas":
+            applyAtlasField(section, indent, tokens, line);
+            return;
+        case "viewpoint":
+            applyViewpointField(section, indent, tokens, line);
+            return;
+        case "annotation":
+            applyAnnotationField(section, tokens, line);
+            return;
+        case "object":
+            applyObjectField(section, indent, tokens, line);
+            return;
+    }
+}
+function applySystemField(section, tokens, line) {
+    const key = requireUniqueField(tokens, section.seenFields, line);
+    if (key !== "title") {
+        throw new WorldOrbitError(`Unknown system atlas field "${tokens[0].value}"`, line, tokens[0].column);
+    }
+    section.system.title = joinFieldValue(tokens, line);
+}
+function applyDefaultsField(section, tokens, line) {
+    const key = requireUniqueField(tokens, section.seenFields, line);
+    const value = joinFieldValue(tokens, line);
+    switch (key) {
+        case "view":
+            section.system.defaults.view = parseProjectionValue(value, line, tokens[0].column);
+            return;
+        case "scale":
+            section.system.defaults.scale = value;
+            return;
+        case "units":
+            section.system.defaults.units = value;
+            return;
+        case "preset":
+            section.system.defaults.preset = parsePresetValue(value, line, tokens[0].column);
+            return;
+        case "theme":
+            section.system.defaults.theme = value;
+            return;
+        default:
+            throw new WorldOrbitError(`Unknown defaults field "${tokens[0].value}"`, line, tokens[0].column);
+    }
+}
+function applyAtlasField(section, indent, tokens, line) {
+    if (section.inMetadata && indent <= (section.metadataIndent ?? 0)) {
+        section.inMetadata = false;
+        section.metadataIndent = null;
+    }
+    if (section.inMetadata) {
+        if (tokens.length < 2) {
+            throw new WorldOrbitError("Invalid atlas metadata entry", line, tokens[0]?.column ?? 1);
+        }
+        const key = tokens[0].value;
+        if (key in section.system.atlasMetadata) {
+            throw new WorldOrbitError(`Duplicate atlas metadata key "${key}"`, line, tokens[0].column);
+        }
+        section.system.atlasMetadata[key] = joinFieldValue(tokens, line);
+        return;
+    }
+    if (tokens.length === 1 && tokens[0].value.toLowerCase() === "metadata") {
+        section.inMetadata = true;
+        section.metadataIndent = indent;
+        return;
+    }
+    throw new WorldOrbitError(`Unknown atlas field "${tokens[0].value}"`, line, tokens[0].column);
+}
+function applyViewpointField(section, indent, tokens, line) {
+    if (section.inFilter && indent <= (section.filterIndent ?? 0)) {
+        section.inFilter = false;
+        section.filterIndent = null;
+    }
+    if (section.inFilter) {
+        applyViewpointFilterField(section, tokens, line);
+        return;
+    }
+    if (tokens.length === 1 && tokens[0].value.toLowerCase() === "filter") {
+        if (section.seenFields.has("filter")) {
+            throw new WorldOrbitError('Duplicate viewpoint field "filter"', line, tokens[0].column);
+        }
+        section.seenFields.add("filter");
+        section.inFilter = true;
+        section.filterIndent = indent;
+        return;
+    }
+    const key = requireUniqueField(tokens, section.seenFields, line);
+    const value = joinFieldValue(tokens, line);
+    switch (key) {
+        case "label":
+            section.viewpoint.label = value;
+            return;
+        case "summary":
+            section.viewpoint.summary = value;
+            return;
+        case "focus":
+            section.viewpoint.focusObjectId = value;
+            return;
+        case "select":
+            section.viewpoint.selectedObjectId = value;
+            return;
+        case "projection":
+            section.viewpoint.projection = parseProjectionValue(value, line, tokens[0].column);
+            return;
+        case "preset":
+            section.viewpoint.preset = parsePresetValue(value, line, tokens[0].column);
+            return;
+        case "zoom":
+            section.viewpoint.zoom = parsePositiveNumber(value, line, tokens[0].column, "zoom");
+            return;
+        case "rotation":
+            section.viewpoint.rotationDeg = parseFiniteNumber(value, line, tokens[0].column, "rotation");
+            return;
+        case "layers":
+            section.viewpoint.layers = parseLayerTokens(tokens.slice(1), line);
+            return;
+        default:
+            throw new WorldOrbitError(`Unknown viewpoint field "${tokens[0].value}"`, line, tokens[0].column);
+    }
+}
+function applyViewpointFilterField(section, tokens, line) {
+    const key = requireUniqueField(tokens, section.seenFilterFields, line);
+    const filter = section.viewpoint.filter ?? createEmptyViewpointFilter();
+    switch (key) {
+        case "query":
+            filter.query = joinFieldValue(tokens, line);
+            break;
+        case "objecttypes":
+            filter.objectTypes = parseObjectTypeTokens(tokens.slice(1), line);
+            break;
+        case "tags":
+            filter.tags = parseTokenList(tokens.slice(1), line, "tags");
+            break;
+        case "groups":
+            filter.groupIds = parseTokenList(tokens.slice(1), line, "groups");
+            break;
+        default:
+            throw new WorldOrbitError(`Unknown viewpoint filter field "${tokens[0].value}"`, line, tokens[0].column);
+    }
+    section.viewpoint.filter = filter;
+}
+function applyAnnotationField(section, tokens, line) {
+    const key = requireUniqueField(tokens, section.seenFields, line);
+    switch (key) {
+        case "label":
+            section.annotation.label = joinFieldValue(tokens, line);
+            return;
+        case "target":
+            section.annotation.targetObjectId = joinFieldValue(tokens, line);
+            return;
+        case "body":
+            section.annotation.body = joinFieldValue(tokens, line);
+            return;
+        case "tags":
+            section.annotation.tags = parseTokenList(tokens.slice(1), line, "tags");
+            return;
+        default:
+            throw new WorldOrbitError(`Unknown annotation field "${tokens[0].value}"`, line, tokens[0].column);
+    }
+}
+function applyObjectField(section, indent, tokens, line) {
+    if (tokens.length === 1 && tokens[0].value === "info") {
+        section.inInfoBlock = true;
+        section.infoIndent = indent;
+        return;
+    }
+    if (section.inInfoBlock && indent <= (section.infoIndent ?? 0)) {
+        section.inInfoBlock = false;
+        section.infoIndent = null;
+    }
+    if (section.inInfoBlock) {
+        section.objectNode.infoEntries.push(parseInfoEntry(tokens, line));
+        return;
+    }
+    section.objectNode.blockFields.push(parseField(tokens, line));
+}
+function requireUniqueField(tokens, seenFields, line) {
+    if (tokens.length < 2) {
+        throw new WorldOrbitError("Invalid atlas field line", line, tokens[0]?.column ?? 1);
+    }
+    const key = tokens[0].value.toLowerCase();
+    if (seenFields.has(key)) {
+        throw new WorldOrbitError(`Duplicate atlas field "${tokens[0].value}"`, line, tokens[0].column);
+    }
+    seenFields.add(key);
+    return key;
+}
+function joinFieldValue(tokens, line) {
+    if (tokens.length < 2) {
+        throw new WorldOrbitError("Missing value for atlas field", line, tokens[0]?.column ?? 1);
+    }
+    return tokens
+        .slice(1)
+        .map((token) => token.value)
+        .join(" ")
+        .trim();
+}
+function parseObjectTypeTokens(tokens, line) {
+    if (tokens.length === 0) {
+        throw new WorldOrbitError("Missing value for atlas field", line);
+    }
+    return tokens.map((token) => {
+        const value = token.value;
+        if (value !== "star" &&
+            value !== "planet" &&
+            value !== "moon" &&
+            value !== "belt" &&
+            value !== "asteroid" &&
+            value !== "comet" &&
+            value !== "ring" &&
+            value !== "structure" &&
+            value !== "phenomenon") {
+            throw new WorldOrbitError(`Unknown viewpoint object type "${token.value}"`, line, token.column);
+        }
+        return value;
+    });
+}
+function parseTokenList(tokens, line, field) {
+    if (tokens.length === 0) {
+        throw new WorldOrbitError(`Missing value for field "${field}"`, line);
+    }
+    return tokens.map((token) => token.value);
+}
+function parseLayerTokens(tokens, line) {
+    if (tokens.length === 0) {
+        throw new WorldOrbitError('Missing value for field "layers"', line);
+    }
+    const next = {};
+    for (const token of tokens) {
+        const enabled = !token.value.startsWith("-") && !token.value.startsWith("!");
+        const rawLayer = token.value.replace(/^[-!]+/, "").toLowerCase();
+        if (rawLayer === "orbits") {
+            next["orbits-back"] = enabled;
+            next["orbits-front"] = enabled;
+            continue;
+        }
+        if (rawLayer === "background" ||
+            rawLayer === "guides" ||
+            rawLayer === "orbits-back" ||
+            rawLayer === "orbits-front" ||
+            rawLayer === "objects" ||
+            rawLayer === "labels" ||
+            rawLayer === "metadata") {
+            next[rawLayer] = enabled;
+            continue;
+        }
+        throw new WorldOrbitError(`Unknown layer token "${token.value}"`, line, token.column);
+    }
+    return next;
+}
+function parseProjectionValue(value, line, column) {
+    const normalized = value.toLowerCase();
+    if (normalized === "topdown" || normalized === "isometric") {
+        return normalized;
+    }
+    throw new WorldOrbitError(`Unknown projection "${value}"`, line, column);
+}
+function parsePresetValue(value, line, column) {
+    const normalized = value.toLowerCase();
+    if (normalized === "diagram" ||
+        normalized === "presentation" ||
+        normalized === "atlas-card" ||
+        normalized === "markdown") {
+        return normalized;
+    }
+    throw new WorldOrbitError(`Unknown render preset "${value}"`, line, column);
+}
+function parsePositiveNumber(value, line, column, field) {
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw new WorldOrbitError(`Field "${field}" expects a positive number`, line, column);
+    }
+    return parsed;
+}
+function parseFiniteNumber(value, line, column, field) {
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed)) {
+        throw new WorldOrbitError(`Field "${field}" expects a finite number`, line, column);
+    }
+    return parsed;
+}
+function createEmptyViewpointFilter() {
+    return {
+        query: null,
+        objectTypes: [],
+        tags: [],
+        groupIds: [],
+    };
+}
+function parseInlineFields(tokens, line) {
+    const fields = [];
+    let index = 0;
+    while (index < tokens.length) {
+        const keyToken = tokens[index];
+        const schema = getFieldSchema(keyToken.value);
+        if (!schema) {
+            throw new WorldOrbitError(`Unknown field "${keyToken.value}"`, line, keyToken.column);
+        }
+        index++;
+        const valueTokens = [];
+        if (schema.arity === "multiple") {
+            while (index < tokens.length && !isKnownFieldKey(tokens[index].value)) {
+                valueTokens.push(tokens[index]);
+                index++;
+            }
+        }
+        else {
+            const nextToken = tokens[index];
+            if (nextToken) {
+                valueTokens.push(nextToken);
+                index++;
+            }
+        }
+        if (valueTokens.length === 0) {
+            throw new WorldOrbitError(`Missing value for field "${keyToken.value}"`, line, keyToken.column);
+        }
+        fields.push({
+            type: "field",
+            key: keyToken.value,
+            values: valueTokens.map((token) => token.value),
+            location: { line, column: keyToken.column },
+        });
+    }
+    return fields;
+}
+function parseField(tokens, line) {
+    if (tokens.length < 2) {
+        throw new WorldOrbitError("Invalid field line", line, tokens[0]?.column ?? 1);
+    }
+    if (!getFieldSchema(tokens[0].value)) {
+        throw new WorldOrbitError(`Unknown field "${tokens[0].value}"`, line, tokens[0].column);
+    }
+    return {
+        type: "field",
+        key: tokens[0].value,
+        values: tokens.slice(1).map((token) => token.value),
+        location: { line, column: tokens[0].column },
+    };
+}
+function parseInfoEntry(tokens, line) {
+    if (tokens.length < 2) {
+        throw new WorldOrbitError("Invalid info entry", line, tokens[0]?.column ?? 1);
+    }
+    return {
+        type: "info-entry",
+        key: tokens[0].value,
+        value: tokens.slice(1).map((token) => token.value).join(" "),
+        location: { line, column: tokens[0].column },
+    };
+}
+function normalizeIdentifier(value) {
+    return value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9_-]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+function humanizeIdentifier(value) {
+    return value
+        .split(/[-_]+/)
+        .filter(Boolean)
+        .map((segment) => segment[0].toUpperCase() + segment.slice(1))
+        .join(" ");
+}

package/packages/core/dist/draft.d.ts

@@ -0,0 +1,15 @@
+import type { SceneRenderOptions, WorldOrbitAtlasDocument, WorldOrbitAtlasSystem, WorldOrbitDiagnostic, WorldOrbitDocument, WorldOrbitObject } from "./types.js";
+interface UpgradeOptions extends Pick<SceneRenderOptions, "preset" | "projection"> {
+}
+export declare function upgradeDocumentToV2(document: WorldOrbitDocument, options?: UpgradeOptions): WorldOrbitAtlasDocument;
+export declare function upgradeDocumentToDraftV2(document: WorldOrbitDocument, options?: UpgradeOptions): {
+    version: "2.0-draft";
+    format: "worldorbit";
+    sourceVersion: import("./types.js").WorldOrbitDocumentVersion;
+    system: WorldOrbitAtlasSystem | null;
+    objects: WorldOrbitObject[];
+    diagnostics: WorldOrbitDiagnostic[];
+};
+export declare function materializeAtlasDocument(document: WorldOrbitAtlasDocument): WorldOrbitDocument;
+export declare function materializeDraftDocument(document: WorldOrbitAtlasDocument): WorldOrbitDocument;
+export {};