spl-lang 0.0.0-stage → 0.1.1

package/dist/lexer.js

@@ -0,0 +1,208 @@
+import { SplSyntaxError } from './errors.js';
+const OPS = [
+    '//=', '**', '//', '==', '!=', '<=', '>=', '+=', '-=', '*=', '/=', '%=',
+    '+', '-', '*', '/', '%', '<', '>', '=', '(', ')', '[', ']', '{', '}', ',', ':', '.', '?', '@', ';',
+];
+const ESCAPES = {
+    n: '\n', t: '\t', r: '\r', '0': '\0', '\\': '\\', "'": "'", '"': '"', '{': '{', '}': '}',
+};
+const isDigit = (c) => c >= '0' && c <= '9';
+const isNameStart = (c) => /[A-Za-z_]/.test(c);
+const isNameChar = (c) => /[A-Za-z0-9_]/.test(c);
+export function tokenize(src, opts = {}) {
+    const tokens = [];
+    let i = 0;
+    let line = opts.line ?? 1;
+    let col = opts.col ?? 1;
+    let depth = opts.inExpr ? 1 : 0;
+    const brackets = [];
+    const err = (msg, l = line, c = col) => {
+        throw new SplSyntaxError(msg, l, c);
+    };
+    const advance = (n = 1) => {
+        for (let k = 0; k < n; k++) {
+            if (src[i] === '\n') {
+                line++;
+                col = 1;
+            }
+            else {
+                col++;
+            }
+            i++;
+        }
+    };
+    while (i < src.length) {
+        const c = src[i];
+        if (c === ' ' || c === '\t' || c === '\r') {
+            advance();
+            continue;
+        }
+        if (c === '#') {
+            while (i < src.length && src[i] !== '\n')
+                advance();
+            continue;
+        }
+        if (c === '\\' && (src[i + 1] === '\n' || (src[i + 1] === '\r' && src[i + 2] === '\n'))) {
+            advance(src[i + 1] === '\r' ? 3 : 2);
+            continue;
+        }
+        if (c === '\n') {
+            if (depth === 0)
+                tokens.push({ type: 'nl', line, col });
+            advance();
+            continue;
+        }
+        const startLine = line;
+        const startCol = col;
+        if (isDigit(c)) {
+            const m = /^\d+(\.\d+)?([eE][+-]?\d+)?/.exec(src.slice(i));
+            advance(m[0].length);
+            if (i < src.length && isNameChar(src[i]))
+                err('invalid number literal', startLine, startCol);
+            tokens.push({ type: 'num', value: Number(m[0]), line: startLine, col: startCol });
+            continue;
+        }
+        const quoteAt = (k) => src[k] === "'" || src[k] === '"';
+        if (quoteAt(i) || (c === 'r' && quoteAt(i + 1))) {
+            const raw = c === 'r';
+            if (raw)
+                advance();
+            tokens.push(readString(raw));
+            continue;
+        }
+        if (isNameStart(c)) {
+            let j = i;
+            while (j < src.length && isNameChar(src[j]))
+                j++;
+            const value = src.slice(i, j);
+            advance(j - i);
+            tokens.push({ type: 'name', value, line: startLine, col: startCol });
+            continue;
+        }
+        const op = OPS.find((o) => src.startsWith(o, i));
+        if (!op)
+            err(`unexpected character '${c}'`);
+        advance(op.length);
+        if (op === '(' || op === '[') {
+            brackets.push(op);
+            depth++;
+        }
+        else if (op === ')' || op === ']') {
+            const open = brackets.pop();
+            if ((op === ')' && open !== '(') || (op === ']' && open !== '[')) {
+                err(`unbalanced '${op}'`, startLine, startCol);
+            }
+            depth--;
+        }
+        tokens.push({ type: 'op', value: op, line: startLine, col: startCol });
+    }
+    if (brackets.length)
+        err(`unclosed '${brackets[brackets.length - 1]}'`);
+    tokens.push({ type: 'eof', line, col });
+    return tokens;
+    function readString(raw) {
+        const startLine = line;
+        const startCol = col;
+        const quote = src[i];
+        const triple = src.startsWith(quote.repeat(3), i);
+        advance(triple ? 3 : 1);
+        const parts = [];
+        let text = '';
+        const flush = () => {
+            if (text)
+                parts.push({ text });
+            text = '';
+        };
+        for (;;) {
+            if (i >= src.length)
+                err('unterminated string', startLine, startCol);
+            const ch = src[i];
+            if (triple ? src.startsWith(quote.repeat(3), i) : ch === quote) {
+                advance(triple ? 3 : 1);
+                break;
+            }
+            if (ch === '\n' && !triple)
+                err('unterminated string', startLine, startCol);
+            if (raw) {
+                text += ch;
+                advance();
+                continue;
+            }
+            if (ch === '\\') {
+                const esc = src[i + 1];
+                if (esc === '\n') {
+                    advance(2);
+                    continue;
+                }
+                if (esc === undefined || !(esc in ESCAPES))
+                    err(`invalid escape sequence '\\${esc ?? ''}'`);
+                text += ESCAPES[esc];
+                advance(2);
+                continue;
+            }
+            if (ch === '{') {
+                if (src[i + 1] === '{') {
+                    text += '{';
+                    advance(2);
+                    continue;
+                }
+                flush();
+                advance();
+                const exprLine = line;
+                const exprCol = col;
+                const exprSrc = readInterpolation();
+                if (!exprSrc.trim())
+                    err('empty interpolation', exprLine, exprCol);
+                parts.push({ expr: exprSrc, line: exprLine, col: exprCol });
+                continue;
+            }
+            if (ch === '}') {
+                if (src[i + 1] === '}') {
+                    text += '}';
+                    advance(2);
+                    continue;
+                }
+                err("single '}' in string; write '}}' or '\\}' for a literal brace");
+            }
+            text += ch;
+            advance();
+        }
+        flush();
+        return { type: 'str', parts, line: startLine, col: startCol };
+    }
+    /** Reads up to the matching '}' of an interpolation, returning the expression source. */
+    function readInterpolation() {
+        const start = i;
+        const startLine = line;
+        const startCol = col;
+        let nest = 0;
+        for (;;) {
+            if (i >= src.length)
+                err("unterminated interpolation, missing '}'", startLine, startCol);
+            const ch = src[i];
+            if (ch === '"' || ch === "'") {
+                advance();
+                while (i < src.length && src[i] !== ch && src[i] !== '\n') {
+                    advance(src[i] === '\\' ? 2 : 1);
+                }
+                if (src[i] !== ch)
+                    err('unterminated string in interpolation', startLine, startCol);
+                advance();
+                continue;
+            }
+            if (ch === '{' || ch === '[' || ch === '(')
+                nest++;
+            if (ch === '}' || ch === ']' || ch === ')') {
+                if (nest === 0) {
+                    if (ch !== '}')
+                        err(`unbalanced '${ch}' in interpolation`);
+                    const body = src.slice(start, i);
+                    advance();
+                    return body;
+                }
+                nest--;
+            }
+            advance();
+        }
+    }
+}

