@ldclabs/kip-lang 0.3.1 → 0.4.0

package/README.md

@@ -2,15 +2,35 @@
 
 TypeScript toolkit for **KIP** (Knowledge Interaction Protocol) — a structured query language for knowledge graphs.
 
-Provides a full-featured **lexer → parser → AST → formatter / diagnostics** pipeline for `.kip` files.
+Provides a full-featured **lexer → parser → AST → formatter / diagnostics**
+pipeline for `.kip` files, plus **`lower`**, which turns a syntax tree into the
+executable AST a KIP engine runs.
 
-The parser targets the KIP v1.0-RC9 command-text syntax, including `:parameter`
+The parser targets the KIP v1.0-RC10 command-text syntax, including `:parameter`
 placeholders in full value positions, JSON-compatible object literals with
 unquoted identifier keys, predicate variables, multi-key `ORDER BY`, `SEARCH`
 retrieval modes and thresholds, `EXPECT VERSION`, `UPDATE`, `MERGE`, `EXPORT`,
-and batch-friendly multi-command source text. The `execute_kip` request envelope
-(`command`, `commands`, `parameters`, `dry_run`) is JSON outside the `.kip`
-language and should be validated by the caller.
+`EXPORT ... CURSOR`, and batch-friendly multi-command source text. The
+`execute_kip` request envelope (`command`, `commands`, `parameters`, `dry_run`)
+is JSON outside the `.kip` language and should be validated by the caller.
+
+## Two trees, two audiences
+
+`parse` returns a **syntax tree**: ranges, comments, quoting style, raw number
+text — everything a formatter or an editor needs to reproduce the source, and
+error recovery that keeps producing a tree after a mistake.
+
+`lower` returns the **executable AST**: every construct collapsed to the one
+shape it means, with the open-ended parts of the grammar closed. A concept
+matcher becomes one of four identified forms; a filter becomes a comparison, a
+logical node, a negation, or a call to one of seven functions; a variable
+becomes a name and a dot path. Anything the syntax admits but the language does
+not — an unknown filter function, `{type: "T"}` where an identity is required,
+an `UPDATE` expression reading a foreign variable — is rejected here, with a
+KIP error code.
+
+That split is why the two exist: an editor wants the loosest tree it can get,
+an engine wants the tightest.
 
 ## Installation
 
@@ -90,6 +110,38 @@ Diagnostics cover:
 - Bracket matching (unclosed / mismatched braces, brackets, parentheses)
 - Parser errors (unexpected tokens, missing clauses)
 
+### Lower to the executable AST
+
+```ts
+import { parse, lower, checkBudget } from '@ldclabs/kip-lang'
+
+function command(source: string) {
+  checkBudget(source)                       // KIP_4002 before parsing recurses
+  const { ast, diagnostics } = parse(source)
+  const fatal = diagnostics.find((d) => d.severity === 'error')
+  if (fatal) throw new Error(`${fatal.code} ${fatal.message}`)
+  return lower(ast)                         // throws KipSyntaxError
+}
+
+command('FIND(?d.name) WHERE { ?d {type: "Drug"} } LIMIT 10')
+// { Kql: { find_clause: { expressions: [{ Variable: { var: "d", path: ["name"] } }] }, ... } }
+```
+
+`lower` requires the program to hold exactly one command; consecutive `UPSERT`
+blocks count as one, since that is how a schema capsule is written. Use
+`lowerAll` for source text that is genuinely a sequence of commands.
+
+The `diagnostics` check above is not decoration. `parse` recovers from a
+malformed string or an unquoted value by reading it leniently, and `lower`
+receives only the tree — so skipping the check lowers `"a\xb"` to `axb` and
+`{a: bare}` to `{a: "bare"}` without a word of complaint.
+
+`checkBudget` is not optional for a server. `parse` is recursive descent, so
+without a depth ceiling a hostile `[[[[…` overflows the JavaScript stack — and
+in a runtime that shares one stack across requests, that takes down more than
+the one request. The budgets match `anda_kip`'s, so a command one KIP engine
+refuses on size is refused by every other engine too.
+
 ## API Reference
 
 | Export                                       | Description                                              |
