@ldclabs/kip-lang 0.4.0 → 2.0.1

package/src/budget.ts

@@ -0,0 +1,108 @@
+import { resourceExhausted } from './errors.js'
+
+/**
+ * Parser budgets.
+ *
+ * KIP source reaches a server as agent-generated text, so the parser is an
+ * attack surface before it is a convenience. `parse` is recursive descent:
+ * without a depth ceiling, `[[[[...` recurses until the JavaScript stack
+ * overflows, and in an environment that shares one stack across requests
+ * (a Cloudflare Worker isolate, say) that takes the whole runtime down rather
+ * than failing the one request. The check runs on raw text, before a single
+ * token is produced, so a hostile input costs one linear scan.
+ *
+ * The values mirror `MAX_KIP_*` in `anda_kip`'s parser: a command rejected by
+ * one KIP engine's budget must be rejected by every other engine's, or the
+ * same command succeeds on one deployment and fails on another.
+ */
+export const MAX_KIP_INPUT_LEN = 256 * 1024
+export const MAX_KIP_NESTING_DEPTH = 64
+export const MAX_KIP_BATCH_COMMANDS = 256
+
+/**
+ * Rejects source that exceeds a parser budget.
+ *
+ * The bracket scan must skip line comments exactly the way the lexer does.
+ * Counting a `"` inside a comment would latch the scanner into string mode
+ * for the rest of the input, after which every bracket goes uncounted and the
+ * depth ceiling silently stops existing — the failure mode is a guard that
+ * looks present and defends nothing.
+ *
+ * @throws {KipSyntaxError} `KIP_4002` when a budget is exceeded.
+ */
+export function checkBudget(source: string): void {
+  if (source.length > MAX_KIP_INPUT_LEN) {
+    throw resourceExhausted(
+      `KIP input length ${source.length} exceeds maximum ${MAX_KIP_INPUT_LEN}`
+    )
+  }
+
+  let depth = 0
+  const stack: string[] = []
+  let inString = false
+  let escaped = false
+  let inLineComment = false
+  let prevSlash = false
+
+  for (let i = 0; i < source.length; i++) {
+    const ch = source[i]!
+
+    if (inLineComment) {
+      if (ch === '\n') inLineComment = false
+      continue
+    }
+
+    if (inString) {
+      prevSlash = false
+      if (escaped) {
+        escaped = false
+        continue
+      }
+      if (ch === '\\') escaped = true
+      else if (ch === '"') inString = false
+      continue
+    }
+
+    if (ch === '/') {
+      if (prevSlash) {
+        inLineComment = true
+        prevSlash = false
+      } else {
+        prevSlash = true
+      }
+      continue
+    }
+    prevSlash = false
+
+    if (ch === '"') {
+      inString = true
+    } else if (ch === '(' || ch === '[' || ch === '{') {
+      stack.push(ch)
+      depth = stack.length
+      if (depth > MAX_KIP_NESTING_DEPTH) {
+        throw resourceExhausted(
+          `KIP input nesting exceeds maximum ${MAX_KIP_NESTING_DEPTH}`
+        )
+      }
+    } else if (ch === ')') {
+      if (stack[stack.length - 1] === '(') stack.pop()
+    } else if (ch === ']') {
+      if (stack[stack.length - 1] === '[') stack.pop()
+    } else if (ch === '}') {
+      if (stack[stack.length - 1] === '{') stack.pop()
+    }
+  }
+}
+
+/**
+ * Rejects an over-long batch of commands.
+ *
+ * @throws {KipSyntaxError} `KIP_4002` when the batch is too large.
+ */
+export function checkBatchBudget(count: number): void {
+  if (count > MAX_KIP_BATCH_COMMANDS) {
+    throw resourceExhausted(
+      `KIP batch of ${count} commands exceeds maximum ${MAX_KIP_BATCH_COMMANDS}`
+    )
+  }
+}

package/src/diagnostics.ts

