@miliastry/quasar 1.0.0

package/src/Types/core.ts

@@ -0,0 +1,270 @@
+/**
+ * DocumentEngine — Core Types
+ *
+ * The foundational types for the entire Language Platform.
+ * Every layer builds on these.
+ */
+
+import type { Diagnostic } from './diagnostics'
+import type { Range } from './tokens'
+
+// ─── Node Identity ─────────────────────────────────────────────
+
+/** Stable identifier that survives incremental re-parses */
+export type NodeId = string & { readonly __brand: 'NodeId' }
+
+/**
+ * Monotonic counter backing `createNodeId`.
+ *
+ * Deliberately NOT a UUID. Node IDs are process-local and ephemeral — they are
+ * regenerated on every parse and never restored from persistence — so the
+ * randomness of `crypto.randomUUID()` bought nothing while costing on two axes:
+ * it is ~7x slower per call (and a full document parse mints one per node), and
+ * its 36 characters are echoed into *every* element as `data-node-id`, inflating
+ * the emitted HTML and the work the DOM morpher has to diff.
+ *
+ * A counter is unique within the process, which is the only scope where node IDs
+ * are ever compared.
+ */
+let _nodeIdCounter = 0
+
+export function createNodeId(): NodeId {
+  return `n${_nodeIdCounter++}` as NodeId
+}
+
+/**
+ * Reset the node ID counter. Test-only: lets a suite assert on stable IDs.
+ * Never call this while a document tree is alive — reusing IDs across live
+ * trees would break every `Map<NodeId, …>` in the engine.
+ */
+export function __resetNodeIdCounter(): void {
+  _nodeIdCounter = 0
+}
+
+// ─── Node Kind ─────────────────────────────────────────────────
+
+/**
+ * The semantic kind of a node in the document tree.
+ *
+ * Language-agnostic at the core — BBCode tags, Markdown headings,
+ * HTML elements, etc. all map to these.
+ */
+export type NodeKind =
+  | 'document'
+  | 'paragraph'
+  | 'text'
+  | 'bold'
+  | 'italic'
+  | 'underline'
+  | 'strikethrough'
+  | 'color'
+  | 'font_size'
+  | 'font'
+  | 'code'
+  | 'inline_code'
+  | 'spoiler'
+  | 'heading'
+  | 'center'
+  | 'right'
+  | 'left'
+  | 'url'
+  | 'email'
+  | 'profile'
+  | 'image'
+  | 'video'
+  | 'audio'
+  | 'imagemap'
+  | 'imagemap_area'
+  | 'svg'
+  | 'quote'
+  | 'notice'
+  | 'spoilerbox'
+  | 'box'
+  | 'boxw'
+  | 'list'
+  | 'list_item'
+  | 'zalgo'
+  | 'aesthetic'
+  | 'sparkle'
+  | 'bubble'
+  | 'flower'
+  | 'gradient'
+  | 'grow'
+  | 'sinewave'
+  | 'rainbow'
+  | 'spacing'
+  | 'empty_line'
+  | 'group'
+  | 'wnotice'
+  | 'align'
+  | 'tables'
+  | 'table_row'
+  | 'table_col'
+  | 'table_th'
+  | 'gallery'
+  | 'columns'
+  | 'separator'
+  | 'scroll'
+  | 'sup'
+  | 'sub'
+  | 'abbr'
+  | 'mark'
+  | 'kbd'
+  | 'tooltip'
+  | 'flip'
+  | 'raw'
+  | 'plain'
+  | 'effect'
+  | 'anim'
+  | 'container'
+  | 'style_tag'
+  | 'guild'
+  | 'map'
+  | 'custom'
+  | 'error'
+  | 'unknown'
+
+// ─── Attributes ────────────────────────────────────────────────
+
+export type NodeAttributes = Record<string, string | number | boolean | null | undefined>
+
+// ─── Metadata ──────────────────────────────────────────────────
+
+export interface NodeMetadata {
+  /** Arbitrary extensions data (plugins can add here) */
+  [key: string]: unknown
+}
+
+// ─── Source Range ──────────────────────────────────────────────
+
+export interface SourceRange {
+  start: number
+  end: number
+}
+
+// ─── Document Node ─────────────────────────────────────────────
+
+/**
+ * The primary user-facing node in the Document Model.
+ *
+ * This is the Red Tree node — mutable, with identity.
+ * It wraps/holds reference to the Green Tree node for structural info.
+ */
+export interface DocumentNode {
+  /** Stable ID that survives incremental re-parses */
+  id: NodeId
+  /** Monotonically increasing version number for change tracking */
+  version: number
+  /** Semantic kind */
+  kind: NodeKind
+  /** Raw text content (for text leaves) */
+  text: string
+  /** Tag-level attributes (e.g. color=#ff0000, size=150) */
+  attributes: NodeAttributes
+  /** Arbitrary metadata (extensible by plugins) */
+  metadata: NodeMetadata
+  /** Child nodes */
+  children: DocumentNode[]
+  /** Diagnostics attached to this specific node */
+  diagnostics: Diagnostic[]
+  /** Source position in the original text (for mapping back) */
+  sourceRange: SourceRange | null
+  /** Reference back to parent (null for root) */
+  parentId: NodeId | null
+  /** Whether this node is "synthetic" (not from source, e.g. auto-generated) */
+  isSynthetic: boolean
+}
+
+// ─── Document ──────────────────────────────────────────────────
+
+export interface DocumentSnapshot {
+  root: DocumentNode
+  source: string
+  language: string
+  version: number
+  createdAt: number
+}
+
+export type DocumentChangeKind =
+  | 'node_inserted'
+  | 'node_deleted'
+  | 'node_updated'
+  | 'node_moved'
+  | 'attribute_changed'
+  | 'text_changed'
+  | 'source_changed'
+  | 'full_rebuild'
+
+export interface DocumentChangeEvent {
+  kind: DocumentChangeKind
+  nodeId: NodeId
+  /** The affected node (after the change) */
+  node: DocumentNode | null
+  /** Previous version of the node (before the change) */
+  previousNode: DocumentNode | null
+  /** Additional context data */
+  metadata?: Record<string, unknown>
+}
+
+// ─── Helpers ───────────────────────────────────────────────────
+
+export function createDocumentNode(
+  kind: NodeKind,
+  text: string = '',
+  attributes: NodeAttributes = {},
+  children: DocumentNode[] = [],
+): DocumentNode {
+  return {
+    id: createNodeId(),
+    version: 1,
+    kind,
+    text,
+    attributes,
+    metadata: {},
+    children,
+    diagnostics: [],
+    sourceRange: null,
+    parentId: null,
+    isSynthetic: false,
+  }
+}
+
+export function cloneNode(node: DocumentNode, deep: boolean = false): DocumentNode {
+  return {
+    ...node,
+    id: node.id,
+    version: node.version + 1,
+    children: deep ? node.children.map(c => cloneNode(c, true)) : [...node.children],
+    diagnostics: [...node.diagnostics],
+  }
+}
+
+/** Get the text content of a node and all its descendants */
+export function getNodeText(node: DocumentNode): string {
+  if (node.children.length === 0) return node.text
+  return node.children.map(getNodeText).join('')
+}
+
+/** Walk all descendants in pre-order */
+export function walkPreOrder(
+  node: DocumentNode,
+  visitor: (n: DocumentNode, depth: number) => void | 'skip',
+  depth: number = 0,
+): void {
+  const result = visitor(node, depth)
+  if (result !== 'skip') {
+    for (const child of node.children) {
+      walkPreOrder(child, visitor, depth + 1)
+    }
+  }
+}
+
+/** Find a node by ID */
+export function findById(root: DocumentNode, id: NodeId): DocumentNode | null {
+  if (root.id === id) return root
+  for (const child of root.children) {
+    const found = findById(child, id)
+    if (found) return found
+  }
+  return null
+}

