@rejot-dev/thalo 0.0.0

package/dist/semantic/analyzer.js

@@ -0,0 +1,261 @@
+//#region src/semantic/analyzer.ts
+/**
+* Analyze an AST to produce a SemanticModel.
+*
+* This function traverses the AST and builds indexes:
+* - Link definitions (entries with explicit ^linkId)
+* - Link references (^linkId in metadata values or actualize targets)
+* - Schema entries for later resolution by SchemaRegistry
+*/
+function analyze(ast, options) {
+	const { file, source, sourceMap, blocks } = options;
+	return {
+		ast,
+		file,
+		source,
+		sourceMap,
+		blocks,
+		linkIndex: buildLinkIndex(ast, file),
+		schemaEntries: collectSchemaEntries(ast)
+	};
+}
+/**
+* Build a link index from an AST.
+* Iterates over all entries and indexes link definitions and references.
+*/
+function buildLinkIndex(ast, file) {
+	const definitions = /* @__PURE__ */ new Map();
+	const references = /* @__PURE__ */ new Map();
+	for (const entry of ast.entries) indexEntryLinks(entry, file, definitions, references);
+	return {
+		definitions,
+		references
+	};
+}
+/**
+* Index all links from an entry.
+*/
+function indexEntryLinks(entry, file, definitions, references) {
+	const linkDef = getEntryLinkDefinition(entry);
+	if (linkDef) definitions.set(linkDef.id, {
+		id: linkDef.id,
+		file,
+		location: linkDef.location,
+		entry
+	});
+	if (entry.type === "instance_entry" || entry.type === "synthesis_entry") indexMetadataLinks(entry.metadata, entry, file, references);
+	else if (entry.type === "actualize_entry") {
+		addReference(references, {
+			id: entry.header.target.id,
+			file,
+			location: entry.header.target.location,
+			entry,
+			context: "target"
+		});
+		indexMetadataLinks(entry.metadata, entry, file, references);
+	}
+}
+/**
+* Get the link definition from an entry's header (if any).
+*/
+function getEntryLinkDefinition(entry) {
+	switch (entry.type) {
+		case "instance_entry": return entry.header.link ? {
+			id: entry.header.link.id,
+			location: entry.header.link.location
+		} : null;
+		case "schema_entry": return entry.header.link ? {
+			id: entry.header.link.id,
+			location: entry.header.link.location
+		} : null;
+		case "synthesis_entry": return {
+			id: entry.header.linkId.id,
+			location: entry.header.linkId.location
+		};
+		case "actualize_entry": return null;
+	}
+}
+/**
+* Index link references from metadata values.
+*/
+function indexMetadataLinks(metadata, entry, file, references) {
+	for (const m of metadata) {
+		const content = m.value.content;
+		if (content.type === "link_value") addReference(references, {
+			id: content.link.id,
+			file,
+			location: content.link.location,
+			entry,
+			context: m.key.value
+		});
+		else if (content.type === "value_array") {
+			for (const element of content.elements) if (element.type === "link") addReference(references, {
+				id: element.id,
+				file,
+				location: element.location,
+				entry,
+				context: m.key.value
+			});
+		}
+	}
+}
+/**
+* Add a reference to the references map.
+*/
+function addReference(references, ref) {
+	const refs = references.get(ref.id) ?? [];
+	refs.push(ref);
+	references.set(ref.id, refs);
+}
+/**
+* Collect all schema entries from an AST.
+*/
+function collectSchemaEntries(ast) {
+	return ast.entries.filter((e) => e.type === "schema_entry");
+}
+/**
+* Update a semantic model incrementally when the AST changes.
+*
+* This function compares the old and new ASTs, identifies what changed,
+* and updates the model's indexes accordingly. This is more efficient
+* than rebuilding the entire model from scratch.
+*
+* @param model - The existing semantic model to update
+* @param newAst - The new AST after changes
+* @param newSource - The new source text
+* @param newSourceMap - The new source map
+* @param newBlocks - The new parsed blocks
+* @returns Information about what changed
+*/
+function updateSemanticModel(model, newAst, newSource, newSourceMap, newBlocks) {
+	const oldAst = model.ast;
+	const file = model.file;
+	const result = {
+		addedLinkDefinitions: [],
+		removedLinkDefinitions: [],
+		changedLinkReferences: [],
+		schemaEntriesChanged: false,
+		changedEntityNames: []
+	};
+	const oldEntryKeys = new Set(oldAst.entries.map(entryKey));
+	const newEntryKeys = new Set(newAst.entries.map(entryKey));
+	const addedEntries = [];
+	const removedEntries = [];
+	for (const entry of oldAst.entries) if (!newEntryKeys.has(entryKey(entry))) removedEntries.push(entry);
+	for (const entry of newAst.entries) if (!oldEntryKeys.has(entryKey(entry))) addedEntries.push(entry);
+	const linkResult = updateLinkIndex(model.linkIndex, file, removedEntries, addedEntries);
+	result.addedLinkDefinitions = linkResult.addedDefinitions;
+	result.removedLinkDefinitions = linkResult.removedDefinitions;
+	result.changedLinkReferences = linkResult.changedReferences;
+	const oldSchemaEntries = model.schemaEntries;
+	const newSchemaEntries = collectSchemaEntries(newAst);
+	if (!schemaEntriesEqual(oldSchemaEntries, newSchemaEntries)) {
+		result.schemaEntriesChanged = true;
+		const oldEntityNames = new Set(oldSchemaEntries.map((e) => e.header.entityName.value));
+		const newEntityNames = new Set(newSchemaEntries.map((e) => e.header.entityName.value));
+		for (const name of oldEntityNames) if (!newEntityNames.has(name)) result.changedEntityNames.push(name);
+		for (const name of newEntityNames) if (!oldEntityNames.has(name)) result.changedEntityNames.push(name);
+		for (const oldEntry of oldSchemaEntries) {
+			const newEntry = newSchemaEntries.find((e) => e.header.entityName.value === oldEntry.header.entityName.value);
+			if (newEntry && !schemaEntryEqual(oldEntry, newEntry)) {
+				if (!result.changedEntityNames.includes(oldEntry.header.entityName.value)) result.changedEntityNames.push(oldEntry.header.entityName.value);
+			}
+		}
+	}
+	model.ast = newAst;
+	model.source = newSource;
+	model.sourceMap = newSourceMap;
+	model.blocks = newBlocks;
+	model.schemaEntries = newSchemaEntries;
+	model.dirty = {
+		linkIndex: false,
+		schemaEntries: false
+	};
+	return result;
+}
+/**
+* Create a unique key for an entry based on its type and position.
+*/
+function entryKey(entry) {
+	return `${entry.type}:${entry.location.startIndex}:${entry.location.endIndex}`;
+}
+/**
+* Update the link index based on removed and added entries.
+*/
+function updateLinkIndex(linkIndex, file, removedEntries, addedEntries) {
+	const addedDefinitions = [];
+	const removedDefinitions = [];
+	const changedReferences = /* @__PURE__ */ new Set();
+	for (const entry of removedEntries) {
+		const linkDef = getEntryLinkDefinition(entry);
+		if (linkDef) {
+			linkIndex.definitions.delete(linkDef.id);
+			removedDefinitions.push(linkDef.id);
+		}
+		removeEntryReferences(linkIndex.references, entry, changedReferences);
+	}
+	for (const entry of addedEntries) {
+		indexEntryLinks(entry, file, linkIndex.definitions, linkIndex.references);
+		const linkDef = getEntryLinkDefinition(entry);
+		if (linkDef) addedDefinitions.push(linkDef.id);
+		trackEntryReferences(entry, changedReferences);
+	}
+	return {
+		addedDefinitions,
+		removedDefinitions,
+		changedReferences: Array.from(changedReferences)
+	};
+}
+/**
+* Remove all references from a specific entry.
+*/
+function removeEntryReferences(references, entry, changedReferences) {
+	for (const [linkId, refs] of references) {
+		const filtered = refs.filter((ref) => ref.entry !== entry);
+		if (filtered.length !== refs.length) {
+			changedReferences.add(linkId);
+			if (filtered.length === 0) references.delete(linkId);
+			else references.set(linkId, filtered);
+		}
+	}
+}
+/**
+* Track which link IDs are referenced by an entry.
+*/
+function trackEntryReferences(entry, changedReferences) {
+	if (entry.type === "instance_entry" || entry.type === "synthesis_entry") for (const m of entry.metadata) {
+		const content = m.value.content;
+		if (content.type === "link_value") changedReferences.add(content.link.id);
+		else if (content.type === "value_array") {
+			for (const element of content.elements) if (element.type === "link") changedReferences.add(element.id);
+		}
+	}
+	else if (entry.type === "actualize_entry") {
+		changedReferences.add(entry.header.target.id);
+		for (const m of entry.metadata) {
+			const content = m.value.content;
+			if (content.type === "link_value") changedReferences.add(content.link.id);
+			else if (content.type === "value_array") {
+				for (const element of content.elements) if (element.type === "link") changedReferences.add(element.id);
+			}
+		}
+	}
+}
+/**
+* Check if two arrays of schema entries are equal.
+*/
+function schemaEntriesEqual(a, b) {
+	if (a.length !== b.length) return false;
+	for (let i = 0; i < a.length; i++) if (!schemaEntryEqual(a[i], b[i])) return false;
+	return true;
+}
+/**
+* Check if two schema entries are equal (by entity name and directive).
+*/
+function schemaEntryEqual(a, b) {
+	return a.header.entityName.value === b.header.entityName.value && a.header.directive === b.header.directive && a.location.startIndex === b.location.startIndex && a.location.endIndex === b.location.endIndex;
+}
+
+//#endregion
+export { analyze, updateSemanticModel };
+//# sourceMappingURL=analyzer.js.map