@@ -0,0 +1,182 @@
+import type { Range } from './token.js'
+import { tokenize } from './lexer.js'
+import { parse } from './parser.js'
+import { analyzeSemantics } from './semantics.js'
+import { lowerStatement } from './lower.js'
+import { KipSyntaxError } from './errors.js'
+import type { Program } from './ast.js'
+import { TokenType } from './token.js'
+
+export interface Diagnostic {
+  range: Range
+  severity: 'error' | 'warning' | 'info'
+  message: string
+  code: string
+}
+
+/**
+ * Runs diagnostics on KIP source code.
+ * Combines lexer and parser errors with schema-independent semantic and
+ * executable-AST validation.
+ */
+export function diagnose(source: string): Diagnostic[] {
+  const diagnostics: Diagnostic[] = []
+
+  // Phase 1: Lexer-level diagnostics
+  const tokens = tokenize(source)
+  for (const tok of tokens) {
+    if (tok.type === TokenType.Unknown) {
+      diagnostics.push({
+        range: {
+          start: { line: tok.line, column: tok.column },
+          end: { line: tok.line, column: tok.column + tok.value.length }
+        },
+        severity: 'error',
+        message: `Unexpected character '${tok.value}'`,
+        code: 'KIP_LEX_UNKNOWN'
+      })
+    }
+
+    // Check for unterminated strings
+    if (tok.type === TokenType.String) {
+      if (!tok.value.endsWith('"') || tok.value.length < 2) {
+        diagnostics.push({
+          range: {
+            start: { line: tok.line, column: tok.column },
+            end: { line: tok.line, column: tok.column + tok.value.length }
+          },
+          severity: 'error',
+          message: 'Unterminated string literal',
+          code: 'KIP_LEX_UNTERMINATED_STRING'
+        })
+      } else {
+        try {
+          JSON.parse(tok.value)
+        } catch {
+          diagnostics.push({
+            range: {
+              start: { line: tok.line, column: tok.column },
+              end: { line: tok.line, column: tok.column + tok.value.length }
+            },
+            severity: 'error',
+            message: 'Invalid JSON string literal escape sequence',
+            code: 'KIP_LEX_INVALID_STRING'
+          })
+        }
+      }
+    }
+
+    if (tok.type === TokenType.Number && !isJsonNumberLiteral(tok.value)) {
+      diagnostics.push({
+        range: {
+          start: { line: tok.line, column: tok.column },
+          end: { line: tok.line, column: tok.column + tok.value.length }
+        },
+        severity: 'error',
+        message: 'Invalid JSON number literal',
+        code: 'KIP_LEX_INVALID_NUMBER'
+      })
+    }
+  }
+
+  // Phase 2: Bracket/paren matching
+  const bracketStack: { type: string; line: number; column: number }[] = []
+  const openers: Record<string, string> = { '{': '}', '(': ')', '[': ']' }
+  const closers: Record<string, string> = { '}': '{', ')': '(', ']': '[' }
+
+  for (const tok of tokens) {
+    if (
+      tok.type === TokenType.LBrace ||
+      tok.type === TokenType.LParen ||
+      tok.type === TokenType.LBracket
+    ) {
+      bracketStack.push({ type: tok.value, line: tok.line, column: tok.column })
+    } else if (
+      tok.type === TokenType.RBrace ||
+      tok.type === TokenType.RParen ||
+      tok.type === TokenType.RBracket
+    ) {
+      const expected = closers[tok.value]
+      if (bracketStack.length === 0) {
+        diagnostics.push({
+          range: {
+            start: { line: tok.line, column: tok.column },
+            end: { line: tok.line, column: tok.column + 1 }
+          },
+          severity: 'error',
+          message: `Unmatched closing '${tok.value}'`,
+          code: 'KIP_LEX_UNMATCHED_BRACKET'
+        })
+      } else {
+        const top = bracketStack[bracketStack.length - 1]!
+        if (top.type !== expected) {
+          diagnostics.push({
+            range: {
+              start: { line: tok.line, column: tok.column },
+              end: { line: tok.line, column: tok.column + 1 }
+            },
+            severity: 'error',
+            message: `Mismatched bracket: expected '${openers[top.type]}' but got '${tok.value}'`,
+            code: 'KIP_LEX_MISMATCHED_BRACKET'
+          })
+        }
+        bracketStack.pop()
+      }
+    }
+  }
+
+  // Report unclosed brackets
+  for (const unclosed of bracketStack) {
+    diagnostics.push({
+      range: {
+        start: { line: unclosed.line, column: unclosed.column },
+        end: { line: unclosed.line, column: unclosed.column + 1 }
+      },
+      severity: 'error',
+      message: `Unclosed '${unclosed.type}'`,
+      code: 'KIP_LEX_UNCLOSED_BRACKET'
+    })
+  }
+
+  // Phase 3: Parser diagnostics
+  const { ast, diagnostics: parseDiags } = parse(source)
+  diagnostics.push(...parseDiags)
+
+  // Phase 4: Semantic checks (only when the AST parsed cleanly, to avoid
+  // cascading false positives from error-recovery placeholders).
+  if (!parseDiags.some((d) => d.severity === 'error')) {
+    const semanticDiags = analyzeSemantics(ast)
+    diagnostics.push(...semanticDiags)
+    if (!semanticDiags.some((d) => d.severity === 'error')) {
+      diagnostics.push(...validateExecutable(ast))
+    }
+  }
+
+  return diagnostics
+}
+
+/**
+ * Runs the schema-independent checks needed for every parsed statement to
+ * lower into the closed executable AST used by a KIP engine.
+ */
+export function validateExecutable(program: Program): Diagnostic[] {
+  const diagnostics: Diagnostic[] = []
+  for (const statement of program.statements) {
+    try {
+      lowerStatement(statement)
+    } catch (error) {
+      if (!(error instanceof KipSyntaxError)) throw error
+      diagnostics.push({
+        range: error.range ?? statement.range,
+        severity: 'error',
+        message: error.message,
+        code: error.code
+      })
+    }
+  }
+  return diagnostics
+}
+
+function isJsonNumberLiteral(value: string): boolean {
+  return /^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$/.test(value)
+}

