@almadar/extensions 2.0.0 → 2.0.2

package/dist/index.d.ts

@@ -0,0 +1,213 @@
+/**
+ * Virtual Document — The TypeScript Wrapper Trick
+ *
+ * Wraps .orb JSON content inside a TypeScript file that imports
+ * OrbitalSchema from @almadar/core. This lets the TypeScript
+ * language server validate the entire .orb structure for free.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Number of lines the prefix adds before .orb content begins.
+ * Used to offset diagnostics back to original .orb line numbers.
+ *
+ * The prefix is exactly 2 lines:
+ *   Line 1: import type { OrbitalSchema } from '@almadar/core';
+ *   Line 2: const _orbital = ... (the .orb content starts on THIS line)
+ *
+ * So .orb line 1 corresponds to virtual .ts line 2.
+ */
+declare const WRAPPER_LINE_OFFSET = 1;
+/**
+ * Number of characters on the prefix line before .orb content begins.
+ * `const _orbital = ` is 18 characters.
+ */
+declare const WRAPPER_COL_OFFSET = 18;
+/**
+ * Wrap raw .orb JSON content into a virtual TypeScript file.
+ *
+ * @param orbContent - The raw JSON string from the .orb file
+ * @returns The complete TypeScript source that tsserver can validate
+ *
+ * @example
+ * ```ts
+ * const orbJson = fs.readFileSync('app.orb', 'utf-8');
+ * const tsContent = wrapOrbContent(orbJson);
+ * // tsContent is now a valid .ts file that TypeScript can check
+ * ```
+ */
+declare function wrapOrbContent(orbContent: string): string;
+/**
+ * Extract the original .orb content from a wrapped virtual TypeScript file.
+ *
+ * @param virtualContent - The virtual .ts file content
+ * @returns The original .orb JSON string, or null if not a valid wrapper
+ */
+declare function unwrapOrbContent(virtualContent: string): string | null;
+/**
+ * Generate the virtual .ts filename for a given .orb file path.
+ *
+ * @param orbFilePath - Absolute path to the .orb file
+ * @returns The virtual .ts file path (same directory, `.orb.ts` extension)
+ *
+ * @example
+ * ```ts
+ * getVirtualPath('/projects/app.orb')
+ * // → '/projects/app.orb.ts'
+ * ```
+ */
+declare function getVirtualPath(orbFilePath: string): string;
+
+/**
+ * Diagnostic Mapper
+ *
+ * Maps TypeScript diagnostics from the virtual .ts file back to
+ * the original .orb file positions, adjusting for the wrapper prefix.
+ *
+ * @packageDocumentation
+ */
+/**
+ * A position in a text document (0-indexed line and character).
+ */
+interface Position {
+    /** 0-indexed line number */
+    line: number;
+    /** 0-indexed character offset within the line */
+    character: number;
+}
+/**
+ * A range in a text document.
+ */
+interface Range {
+    start: Position;
+    end: Position;
+}
+/**
+ * Severity levels matching both VSCode and Zed conventions.
+ */
+type DiagnosticSeverity = 'error' | 'warning' | 'info' | 'hint';
+/**
+ * An editor-agnostic diagnostic — the universal unit that
+ * VSCode and Zed extensions translate into their native format.
+ */
+interface OrbDiagnostic {
+    /** Human-readable error message */
+    message: string;
+    /** Location in the .orb file (already adjusted from virtual .ts) */
+    range: Range;
+    /** Severity level */
+    severity: DiagnosticSeverity;
+    /** TypeScript error code (e.g. 2322, 2353) for filtering */
+    code?: number;
+    /** Source identifier */
+    source: 'almadar-ts';
+}
+/**
+ * Raw TypeScript diagnostic (minimal shape matching ts.Diagnostic).
+ * Extensions should map their TS server output to this shape.
+ */
+interface TsDiagnostic {
+    /** 0-indexed line in the virtual .ts file */
+    line: number;
+    /** 0-indexed character in the virtual .ts file */
+    character: number;
+    /** End line (optional, defaults to same as line) */
+    endLine?: number;
+    /** End character (optional) */
+    endCharacter?: number;
+    /** Error message text */
+    messageText: string;
+    /** TS error code */
+    code?: number;
+    /** 1 = error, 2 = warning, 3 = info, 4 = hint */
+    category?: number;
+}
+/**
+ * Map a virtual .ts file position back to the original .orb position.
+ *
+ * @param virtualLine - 0-indexed line in the virtual .ts file
+ * @param virtualChar - 0-indexed character in the virtual .ts file
+ * @returns Adjusted position in the .orb file
+ */
+declare function mapPositionToOrb(virtualLine: number, virtualChar: number): Position;
+/**
+ * Map a single TypeScript diagnostic to an OrbDiagnostic.
+ *
+ * @param tsDiag - The raw TypeScript diagnostic
+ * @returns An editor-agnostic diagnostic with adjusted positions
+ */
+declare function mapDiagnostic(tsDiag: TsDiagnostic): OrbDiagnostic;
+/**
+ * Map an array of TypeScript diagnostics to OrbDiagnostics.
+ * Filters out diagnostics that fall within the wrapper prefix.
+ *
+ * @param diagnostics - Array of raw TypeScript diagnostics
+ * @returns Array of editor-agnostic diagnostics
+ */
+declare function mapDiagnostics(diagnostics: TsDiagnostic[]): OrbDiagnostic[];
+
+/**
+ * S-Expression Grammar Generator
+ *
+ * Generates a TextMate injection grammar for S-expression syntax
+ * highlighting inside .orb files. The grammar is derived from
+ * @almadar/operators — the single source of truth for all operator names.
+ *
+ * This means new operators automatically get highlighting when
+ * the package is rebuilt. No manual grammar maintenance.
+ *
+ * @packageDocumentation
+ */
+/**
+ * TextMate grammar rule
+ */
+interface TmRule {
+    name: string;
+    match: string;
+}
+/**
+ * TextMate injection grammar structure
+ */
+interface TmInjectionGrammar {
+    scopeName: string;
+    injectionSelector: string;
+    patterns: TmRule[];
+}
+/**
+ * Generate a TextMate injection grammar for S-expression highlighting.
+ *
+ * The grammar injects into `.orb` files (JSON scope) and highlights:
+ * - **Operators** by category (arithmetic, effect, control, etc.)
+ * - **Bindings** (`@entity.field`, `@payload.value`)
+ * - **Events** (UPPER_CASE_NAMES)
+ *
+ * @returns A complete TextMate injection grammar object
+ *
+ * @example
+ * ```ts
+ * import { generateSExprGrammar } from '@almadar/extensions';
+ * import { writeFileSync } from 'fs';
+ *
+ * const grammar = generateSExprGrammar();
+ * writeFileSync('sexpr.injection.json', JSON.stringify(grammar, null, 2));
+ * ```
+ */
+declare function generateSExprGrammar(): TmInjectionGrammar;
+/**
+ * Serialize the grammar to a formatted JSON string.
+ * Ready to be written to `sexpr.injection.json`.
+ */
+declare function generateSExprGrammarJson(): string;
+/**
+ * Get a flat list of all operator names from the registry.
+ * Useful for editor extensions that need the operator list without
+ * importing @almadar/operators directly.
+ */
+declare function getOperatorNames(): string[];
+/**
+ * Get operators grouped by category.
+ * Useful for autocomplete that groups suggestions by category.
+ */
+declare function getOperatorsByCategory(): Record<string, string[]>;
+
+export { type DiagnosticSeverity, type OrbDiagnostic, type Position, type Range, type TmInjectionGrammar, type TsDiagnostic, WRAPPER_COL_OFFSET, WRAPPER_LINE_OFFSET, generateSExprGrammar, generateSExprGrammarJson, getOperatorNames, getOperatorsByCategory, getVirtualPath, mapDiagnostic, mapDiagnostics, mapPositionToOrb, unwrapOrbContent, wrapOrbContent };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almadar/extensions",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "Editor extension utilities for .orb files — virtual document wrapper and S-expression grammar generator",
   "type": "module",
   "main": "./dist/index.js",