package/dist/semantic/analyzer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyzer.js","names":["result: SemanticUpdateResult","addedEntries: Entry[]","removedEntries: Entry[]","addedDefinitions: string[]","removedDefinitions: string[]"],"sources":["../../src/semantic/analyzer.ts"],"sourcesContent":["import type { SourceFile, Entry, SchemaEntry, Metadata, Location } from \"../ast/ast-types.js\";\nimport type { SourceMap } from \"../source-map.js\";\nimport type { ParsedBlock, GenericTree } from \"../parser.shared.js\";\n\n// ===================\n// Link Index Types\n// ===================\n\n/**\n * A link definition in an entry header.\n * Created when an entry has an explicit ^linkId in its header.\n */\nexport interface LinkDefinition {\n  /** The link ID (without ^ prefix) */\n  id: string;\n  /** The file path containing this definition */\n  file: string;\n  /** Location of the link in the source */\n  location: Location;\n  /** The entry that defines this link */\n  entry: Entry;\n}\n\n/**\n * A link reference in metadata or as an actualize target.\n * Created when an entry references another entry via ^linkId.\n */\nexport interface LinkReference {\n  /** The link ID (without ^ prefix) */\n  id: string;\n  /** The file path containing this reference */\n  file: string;\n  /** Location of the link in the source */\n  location: Location;\n  /** The entry containing this reference */\n  entry: Entry;\n  /** The context where this reference appears (metadata key or \"target\") */\n  context: string;\n}\n\n/**\n * Index for link definitions and references within a document.\n */\nexport interface LinkIndex {\n  /** Map from link ID to its definition (if any) */\n  definitions: Map<string, LinkDefinition>;\n  /** Map from link ID to all references */\n  references: Map<string, LinkReference[]>;\n}\n\n// ===================\n// Semantic Model\n// ===================\n\n/**\n * A semantic model for a single document.\n * Contains the AST plus indexes built during semantic analysis.\n *\n * This is the per-document semantic representation. The Workspace\n * aggregates multiple SemanticModels and combines their indexes.\n */\nexport interface SemanticModel {\n  /** The AST for this document */\n  ast: SourceFile;\n  /** The file path */\n  file: string;\n  /** The original source text */\n  source: string;\n  /** Source map for position translation (block-relative to file-absolute) */\n  sourceMap: SourceMap;\n  /** The parsed blocks (containing tree-sitter trees) for CST operations */\n  blocks: ParsedBlock<GenericTree>[];\n\n  /**\n   * Link index for this document.\n   * Contains definitions and references found in this document only.\n   */\n  linkIndex: LinkIndex;\n\n  /**\n   * Schema entries from this document.\n   * These are used by the SchemaRegistry at the workspace level\n   * to build resolved entity schemas.\n   */\n  schemaEntries: SchemaEntry[];\n\n  /**\n   * Dirty flags for incremental updates.\n   * When true, the corresponding index needs to be rebuilt.\n   */\n  dirty?: SemanticModelDirtyFlags;\n}\n\n/**\n * Dirty flags indicating which parts of the semantic model need rebuilding.\n */\nexport interface SemanticModelDirtyFlags {\n  /** Link index needs rebuild (definitions or references changed) */\n  linkIndex: boolean;\n  /** Schema entries need re-extraction (schema entries changed) */\n  schemaEntries: boolean;\n}\n\n/**\n * Result of an incremental semantic model update.\n */\nexport interface SemanticUpdateResult {\n  /** Link IDs that were added (new definitions) */\n  addedLinkDefinitions: string[];\n  /** Link IDs that were removed (deleted definitions) */\n  removedLinkDefinitions: string[];\n  /** Link IDs whose references changed */\n  changedLinkReferences: string[];\n  /** Whether schema entries changed */\n  schemaEntriesChanged: boolean;\n  /** Entity names whose schema definitions changed */\n  changedEntityNames: string[];\n}\n\n/**\n * Options for analyzing a document\n */\nexport interface AnalyzeOptions {\n  /** The file path for this document */\n  file: string;\n  /** The original source text */\n  source: string;\n  /** Source map for position translation */\n  sourceMap: SourceMap;\n  /** The parsed blocks (containing tree-sitter trees) */\n  blocks: ParsedBlock<GenericTree>[];\n}\n\n/**\n * Analyze an AST to produce a SemanticModel.\n *\n * This function traverses the AST and builds indexes:\n * - Link definitions (entries with explicit ^linkId)\n * - Link references (^linkId in metadata values or actualize targets)\n * - Schema entries for later resolution by SchemaRegistry\n */\nexport function analyze(ast: SourceFile, options: AnalyzeOptions): SemanticModel {\n  const { file, source, sourceMap, blocks } = options;\n\n  return {\n    ast,\n    file,\n    source,\n    sourceMap,\n    blocks,\n    linkIndex: buildLinkIndex(ast, file),\n    schemaEntries: collectSchemaEntries(ast),\n  };\n}\n\n/**\n * Build a link index from an AST.\n * Iterates over all entries and indexes link definitions and references.\n */\nfunction buildLinkIndex(ast: SourceFile, file: string): LinkIndex {\n  const definitions = new Map<string, LinkDefinition>();\n  const references = new Map<string, LinkReference[]>();\n\n  for (const entry of ast.entries) {\n    indexEntryLinks(entry, file, definitions, references);\n  }\n\n  return { definitions, references };\n}\n\n/**\n * Index all links from an entry.\n */\nfunction indexEntryLinks(\n  entry: Entry,\n  file: string,\n  definitions: Map<string, LinkDefinition>,\n  references: Map<string, LinkReference[]>,\n): void {\n  // Index header link definition\n  const linkDef = getEntryLinkDefinition(entry);\n  if (linkDef) {\n    definitions.set(linkDef.id, {\n      id: linkDef.id,\n      file,\n      location: linkDef.location,\n      entry,\n    });\n  }\n\n  // Index references based on entry type\n  if (entry.type === \"instance_entry\" || entry.type === \"synthesis_entry\") {\n    indexMetadataLinks(entry.metadata, entry, file, references);\n  } else if (entry.type === \"actualize_entry\") {\n    // Actualize target is a reference\n    addReference(references, {\n      id: entry.header.target.id,\n      file,\n      location: entry.header.target.location,\n      entry,\n      context: \"target\",\n    });\n    indexMetadataLinks(entry.metadata, entry, file, references);\n  }\n}\n\n/**\n * Get the link definition from an entry's header (if any).\n */\nfunction getEntryLinkDefinition(\n  entry: Entry,\n): { id: string; location: import(\"../ast/ast-types.js\").Location } | null {\n  switch (entry.type) {\n    case \"instance_entry\":\n      return entry.header.link\n        ? { id: entry.header.link.id, location: entry.header.link.location }\n        : null;\n    case \"schema_entry\":\n      return entry.header.link\n        ? { id: entry.header.link.id, location: entry.header.link.location }\n        : null;\n    case \"synthesis_entry\":\n      return { id: entry.header.linkId.id, location: entry.header.linkId.location };\n    case \"actualize_entry\":\n      return null; // Actualize entries don't define links\n  }\n}\n\n/**\n * Index link references from metadata values.\n */\nfunction indexMetadataLinks(\n  metadata: Metadata[],\n  entry: Entry,\n  file: string,\n  references: Map<string, LinkReference[]>,\n): void {\n  for (const m of metadata) {\n    const content = m.value.content;\n\n    if (content.type === \"link_value\") {\n      addReference(references, {\n        id: content.link.id,\n        file,\n        location: content.link.location,\n        entry,\n        context: m.key.value,\n      });\n    } else if (content.type === \"value_array\") {\n      for (const element of content.elements) {\n        if (element.type === \"link\") {\n          addReference(references, {\n            id: element.id,\n            file,\n            location: element.location,\n            entry,\n            context: m.key.value,\n          });\n        }\n      }\n    }\n  }\n}\n\n/**\n * Add a reference to the references map.\n */\nfunction addReference(references: Map<string, LinkReference[]>, ref: LinkReference): void {\n  const refs = references.get(ref.id) ?? [];\n  refs.push(ref);\n  references.set(ref.id, refs);\n}\n\n/**\n * Collect all schema entries from an AST.\n */\nfunction collectSchemaEntries(ast: SourceFile): SchemaEntry[] {\n  return ast.entries.filter((e): e is SchemaEntry => e.type === \"schema_entry\");\n}\n\n// ===================\n// Incremental Updates\n// ===================\n\n/**\n * Update a semantic model incrementally when the AST changes.\n *\n * This function compares the old and new ASTs, identifies what changed,\n * and updates the model's indexes accordingly. This is more efficient\n * than rebuilding the entire model from scratch.\n *\n * @param model - The existing semantic model to update\n * @param newAst - The new AST after changes\n * @param newSource - The new source text\n * @param newSourceMap - The new source map\n * @param newBlocks - The new parsed blocks\n * @returns Information about what changed\n */\nexport function updateSemanticModel(\n  model: SemanticModel,\n  newAst: SourceFile,\n  newSource: string,\n  newSourceMap: SourceMap,\n  newBlocks: ParsedBlock<GenericTree>[],\n): SemanticUpdateResult {\n  const oldAst = model.ast;\n  const file = model.file;\n\n  // Track what changed\n  const result: SemanticUpdateResult = {\n    addedLinkDefinitions: [],\n    removedLinkDefinitions: [],\n    changedLinkReferences: [],\n    schemaEntriesChanged: false,\n    changedEntityNames: [],\n  };\n\n  // Build entry sets for comparison (using position as identity)\n  const oldEntryKeys = new Set(oldAst.entries.map(entryKey));\n  const newEntryKeys = new Set(newAst.entries.map(entryKey));\n\n  // Find added and removed entries\n  const addedEntries: Entry[] = [];\n  const removedEntries: Entry[] = [];\n\n  for (const entry of oldAst.entries) {\n    if (!newEntryKeys.has(entryKey(entry))) {\n      removedEntries.push(entry);\n    }\n  }\n\n  for (const entry of newAst.entries) {\n    if (!oldEntryKeys.has(entryKey(entry))) {\n      addedEntries.push(entry);\n    }\n  }\n\n  // Update link index\n  const linkResult = updateLinkIndex(model.linkIndex, file, removedEntries, addedEntries);\n  result.addedLinkDefinitions = linkResult.addedDefinitions;\n  result.removedLinkDefinitions = linkResult.removedDefinitions;\n  result.changedLinkReferences = linkResult.changedReferences;\n\n  // Update schema entries\n  const oldSchemaEntries = model.schemaEntries;\n  const newSchemaEntries = collectSchemaEntries(newAst);\n\n  // Check if schema entries changed\n  if (!schemaEntriesEqual(oldSchemaEntries, newSchemaEntries)) {\n    result.schemaEntriesChanged = true;\n\n    // Find changed entity names\n    const oldEntityNames = new Set(oldSchemaEntries.map((e) => e.header.entityName.value));\n    const newEntityNames = new Set(newSchemaEntries.map((e) => e.header.entityName.value));\n\n    for (const name of oldEntityNames) {\n      if (!newEntityNames.has(name)) {\n        result.changedEntityNames.push(name);\n      }\n    }\n    for (const name of newEntityNames) {\n      if (!oldEntityNames.has(name)) {\n        result.changedEntityNames.push(name);\n      }\n    }\n\n    // Also check for modified entries (same name but different content)\n    for (const oldEntry of oldSchemaEntries) {\n      const newEntry = newSchemaEntries.find(\n        (e) => e.header.entityName.value === oldEntry.header.entityName.value,\n      );\n      if (newEntry && !schemaEntryEqual(oldEntry, newEntry)) {\n        if (!result.changedEntityNames.includes(oldEntry.header.entityName.value)) {\n          result.changedEntityNames.push(oldEntry.header.entityName.value);\n        }\n      }\n    }\n  }\n\n  // Update the model in place\n  model.ast = newAst;\n  model.source = newSource;\n  model.sourceMap = newSourceMap;\n  model.blocks = newBlocks;\n  model.schemaEntries = newSchemaEntries;\n  model.dirty = {\n    linkIndex: false,\n    schemaEntries: false,\n  };\n\n  return result;\n}\n\n/**\n * Create a unique key for an entry based on its type and position.\n */\nfunction entryKey(entry: Entry): string {\n  return `${entry.type}:${entry.location.startIndex}:${entry.location.endIndex}`;\n}\n\n/**\n * Update the link index based on removed and added entries.\n */\nfunction updateLinkIndex(\n  linkIndex: LinkIndex,\n  file: string,\n  removedEntries: Entry[],\n  addedEntries: Entry[],\n): { addedDefinitions: string[]; removedDefinitions: string[]; changedReferences: string[] } {\n  const addedDefinitions: string[] = [];\n  const removedDefinitions: string[] = [];\n  const changedReferences = new Set<string>();\n\n  // Remove links from removed entries\n  for (const entry of removedEntries) {\n    const linkDef = getEntryLinkDefinition(entry);\n    if (linkDef) {\n      linkIndex.definitions.delete(linkDef.id);\n      removedDefinitions.push(linkDef.id);\n    }\n\n    // Remove references from this entry\n    removeEntryReferences(linkIndex.references, entry, changedReferences);\n  }\n\n  // Add links from added entries\n  for (const entry of addedEntries) {\n    indexEntryLinks(entry, file, linkIndex.definitions, linkIndex.references);\n\n    const linkDef = getEntryLinkDefinition(entry);\n    if (linkDef) {\n      addedDefinitions.push(linkDef.id);\n    }\n\n    // Track changed references\n    trackEntryReferences(entry, changedReferences);\n  }\n\n  return {\n    addedDefinitions,\n    removedDefinitions,\n    changedReferences: Array.from(changedReferences),\n  };\n}\n\n/**\n * Remove all references from a specific entry.\n */\nfunction removeEntryReferences(\n  references: Map<string, LinkReference[]>,\n  entry: Entry,\n  changedReferences: Set<string>,\n): void {\n  for (const [linkId, refs] of references) {\n    const filtered = refs.filter((ref) => ref.entry !== entry);\n    if (filtered.length !== refs.length) {\n      changedReferences.add(linkId);\n      if (filtered.length === 0) {\n        references.delete(linkId);\n      } else {\n        references.set(linkId, filtered);\n      }\n    }\n  }\n}\n\n/**\n * Track which link IDs are referenced by an entry.\n */\nfunction trackEntryReferences(entry: Entry, changedReferences: Set<string>): void {\n  if (entry.type === \"instance_entry\" || entry.type === \"synthesis_entry\") {\n    for (const m of entry.metadata) {\n      const content = m.value.content;\n      if (content.type === \"link_value\") {\n        changedReferences.add(content.link.id);\n      } else if (content.type === \"value_array\") {\n        for (const element of content.elements) {\n          if (element.type === \"link\") {\n            changedReferences.add(element.id);\n          }\n        }\n      }\n    }\n  } else if (entry.type === \"actualize_entry\") {\n    changedReferences.add(entry.header.target.id);\n    for (const m of entry.metadata) {\n      const content = m.value.content;\n      if (content.type === \"link_value\") {\n        changedReferences.add(content.link.id);\n      } else if (content.type === \"value_array\") {\n        for (const element of content.elements) {\n          if (element.type === \"link\") {\n            changedReferences.add(element.id);\n          }\n        }\n      }\n    }\n  }\n}\n\n/**\n * Check if two arrays of schema entries are equal.\n */\nfunction schemaEntriesEqual(a: SchemaEntry[], b: SchemaEntry[]): boolean {\n  if (a.length !== b.length) {\n    return false;\n  }\n  for (let i = 0; i < a.length; i++) {\n    if (!schemaEntryEqual(a[i], b[i])) {\n      return false;\n    }\n  }\n  return true;\n}\n\n/**\n * Check if two schema entries are equal (by entity name and directive).\n */\nfunction schemaEntryEqual(a: SchemaEntry, b: SchemaEntry): boolean {\n  return (\n    a.header.entityName.value === b.header.entityName.value &&\n    a.header.directive === b.header.directive &&\n    a.location.startIndex === b.location.startIndex &&\n    a.location.endIndex === b.location.endIndex\n  );\n}\n"],"mappings":"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"}

