@glyphjs/ir 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,111 @@
+import { GlyphIR, Diagnostic, GlyphPatch, IRMigration } from '@glyphjs/types';
+
+/**
+ * Generates a content-addressed block ID.
+ *
+ * Returns `"b-"` + first 12 hex chars of SHA-256(documentId + blockType + SHA-256(content)).
+ */
+declare function generateBlockId(documentId: string, blockType: string, content: string): string;
+/**
+ * Generates a document ID from the given options.
+ *
+ * Priority:
+ * 1. If `glyphId` is present, return it directly.
+ * 2. If `filePath` is present, normalize to forward slashes and return.
+ * 3. If `content` is present, return `"doc-"` + first 16 hex chars of SHA-256(content).
+ */
+declare function generateDocumentId(options: {
+    glyphId?: string;
+    filePath?: string;
+    content?: string;
+}): string;
+/**
+ * Resolves duplicate block IDs by appending `-1`, `-2`, etc. to collisions.
+ *
+ * The first occurrence of an ID is left unchanged; subsequent duplicates
+ * receive numeric suffixes.
+ */
+declare function resolveBlockIdCollisions(ids: string[]): string[];
+
+/**
+ * Validates a GlyphIR document for structural integrity.
+ *
+ * Checks:
+ * - `version` is a non-empty string
+ * - `id` is a non-empty string
+ * - all block IDs are unique
+ * - all reference `sourceBlockId` / `targetBlockId` exist in blocks
+ * - blocks have required fields (`id`, `type`, `data`, `position`)
+ * - layout mode is valid
+ *
+ * Returns an array of `Diagnostic` objects describing any issues found.
+ */
+declare function validateIR(ir: GlyphIR): Diagnostic[];
+
+/**
+ * Computes a patch that transforms `before` into `after`.
+ *
+ * Compares blocks (added, removed, updated, moved), references (added, removed),
+ * metadata changes, and layout changes.
+ *
+ * Invariant: `applyPatch(before, diffIR(before, after))` deep-equals `after`.
+ */
+declare function diffIR(before: GlyphIR, after: GlyphIR): GlyphPatch;
+
+/**
+ * Applies a patch to an IR document, returning a new IR (immutable).
+ *
+ * Invariant: `applyPatch(ir, [])` returns `ir` unchanged (identity).
+ */
+declare function applyPatch(ir: GlyphIR, patch: GlyphPatch): GlyphIR;
+/**
+ * Composes two patches into a single patch.
+ *
+ * Simplistic but correct: concatenates the operations of `a` followed by `b`.
+ *
+ * Invariant: `composePatch` is associative —
+ * `compose(compose(a, b), c)` equals `compose(a, compose(b, c))`.
+ */
+declare function composePatch(a: GlyphPatch, b: GlyphPatch): GlyphPatch;
+
+/**
+ * Registers a migration that transforms IR from one version to another.
+ *
+ * Migrations are pure functions registered in `@glyphjs/ir`.
+ * They are applied in sequence by `migrateIR`.
+ */
+declare function registerMigration(migration: IRMigration): void;
+/**
+ * Migrates an IR document from its current version to the target version
+ * by applying registered migrations in sequence.
+ *
+ * Throws an error if:
+ * - The IR version is already at or ahead of the target version
+ *   and no migration path exists.
+ * - No migration is registered for a required intermediate version.
+ * - The target version is older than the current version (downgrade).
+ */
+declare function migrateIR(ir: GlyphIR, targetVersion: string): GlyphIR;
+/**
+ * Clears all registered migrations. Useful for testing.
+ */
+declare function clearMigrations(): void;
+
+/**
+ * Creates a valid empty GlyphIR document with default values.
+ *
+ * Returns:
+ * ```json
+ * {
+ *   "version": "1.0.0",
+ *   "id": id,
+ *   "metadata": {},
+ *   "blocks": [],
+ *   "references": [],
+ *   "layout": { "mode": "document", "spacing": "normal" }
+ * }
+ * ```
+ */
+declare function createEmptyIR(id: string): GlyphIR;
+
+export { applyPatch, clearMigrations, composePatch, createEmptyIR, diffIR, generateBlockId, generateDocumentId, migrateIR, registerMigration, resolveBlockIdCollisions, validateIR };

