@cristianormazabal/triton-core 0.1.12 → 0.1.13

package/dist/theme/discover.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Theme Discovery Utility — src/theme/discover.ts
+ *
+ * Scans directories for `.triton-theme.json` files, validates them, resolves
+ * them over their declared base preset, and returns a name→ResolvedTheme
+ * registry.
+ *
+ * ⚠️  This module performs filesystem I/O (node:fs / node:path).
+ *     It MUST NOT be imported from src/index.ts or src/frontend/index.ts.
+ *     Hosts (VS Code extension, triton-latex CLI) consume it by relative path:
+ *       import { discoverThemes } from '../../src/theme/discover.js'
+ */
+import type { ResolvedTheme } from '../contracts/theme.js';
+import { type Result } from '../contracts/result.js';
+export interface ThemeDiscoveryResult {
+    /** Resolved themes keyed by name (declared `name` field or filename-derived). */
+    readonly themes: ReadonlyMap<string, ResolvedTheme>;
+    /** Human-readable warnings for skipped/invalid files. Never throws. */
+    readonly warnings: readonly string[];
+}
+/**
+ * Load, validate, and resolve a single `.triton-theme.json` file.
+ *
+ * Returns ok(ResolvedTheme) on success, err(...) on any failure.
+ * Never throws.
+ */
+export declare function loadThemeFile(filePath: string): Result<ResolvedTheme>;
+/**
+ * Scan `dir` for all `.triton-theme.json` files, load and resolve each one,
+ * and return a name→ResolvedTheme map plus any warnings for skipped files.
+ *
+ * Rules (Cristian's decisions):
+ *  - Name = the theme's `name` field if present; else derived from filename.
+ *  - Derived name must satisfy slug rule; if not → warning + skipped.
+ *  - If name is a built-in preset name → warning + skipped (no shadowing).
+ *  - Duplicate custom name within same dir → last wins + warning.
+ *  - Errors (bad JSON, validation failure) → warning + skipped. Never throws.
+ */
+export declare function discoverThemes(dir: string): ThemeDiscoveryResult;
+/**
+ * Walk up from `startDir` looking for a `.triton/themes/` directory.
+ * Returns its absolute path when found, or undefined if not found.
+ *
+ * Stops at the filesystem root or after 10 levels (infinite-loop guard).
+ */
+export declare function findTritonThemesDir(startDir: string): string | undefined;
+//# sourceMappingURL=discover.d.ts.map

package/dist/theme/discover.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discover.d.ts","sourceRoot":"","sources":["../../../../src/theme/discover.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAO9D,MAAM,WAAW,oBAAoB;IACnC,iFAAiF;IACjF,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACpD,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAcD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,aAAa,CAAC,CAkCrE;AAID;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,oBAAoB,CAuDhE;AAiBD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAoBxE"}

package/dist/theme/discover.js