package/dist/llm.d.ts

@@ -0,0 +1,46 @@
+import type { AskMods, ToolName } from './ast.js';
+import type { Restrictions } from './restrict.js';
+import type { ToolHost } from './tools.js';
+import { type Value } from './values.js';
+export type ReasoningLevel = 'low' | 'medium' | 'high';
+export interface Constraint {
+    kind: 'enforce' | 'forbid';
+    text: string;
+}
+export interface LlmRequest {
+    kind: 'ask' | 'think' | 'tool';
+    /** The fully assembled query: constraints, restriction guidance and hints are already prepended. */
+    prompt: string;
+    model?: string;
+    reasoningEffort?: ReasoningLevel;
+    showReasoning: boolean;
+    restrictions: Restrictions;
+    tools: ToolHost;
+    /** For tools the script left parameters out of: the LLM calls the tool itself, these params are fixed by the script. */
+    pinned?: {
+        tool: ToolName;
+        params: Record<string, string>;
+    };
+}
+export interface LlmResponse {
+    text: string;
+    reasoning?: string;
+    /** Effective model and parameters, recorded in the logs. */
+    effective: Record<string, unknown>;
+}
+export interface LlmBackend {
+    call(req: LlmRequest): Promise<LlmResponse>;
+    close(): Promise<void>;
+}
+/** Raised by a backend for any non-script-level LLM problem; becomes `llm_error`. */
+export declare class LlmError extends Error {
+}
+export declare function buildPrompt(opts: {
+    prompt: string;
+    mods?: AskMods;
+    thinking?: boolean;
+    constraints: readonly Constraint[];
+    restrictions: Restrictions;
+}): string;
+/** Parses an `fmt='object'` response; anything that is not a JSON object or array is `invalid_format`. */
+export declare function parseObjectResponse(text: string): Value;

package/dist/llm.js

