@cavelang/highlight 0.5.0

package/License.md

@@ -0,0 +1,6 @@
+# CC0 1.0 Universal (CC0 1.0) Public Domain Dedication
+
+To the extent possible under law, the authors listed in [Authors.md](./Authors.md) have waived all copyright and related or neighboring rights to this software and associated documentation files (the "Software").
+
+For more information, please see:
+https://creativecommons.org/publicdomain/zero/1.0/

package/README.md

@@ -0,0 +1,21 @@
+# @cavelang/highlight
+
+CAVE syntax highlighting for terminals — web-tree-sitter over the
+[`@cavelang/tree-sitter-cave`](../tree-sitter-cave) grammar, colored by the
+grammar's own `queries/highlights.scm` so terminal output and editor
+highlighting share one source of truth.
+
+```ts
+import { highlighter } from '@cavelang/highlight'
+
+const { ansi, spans } = await highlighter()
+process.stdout.write(ansi('auth/middleware USES jwt @ 90% #security\n'))
+```
+
+- `spans(text)` — flat, non-overlapping `{ start, end, capture }` ranges
+- `ansi(text, theme?)` — ANSI-colored text; themes map capture names (or
+  dotted prefixes, longest wins) to SGR parameters
+- `paint(text, spans, theme?)` — renderer, exported for custom span sources
+
+The default theme leaves entities uncolored — they are the bulk of every
+line; color carries the structure (verbs, values, metadata, comments).

package/dist/src/index.d.ts

@@ -0,0 +1,37 @@
+/**
+ * CAVE syntax highlighting.
+ *
+ * Single-source: parses with the `@cavelang/tree-sitter-cave` WASM grammar
+ * via web-tree-sitter and colors the captures of its `queries/highlights.scm`
+ * — the same query editors use — so terminal output and editor highlighting
+ * can never drift apart.
+ *
+ * `highlighter()` loads the grammar once per process; `spans` yields flat,
+ * non-overlapping capture ranges and `ansi` renders them with a
+ * capture-name-keyed theme (longest dotted prefix wins, unstyled text passes
+ * through untouched).
+ */
+/** One highlighted range: `capture` is a `highlights.scm` name like `keyword`. */
+export type Span = {
+    readonly start: number;
+    readonly end: number;
+    readonly capture: string;
+};
+/** Capture name (or dotted prefix) to ANSI SGR parameters, e.g. `keyword: '35'`. */
+export type Theme = Readonly<Record<string, string>>;
+/**
+ * Terminal-default-friendly theme: entities (`variable`) stay uncolored on
+ * purpose — they are the bulk of every line; color carries the structure.
+ */
+export declare const defaultTheme: Theme;
+export type Highlighter = {
+    /** Non-overlapping capture spans of `text`, in document order. */
+    readonly spans: (text: string) => readonly Span[];
+    /** `text` with ANSI colors applied per `theme` (default {@link defaultTheme}). */
+    readonly ansi: (text: string, theme?: Theme) => string;
+};
+/** Renders `spans` over `text` as ANSI; exported for custom span sources. */
+export declare const paint: (text: string, spans: readonly Span[], theme?: Theme) => string;
+/** The process-wide highlighter; loads the grammar WASM on first call. */
+export declare const highlighter: () => Promise<Highlighter>;
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH,kFAAkF;AAClF,MAAM,MAAM,IAAI,GAAG;IACjB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB,CAAA;AAED,oFAAoF;AACpF,MAAM,MAAM,KAAK,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;AAEpD;;;GAGG;AACH,eAAO,MAAM,YAAY,EAAE,KAc1B,CAAA;AAED,MAAM,MAAM,WAAW,GAAG;IACxB,kEAAkE;IAClE,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,SAAS,IAAI,EAAE,CAAA;IACjD,kFAAkF;IAClF,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK,KAAK,MAAM,CAAA;CACvD,CAAA;AAkBD,6EAA6E;AAC7E,eAAO,MAAM,KAAK,GAAI,MAAM,MAAM,EAAE,OAAO,SAAS,IAAI,EAAE,EAAE,QAAO,KAAoB,KAAG,MAWzF,CAAA;AAyCD,0EAA0E;AAC1E,eAAO,MAAM,WAAW,QAAO,OAAO,CAAC,WAAW,CAC7B,CAAA"}

package/dist/src/index.js

