@lensmap/document 0.1.0 → 0.2.0

package/README.md

@@ -5,10 +5,10 @@ semantic graphs, revision-bound source bindings, session identities and bounded
 source-preserving content edits. Does not own layout, browser rendering or LSP.
 
 Requires Node 24.16 or newer. ESM only. The API and `version: v1` authoring format
-are incomplete and experimental; `0.1.x` is not a promise of a stable schema.
+are incomplete and experimental; `0.x` is not a promise of a stable schema.
 
 ```sh
-npm install @lensmap/document@next
+npm install @lensmap/document
 ```
 
 ```js

package/dist/index.d.ts

@@ -1,10 +1,22 @@
 import { z } from "zod";
-export type { LensmapDocument, Reference, RichNode } from "./v1/schema.js";
-export { DocumentSchema } from "./v1/schema.js";
+import { type ConnectionType } from "./v1/schema.js";
+export type { ConnectionType, LensmapDocument, Reference, RichNode, } from "./v1/schema.js";
+export { ConnectionTypeSchema, DocumentSchema } from "./v1/schema.js";
 export declare function generateJSONSchema(): z.core.ZodStandardJSONSchemaPayload<z.ZodObject<{
     version: z.ZodLiteral<"v1">;
+    frontmatter: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     nodes: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodType<import("./v1/schema.js").RichNode, unknown, z.core.$ZodTypeInternals<import("./v1/schema.js").RichNode, unknown>>]>>;
 }, z.core.$strict>>;
+/** Read the edge from the inspected endpoint, independently of structural kind. */
+export declare function connectionWording(type: ConnectionType | undefined, direction: "outgoing" | "incoming"): string;
+type AnchorThought = {
+    readonly key: string;
+    readonly id?: string;
+};
+/** Generated spelling is private to this rendered document version. */
+export declare function thoughtAnchors(nodes: readonly AnchorThought[]): Map<string, string>;
+/** The host decodes the fragment once before calling; authored names stay exact. */
+export declare function resolveThoughtAnchor(nodes: readonly AnchorThought[], decodedAnchor: string): string | undefined;
 export type SourcePosition = {
     line: number;
     character: number;
@@ -28,12 +40,17 @@ export type Thought = {
         y: number;
     };
     path: string;
+    destination?: {
+        kind: "map_link" | "external_link";
+        url: string;
+    };
 };
 export type Connection = {
     key: string;
     from: string;
     to: string;
     kind: "branch" | "cross";
+    type?: ConnectionType;
     path: string;
 };
 export type SemanticGraph = {
@@ -51,6 +68,7 @@ export type Diagnostic = {
     range: SourceRange;
 };
 export type DocumentSnapshot = {
+    attachmentId?: string;
     uri: string;
     revision: number;
     analyzedRevision: number | null;
@@ -80,6 +98,7 @@ export declare function positionToOffset(source: string, position: SourcePositio
 export declare function offsetToPosition(source: string, offset: number): SourcePosition;
 export declare class DocumentSession {
     readonly uri: string;
+    private readonly attachmentId;
     private text;
     private version;
     private state;

package/dist/index.js

@@ -1,10 +1,58 @@
 import { isAlias, isMap, isScalar, parseDocument } from "yaml";
 import { z } from "zod";
 import { DocumentSchema, } from "./v1/schema.js";
-export { DocumentSchema } from "./v1/schema.js";
+export { ConnectionTypeSchema, DocumentSchema } from "./v1/schema.js";
 export function generateJSONSchema() {
     return z.toJSONSchema(DocumentSchema, { io: "input" });
 }
+/** Read the edge from the inspected endpoint, independently of structural kind. */
+export function connectionWording(type, direction) {
+    switch (type) {
+        case "precedes":
+            return direction === "outgoing" ? "precedes" : "follows";
+        case "follows":
+            return direction === "outgoing" ? "follows" : "precedes";
+        case "prevents":
+            return direction === "outgoing" ? "prevents" : "is prevented by";
+        case "optional":
+            return "optionally connected to";
+        case "map_link":
+            return direction === "outgoing" ? "links to map" : "map linked from";
+        case "external_link":
+            return direction === "outgoing"
+                ? "links to resource"
+                : "resource linked from";
+        default:
+            return "connected to";
+    }
+}
+/** Generated spelling is private to this rendered document version. */
+export function thoughtAnchors(nodes) {
+    const reserved = new Set(nodes.flatMap((node) => (node.id === undefined ? [] : [node.id])));
+    const anchors = new Map();
+    for (const node of nodes) {
+        if (node.id !== undefined) {
+            anchors.set(node.key, node.id);
+            continue;
+        }
+        const base = `thought-${node.key}`;
+        let anchor = base;
+        let suffix = 0;
+        while (reserved.has(anchor))
+            anchor = `${base}-${++suffix}`;
+        reserved.add(anchor);
+        anchors.set(node.key, anchor);
+    }
+    return anchors;
+}
+/** The host decodes the fragment once before calling; authored names stay exact. */
+export function resolveThoughtAnchor(nodes, decodedAnchor) {
+    for (const [key, anchor] of thoughtAnchors(nodes))
+        if (anchor === decodedAnchor)
+            return key;
+    return undefined;
+}
+let attachmentSerial = 0;
 export class ContentEditError extends Error {
     code;
     constructor(code, message) {
@@ -45,6 +93,7 @@ function rejectCycles(value, ancestors = new Set()) {
 }
 export class DocumentSession {
     uri;
+    attachmentId = `attachment:${++attachmentSerial}`;
     text;
     version;
     state;
@@ -57,6 +106,7 @@ export class DocumentSession {
         this.version = revision;
         this.state = {
             uri,
+            attachmentId: this.attachmentId,
             revision,
             analyzedRevision: null,
             graphRevision: null,
@@ -111,8 +161,27 @@ export class DocumentSession {
             const input = doc.toJS();
             rejectCycles(input);
             const result = DocumentSchema.safeParse(input);
-            if (!result.success)
-                throw new Error(z.prettifyError(result.error));
+            if (!result.success) {
+                // Union alternatives report their paths at the union boundary. Locate
+                // a concrete failing field in the source, not an unrelated line zero.
+                const leaves = (issues, prefix = []) => issues.flatMap((issue) => {
+                    const path = [...prefix, ...issue.path];
+                    return issue.code === "invalid_union"
+                        ? leaves(issue.errors.flat(), path)
+                        : [{ ...issue, path }];
+                });
+                const located = leaves(result.error.issues)
+                    .map((issue) => {
+                    const path = issue.path.filter((part) => typeof part !== "symbol");
+                    if (issue.code === "unrecognized_keys" && issue.keys[0])
+                        path.push(issue.keys[0]);
+                    const ast = doc.getIn(path, true);
+                    return { issue, path, offset: ast?.range?.[0] };
+                })
+                    .filter((item) => item.offset !== undefined)
+                    .sort((a, b) => b.path.length - a.path.length)[0];
+                throw Object.assign(new Error(located?.issue.message ?? z.prettifyError(result.error)), { offset: located?.offset ?? 0 });
+            }
             const records = [];
             const edges = [];
             const bindings = [];
@@ -157,6 +226,7 @@ export class DocumentSession {
                         refs.push({
                             from: parent,
                             id: entry.node_id,
+                            type: entry.type,
                             path: pathName,
                             span,
                         });
@@ -167,10 +237,17 @@ export class DocumentSession {
                     : Array.isArray(entry)
                         ? { full_text: null, connections: entry }
                         : entry;
-                const markdown = content.full_text ?? content.summary ?? "";
+                const destination = (content.type === "map_link" || content.type === "external_link") &&
+                    content.url !== undefined
+                    ? { kind: content.type, url: content.url }
+                    : undefined;
+                const fallback = content.summary === undefined && content.full_text === undefined
+                    ? (destination?.url ?? "")
+                    : "";
+                const markdown = content.full_text ?? content.summary ?? fallback;
                 const title = content.summary !== undefined
                     ? (content.summary ?? "")
-                    : (content.full_text ?? "").split(/\r?\n/, 1)[0];
+                    : (content.full_text ?? fallback).split(/\r?\n/, 1)[0];
                 const key = `thought:${++this.serial}`;
                 const thought = {
                     key,
@@ -180,6 +257,7 @@ export class DocumentSession {
                     unresolved: title.trim() === "",
                     position: content.position,
                     path: pathName,
+                    ...(destination ? { destination } : {}),
                 };
                 records.push({ thought, span, ast });
                 bindings.push({ key, kind: "definition", span });
@@ -194,6 +272,7 @@ export class DocumentSession {
                         from: parent,
                         to: key,
                         kind: "branch",
+                        ...(content.type !== undefined ? { type: content.type } : {}),
                         path: pathName,
                     });
                 content.connections?.forEach((child, i) => {
@@ -257,7 +336,11 @@ export class DocumentSession {
             for (const ref of refs) {
                 const to = ids.get(ref.id);
                 if (!to)
-                    throw new Error(`${ref.path}.node_id: no node has id "${ref.id}".`);
+                    throw Object.assign(new Error(`${ref.path}.node_id: no node has id "${ref.id}".`), { offset: ref.span.start });
+                if ((ref.type === "map_link" || ref.type === "external_link") &&
+                    records.find((r) => r.thought.key === to)?.thought.destination
+                        ?.kind !== ref.type)
+                    throw Object.assign(new Error(`${ref.path}.type: reference requires a ${ref.type} destination.`), { offset: ref.span.start });
                 const endpoints = `${ref.from}:${to}`;
                 const occurrence = parallelReferences.get(endpoints) ?? 0;
                 parallelReferences.set(endpoints, occurrence + 1);
@@ -266,6 +349,7 @@ export class DocumentSession {
                     from: ref.from,
                     to,
                     kind: "cross",
+                    ...(ref.type !== undefined ? { type: ref.type } : {}),
                     path: ref.path,
                 });
                 bindings.push({
@@ -279,6 +363,7 @@ export class DocumentSession {
             this.validSource = this.text;
             this.state = {
                 uri: this.uri,
+                attachmentId: this.attachmentId,
                 revision: this.version,
                 analyzedRevision: this.version,
                 graphRevision: this.version,

package/dist/v1/schema.d.ts

@@ -4,8 +4,27 @@ export declare const PositionSchema: z.ZodObject<{
     x: z.ZodNumber;
     y: z.ZodNumber;
 }, z.core.$strict>;
+export declare const ConnectionTypeSchema: z.ZodEnum<{
+    connected: "connected";
+    external_link: "external_link";
+    follows: "follows";
+    map_link: "map_link";
+    optional: "optional";
+    precedes: "precedes";
+    prevents: "prevents";
+}>;
+export type ConnectionType = z.infer<typeof ConnectionTypeSchema>;
 export declare const ReferenceSchema: z.ZodObject<{
     node_id: z.ZodString;
+    type: z.ZodOptional<z.ZodEnum<{
+        connected: "connected";
+        external_link: "external_link";
+        follows: "follows";
+        map_link: "map_link";
+        optional: "optional";
+        precedes: "precedes";
+        prevents: "prevents";
+    }>>;
 }, z.core.$strict>;
 declare const NodeContentSchema: z.ZodObject<{
     id: z.ZodOptional<z.ZodString>;
@@ -19,6 +38,8 @@ declare const NodeContentSchema: z.ZodObject<{
 export type Reference = z.infer<typeof ReferenceSchema>;
 export type RichNode = z.infer<typeof NodeContentSchema> & {
     connections?: Connection[];
+    type?: ConnectionType;
+    url?: string;
 };
 export type Connection = string | RichNode | Reference | Connection[];
 export declare const RichNodeSchema: z.ZodType<RichNode>;
@@ -26,6 +47,7 @@ export declare const ConnectionSchema: z.ZodType<Connection>;
 export declare const NodeSchema: z.ZodUnion<readonly [z.ZodString, z.ZodType<RichNode, unknown, z.core.$ZodTypeInternals<RichNode, unknown>>]>;
 export declare const DocumentSchema: z.ZodObject<{
     version: z.ZodLiteral<"v1">;
+    frontmatter: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     nodes: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodType<RichNode, unknown, z.core.$ZodTypeInternals<RichNode, unknown>>]>>;
 }, z.core.$strict>;
 export type LensmapDocument = z.infer<typeof DocumentSchema>;

package/dist/v1/schema.js

@@ -5,31 +5,63 @@ export const PositionSchema = z.strictObject({
     y: z.number().finite(),
 });
 const IdSchema = z.string().regex(/\S/, "An ID must not be empty.");
-export const ReferenceSchema = z.strictObject({ node_id: IdSchema });
+export const ConnectionTypeSchema = z.enum([
+    "connected",
+    "precedes",
+    "follows",
+    "prevents",
+    "optional",
+    "external_link",
+    "map_link",
+]);
+const LocalTypeSchema = z.enum([
+    "connected",
+    "precedes",
+    "follows",
+    "prevents",
+    "optional",
+]);
+export const ReferenceSchema = z.strictObject({
+    node_id: IdSchema,
+    type: ConnectionTypeSchema.optional(),
+});
 const NodeContentSchema = z.strictObject({
     id: IdSchema.optional(),
     summary: z.string().nullable().optional(),
     full_text: z.string().nullable().optional(),
     position: PositionSchema.optional(),
 });
-export const RichNodeSchema = z.lazy(() => z.union([
-    NodeContentSchema.extend({
-        summary: z.string().nullable(),
-        connections: z.array(ConnectionSchema).optional(),
-    }),
-    NodeContentSchema.extend({
-        full_text: z.string().nullable(),
-        connections: z.array(ConnectionSchema).optional(),
-    }),
-]));
+const ordinary = (typed) => {
+    const base = typed
+        ? NodeContentSchema.extend({ type: LocalTypeSchema.optional() })
+        : NodeContentSchema;
+    return z.union([
+        base.extend({
+            summary: z.string().nullable(),
+            connections: z.array(ConnectionSchema).optional(),
+        }),
+        base.extend({
+            full_text: z.string().nullable(),
+            connections: z.array(ConnectionSchema).optional(),
+        }),
+    ]);
+};
+const portal = () => NodeContentSchema.extend({
+    type: z.enum(["map_link", "external_link"]),
+    url: z.string().regex(/\S/, "A portal URL must not be blank."),
+    connections: z.array(ConnectionSchema).optional(),
+});
+export const RichNodeSchema = z.lazy(() => z.union([ordinary(true), portal()]));
+const RootNodeSchema = z.lazy(() => z.union([ordinary(false), portal()]));
 export const ConnectionSchema = z.lazy(() => z.union([
     z.string(),
     ReferenceSchema,
     RichNodeSchema,
     z.array(ConnectionSchema),
 ]));
-export const NodeSchema = z.union([z.string(), RichNodeSchema]);
+export const NodeSchema = z.union([z.string(), RootNodeSchema]);
 export const DocumentSchema = z.strictObject({
     version: z.literal("v1"),
+    frontmatter: z.record(z.string(), z.unknown()).optional(),
     nodes: z.array(NodeSchema),
 });

package/package.json

@@ -2,13 +2,13 @@
   "name": "@lensmap/document",
   "license": "MIT",
   "description": "Experimental Lensmap document engine: YAML analysis, semantic graphs and revision-bound source edits",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "files": [
     "dist"
   ],
   "publishConfig": {
     "access": "public",
-    "tag": "next",
+    "tag": "latest",
     "registry": "https://registry.npmjs.org/"
   },
   "repository": {
@@ -36,9 +36,9 @@
   },
   "devDependencies": {
     "@types/node": "24.19.2",
+    "ajv": "8.20.0",
     "typescript": "7.0.2",
-    "vitest": "5.1.0",
-    "ajv": "8.20.0"
+    "vitest": "5.1.0"
   },
   "scripts": {
     "build": "tsc",