@@ -0,0 +1,54 @@
+import { Failure } from './errors.js';
+import { fromJson, isDict, isList } from './values.js';
+/** Raised by a backend for any non-script-level LLM problem; becomes `llm_error`. */
+export class LlmError extends Error {
+}
+const LEN_HINTS = {
+    word: 'Answer with a single word.',
+    sentence: 'Answer in a single sentence.',
+    paragraph: 'Answer in a single paragraph.',
+    long: 'Give a long, detailed answer.',
+};
+const FMT_OBJECT_HINT = 'Respond with ONLY a valid JSON value (an object unless the task clearly asks for a list). No prose, no markdown, no code fences.';
+export function buildPrompt(opts) {
+    const sections = [];
+    if (opts.constraints.length) {
+        sections.push('Rules you must follow strictly:\n' +
+            opts.constraints.map((c) => `- You ${c.kind === 'enforce' ? 'MUST' : 'MUST NOT'}: ${c.text}`).join('\n'));
+    }
+    const guidance = opts.restrictions.guidance();
+    if (guidance.length)
+        sections.push(`Active restrictions (enforced by the runtime):\n${guidance.map((g) => `- ${g}`).join('\n')}`);
+    if (opts.thinking)
+        sections.push('Think carefully about the problem before giving the final answer.');
+    if (opts.mods?.len)
+        sections.push(LEN_HINTS[opts.mods.len]);
+    if (opts.mods?.fmt === 'object')
+        sections.push(FMT_OBJECT_HINT);
+    sections.push(opts.prompt);
+    return sections.join('\n\n');
+}
+/** Parses an `fmt='object'` response; anything that is not a JSON object or array is `invalid_format`. */
+export function parseObjectResponse(text) {
+    const candidates = [text.trim()];
+    const fenced = /^```[a-zA-Z]*\s*\n([\s\S]*?)\n?```$/.exec(text.trim());
+    if (fenced)
+        candidates.push(fenced[1].trim());
+    const open = text.search(/[{[]/);
+    const close = Math.max(text.lastIndexOf('}'), text.lastIndexOf(']'));
+    if (open >= 0 && close > open)
+        candidates.push(text.slice(open, close + 1));
+    let lastError = 'empty response';
+    for (const c of candidates) {
+        try {
+            const v = fromJson(JSON.parse(c));
+            if (isDict(v) || isList(v))
+                return v;
+            lastError = 'response is JSON but not an object or array';
+        }
+        catch (e) {
+            lastError = e.message;
+        }
+    }
+    throw new Failure('invalid_format', `LLM response is not valid JSON: ${lastError}`);
+}

package/dist/logger.d.ts

@@ -0,0 +1,12 @@
+export type LogLevel = 'error' | 'info' | 'debug';
+/** Logs go to stderr so that stdout carries only the script result. */
+export declare class Logger {
+    private level;
+    private readonly sink;
+    constructor(level?: LogLevel | 'silent', sink?: (line: string) => void);
+    private emit;
+    error(msg: string): void;
+    warn(msg: string): void;
+    info(msg: string): void;
+    debug(msg: string): void;
+}

package/dist/logger.js

@@ -0,0 +1,27 @@
+const RANK = { error: 0, info: 1, debug: 2 };
+/** Logs go to stderr so that stdout carries only the script result. */
+export class Logger {
+    level;
+    sink;
+    constructor(level = 'info', sink = (l) => process.stderr.write(l + '\n')) {
+        this.level = level;
+        this.sink = sink;
+    }
+    emit(min, tag, msg) {
+        if (this.level === 'silent' || RANK[this.level] < RANK[min])
+            return;
+        this.sink(`[${tag}] ${msg}`);
+    }
+    error(msg) {
+        this.emit('error', 'error', msg);
+    }
+    warn(msg) {
+        this.emit('info', 'warn', msg);
+    }
+    info(msg) {
+        this.emit('info', 'info', msg);
+    }
+    debug(msg) {
+        this.emit('debug', 'debug', msg);
+    }
+}

package/dist/parser.d.ts

@@ -0,0 +1,13 @@
+import type { Program, ToolName } from './ast.js';
+export declare const TOOL_NAMES: readonly ToolName[];
+/** Fixed modifier schema per command; anything else is a syntax error. */
+export declare const MODIFIER_SCHEMA: Record<'?' | 'think', Record<string, readonly (string | boolean)[]>>;
+/**
+ * Tool parameter schema: the allowed names, and the `required` ones that let the runtime run the tool itself.
+ * Every parameter is optional in a script; the LLM supplies the missing required ones when it calls the tool.
+ */
+export declare const TOOL_SCHEMA: Record<ToolName, {
+    params: string[];
+    required: string[];
+}>;
+export declare function parse(source: string): Program;