package/dist/services/change-tracker/change-tracker.d.ts

@@ -0,0 +1,111 @@
+import { InstanceEntry } from "../../ast/ast-types.js";
+import { Workspace } from "../../model/workspace.js";
+import { Query } from "../query.js";
+import { TimestampChangeTracker } from "./timestamp-tracker.js";
+
+//#region src/services/change-tracker/change-tracker.d.ts
+
+/**
+ * Known checkpoint provider types.
+ *
+ * - "git": Git commit hash
+ * - "ts": ISO timestamp
+ *
+ * This is extensible - future providers could include "db" for database, etc.
+ */
+type CheckpointProvider = "git" | "ts";
+/**
+ * A marker representing a point in time for change tracking.
+ *
+ * Stored as `checkpoint: "git:abc123"` or `checkpoint: "ts:2026-01-08T15:00Z"`.
+ */
+interface ChangeMarker {
+  /** Provider type (git, ts, etc.) */
+  type: CheckpointProvider;
+  /** The marker value - commit hash or ISO timestamp */
+  value: string;
+}
+/**
+ * Result of getting changed entries, including the marker to store
+ */
+interface ChangedEntriesResult {
+  /** Entries that have changed since the marker */
+  entries: InstanceEntry[];
+  /** The current marker to store for next comparison */
+  currentMarker: ChangeMarker;
+}
+/**
+ * Options for creating a ChangeTracker
+ */
+interface ChangeTrackerOptions {
+  /** Working directory for git operations */
+  cwd?: string;
+  /**
+   * Force operation even if there are uncommitted changes.
+   * When false (default), git tracker will error if source files have uncommitted changes.
+   */
+  force?: boolean;
+}
+/**
+ * Error thrown when source files have uncommitted changes.
+ *
+ * This prevents incorrect change tracking since uncommitted changes
+ * are not captured in the checkpoint.
+ */
+declare class UncommittedChangesError extends Error {
+  /** Files with uncommitted changes */
+  readonly files: string[];
+  constructor(files: string[]);
+}
+/**
+ * Interface for tracking changes to entries.
+ *
+ * Implementations can use different backends (git, timestamps, database, etc.)
+ * to determine which entries have changed since a marker point.
+ */
+interface ChangeTracker {
+  /**
+   * Type of tracker - matches the checkpoint provider type.
+   */
+  readonly type: CheckpointProvider;
+  /**
+   * Get the current position marker (HEAD commit or current time).
+   *
+   * @returns Current marker to store for future comparisons
+   */
+  getCurrentMarker(): Promise<ChangeMarker>;
+  /**
+   * Get entries that have changed since a marker.
+   *
+   * For git tracker: Finds files modified since the commit, parses them,
+   * and compares entry content to identify changed entries.
+   *
+   * For timestamp tracker: Filters entries with timestamps after the marker.
+   *
+   * @param workspace - The workspace containing current entries
+   * @param queries - Queries to filter which entries to consider
+   * @param marker - The marker to compare against (from previous actualization)
+   * @returns Changed entries and the current marker to store
+   */
+  getChangedEntries(workspace: Workspace, queries: Query[], marker: ChangeMarker | null): Promise<ChangedEntriesResult>;
+}
+/**
+ * Parse a checkpoint value into a ChangeMarker.
+ *
+ * Expected format: "git:abc123" or "ts:2026-01-08T15:00Z"
+ * Strips quotes from the raw value as metadata raw values include quotes.
+ *
+ * @param checkpointRaw - Raw checkpoint metadata value (may include quotes)
+ * @returns Parsed marker or null if invalid/missing
+ */
+declare function parseCheckpoint(checkpointRaw: string | undefined): ChangeMarker | null;
+/**
+ * Format a ChangeMarker as a checkpoint string.
+ *
+ * @param marker - The marker to format
+ * @returns Formatted string like "git:abc123" or "ts:2026-01-08T15:00Z"
+ */
+declare function formatCheckpoint(marker: ChangeMarker): string;
+//#endregion
+export { ChangeMarker, ChangeTracker, ChangeTrackerOptions, ChangedEntriesResult, CheckpointProvider, TimestampChangeTracker, UncommittedChangesError, formatCheckpoint, parseCheckpoint };
+//# sourceMappingURL=change-tracker.d.ts.map