@@ -0,0 +1,159 @@
+/**
+ * Theme Discovery Utility — src/theme/discover.ts
+ *
+ * Scans directories for `.triton-theme.json` files, validates them, resolves
+ * them over their declared base preset, and returns a name→ResolvedTheme
+ * registry.
+ *
+ * ⚠️  This module performs filesystem I/O (node:fs / node:path).
+ *     It MUST NOT be imported from src/index.ts or src/frontend/index.ts.
+ *     Hosts (VS Code extension, triton-latex CLI) consume it by relative path:
+ *       import { discoverThemes } from '../../src/theme/discover.js'
+ */
+import { readFileSync, readdirSync, existsSync, statSync } from 'node:fs';
+import { join, basename, resolve } from 'node:path';
+import { ok, err } from '../contracts/result.js';
+import { validateThemeInput, isBuiltinThemeName } from './validate.js';
+import { resolveTheme } from './resolver.js';
+import { getThemePreset } from './preset.js';
+// ─── Name derivation ──────────────────────────────────────────────────────────
+const THEME_SUFFIX = '.triton-theme.json';
+const SLUG = /^[a-z0-9-]+$/;
+/** Strip `.triton-theme.json` from a filename to derive a theme name. */
+function deriveNameFromFilename(filename) {
+    return basename(filename, THEME_SUFFIX);
+}
+// ─── loadThemeFile ────────────────────────────────────────────────────────────
+/**
+ * Load, validate, and resolve a single `.triton-theme.json` file.
+ *
+ * Returns ok(ResolvedTheme) on success, err(...) on any failure.
+ * Never throws.
+ */
+export function loadThemeFile(filePath) {
+    // 1. Read file
+    let raw;
+    try {
+        raw = readFileSync(filePath, 'utf8');
+    }
+    catch (cause) {
+        return err('THEME_VALIDATION_ERROR', `Cannot read theme file "${filePath}": ${String(cause)}`, cause);
+    }
+    // 2. Parse JSON
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (cause) {
+        return err('THEME_VALIDATION_ERROR', `Invalid JSON in theme file "${filePath}": ${String(cause)}`, cause);
+    }
+    // 3. Validate against ThemeInput schema (strict — unknown keys are errors)
+    const validated = validateThemeInput(parsed);
+    if (!validated.ok) {
+        return err('THEME_VALIDATION_ERROR', `Theme file "${filePath}" failed validation: ${validated.error.message}`, validated.error);
+    }
+    // 4. Resolve over declared base (or 'default' if absent)
+    const input = validated.value;
+    const baseName = parsed['base'] ?? 'default';
+    const base = getThemePreset(baseName);
+    const resolved = resolveTheme(input, base);
+    return ok(resolved);
+}
+// ─── discoverThemes ───────────────────────────────────────────────────────────
+/**
+ * Scan `dir` for all `.triton-theme.json` files, load and resolve each one,
+ * and return a name→ResolvedTheme map plus any warnings for skipped files.
+ *
+ * Rules (Cristian's decisions):
+ *  - Name = the theme's `name` field if present; else derived from filename.
+ *  - Derived name must satisfy slug rule; if not → warning + skipped.
+ *  - If name is a built-in preset name → warning + skipped (no shadowing).
+ *  - Duplicate custom name within same dir → last wins + warning.
+ *  - Errors (bad JSON, validation failure) → warning + skipped. Never throws.
+ */
+export function discoverThemes(dir) {
+    const themes = new Map();
+    const warnings = [];
+    // Gracefully handle missing / unreadable directory
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch (cause) {
+        warnings.push(`Cannot read themes directory "${dir}": ${String(cause)}`);
+        return { themes, warnings };
+    }
+    const themeFiles = entries.filter(e => e.endsWith(THEME_SUFFIX));
+    for (const filename of themeFiles) {
+        const filePath = join(dir, filename);
+        // Load + validate + resolve
+        const result = loadThemeFile(filePath);
+        if (!result.ok) {
+            warnings.push(result.error.message);
+            continue;
+        }
+        const resolved = result.value;
+        // Determine registered name:
+        //   - declared `name` field in the file → use it (already validated as a slug)
+        //   - no `name` field → derive from filename
+        // We re-read the raw name field here rather than relying on resolved.name,
+        // because resolveTheme always fills name from the base preset when absent.
+        const name = extractNameFromFile(filePath) ?? deriveNameFromFilename(filename);
+        // Validate slug rule on derived name
+        if (!SLUG.test(name)) {
+            warnings.push(`Theme file "${filename}": derived name "${name}" is not a valid slug (^[a-z0-9-]+$); skipped`);
+            continue;
+        }
+        // Built-in collision check
+        if (isBuiltinThemeName(name)) {
+            warnings.push(`Theme "${name}" shadows a built-in preset; skipped`);
+            continue;
+        }
+        // Duplicate within same dir → last wins + warning
+        if (themes.has(name)) {
+            warnings.push(`Duplicate theme name "${name}": "${filename}" overrides an earlier definition`);
+        }
+        themes.set(name, resolved);
+    }
+    return { themes, warnings };
+}
+// ─── extractNameFromFile ──────────────────────────────────────────────────────
+/** Read the `name` field directly from the raw JSON (returns null if absent or unreadable). */
+function extractNameFromFile(filePath) {
+    try {
+        const raw = readFileSync(filePath, 'utf8');
+        const parsed = JSON.parse(raw);
+        return typeof parsed['name'] === 'string' ? parsed['name'] : null;
+    }
+    catch {
+        return null;
+    }
+}
+// ─── findTritonThemesDir ──────────────────────────────────────────────────────
+/**
+ * Walk up from `startDir` looking for a `.triton/themes/` directory.
+ * Returns its absolute path when found, or undefined if not found.
+ *
+ * Stops at the filesystem root or after 10 levels (infinite-loop guard).
+ */
+export function findTritonThemesDir(startDir) {
+    const MAX_LEVELS = 10;
+    let current = resolve(startDir);
+    for (let level = 0; level < MAX_LEVELS; level++) {
+        const candidate = join(current, '.triton', 'themes');
+        try {
+            if (existsSync(candidate) && statSync(candidate).isDirectory()) {
+                return candidate;
+            }
+        }
+        catch {
+            // permission error or similar — keep walking up
+        }
+        const parent = resolve(join(current, '..'));
+        if (parent === current)
+            break; // filesystem root
+        current = parent;
+    }
+    return undefined;
+}
+//# sourceMappingURL=discover.js.map

package/dist/theme/discover.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cristianormazabal/triton-core",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "description": "Triton diagram compiler — deterministic SVG rendering for 50+ diagram types (Mermaid-compatible, trees, data structures, posters).",
   "type": "module",
   "license": "MIT",