package/dist/index.d.ts

@@ -0,0 +1,111 @@
+import { GlyphIR, Diagnostic, GlyphPatch, IRMigration } from '@glyphjs/types';
+
+/**
+ * Generates a content-addressed block ID.
+ *
+ * Returns `"b-"` + first 12 hex chars of SHA-256(documentId + blockType + SHA-256(content)).
+ */
+declare function generateBlockId(documentId: string, blockType: string, content: string): string;
+/**
+ * Generates a document ID from the given options.
+ *
+ * Priority:
+ * 1. If `glyphId` is present, return it directly.
+ * 2. If `filePath` is present, normalize to forward slashes and return.
+ * 3. If `content` is present, return `"doc-"` + first 16 hex chars of SHA-256(content).
+ */
+declare function generateDocumentId(options: {
+    glyphId?: string;
+    filePath?: string;
+    content?: string;
+}): string;
+/**
+ * Resolves duplicate block IDs by appending `-1`, `-2`, etc. to collisions.
+ *
+ * The first occurrence of an ID is left unchanged; subsequent duplicates
+ * receive numeric suffixes.
+ */
+declare function resolveBlockIdCollisions(ids: string[]): string[];
+
+/**
+ * Validates a GlyphIR document for structural integrity.
+ *
+ * Checks:
+ * - `version` is a non-empty string
+ * - `id` is a non-empty string
+ * - all block IDs are unique
+ * - all reference `sourceBlockId` / `targetBlockId` exist in blocks
+ * - blocks have required fields (`id`, `type`, `data`, `position`)
+ * - layout mode is valid
+ *
+ * Returns an array of `Diagnostic` objects describing any issues found.
+ */
+declare function validateIR(ir: GlyphIR): Diagnostic[];
+
+/**
+ * Computes a patch that transforms `before` into `after`.
+ *
+ * Compares blocks (added, removed, updated, moved), references (added, removed),
+ * metadata changes, and layout changes.
+ *
+ * Invariant: `applyPatch(before, diffIR(before, after))` deep-equals `after`.
+ */
+declare function diffIR(before: GlyphIR, after: GlyphIR): GlyphPatch;
+
+/**
+ * Applies a patch to an IR document, returning a new IR (immutable).
+ *
+ * Invariant: `applyPatch(ir, [])` returns `ir` unchanged (identity).
+ */
+declare function applyPatch(ir: GlyphIR, patch: GlyphPatch): GlyphIR;
+/**
+ * Composes two patches into a single patch.
+ *
+ * Simplistic but correct: concatenates the operations of `a` followed by `b`.
+ *
+ * Invariant: `composePatch` is associative —
+ * `compose(compose(a, b), c)` equals `compose(a, compose(b, c))`.
+ */
+declare function composePatch(a: GlyphPatch, b: GlyphPatch): GlyphPatch;
+
+/**
+ * Registers a migration that transforms IR from one version to another.
+ *
+ * Migrations are pure functions registered in `@glyphjs/ir`.
+ * They are applied in sequence by `migrateIR`.
+ */
+declare function registerMigration(migration: IRMigration): void;
+/**
+ * Migrates an IR document from its current version to the target version
+ * by applying registered migrations in sequence.
+ *
+ * Throws an error if:
+ * - The IR version is already at or ahead of the target version
+ *   and no migration path exists.
+ * - No migration is registered for a required intermediate version.
+ * - The target version is older than the current version (downgrade).
+ */
+declare function migrateIR(ir: GlyphIR, targetVersion: string): GlyphIR;
+/**
+ * Clears all registered migrations. Useful for testing.
+ */
+declare function clearMigrations(): void;
+
+/**
+ * Creates a valid empty GlyphIR document with default values.
+ *
+ * Returns:
+ * ```json
+ * {
+ *   "version": "1.0.0",
+ *   "id": id,
+ *   "metadata": {},
+ *   "blocks": [],
+ *   "references": [],
+ *   "layout": { "mode": "document", "spacing": "normal" }
+ * }
+ * ```
+ */
+declare function createEmptyIR(id: string): GlyphIR;
+
+export { applyPatch, clearMigrations, composePatch, createEmptyIR, diffIR, generateBlockId, generateDocumentId, migrateIR, registerMigration, resolveBlockIdCollisions, validateIR };