package/dist/services/change-tracker/change-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"change-tracker.d.ts","names":[],"sources":["../../../src/services/change-tracker/change-tracker.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;AAaA;AAOA;AAUA;AAUA;AAgBA;AAoBiB,KA/DL,kBAAA,GA+DkB,KAAA,GAAA,IAAA;;;;;;AA6BlB,UArFK,YAAA,CAqFL;EACC;EAAR,IAAA,EApFG,kBAoFH;EAAO;EA0BI,KAAA,EAAA,MAAA;AAiChB;;;;UAvIiB,oBAAA;;WAEN;;iBAEM;;;;;UAMA,oBAAA;;;;;;;;;;;;;;;cAgBJ,uBAAA,SAAgC,KAAA;;;;;;;;;;;UAoB5B,aAAA;;;;iBAIA;;;;;;sBAOK,QAAQ;;;;;;;;;;;;;;+BAgBf,oBACF,iBACD,sBACP,QAAQ;;;;;;;;;;;iBA0BG,eAAA,qCAAoD;;;;;;;iBAiCpD,gBAAA,SAAyB"}

package/dist/services/change-tracker/change-tracker.js

@@ -0,0 +1,62 @@
+import { TimestampChangeTracker } from "./timestamp-tracker.js";
+
+//#region src/services/change-tracker/change-tracker.ts
+/**
+* Error thrown when source files have uncommitted changes.
+*
+* This prevents incorrect change tracking since uncommitted changes
+* are not captured in the checkpoint.
+*/
+var UncommittedChangesError = class extends Error {
+	/** Files with uncommitted changes */
+	files;
+	constructor(files) {
+		super(`Source files have uncommitted changes: ${files.join(", ")}. Commit your changes or use --force to proceed anyway.`);
+		this.name = "UncommittedChangesError";
+		this.files = files;
+	}
+};
+/**
+* Strip quotes from a string value if present.
+* Handles both single and double quotes.
+*/
+function stripQuotes(value) {
+	if (value.startsWith("\"") && value.endsWith("\"") || value.startsWith("'") && value.endsWith("'")) return value.slice(1, -1);
+	return value;
+}
+/**
+* Parse a checkpoint value into a ChangeMarker.
+*
+* Expected format: "git:abc123" or "ts:2026-01-08T15:00Z"
+* Strips quotes from the raw value as metadata raw values include quotes.
+*
+* @param checkpointRaw - Raw checkpoint metadata value (may include quotes)
+* @returns Parsed marker or null if invalid/missing
+*/
+function parseCheckpoint(checkpointRaw) {
+	if (!checkpointRaw) return null;
+	const value = stripQuotes(checkpointRaw);
+	const colonIndex = value.indexOf(":");
+	if (colonIndex === -1) return null;
+	const provider = value.slice(0, colonIndex);
+	const markerValue = value.slice(colonIndex + 1);
+	if (!markerValue) return null;
+	if (provider === "git" || provider === "ts") return {
+		type: provider,
+		value: markerValue
+	};
+	return null;
+}
+/**
+* Format a ChangeMarker as a checkpoint string.
+*
+* @param marker - The marker to format
+* @returns Formatted string like "git:abc123" or "ts:2026-01-08T15:00Z"
+*/
+function formatCheckpoint(marker) {
+	return `${marker.type}:${marker.value}`;
+}
+
+//#endregion
+export { TimestampChangeTracker, UncommittedChangesError, formatCheckpoint, parseCheckpoint };
+//# sourceMappingURL=change-tracker.js.map

