@hatua/document 0.0.0 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pedro Gomes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,36 @@
+import { WorkflowDefinition, workflowDefinition } from '@hatua/schema';
+import { Document } from 'yaml';
+export * from './lex';
+/**
+ * Owns the YAML document. This layer holds the source of truth (ADR-0001) —
+ * the parsed representation, not a typed object graph. Canvas edits and text
+ * edits both land here, so the user's comments, key order and style survive.
+ *
+ * There are two layers, and the distinction matters:
+ *
+ *   CST  — concrete syntax tree. Byte-exact: stringifying an unmodified CST
+ *          reproduces the input character for character, whitespace included.
+ *   AST  — the `Document` API. Ergonomic (getIn/setIn), and it preserves
+ *          comments, but it NORMALISES some whitespace: three spaces before an
+ *          inline comment come back as one.
+ *
+ * We keep both. Because Hatua does not own the file, an untouched document must
+ * come back byte-identical; once edited, the AST's serialisation is the best
+ * available and still keeps every comment.
+ */
+export interface WorkflowDocument {
+    /** Ergonomic view. Mutating it is how you edit the document. */
+    readonly ast: Document;
+    /**
+     * Typed projection. Throws if the document is not a valid Workflow
+     * Definition — use `validate()` first when the source may be malformed, and
+     * `toString()`/`ast` to drive Text Mode over a document that does not parse
+     * into a workflow yet.
+     */
+    toJSON(): WorkflowDefinition;
+    /** Non-throwing counterpart to `toJSON()`. */
+    validate(): ReturnType<typeof workflowDefinition.safeParse>;
+    /** Byte-identical to the input while untouched; comment-preserving once edited. */
+    toString(): string;
+}
+export declare function parseWorkflow(source: string): WorkflowDocument;

package/dist/index.js

@@ -0,0 +1,91 @@
+import { CST as e, Composer as t, Lexer as n, Parser as r } from "yaml";
+import { workflowDefinition as i } from "@hatua/schema";
+//#region src/lex.ts
+var a = (e) => e.charCodeAt(0) < 32 && e !== "\n" && e !== "	", o = /* @__PURE__ */ new Set([
+	":",
+	"-",
+	"?",
+	",",
+	"[",
+	"]",
+	"{",
+	"}",
+	"---",
+	"..."
+]), s = /* @__PURE__ */ new Set([
+	"true",
+	"false",
+	"True",
+	"False",
+	"TRUE",
+	"FALSE",
+	"yes",
+	"no",
+	"on",
+	"off"
+]), c = /* @__PURE__ */ new Set([
+	"null",
+	"Null",
+	"NULL",
+	"~"
+]), l = (e) => e.startsWith("\"") || e.startsWith("'") || e.startsWith("|") || e.startsWith(">") ? "string" : s.has(e) ? "boolean" : c.has(e) ? "null" : /^[-+]?(\d[\d_]*)(\.\d*)?([eE][-+]?\d+)?$/.test(e) || /^0[xob][\dA-Fa-f_]+$/.test(e) ? "number" : "scalar";
+function u(e) {
+	let t = [], r = 0, i = null, s = (e, n, r) => {
+		n > e && t.push({
+			from: e,
+			to: n,
+			kind: r
+		});
+	};
+	for (let c of new n().lex(e)) {
+		if (a(c)) continue;
+		let e = r;
+		r += c.length;
+		let n = r;
+		if (c.startsWith("#")) {
+			s(e, n, "comment"), i = null;
+			continue;
+		}
+		if (c.trim() === "") {
+			s(e, n, "space");
+			continue;
+		}
+		if (o.has(c)) {
+			if (c === ":" && i !== null) {
+				let e = t[i];
+				e && (e.kind = "key");
+			}
+			s(e, n, "punctuation"), i = null;
+			continue;
+		}
+		if (/^[&*!%]/.test(c)) {
+			s(e, n, "annotation"), i = null;
+			continue;
+		}
+		i = t.length, s(e, n, l(c));
+	}
+	return s(r, e.length, "scalar"), t;
+}
+//#endregion
+//#region src/index.ts
+function d(n) {
+	let a = [...new r().parse(n)], o = [...new t({ keepSourceTokens: !0 }).compose(a)], [s] = o;
+	if (!s) throw Error("No YAML document found in source");
+	if (o.length > 1) throw Error(`A Workflow Definition is a single YAML document; this source holds ${o.length}. Split the file, or edit it as text outside Hatua.`);
+	let c = String(s), l = a.map((t) => e.stringify(t)).join("");
+	return {
+		ast: s,
+		toString: () => {
+			let e = String(s);
+			return e === c ? l : e;
+		},
+		validate: () => i.safeParse(s.toJS()),
+		toJSON: () => {
+			let e = i.safeParse(s.toJS());
+			if (!e.success) throw Error(`Not a valid Workflow Definition: ${e.error.issues[0]?.message}`);
+			return e.data;
+		}
+	};
+}
+//#endregion
+export { u as lexYaml, d as parseWorkflow };