package/src/Types/diagnostics.ts

@@ -0,0 +1,156 @@
+/**
+ * DocumentEngine — Diagnostic Types
+ *
+ * Diagnostics are messages attached to specific nodes or ranges
+ * in the document tree. Inspired by VSCode's diagnostic model.
+ */
+
+import type { Range } from './tokens'
+import type { NodeId, NodeKind } from './core'
+
+// ─── Severity ──────────────────────────────────────────────────
+
+export type DiagnosticSeverity = 'hint' | 'info' | 'warning' | 'error'
+
+export const DIAGNOSTIC_SEVERITY: Record<DiagnosticSeverity, number> = {
+  hint: 0,
+  info: 1,
+  warning: 2,
+  error: 3,
+}
+
+// ─── Tags ──────────────────────────────────────────────────────
+
+export type DiagnosticTag =
+  | 'unnecessary'
+  | 'deprecated'
+  | 'unused'
+  | 'redundant'
+
+// ─── Diagnostic ────────────────────────────────────────────────
+
+export interface Diagnostic {
+  // There is deliberately no `id` field. Each diagnostic used to mint a
+  // crypto.randomUUID() that no reader in the engine or the app ever
+  // consumed — measured at 14% of analyze() on error-heavy documents. A
+  // diagnostic is identified by what it says and where: (code, range, nodeId).
+  /** Machine-readable code (e.g. 'invalid-color', 'missing-close-tag') */
+  code: string
+  /** Human-readable message */
+  message: string
+  /** Severity level */
+  severity: DiagnosticSeverity
+  /** Optional tags for additional categorization */
+  tags: DiagnosticTag[]
+  /** Source range in the original text */
+  range: Range | null
+  /** Node ID this diagnostic is attached to */
+  nodeId: NodeId | null
+  /** Node kind for context */
+  nodeKind: NodeKind | null
+  /** Source of this diagnostic (built-in, plugin name, etc.) */
+  source: string
+  /** Optional related information */
+  related?: DiagnosticRelatedInfo[]
+  /** Optional fix suggestions */
+  fixes?: DiagnosticFix[]
+}
+
+export interface DiagnosticRelatedInfo {
+  message: string
+  range: Range | null
+  nodeId: NodeId | null
+}
+
+export interface DiagnosticFix {
+  description: string
+  /** Whether this fix is automatic or requires user confirmation */
+  isAutomatic: boolean
+  /** The operations to apply as a fix */
+  operations: FixOperation[]
+}
+
+export type FixOperation =
+  | { kind: 'replace_text'; range: Range; newText: string }
+  | { kind: 'insert_text'; position: number; text: string }
+  | { kind: 'delete_range'; range: Range }
+  | { kind: 'wrap_in_tag'; tagName: string; range: Range }
+
+// ─── Diagnostic Collection ─────────────────────────────────────
+
+export interface DiagnosticCollection {
+  /** All diagnostics */
+  items: Diagnostic[]
+  /** Count by severity */
+  errorCount: number
+  warningCount: number
+  infoCount: number
+  hintCount: number
+  /** Quick access: only errors */
+  errors: Diagnostic[]
+  /** Quick access: only warnings */
+  warnings: Diagnostic[]
+}
+
+export function createDiagnosticCollection(): DiagnosticCollection {
+  return {
+    items: [],
+    errorCount: 0,
+    warningCount: 0,
+    infoCount: 0,
+    hintCount: 0,
+    errors: [],
+    warnings: [],
+  }
+}
+
+export function createDiagnostic(
+  code: string,
+  message: string,
+  severity: DiagnosticSeverity,
+  options?: {
+    nodeId?: NodeId | null
+    nodeKind?: NodeKind | null
+    range?: Range | null
+    tags?: DiagnosticTag[]
+    source?: string
+    related?: DiagnosticRelatedInfo[]
+    fixes?: DiagnosticFix[]
+  },
+): Diagnostic {
+  return {
+    code,
+    message,
+    severity,
+    tags: options?.tags ?? [],
+    range: options?.range ?? null,
+    nodeId: options?.nodeId ?? null,
+    nodeKind: options?.nodeKind ?? null,
+    source: options?.source ?? 'document-engine',
+    related: options?.related,
+    fixes: options?.fixes,
+  }
+}
+
+export function addDiagnostic(
+  collection: DiagnosticCollection,
+  diagnostic: Diagnostic,
+): void {
+  collection.items.push(diagnostic)
+  switch (diagnostic.severity) {
+    case 'error':
+      collection.errorCount++
+      collection.errors.push(diagnostic)
+      break
+    case 'warning':
+      collection.warningCount++
+      collection.warnings.push(diagnostic)
+      break
+    case 'info':
+      collection.infoCount++
+      break
+    case 'hint':
+      collection.hintCount++
+      break
+  }
+}