package/dist/services/change-tracker/change-tracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"change-tracker.js","names":[],"sources":["../../../src/services/change-tracker/change-tracker.ts"],"sourcesContent":["import type { InstanceEntry } from \"../../ast/ast-types.js\";\nimport type { Query } from \"../query.js\";\nimport type { Workspace } from \"../../model/workspace.js\";\nimport { TimestampChangeTracker } from \"./timestamp-tracker.js\";\n\n/**\n * Known checkpoint provider types.\n *\n * - \"git\": Git commit hash\n * - \"ts\": ISO timestamp\n *\n * This is extensible - future providers could include \"db\" for database, etc.\n */\nexport type CheckpointProvider = \"git\" | \"ts\";\n\n/**\n * A marker representing a point in time for change tracking.\n *\n * Stored as `checkpoint: \"git:abc123\"` or `checkpoint: \"ts:2026-01-08T15:00Z\"`.\n */\nexport interface ChangeMarker {\n  /** Provider type (git, ts, etc.) */\n  type: CheckpointProvider;\n  /** The marker value - commit hash or ISO timestamp */\n  value: string;\n}\n\n/**\n * Result of getting changed entries, including the marker to store\n */\nexport interface ChangedEntriesResult {\n  /** Entries that have changed since the marker */\n  entries: InstanceEntry[];\n  /** The current marker to store for next comparison */\n  currentMarker: ChangeMarker;\n}\n\n/**\n * Options for creating a ChangeTracker\n */\nexport interface ChangeTrackerOptions {\n  /** Working directory for git operations */\n  cwd?: string;\n  /**\n   * Force operation even if there are uncommitted changes.\n   * When false (default), git tracker will error if source files have uncommitted changes.\n   */\n  force?: boolean;\n}\n\n/**\n * Error thrown when source files have uncommitted changes.\n *\n * This prevents incorrect change tracking since uncommitted changes\n * are not captured in the checkpoint.\n */\nexport class UncommittedChangesError extends Error {\n  /** Files with uncommitted changes */\n  readonly files: string[];\n\n  constructor(files: string[]) {\n    super(\n      `Source files have uncommitted changes: ${files.join(\", \")}. ` +\n        `Commit your changes or use --force to proceed anyway.`,\n    );\n    this.name = \"UncommittedChangesError\";\n    this.files = files;\n  }\n}\n\n/**\n * Interface for tracking changes to entries.\n *\n * Implementations can use different backends (git, timestamps, database, etc.)\n * to determine which entries have changed since a marker point.\n */\nexport interface ChangeTracker {\n  /**\n   * Type of tracker - matches the checkpoint provider type.\n   */\n  readonly type: CheckpointProvider;\n\n  /**\n   * Get the current position marker (HEAD commit or current time).\n   *\n   * @returns Current marker to store for future comparisons\n   */\n  getCurrentMarker(): Promise<ChangeMarker>;\n\n  /**\n   * Get entries that have changed since a marker.\n   *\n   * For git tracker: Finds files modified since the commit, parses them,\n   * and compares entry content to identify changed entries.\n   *\n   * For timestamp tracker: Filters entries with timestamps after the marker.\n   *\n   * @param workspace - The workspace containing current entries\n   * @param queries - Queries to filter which entries to consider\n   * @param marker - The marker to compare against (from previous actualization)\n   * @returns Changed entries and the current marker to store\n   */\n  getChangedEntries(\n    workspace: Workspace,\n    queries: Query[],\n    marker: ChangeMarker | null,\n  ): Promise<ChangedEntriesResult>;\n}\n\n/**\n * Strip quotes from a string value if present.\n * Handles both single and double quotes.\n */\nfunction stripQuotes(value: string): string {\n  if (\n    (value.startsWith('\"') && value.endsWith('\"')) ||\n    (value.startsWith(\"'\") && value.endsWith(\"'\"))\n  ) {\n    return value.slice(1, -1);\n  }\n  return value;\n}\n\n/**\n * Parse a checkpoint value into a ChangeMarker.\n *\n * Expected format: \"git:abc123\" or \"ts:2026-01-08T15:00Z\"\n * Strips quotes from the raw value as metadata raw values include quotes.\n *\n * @param checkpointRaw - Raw checkpoint metadata value (may include quotes)\n * @returns Parsed marker or null if invalid/missing\n */\nexport function parseCheckpoint(checkpointRaw: string | undefined): ChangeMarker | null {\n  if (!checkpointRaw) {\n    return null;\n  }\n\n  const value = stripQuotes(checkpointRaw);\n  const colonIndex = value.indexOf(\":\");\n\n  if (colonIndex === -1) {\n    return null;\n  }\n\n  const provider = value.slice(0, colonIndex);\n  const markerValue = value.slice(colonIndex + 1);\n\n  if (!markerValue) {\n    return null;\n  }\n\n  // Validate known providers\n  if (provider === \"git\" || provider === \"ts\") {\n    return { type: provider, value: markerValue };\n  }\n\n  return null;\n}\n\n/**\n * Format a ChangeMarker as a checkpoint string.\n *\n * @param marker - The marker to format\n * @returns Formatted string like \"git:abc123\" or \"ts:2026-01-08T15:00Z\"\n */\nexport function formatCheckpoint(marker: ChangeMarker): string {\n  return `${marker.type}:${marker.value}`;\n}\n\nexport { TimestampChangeTracker } from \"./timestamp-tracker.js\";\n\n// For Node.js environments that need git-based tracking, use:\n// import { createChangeTracker, GitChangeTracker } from \"@rejot-dev/thalo/change-tracker/node\";\n"],"mappings":";;;;;;;;;AAwDA,IAAa,0BAAb,cAA6C,MAAM;;CAEjD,AAAS;CAET,YAAY,OAAiB;AAC3B,QACE,0CAA0C,MAAM,KAAK,KAAK,CAAC,yDAE5D;AACD,OAAK,OAAO;AACZ,OAAK,QAAQ;;;;;;;AA+CjB,SAAS,YAAY,OAAuB;AAC1C,KACG,MAAM,WAAW,KAAI,IAAI,MAAM,SAAS,KAAI,IAC5C,MAAM,WAAW,IAAI,IAAI,MAAM,SAAS,IAAI,CAE7C,QAAO,MAAM,MAAM,GAAG,GAAG;AAE3B,QAAO;;;;;;;;;;;AAYT,SAAgB,gBAAgB,eAAwD;AACtF,KAAI,CAAC,cACH,QAAO;CAGT,MAAM,QAAQ,YAAY,cAAc;CACxC,MAAM,aAAa,MAAM,QAAQ,IAAI;AAErC,KAAI,eAAe,GACjB,QAAO;CAGT,MAAM,WAAW,MAAM,MAAM,GAAG,WAAW;CAC3C,MAAM,cAAc,MAAM,MAAM,aAAa,EAAE;AAE/C,KAAI,CAAC,YACH,QAAO;AAIT,KAAI,aAAa,SAAS,aAAa,KACrC,QAAO;EAAE,MAAM;EAAU,OAAO;EAAa;AAG/C,QAAO;;;;;;;;AAST,SAAgB,iBAAiB,QAA8B;AAC7D,QAAO,GAAG,OAAO,KAAK,GAAG,OAAO"}