@@ -25,7 +25,7 @@
   "devDependencies": {
     "tsup": "^8.0.0",
     "typescript": "^5.4.0",
-    "tsx": "^4.0.0"
+    "@types/node": "^22.0.0"
   },
   "repository": {
     "type": "git",
@@ -43,7 +43,7 @@
   ],
   "homepage": "https://github.com/almadar-io/almadar#readme",
   "scripts": {
-    "build": "tsup && pnpm run generate-grammar && pnpm run build:editors",
+    "build": "tsup && pnpm run generate-grammar && pnpm run build:editors || true",
     "build:core": "tsup && pnpm run generate-grammar",
     "build:watch": "tsup --watch",
     "build:editors": "pnpm run build:lsp && pnpm run build:vscode && pnpm run build:zed",

package/dist/sexpr.injection.json

@@ -1,74 +0,0 @@
-{
-  "scopeName": "source.orb.sexpr-injection",
-  "injectionSelector": "L:source.orb -comment",
-  "patterns": [
-    {
-      "name": "keyword.operator.arithmetic.sexpr",
-      "match": "(?<=\")(floor|round|clamp|ceil|abs|min|max|\\+|-|\\*|/|%)(?=\")"
-    },
-    {
-      "name": "keyword.operator.comparison.sexpr",
-      "match": "(?<=\")(!=|<=|>=|=|<|>)(?=\")"
-    },
-    {
-      "name": "keyword.operator.logical.sexpr",
-      "match": "(?<=\")(and|not|or|if)(?=\")"
-    },
-    {
-      "name": "keyword.control.sexpr",
-      "match": "(?<=\")(when|let|do|fn)(?=\")"
-    },
-    {
-      "name": "keyword.other.effect.sexpr",
-      "match": "(?<=\")(call-service|render-ui|navigate|persist|despawn|notify|spawn|emit|set)(?=\")"
-    },
-    {
-      "name": "support.function.collection.sexpr",
-      "match": "(?<=\")(includes|contains|average|filter|concat|count|first|empty|find|last|map|sum|nth)(?=\")"
-    },
-    {
-      "name": "support.function.math.sexpr",
-      "match": "(?<=\")(math/randomInt|math/default|math/random|math/clamp|math/floor|math/round|math/ceil|math/sqrt|math/sign|math/lerp|math/abs|math/min|math/max|math/pow|math/mod|math/map)(?=\")"
-    },
-    {
-      "name": "support.function.string.sexpr",
-      "match": "(?<=\")(str/startsWith|str/replaceAll|str/capitalize|str/includes|str/endsWith|str/template|str/truncate|str/replace|str/reverse|str/default|str/concat|str/repeat|str/upper|str/lower|str/slice|str/split|str/trim|str/join|str/len)(?=\")"
-    },
-    {
-      "name": "support.function.array.sexpr",
-      "match": "(?<=\")(array/partition|array/findIndex|array/includes|array/dropLast|array/takeLast|array/reverse|array/flatten|array/groupBy|array/prepend|array/shuffle|array/indexOf|array/filter|array/reduce|array/concat|array/unique|array/append|array/insert|array/remove|array/reject|array/repeat|array/every|array/first|array/slice|array/range|array/find|array/some|array/last|array/sort|array/take|array/drop|array/len|array/map|array/nth|array/sum|array/avg|array/min|array/max|array/zip)(?=\")"
-    },
-    {
-      "name": "support.function.object.sexpr",
-      "match": "(?<=\")(object/entries|object/values|object/equals|object/filter|object/merge|object/clone|object/keys|object/pick|object/omit|object/get|object/set|object/has)(?=\")"
-    },
-    {
-      "name": "support.function.time.sexpr",
-      "match": "(?<=\")(time/subtract|time/isBefore|time/isFuture|time/isAfter|time/weekday|time/format|time/isPast|time/minute|time/today|time/parse|time/month|time/diff|time/year|time/hour|time/now|time/add|time/day)(?=\")"
-    },
-    {
-      "name": "support.function.validate.sexpr",
-      "match": "(?<=\")(validate/minLength|validate/maxLength|validate/required|validate/pattern|validate/length|validate/equals|validate/email|validate/phone|validate/range|validate/oneOf|validate/check|validate/uuid|validate/url|validate/min|validate/max)(?=\")"
-    },
-    {
-      "name": "support.function.format.sexpr",
-      "match": "(?<=\")(format/currency|format/percent|format/ordinal|format/number|format/plural|format/bytes|format/phone|format/list)(?=\")"
-    },
-    {
-      "name": "support.function.async.sexpr",
-      "match": "(?<=\")(async/debounce|async/throttle|async/sequence|async/timeout|async/delay|async/retry|async/race|async/all)(?=\")"
-    },
-    {
-      "name": "variable.other.binding.sexpr",
-      "match": "(?<=\")@(entity|payload|context|config)\\.[a-zA-Z_][a-zA-Z0-9_.]*(?=\")"
-    },
-    {
-      "name": "constant.other.event.sexpr",
-      "match": "(?<=\")[A-Z][A-Z0-9_]{2,}(?=\")"
-    },
-    {
-      "name": "entity.name.tag.slot.sexpr",
-      "match": "(?<=\")(main|sidebar|modal|drawer|overlay|center|toast|hud-top|hud-bottom|floating|system)(?=\")"
-    }
-  ]
-}