package/src/Types/index.ts

@@ -0,0 +1,23 @@
+export type { Token, TokenKind, TokenStream, Trivia, TriviaKind, Range } from './tokens'
+export { createToken, createTrivia, range, rangeLength, rangeContains, ArrayTokenStream } from './tokens'
+export type {
+  DocumentNode, NodeId, NodeKind, NodeAttributes, NodeMetadata,
+  DocumentSnapshot, DocumentChangeEvent, DocumentChangeKind, SourceRange,
+} from './core'
+export { createNodeId, createDocumentNode, cloneNode, getNodeText, walkPreOrder, findById } from './core'
+export type {
+  Diagnostic, DiagnosticSeverity, DiagnosticTag, DiagnosticCollection,
+  DiagnosticRelatedInfo, DiagnosticFix, FixOperation,
+} from './diagnostics'
+export { createDiagnosticCollection, createDiagnostic, addDiagnostic, DIAGNOSTIC_SEVERITY } from './diagnostics'
+export type {
+  Operation, OperationKind,
+  InsertNodeOperation, DeleteNodeOperation, ReplaceNodeOperation,
+  MoveNodeOperation, UpdateAttributesOperation, SetTextOperation,
+  InsertTextOperation, DeleteTextOperation, ReplaceTextOperation,
+  WrapInTagOperation, UnwrapNodeOperation, SplitNodeOperation, MergeNodesOperation,
+} from './operations'
+export { createOperationId, operationLabel } from './operations'
+export type { Query, QuerySelector, QueryCombinator, QueryStep, QueryMatch, QueryResult } from './queries'
+export { query } from './queries'
+export type { SymbolInfo, SymbolKind, Reference, SymbolTableData, SymbolSearchResult } from './symbols'