package/dist/index.js

@@ -0,0 +1,441 @@
+import { createHash } from 'crypto';
+
+// src/ids.ts
+function sha256Hex(input) {
+  return createHash("sha256").update(input).digest("hex");
+}
+function generateBlockId(documentId, blockType, content) {
+  const contentFingerprint = sha256Hex(content);
+  const hash = sha256Hex(documentId + blockType + contentFingerprint);
+  return `b-${hash.slice(0, 12)}`;
+}
+function generateDocumentId(options) {
+  if (options.glyphId) {
+    return options.glyphId;
+  }
+  if (options.filePath) {
+    return options.filePath.replace(/\\/g, "/");
+  }
+  if (options.content) {
+    const hash = sha256Hex(options.content);
+    return `doc-${hash.slice(0, 16)}`;
+  }
+  return `doc-${sha256Hex("")}`.slice(0, 20);
+}
+function resolveBlockIdCollisions(ids) {
+  const seen = /* @__PURE__ */ new Map();
+  const result = [];
+  for (const id of ids) {
+    const count = seen.get(id);
+    if (count === void 0) {
+      seen.set(id, 1);
+      result.push(id);
+    } else {
+      seen.set(id, count + 1);
+      result.push(`${id}-${String(count)}`);
+    }
+  }
+  return result;
+}
+
+// src/validate.ts
+var VALID_LAYOUT_MODES = /* @__PURE__ */ new Set(["document", "dashboard", "presentation"]);
+function validateIR(ir) {
+  const diagnostics = [];
+  if (!ir.version || typeof ir.version !== "string") {
+    diagnostics.push({
+      severity: "error",
+      code: "IR_MISSING_VERSION",
+      message: 'IR document must have a non-empty "version" string.',
+      source: "compiler"
+    });
+  }
+  if (!ir.id || typeof ir.id !== "string") {
+    diagnostics.push({
+      severity: "error",
+      code: "IR_MISSING_ID",
+      message: 'IR document must have a non-empty "id" string.',
+      source: "compiler"
+    });
+  }
+  const blockIds = /* @__PURE__ */ new Set();
+  for (const block of ir.blocks) {
+    if (!block.id || typeof block.id !== "string") {
+      diagnostics.push({
+        severity: "error",
+        code: "BLOCK_MISSING_ID",
+        message: 'Block is missing a non-empty "id" field.',
+        source: "compiler"
+      });
+    }
+    if (!block.type || typeof block.type !== "string") {
+      diagnostics.push({
+        severity: "error",
+        code: "BLOCK_MISSING_TYPE",
+        message: `Block "${String(block.id)}" is missing a non-empty "type" field.`,
+        source: "compiler"
+      });
+    }
+    if (block.data === void 0 || block.data === null) {
+      diagnostics.push({
+        severity: "error",
+        code: "BLOCK_MISSING_DATA",
+        message: `Block "${String(block.id)}" is missing a "data" field.`,
+        source: "compiler"
+      });
+    }
+    if (!block.position) {
+      diagnostics.push({
+        severity: "error",
+        code: "BLOCK_MISSING_POSITION",
+        message: `Block "${String(block.id)}" is missing a "position" field.`,
+        source: "compiler"
+      });
+    }
+    if (block.id) {
+      if (blockIds.has(block.id)) {
+        diagnostics.push({
+          severity: "error",
+          code: "BLOCK_DUPLICATE_ID",
+          message: `Duplicate block ID: "${block.id}".`,
+          source: "compiler"
+        });
+      }
+      blockIds.add(block.id);
+    }
+  }
+  for (const ref of ir.references) {
+    if (!blockIds.has(ref.sourceBlockId)) {
+      diagnostics.push({
+        severity: "error",
+        code: "REF_MISSING_SOURCE",
+        message: `Reference "${ref.id}" has sourceBlockId "${ref.sourceBlockId}" which does not exist in blocks.`,
+        source: "compiler"
+      });
+    }
+    if (!blockIds.has(ref.targetBlockId)) {
+      diagnostics.push({
+        severity: "error",
+        code: "REF_MISSING_TARGET",
+        message: `Reference "${ref.id}" has targetBlockId "${ref.targetBlockId}" which does not exist in blocks.`,
+        source: "compiler"
+      });
+    }
+  }
+  if (ir.layout && !VALID_LAYOUT_MODES.has(ir.layout.mode)) {
+    diagnostics.push({
+      severity: "error",
+      code: "LAYOUT_INVALID_MODE",
+      message: `Invalid layout mode: "${ir.layout.mode}". Expected one of: ${[...VALID_LAYOUT_MODES].join(", ")}.`,
+      source: "compiler"
+    });
+  }
+  return diagnostics;
+}
+
+// src/diff.ts
+function deepEqual(a, b) {
+  if (a === b) return true;
+  if (a === null || b === null) return false;
+  if (typeof a !== typeof b) return false;
+  if (Array.isArray(a)) {
+    if (!Array.isArray(b)) return false;
+    if (a.length !== b.length) return false;
+    return a.every((val, idx) => deepEqual(val, b[idx]));
+  }
+  if (typeof a === "object" && typeof b === "object") {
+    const objA = a;
+    const objB = b;
+    const keysA = Object.keys(objA);
+    const keysB = Object.keys(objB);
+    if (keysA.length !== keysB.length) return false;
+    return keysA.every((key) => deepEqual(objA[key], objB[key]));
+  }
+  return false;
+}
+function blockContentEqual(a, b) {
+  return a.type === b.type && deepEqual(a.data, b.data) && deepEqual(a.position, b.position) && deepEqual(a.children, b.children) && deepEqual(a.diagnostics, b.diagnostics) && deepEqual(a.metadata, b.metadata);
+}
+function referenceEqual(a, b) {
+  return deepEqual(a, b);
+}
+function getBlockAt(blocks, index) {
+  return blocks[index];
+}
+function diffIR(before, after) {
+  const ops = [];
+  if (!deepEqual(before.metadata, after.metadata)) {
+    ops.push({
+      op: "updateMetadata",
+      metadata: after.metadata
+    });
+  }
+  if (!deepEqual(before.layout, after.layout)) {
+    ops.push({
+      op: "updateLayout",
+      layout: after.layout
+    });
+  }
+  const beforeBlockMap = /* @__PURE__ */ new Map();
+  for (const block of before.blocks) {
+    beforeBlockMap.set(block.id, block);
+  }
+  const afterBlockMap = /* @__PURE__ */ new Map();
+  for (const block of after.blocks) {
+    afterBlockMap.set(block.id, block);
+  }
+  for (const block of before.blocks) {
+    if (!afterBlockMap.has(block.id)) {
+      ops.push({ op: "removeBlock", blockId: block.id });
+    }
+  }
+  for (let i = 0; i < after.blocks.length; i++) {
+    const afterBlock = getBlockAt(after.blocks, i);
+    if (!afterBlock) continue;
+    const beforeBlock = beforeBlockMap.get(afterBlock.id);
+    const prevBlock = i > 0 ? getBlockAt(after.blocks, i - 1) : void 0;
+    const afterBlockId = prevBlock?.id;
+    if (!beforeBlock) {
+      ops.push({
+        op: "addBlock",
+        block: afterBlock,
+        afterBlockId
+      });
+    } else {
+      if (!blockContentEqual(beforeBlock, afterBlock)) {
+        const data = {};
+        if (afterBlock.type !== beforeBlock.type) {
+          data.type = afterBlock.type;
+        }
+        if (!deepEqual(afterBlock.data, beforeBlock.data)) {
+          data.data = afterBlock.data;
+        }
+        if (!deepEqual(afterBlock.position, beforeBlock.position)) {
+          data.position = afterBlock.position;
+        }
+        if (!deepEqual(afterBlock.children, beforeBlock.children)) {
+          data.children = afterBlock.children;
+        }
+        if (!deepEqual(afterBlock.diagnostics, beforeBlock.diagnostics)) {
+          data.diagnostics = afterBlock.diagnostics;
+        }
+        if (!deepEqual(afterBlock.metadata, beforeBlock.metadata)) {
+          data.metadata = afterBlock.metadata;
+        }
+        ops.push({
+          op: "updateBlock",
+          blockId: afterBlock.id,
+          data
+        });
+      }
+      const beforeIndex = before.blocks.findIndex(
+        (b) => b.id === afterBlock.id
+      );
+      const prevBeforeBlock = beforeIndex > 0 ? getBlockAt(before.blocks, beforeIndex - 1) : void 0;
+      const expectedAfterBlockId = prevBeforeBlock?.id;
+      if (afterBlockId !== expectedAfterBlockId) {
+        ops.push({
+          op: "moveBlock",
+          blockId: afterBlock.id,
+          afterBlockId
+        });
+      }
+    }
+  }
+  const beforeRefMap = /* @__PURE__ */ new Map();
+  for (const ref of before.references) {
+    beforeRefMap.set(ref.id, ref);
+  }
+  const afterRefMap = /* @__PURE__ */ new Map();
+  for (const ref of after.references) {
+    afterRefMap.set(ref.id, ref);
+  }
+  for (const ref of before.references) {
+    if (!afterRefMap.has(ref.id)) {
+      ops.push({ op: "removeReference", referenceId: ref.id });
+    }
+  }
+  for (const ref of after.references) {
+    const beforeRef = beforeRefMap.get(ref.id);
+    if (!beforeRef) {
+      ops.push({ op: "addReference", reference: ref });
+    } else if (!referenceEqual(beforeRef, ref)) {
+      ops.push({ op: "removeReference", referenceId: ref.id });
+      ops.push({ op: "addReference", reference: ref });
+    }
+  }
+  return ops;
+}
+
+// src/patch.ts
+function deepClone(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+function applyOperation(ir, op) {
+  switch (op.op) {
+    case "addBlock": {
+      const blocks = [...ir.blocks];
+      if (op.afterBlockId) {
+        const idx = blocks.findIndex((b) => b.id === op.afterBlockId);
+        if (idx !== -1) {
+          blocks.splice(idx + 1, 0, deepClone(op.block));
+        } else {
+          blocks.push(deepClone(op.block));
+        }
+      } else {
+        blocks.unshift(deepClone(op.block));
+      }
+      return { ...ir, blocks };
+    }
+    case "removeBlock": {
+      const blocks = ir.blocks.filter((b) => b.id !== op.blockId);
+      return { ...ir, blocks };
+    }
+    case "updateBlock": {
+      const blocks = ir.blocks.map((b) => {
+        if (b.id !== op.blockId) return b;
+        const updated = { ...b };
+        if (op.data.type !== void 0) updated.type = op.data.type;
+        if (op.data.data !== void 0) updated.data = deepClone(op.data.data);
+        if (op.data.position !== void 0)
+          updated.position = deepClone(op.data.position);
+        if (op.data.children !== void 0)
+          updated.children = deepClone(op.data.children);
+        if (op.data.diagnostics !== void 0)
+          updated.diagnostics = deepClone(op.data.diagnostics);
+        if (op.data.metadata !== void 0)
+          updated.metadata = deepClone(op.data.metadata);
+        return updated;
+      });
+      return { ...ir, blocks };
+    }
+    case "moveBlock": {
+      const blockToMove = ir.blocks.find((b) => b.id === op.blockId);
+      if (!blockToMove) return ir;
+      const blocks = ir.blocks.filter((b) => b.id !== op.blockId);
+      if (op.afterBlockId) {
+        const idx = blocks.findIndex((b) => b.id === op.afterBlockId);
+        if (idx !== -1) {
+          blocks.splice(idx + 1, 0, blockToMove);
+        } else {
+          blocks.push(blockToMove);
+        }
+      } else {
+        blocks.unshift(blockToMove);
+      }
+      return { ...ir, blocks };
+    }
+    case "addReference": {
+      return {
+        ...ir,
+        references: [...ir.references, deepClone(op.reference)]
+      };
+    }
+    case "removeReference": {
+      return {
+        ...ir,
+        references: ir.references.filter((r) => r.id !== op.referenceId)
+      };
+    }
+    case "updateMetadata": {
+      return { ...ir, metadata: deepClone(op.metadata) };
+    }
+    case "updateLayout": {
+      const newLayout = {
+        mode: ir.layout.mode,
+        ...deepClone(op.layout)
+      };
+      return { ...ir, layout: newLayout };
+    }
+  }
+}
+function applyPatch(ir, patch) {
+  if (patch.length === 0) return ir;
+  let result = deepClone(ir);
+  for (const op of patch) {
+    result = applyOperation(result, op);
+  }
+  return result;
+}
+function composePatch(a, b) {
+  return [...a, ...b];
+}
+
+// src/migrate.ts
+var migrations = [];
+function registerMigration(migration) {
+  migrations.push(migration);
+}
+function compareVersions(a, b) {
+  const partsA = a.split(".").map(Number);
+  const partsB = b.split(".").map(Number);
+  const len = Math.max(partsA.length, partsB.length);
+  for (let i = 0; i < len; i++) {
+    const numA = partsA[i] ?? 0;
+    const numB = partsB[i] ?? 0;
+    if (numA < numB) return -1;
+    if (numA > numB) return 1;
+  }
+  return 0;
+}
+function migrateIR(ir, targetVersion) {
+  let current = { ...ir };
+  if (current.version === targetVersion) {
+    return current;
+  }
+  if (compareVersions(current.version, targetVersion) > 0) {
+    throw new Error(
+      `Cannot downgrade IR from version "${current.version}" to "${targetVersion}". Only forward migrations are supported.`
+    );
+  }
+  const migrationMap = /* @__PURE__ */ new Map();
+  for (const m of migrations) {
+    migrationMap.set(m.from, m);
+  }
+  let iterations = 0;
+  const maxIterations = migrations.length + 1;
+  while (current.version !== targetVersion && iterations < maxIterations) {
+    const migration = migrationMap.get(current.version);
+    if (!migration) {
+      throw new Error(
+        `No migration registered from version "${current.version}" toward target "${targetVersion}".`
+      );
+    }
+    if (compareVersions(migration.to, targetVersion) > 0) {
+      throw new Error(
+        `Migration from "${migration.from}" to "${migration.to}" would overshoot target version "${targetVersion}".`
+      );
+    }
+    current = migration.migrate(current);
+    current = { ...current, version: migration.to };
+    iterations++;
+  }
+  if (current.version !== targetVersion) {
+    throw new Error(
+      `Could not reach target version "${targetVersion}" from "${ir.version}". Stopped at "${current.version}".`
+    );
+  }
+  return current;
+}
+function clearMigrations() {
+  migrations.length = 0;
+}
+
+// src/factory.ts
+function createEmptyIR(id) {
+  return {
+    version: "1.0.0",
+    id,
+    metadata: {},
+    blocks: [],
+    references: [],
+    layout: {
+      mode: "document",
+      spacing: "normal"
+    }
+  };
+}
+
+export { applyPatch, clearMigrations, composePatch, createEmptyIR, diffIR, generateBlockId, generateDocumentId, migrateIR, registerMigration, resolveBlockIdCollisions, validateIR };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map