@kernlang/core 3.1.5 → 3.1.6

package/dist/parser.d.ts

@@ -1,21 +1,53 @@
+/**
+ * KERN Parser — public API surface.
+ *
+ * Implementation is split across sibling modules:
+ * - parser-diagnostics.ts — diagnostic infrastructure
+ * - parser-tokenizer.ts   — character-level tokenizer
+ * - parser-token-stream.ts — token cursor
+ * - parser-style.ts       — style block parsing
+ * - parser-keywords.ts    — keyword-specific handlers
+ * - parser-core.ts        — line parsing, tree building, orchestration
+ */
 import type { IRNode, ParseDiagnostic, ParseResult } from './types.js';
 import { type KernRuntime } from './runtime.js';
 import type { ParserHintsConfig } from './runtime.js';
-export type TokenKind = 'identifier' | 'number' | 'equals' | 'quoted' | 'expr' | 'style' | 'themeRef' | 'slash' | 'comma' | 'whitespace' | 'unknown';
-export interface Token {
-    kind: TokenKind;
-    value: string;
-    pos: number;
-}
-export declare function tokenizeLine(line: string): Token[];
+export type { TokenKind, Token } from './parser-tokenizer.js';
+export { tokenizeLine } from './parser-tokenizer.js';
 /** Register parser hints for an evolved node type. */
 export declare function registerParserHints(keyword: string, hints: ParserHintsConfig): void;
 /** Unregister parser hints (for rollback/testing). */
 export declare function unregisterParserHints(keyword: string): void;
 /** Clear all parser hints (for test isolation). */
 export declare function clearParserHints(): void;
-/** Get warnings from the last parse() call */
+/**
+ * Get diagnostic messages from the last parse() call as plain strings.
+ *
+ * @remarks Returns messages for all severities (error, warning, info).
+ * For structured diagnostics with severity filtering, use {@link getParseDiagnostics}.
+ */
 export declare function getParseWarnings(): string[];
+/** Get structured diagnostics from the last parse() call. */
+export declare function getParseDiagnostics(runtime?: KernRuntime): ParseDiagnostic[];
+/**
+ * Parse KERN source into an IR node tree.
+ *
+ * Recovers from errors gracefully — malformed lines produce `DROPPED_LINE`
+ * diagnostics but never throw. Use {@link parseStrict} if you want errors to throw.
+ *
+ * @param source - KERN indentation-based source text
+ * @param runtime - Optional KernRuntime instance for isolation (defaults to shared singleton)
+ * @returns Root IRNode of the parsed tree
+ *
+ * @example
+ * ```ts
+ * const root = parse('page "Home"\n  text "Hello"');
+ * // root.type === 'page', root.children[0].type === 'text'
+ * ```
+ *
+ * @see {@link parseWithDiagnostics} to also receive parse diagnostics
+ * @see {@link parseStrict} to throw on errors
+ */
 export declare function parse(source: string, runtime?: KernRuntime): IRNode;
 /**
  * Parse KERN source into a document-wrapped IR tree.
@@ -23,13 +55,28 @@ export declare function parse(source: string, runtime?: KernRuntime): IRNode;
  * top-level nodes (e.g., multiple `rule` definitions) are siblings.
  */
 export declare function parseDocument(source: string, runtime?: KernRuntime): IRNode;
-/** Get structured diagnostics from the last parse() call. */
-export declare function getParseDiagnostics(runtime?: KernRuntime): ParseDiagnostic[];
-/** Parse with diagnostics — returns both tree and structured diagnostics. */
+/**
+ * Parse KERN source and return both the IR tree and structured diagnostics.
+ *
+ * Unlike {@link parse}, this returns a {@link ParseResult} containing the full
+ * diagnostics array, useful for editor integrations and lint-style reporting.
+ *
+ * @param source - KERN indentation-based source text
+ * @param runtime - Optional KernRuntime instance for isolation
+ * @returns `{ root: IRNode, diagnostics: ParseDiagnostic[] }`
+ */
 export declare function parseWithDiagnostics(source: string, runtime?: KernRuntime): ParseResult;
 /** Parse with diagnostics (document mode). */
 export declare function parseDocumentWithDiagnostics(source: string, runtime?: KernRuntime): ParseResult;
-/** Strict parse — throws KernParseError if any diagnostic has severity=error or schema violation. */
+/**
+ * Strict parse — throws if any diagnostic has severity `'error'` or a schema violation is found.
+ *
+ * @param source - KERN indentation-based source text
+ * @param runtime - Optional KernRuntime instance for isolation
+ * @returns Root IRNode of the parsed tree
+ * @throws {KernParseError} When the source contains errors or schema violations.
+ *   The error includes a code frame and the full diagnostics array.
+ */
 export declare function parseStrict(source: string, runtime?: KernRuntime): IRNode;
 /** Strict document parse — throws KernParseError if any diagnostic has severity=error or schema violation. */
 export declare function parseDocumentStrict(source: string, runtime?: KernRuntime): IRNode;