@@ -99,6 +151,13 @@ Diagnostics cover:
 | `format(source, options?)`                   | AST-based formatting with comment preservation           |
 | `formatPreservingComments(source, options?)` | Line-level indent normalization                          |
 | `diagnose(source)`                           | Return `Diagnostic[]` (lexer + bracket + parser errors)  |
+| `analyzeSemantics(program)`                  | Spec SHOULD/MUST checks decidable without a live schema  |
+| `lower(program)`                             | Lower one command to the executable `Command` AST        |
+| `lowerAll(program)`                          | Lower every command in a multi-statement program         |
+| `lowerStatement(statement)`                  | Lower a single statement                                 |
+| `checkBudget(source)`                        | Enforce length and nesting ceilings (`KIP_4002`)         |
+| `checkBatchBudget(count)`                    | Enforce the command-count ceiling (`KIP_4002`)           |
+| `KipSyntaxError`                             | Thrown by `lower` / `checkBudget`, carries a KIP code    |
 | `TokenType`                                  | Enum of all token types                                  |
 | `KEYWORDS` / `FUNCTIONS`                     | Maps of KIP keywords and built-in functions              |
 
@@ -111,6 +170,11 @@ All AST types are exported for downstream consumption:
 - **Patterns**: `ConceptPattern`, `PropositionPattern`, `FilterClause`, `NotClause`, `OptionalClause`, `UnionClause`
 - **Expressions**: `ObjectLiteral`, `ArrayLiteral`, `ObjectEntry`, `Expression`
 
+The executable AST is exported separately: `Command`, `KqlQuery`,
+`KmlStatement`, `MetaCommand`, `ExecConceptMatcher`, `PropositionMatcher`,
+`TargetTerm`, `PredTerm`, `FilterExpression`, `UpdateValue`, `KipValue`, and
+friends. Names that collide with a syntax-tree node carry an `Exec` prefix.
+
 String-or-parameter statement fields such as `SearchStatement.termValue`,
 `SearchStatement.withTypeValue`, `SearchStatement.modeValue`, and
 `DescribeStatement.typeNameValue` preserve whether the original source used a

package/dist/ast.d.ts