@@ -0,0 +1,102 @@
+/**
+ * CAVE syntax highlighting.
+ *
+ * Single-source: parses with the `@cavelang/tree-sitter-cave` WASM grammar
+ * via web-tree-sitter and colors the captures of its `queries/highlights.scm`
+ * — the same query editors use — so terminal output and editor highlighting
+ * can never drift apart.
+ *
+ * `highlighter()` loads the grammar once per process; `spans` yields flat,
+ * non-overlapping capture ranges and `ansi` renders them with a
+ * capture-name-keyed theme (longest dotted prefix wins, unstyled text passes
+ * through untouched).
+ */
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { Language, Parser, Query } from 'web-tree-sitter';
+/**
+ * Terminal-default-friendly theme: entities (`variable`) stay uncolored on
+ * purpose — they are the bulk of every line; color carries the structure.
+ */
+export const defaultTheme = {
+    comment: '90',
+    keyword: '35',
+    'keyword.operator': '95',
+    property: '33',
+    number: '36',
+    type: '36',
+    string: '32',
+    'string.special': '96',
+    label: '34',
+    constant: '33',
+    operator: '91',
+    tag: '94',
+    punctuation: '90'
+};
+const resolvePath = (specifier) => fileURLToPath(import.meta.resolve(specifier));
+/** Longest dotted prefix of `capture` present in `theme`. */
+const styleOf = (theme, capture) => {
+    for (let name = capture;; name = name.slice(0, name.lastIndexOf('.'))) {
+        const style = theme[name];
+        if (style !== undefined) {
+            return style;
+        }
+        if (!name.includes('.')) {
+            return undefined;
+        }
+    }
+};
+/** Renders `spans` over `text` as ANSI; exported for custom span sources. */
+export const paint = (text, spans, theme = defaultTheme) => {
+    let out = '';
+    let at = 0;
+    for (const span of spans) {
+        const style = styleOf(theme, span.capture);
+        out += text.slice(at, span.start);
+        const piece = text.slice(span.start, span.end);
+        out += style === undefined ? piece : `\u001B[${style}m${piece}\u001B[0m`;
+        at = span.end;
+    }
+    return out + text.slice(at);
+};
+const create = async () => {
+    await Parser.init();
+    const language = await Language.load(resolvePath('@cavelang/tree-sitter-cave/wasm'));
+    const query = new Query(language, readFileSync(resolvePath('@cavelang/tree-sitter-cave/highlights'), 'utf8'));
+    const parser = new Parser();
+    parser.setLanguage(language);
+    const spans = (text) => {
+        const tree = parser.parse(text);
+        if (tree === null) {
+            return [];
+        }
+        try {
+            const all = query.captures(tree.rootNode)
+                .map(({ name, node }) => ({ start: node.startIndex, end: node.endIndex, capture: name }))
+                .filter(span => span.end > span.start)
+                .sort((a, b) => a.start - b.start || b.end - a.end);
+            // One capture per node keeps these disjoint already; guard anyway so a
+            // future query with nested captures degrades to outermost-wins.
+            const disjoint = [];
+            let at = 0;
+            for (const span of all) {
+                if (span.start >= at) {
+                    disjoint.push(span);
+                    at = span.end;
+                }
+            }
+            return disjoint;
+        }
+        finally {
+            tree.delete();
+        }
+    };
+    return {
+        spans,
+        ansi: (text, theme = defaultTheme) => paint(text, spans(text), theme)
+    };
+};
+let cached;
+/** The process-wide highlighter; loads the grammar WASM on first call. */
+export const highlighter = () => cached ??= create();
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@cavelang/highlight",
+  "version": "0.5.0",
+  "type": "module",
+  "description": "CAVE syntax highlighting — web-tree-sitter over the @cavelang/tree-sitter-cave grammar, rendered to ANSI for terminals.",
+  "license": "CC0-1.0",
+  "author": "Mirek Rusin (https://github.com/mirek)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mirek/cave.git",
+    "directory": "packages/highlight"
+  },
+  "engines": {
+    "node": ">=22.18"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/test",
+    "!dist/tsconfig.tsbuildinfo",
+    "src",
+    "!src/**/*.test.ts",
+    "README.md",
+    "License.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "web-tree-sitter": "^0.26.10",
+    "@cavelang/tree-sitter-cave": "0.5.0"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "test": "node --disable-warning=ExperimentalWarning --test 'test/*.test.ts'",
+    "typecheck": "tsc -b"
+  }
+}

package/src/index.ts