package/src/errors.ts

@@ -0,0 +1,42 @@
+import type { Range } from './token.js'
+
+/**
+ * The subset of the KIP error taxonomy this package can produce.
+ *
+ * A KIP engine owns the full taxonomy (schema, logic and execution codes);
+ * a language toolkit only ever reaches the parse-time codes. The `hint` that
+ * accompanies each code on the wire is deliberately *not* duplicated here —
+ * it is engine-side wire contract, and a second copy that drifts is worse
+ * than no copy at all.
+ */
+export type KipSyntaxCode = 'KIP_1001' | 'KIP_1002' | 'KIP_4002'
+
+/**
+ * A fatal, single-error view of a KIP source problem.
+ *
+ * `parse` reports every problem it can recover from as a `Diagnostic`, which
+ * is what an editor wants. An engine wants the opposite: the first thing that
+ * makes the command unexecutable, thrown, with a code it can put on the wire.
+ * `lower` and `checkBudget` therefore throw this instead of accumulating.
+ */
+export class KipSyntaxError extends Error {
+  readonly code: KipSyntaxCode
+  readonly range: Range | undefined
+
+  constructor(code: KipSyntaxCode, message: string, range?: Range) {
+    super(message)
+    this.name = 'KipSyntaxError'
+    this.code = code
+    this.range = range
+  }
+}
+
+/** `KIP_1001 InvalidSyntax` — the command does not parse, or violates a grammar rule. */
+export function invalidSyntax(message: string, range?: Range): KipSyntaxError {
+  return new KipSyntaxError('KIP_1001', message, range)
+}
+
+/** `KIP_4002 ResourceExhausted` — the input exceeds a parser budget. */
+export function resourceExhausted(message: string): KipSyntaxError {
+  return new KipSyntaxError('KIP_4002', message)
+}