package/dist/services/change-tracker/create-tracker.d.ts

@@ -0,0 +1,42 @@
+import { ChangeTracker, ChangeTrackerOptions, UncommittedChangesError } from "./change-tracker.js";
+import { GitChangeTracker } from "./git-tracker.js";
+
+//#region src/services/change-tracker/create-tracker.d.ts
+
+/**
+ * Error thrown when a git tracker is requested but the current directory
+ * is not inside a git repository.
+ */
+declare class NotInGitRepoError extends Error {
+  /** The directory that was checked */
+  readonly cwd: string;
+  constructor(cwd: string);
+}
+/**
+ * Options for creating a change tracker
+ */
+interface CreateChangeTrackerOptions extends ChangeTrackerOptions {
+  /**
+   * Preferred tracker type.
+   * - "auto": Use git if in a git repo, otherwise timestamp (default)
+   * - "git": Force git tracker (throws if not in git repo)
+   * - "timestamp": Force timestamp tracker
+   */
+  preferredType?: "auto" | "git" | "timestamp";
+}
+/**
+ * Create a change tracker based on environment and options.
+ *
+ * By default, auto-detects git repository and uses GitChangeTracker
+ * if available, otherwise falls back to TimestampChangeTracker.
+ *
+ * NOTE: This is a Node.js-only function. For browser environments,
+ * use TimestampChangeTracker directly.
+ *
+ * @param options - Tracker creation options
+ * @returns Appropriate change tracker implementation
+ */
+declare function createChangeTracker(options?: CreateChangeTrackerOptions): Promise<ChangeTracker>;
+//#endregion
+export { CreateChangeTrackerOptions, GitChangeTracker, NotInGitRepoError, UncommittedChangesError, createChangeTracker };
+//# sourceMappingURL=create-tracker.d.ts.map