@@ -0,0 +1,127 @@
+/**
+ * CAVE syntax highlighting.
+ *
+ * Single-source: parses with the `@cavelang/tree-sitter-cave` WASM grammar
+ * via web-tree-sitter and colors the captures of its `queries/highlights.scm`
+ * — the same query editors use — so terminal output and editor highlighting
+ * can never drift apart.
+ *
+ * `highlighter()` loads the grammar once per process; `spans` yields flat,
+ * non-overlapping capture ranges and `ansi` renders them with a
+ * capture-name-keyed theme (longest dotted prefix wins, unstyled text passes
+ * through untouched).
+ */
+
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { Language, Parser, Query } from 'web-tree-sitter'
+
+/** One highlighted range: `capture` is a `highlights.scm` name like `keyword`. */
+export type Span = {
+  readonly start: number
+  readonly end: number
+  readonly capture: string
+}
+
+/** Capture name (or dotted prefix) to ANSI SGR parameters, e.g. `keyword: '35'`. */
+export type Theme = Readonly<Record<string, string>>
+
+/**
+ * Terminal-default-friendly theme: entities (`variable`) stay uncolored on
+ * purpose — they are the bulk of every line; color carries the structure.
+ */
+export const defaultTheme: Theme = {
+  comment: '90',
+  keyword: '35',
+  'keyword.operator': '95',
+  property: '33',
+  number: '36',
+  type: '36',
+  string: '32',
+  'string.special': '96',
+  label: '34',
+  constant: '33',
+  operator: '91',
+  tag: '94',
+  punctuation: '90'
+}
+
+export type Highlighter = {
+  /** Non-overlapping capture spans of `text`, in document order. */
+  readonly spans: (text: string) => readonly Span[]
+  /** `text` with ANSI colors applied per `theme` (default {@link defaultTheme}). */
+  readonly ansi: (text: string, theme?: Theme) => string
+}
+
+const resolvePath = (specifier: string): string =>
+  fileURLToPath(import.meta.resolve(specifier))
+
+/** Longest dotted prefix of `capture` present in `theme`. */
+const styleOf = (theme: Theme, capture: string): undefined | string => {
+  for (let name = capture; ; name = name.slice(0, name.lastIndexOf('.'))) {
+    const style = theme[name]
+    if (style !== undefined) {
+      return style
+    }
+    if (!name.includes('.')) {
+      return undefined
+    }
+  }
+}
+
+/** Renders `spans` over `text` as ANSI; exported for custom span sources. */
+export const paint = (text: string, spans: readonly Span[], theme: Theme = defaultTheme): string => {
+  let out = ''
+  let at = 0
+  for (const span of spans) {
+    const style = styleOf(theme, span.capture)
+    out += text.slice(at, span.start)
+    const piece = text.slice(span.start, span.end)
+    out += style === undefined ? piece : `\u001B[${style}m${piece}\u001B[0m`
+    at = span.end
+  }
+  return out + text.slice(at)
+}
+
+const create = async (): Promise<Highlighter> => {
+  await Parser.init()
+  const language = await Language.load(resolvePath('@cavelang/tree-sitter-cave/wasm'))
+  const query = new Query(language, readFileSync(resolvePath('@cavelang/tree-sitter-cave/highlights'), 'utf8'))
+  const parser = new Parser()
+  parser.setLanguage(language)
+  const spans = (text: string): readonly Span[] => {
+    const tree = parser.parse(text)
+    if (tree === null) {
+      return []
+    }
+    try {
+      const all = query.captures(tree.rootNode)
+        .map(({ name, node }) => ({ start: node.startIndex, end: node.endIndex, capture: name }))
+        .filter(span => span.end > span.start)
+        .sort((a, b) => a.start - b.start || b.end - a.end)
+      // One capture per node keeps these disjoint already; guard anyway so a
+      // future query with nested captures degrades to outermost-wins.
+      const disjoint: Span[] = []
+      let at = 0
+      for (const span of all) {
+        if (span.start >= at) {
+          disjoint.push(span)
+          at = span.end
+        }
+      }
+      return disjoint
+    } finally {
+      tree.delete()
+    }
+  }
+  return {
+    spans,
+    ansi: (text, theme = defaultTheme) => paint(text, spans(text), theme)
+  }
+}
+
+let cached: undefined | Promise<Highlighter>
+
+/** The process-wide highlighter; loads the grammar WASM on first call. */
+export const highlighter = (): Promise<Highlighter> =>
+  cached ??= create()