package/src/Types/operations.ts

@@ -0,0 +1,180 @@
+/**
+ * DocumentEngine — Operation & Transaction Types
+ *
+ * Operations are the atomic units of change in the document.
+ * Every modification goes through operations, never direct mutation.
+ *
+ * Inspired by ProseMirror and Roslyn.
+ */
+
+import type { NodeId, NodeKind, NodeAttributes } from './core'
+import type { Range } from './tokens'
+import type { RedNode } from '../Syntax/RedNode'
+
+// ─── Operation ─────────────────────────────────────────────────
+
+export type OperationKind =
+  | 'insert_node'
+  | 'delete_node'
+  | 'replace_node'
+  | 'move_node'
+  | 'update_attributes'
+  | 'set_text'
+  | 'insert_text'
+  | 'delete_text'
+  | 'replace_text'
+  | 'wrap_in_tag'
+  | 'unwrap_node'
+  | 'split_node'
+  | 'merge_nodes'
+
+export interface BaseOperation {
+  kind: OperationKind
+  /** Stable ID for the operation (for undo/redo pairing) */
+  id: string
+  /** Whether this operation can be undone */
+  undoable: boolean
+  /** Timestamp */
+  timestamp: number
+}
+
+export interface InsertNodeOperation extends BaseOperation {
+  kind: 'insert_node'
+  parentId: NodeId
+  index: number
+  node: RedNode
+}
+
+export interface DeleteNodeOperation extends BaseOperation {
+  kind: 'delete_node'
+  nodeId: NodeId
+  /** The deleted node (stored for undo) */
+  node: RedNode
+  parentId: NodeId
+  index: number
+}
+
+export interface ReplaceNodeOperation extends BaseOperation {
+  kind: 'replace_node'
+  nodeId: NodeId
+  newNode: RedNode
+  oldNode: RedNode
+}
+
+export interface MoveNodeOperation extends BaseOperation {
+  kind: 'move_node'
+  nodeId: NodeId
+  fromParentId: NodeId
+  fromIndex: number
+  toParentId: NodeId
+  toIndex: number
+}
+
+export interface UpdateAttributesOperation extends BaseOperation {
+  kind: 'update_attributes'
+  nodeId: NodeId
+  newAttributes: NodeAttributes
+  oldAttributes: NodeAttributes
+}
+
+export interface SetTextOperation extends BaseOperation {
+  kind: 'set_text'
+  nodeId: NodeId
+  newText: string
+  oldText: string
+}
+
+export interface InsertTextOperation extends BaseOperation {
+  kind: 'insert_text'
+  nodeId: NodeId
+  position: number
+  text: string
+}
+
+export interface DeleteTextOperation extends BaseOperation {
+  kind: 'delete_text'
+  nodeId: NodeId
+  position: number
+  length: number
+  text: string
+}
+
+export interface ReplaceTextOperation extends BaseOperation {
+  kind: 'replace_text'
+  nodeId: NodeId
+  position: number
+  length: number
+  newText: string
+  oldText: string
+}
+
+export interface WrapInTagOperation extends BaseOperation {
+  kind: 'wrap_in_tag'
+  nodeId: NodeId
+  tagName: string
+  attributes: NodeAttributes
+}
+
+export interface UnwrapNodeOperation extends BaseOperation {
+  kind: 'unwrap_node'
+  nodeId: NodeId
+  parentId: NodeId
+  children: RedNode[]
+}
+
+export interface SplitNodeOperation extends BaseOperation {
+  kind: 'split_node'
+  nodeId: NodeId
+  position: number
+  leftNode: RedNode
+  rightNode: RedNode
+}
+
+export interface MergeNodesOperation extends BaseOperation {
+  kind: 'merge_nodes'
+  leftNodeId: NodeId
+  rightNodeId: NodeId
+  mergedNode: RedNode
+}
+
+export type Operation =
+  | InsertNodeOperation
+  | DeleteNodeOperation
+  | ReplaceNodeOperation
+  | MoveNodeOperation
+  | UpdateAttributesOperation
+  | SetTextOperation
+  | InsertTextOperation
+  | DeleteTextOperation
+  | ReplaceTextOperation
+  | WrapInTagOperation
+  | UnwrapNodeOperation
+  | SplitNodeOperation
+  | MergeNodesOperation
+
+// ─── Operation Helpers ─────────────────────────────────────────
+
+let opCounter = 0
+
+export function createOperationId(): string {
+  return `op-${Date.now()}-${++opCounter}`
+}
+
+export function operationLabel(op: Operation): string {
+  const labels: Record<OperationKind, string> = {
+    insert_node: 'Insert Node',
+    delete_node: 'Delete Node',
+    replace_node: 'Replace Node',
+    move_node: 'Move Node',
+    update_attributes: 'Update Attributes',
+    set_text: 'Set Text',
+    insert_text: 'Insert Text',
+    delete_text: 'Delete Text',
+    replace_text: 'Replace Text',
+    wrap_in_tag: 'Wrap in Tag',
+    unwrap_node: 'Unwrap Node',
+    split_node: 'Split Node',
+    merge_nodes: 'Merge Nodes',
+  }
+  return labels[op.kind]
+}