package/dist/services/change-tracker/create-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-tracker.d.ts","names":[],"sources":["../../../src/services/change-tracker/create-tracker.ts"],"sourcesContent":[],"mappings":";;;;;;;;;cAiBa,iBAAA,SAA0B,KAAA;;;;;;;;UActB,0BAAA,SAAmC;;;;;;;;;;;;;;;;;;;;;iBAsB9B,mBAAA,WACX,6BACR,QAAQ"}

package/dist/services/change-tracker/create-tracker.js

@@ -0,0 +1,53 @@
+import { TimestampChangeTracker } from "./timestamp-tracker.js";
+import { UncommittedChangesError } from "./change-tracker.js";
+import { detectGitContext } from "../../git/git.js";
+import { GitChangeTracker } from "./git-tracker.js";
+
+//#region src/services/change-tracker/create-tracker.ts
+/**
+* Error thrown when a git tracker is requested but the current directory
+* is not inside a git repository.
+*/
+var NotInGitRepoError = class extends Error {
+	/** The directory that was checked */
+	cwd;
+	constructor(cwd) {
+		super(`Git tracker requested but "${cwd}" is not in a git repository`);
+		this.name = "NotInGitRepoError";
+		this.cwd = cwd;
+	}
+};
+/**
+* Create a change tracker based on environment and options.
+*
+* By default, auto-detects git repository and uses GitChangeTracker
+* if available, otherwise falls back to TimestampChangeTracker.
+*
+* NOTE: This is a Node.js-only function. For browser environments,
+* use TimestampChangeTracker directly.
+*
+* @param options - Tracker creation options
+* @returns Appropriate change tracker implementation
+*/
+async function createChangeTracker(options = {}) {
+	const { preferredType = "auto", cwd, force } = options;
+	if (preferredType === "timestamp") return new TimestampChangeTracker();
+	const nodeCwd = cwd ?? process.cwd();
+	const gitContext = await detectGitContext(nodeCwd);
+	if (preferredType === "git") {
+		if (!gitContext.isGitRepo) throw new NotInGitRepoError(nodeCwd);
+		return new GitChangeTracker({
+			cwd: nodeCwd,
+			force
+		});
+	}
+	if (gitContext.isGitRepo) return new GitChangeTracker({
+		cwd: nodeCwd,
+		force
+	});
+	return new TimestampChangeTracker();
+}
+
+//#endregion
+export { GitChangeTracker, NotInGitRepoError, UncommittedChangesError, createChangeTracker };
+//# sourceMappingURL=create-tracker.js.map