@@ -106,7 +106,8 @@ export interface UpsertStatement extends BaseNode {
 export type UpsertBlock = ConceptBlock | PropositionBlock;
 export interface ConceptBlock extends BaseNode {
     kind: 'ConceptBlock';
-    handle: string;
+    /** `?local_handle`, absent when the block is not referenced elsewhere. */
+    handle?: string;
     matcher: ConceptMatcher;
     expectVersion?: ExpectVersion;
     setAttributes?: SetAttributes;
@@ -210,6 +211,7 @@ export interface ExportStatement extends BaseNode {
     target: string;
     where: WhereClause;
     limit?: LimitClause;
+    cursor?: CursorClause;
 }
 export type Expression = BinaryExpression | UnaryExpression | FunctionCallExpr | DotExpression | VariableRef | ParameterRef | StringLiteral | NumberLiteral | BooleanLiteral | NullLiteral | ArrayLiteral | ObjectLiteral;
 export interface BinaryExpression extends BaseNode {
@@ -261,10 +263,17 @@ export interface NullLiteral extends BaseNode {
 export interface ArrayLiteral extends BaseNode {
     kind: 'ArrayLiteral';
     elements: Expression[];
+    /**
+     * Whether a comma preceded the closing bracket. JSON-value position tolerates
+     * it; a FILTER list does not, and only the source says which was written.
+     */
+    trailingComma?: boolean;
 }
 export interface ObjectLiteral extends BaseNode {
     kind: 'ObjectLiteral';
     entries: ObjectEntry[];
+    /** See {@link ArrayLiteral.trailingComma}. */
+    trailingComma?: boolean;
 }
 export interface ObjectEntry extends BaseNode {
     kind: 'ObjectEntry';

package/dist/ast.d.ts.map

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

package/dist/budget.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 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 declare const MAX_KIP_INPUT_LEN: number;
+export declare const MAX_KIP_NESTING_DEPTH = 64;
+export declare 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 declare function checkBudget(source: string): void;
+/**
+ * Rejects an over-long batch of commands.
+ *
+ * @throws {KipSyntaxError} `KIP_4002` when the batch is too large.
+ */
+export declare function checkBatchBudget(count: number): void;
+//# sourceMappingURL=budget.d.ts.map

package/dist/budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.d.ts","sourceRoot":"","sources":["../src/budget.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,iBAAiB,QAAa,CAAA;AAC3C,eAAO,MAAM,qBAAqB,KAAK,CAAA;AACvC,eAAO,MAAM,sBAAsB,MAAM,CAAA;AAEzC;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CA8DhD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAMpD"}

package/dist/budget.js

@@ -0,0 +1,105 @@
+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) {
+    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 = [];
+    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) {
+    if (count > MAX_KIP_BATCH_COMMANDS) {
+        throw resourceExhausted(`KIP batch of ${count} commands exceeds maximum ${MAX_KIP_BATCH_COMMANDS}`);
+    }
+}
+//# sourceMappingURL=budget.js.map

package/dist/budget.js.map

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

package/dist/errors.d.ts

@@ -0,0 +1,29 @@
+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 declare class KipSyntaxError extends Error {
+    readonly code: KipSyntaxCode;
+    readonly range: Range | undefined;
+    constructor(code: KipSyntaxCode, message: string, range?: Range);
+}
+/** `KIP_1001 InvalidSyntax` — the command does not parse, or violates a grammar rule. */
+export declare function invalidSyntax(message: string, range?: Range): KipSyntaxError;
+/** `KIP_4002 ResourceExhausted` — the input exceeds a parser budget. */
+export declare function resourceExhausted(message: string): KipSyntaxError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAEvC;;;;;;;;GAQG;AACH,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,UAAU,GAAG,UAAU,CAAA;AAEhE;;;;;;;GAOG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;IAC5B,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS,CAAA;gBAErB,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK;CAMhE;AAED,yFAAyF;AACzF,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK,GAAG,cAAc,CAE5E;AAED,wEAAwE;AACxE,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,CAEjE"}

package/dist/errors.js

@@ -0,0 +1,27 @@
+/**
+ * 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 {
+    code;
+    range;
+    constructor(code, message, 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, range) {
+    return new KipSyntaxError('KIP_1001', message, range);
+}
+/** `KIP_4002 ResourceExhausted` — the input exceeds a parser budget. */
+export function resourceExhausted(message) {
+    return new KipSyntaxError('KIP_4002', message);
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAaA;;;;;;;GAOG;AACH,MAAM,OAAO,cAAe,SAAQ,KAAK;IAC9B,IAAI,CAAe;IACnB,KAAK,CAAmB;IAEjC,YAAY,IAAmB,EAAE,OAAe,EAAE,KAAa;QAC7D,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAA;QAC5B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;QAChB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAA;IACpB,CAAC;CACF;AAED,yFAAyF;AACzF,MAAM,UAAU,aAAa,CAAC,OAAe,EAAE,KAAa;IAC1D,OAAO,IAAI,cAAc,CAAC,UAAU,EAAE,OAAO,EAAE,KAAK,CAAC,CAAA;AACvD,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,iBAAiB,CAAC,OAAe;IAC/C,OAAO,IAAI,cAAc,CAAC,UAAU,EAAE,OAAO,CAAC,CAAA;AAChD,CAAC"}