package/dist/lex.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The source text, split into the pieces a reader tells apart by eye.
+ *
+ * Here rather than in the renderer because this package owns the YAML seam:
+ * `yaml` is its dependency and its whole reason for existing is that nothing
+ * else has to know how a YAML document is taken apart. A second package
+ * importing the lexer would be a second answer to "what is this text made of".
+ *
+ * ## Why the lexer and not the parser
+ *
+ * `parseWorkflow` refuses a source it cannot compose, and refusing is right —
+ * there is nothing to edit through. But a reader typing in **Text Mode** spends
+ * most of their keystrokes on text that does not parse, and colour that flickered
+ * off between two valid states would be worse than no colour at all. A lexer has
+ * no such state: it splits what is there and says nothing about whether it means
+ * anything.
+ *
+ * ## Offsets rather than substrings
+ *
+ * The lexer yields the source in order, so the spans below reassemble it exactly.
+ * Handing back offsets keeps that checkable — `spans.map(text.slice)` IS the
+ * source — and lets a caller cut a span finer without re-lexing, which is what
+ * a **Template** inside a scalar needs.
+ */
+export type SpanKind = 
+/** A `#` comment, to the end of its line. */
+'comment'
+/** The scalar on the left of a `:`. */
+ | 'key'
+/** A quoted scalar, or a block scalar's body. */
+ | 'string' | 'number' | 'boolean' | 'null'
+/** An unquoted scalar that is none of the above. */
+ | 'scalar'
+/** `:`, `-`, `,`, brackets, braces, and the document markers. */
+ | 'punctuation'
+/** `&anchor`, `*alias`, `!!tag`, `%DIRECTIVE`. */
+ | 'annotation'
+/** Whitespace and newlines, carried so the spans reassemble the source. */
+ | 'space';
+export interface Span {
+    /** Index into the source, inclusive. */
+    from: number;
+    /** Index into the source, exclusive. */
+    to: number;
+    kind: SpanKind;
+}
+/**
+ * Split `source` into spans covering every character exactly once.
+ *
+ * A lexer error is not raised: `yaml`'s lexer is total over any string, and the
+ * point of using it here is that half-typed input has an answer. What it cannot
+ * classify comes back as `scalar`, which renders as ordinary text.
+ */
+export declare function lexYaml(source: string): Span[];

package/dist/lex.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/round-trip.test.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,17 +1,35 @@
 {
   "name": "@hatua/document",
-  "version": "0.0.0",
-  "description": "Placeholder reserving the name. Nothing is published here; see 0.1.0 and later.",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Internal to @hatua/react — published because it is an external of its build, not a supported API. Owns the YAML document: parse, surgical edit, serialise, source positions.",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pedromvgomes/hatua.git",
     "directory": "source/packages/document"
   },
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
   "publishConfig": {
     "access": "public"
   },
-  "files": [
-    "README.md"
-  ]
+  "dependencies": {
+    "yaml": "^2.8.1",
+    "@hatua/schema": "0.1.0"
+  },
+  "scripts": {
+    "build": "vite build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "test:coverage": "vitest run --coverage --coverage.reporter=text-summary --coverage.reporter=json-summary --coverage.reporter=lcovonly --passWithNoTests"
+  }
 }

package/README.md

@@ -1,5 +0,0 @@
-# @hatua/document
-
-This version reserves the package name and contains no code.
-
-Install `0.1.0` or later.