package/dist/services/change-tracker/create-tracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-tracker.js","names":[],"sources":["../../../src/services/change-tracker/create-tracker.ts"],"sourcesContent":["/**\n * Node.js-only module for creating change trackers.\n *\n * This module imports git functionality directly and should only be used\n * in Node.js environments (CLI, scripts). For browser code, use\n * TimestampChangeTracker directly from \"./change-tracker.js\".\n */\n\nimport { detectGitContext } from \"../../git/git.js\";\nimport type { ChangeTracker, ChangeTrackerOptions } from \"./change-tracker.js\";\nimport { GitChangeTracker } from \"./git-tracker.js\";\nimport { TimestampChangeTracker } from \"./timestamp-tracker.js\";\n\n/**\n * Error thrown when a git tracker is requested but the current directory\n * is not inside a git repository.\n */\nexport class NotInGitRepoError extends Error {\n  /** The directory that was checked */\n  readonly cwd: string;\n\n  constructor(cwd: string) {\n    super(`Git tracker requested but \"${cwd}\" is not in a git repository`);\n    this.name = \"NotInGitRepoError\";\n    this.cwd = cwd;\n  }\n}\n\n/**\n * Options for creating a change tracker\n */\nexport interface CreateChangeTrackerOptions extends ChangeTrackerOptions {\n  /**\n   * Preferred tracker type.\n   * - \"auto\": Use git if in a git repo, otherwise timestamp (default)\n   * - \"git\": Force git tracker (throws if not in git repo)\n   * - \"timestamp\": Force timestamp tracker\n   */\n  preferredType?: \"auto\" | \"git\" | \"timestamp\";\n}\n\n/**\n * Create a change tracker based on environment and options.\n *\n * By default, auto-detects git repository and uses GitChangeTracker\n * if available, otherwise falls back to TimestampChangeTracker.\n *\n * NOTE: This is a Node.js-only function. For browser environments,\n * use TimestampChangeTracker directly.\n *\n * @param options - Tracker creation options\n * @returns Appropriate change tracker implementation\n */\nexport async function createChangeTracker(\n  options: CreateChangeTrackerOptions = {},\n): Promise<ChangeTracker> {\n  const { preferredType = \"auto\", cwd, force } = options;\n\n  if (preferredType === \"timestamp\") {\n    return new TimestampChangeTracker();\n  }\n\n  const nodeCwd = cwd ?? process.cwd();\n  const gitContext = await detectGitContext(nodeCwd);\n\n  if (preferredType === \"git\") {\n    if (!gitContext.isGitRepo) {\n      throw new NotInGitRepoError(nodeCwd);\n    }\n    return new GitChangeTracker({ cwd: nodeCwd, force });\n  }\n\n  // Auto mode: use git if available\n  if (gitContext.isGitRepo) {\n    return new GitChangeTracker({ cwd: nodeCwd, force });\n  }\n\n  return new TimestampChangeTracker();\n}\n\n// Re-export things CLI needs\nexport { GitChangeTracker } from \"./git-tracker.js\";\nexport { UncommittedChangesError } from \"./change-tracker.js\";\n"],"mappings":";;;;;;;;;;AAiBA,IAAa,oBAAb,cAAuC,MAAM;;CAE3C,AAAS;CAET,YAAY,KAAa;AACvB,QAAM,8BAA8B,IAAI,8BAA8B;AACtE,OAAK,OAAO;AACZ,OAAK,MAAM;;;;;;;;;;;;;;;AA6Bf,eAAsB,oBACpB,UAAsC,EAAE,EAChB;CACxB,MAAM,EAAE,gBAAgB,QAAQ,KAAK,UAAU;AAE/C,KAAI,kBAAkB,YACpB,QAAO,IAAI,wBAAwB;CAGrC,MAAM,UAAU,OAAO,QAAQ,KAAK;CACpC,MAAM,aAAa,MAAM,iBAAiB,QAAQ;AAElD,KAAI,kBAAkB,OAAO;AAC3B,MAAI,CAAC,WAAW,UACd,OAAM,IAAI,kBAAkB,QAAQ;AAEtC,SAAO,IAAI,iBAAiB;GAAE,KAAK;GAAS;GAAO,CAAC;;AAItD,KAAI,WAAW,UACb,QAAO,IAAI,iBAAiB;EAAE,KAAK;EAAS;EAAO,CAAC;AAGtD,QAAO,IAAI,wBAAwB"}