@kumikijs/compiler 0.1.0

package/README.md

@@ -0,0 +1,34 @@
+# @kumikijs/compiler
+
+Kumiki compiler — lexer, parser, typechecker, and code generator. Part of [Kumiki](https://github.com/kage1020/Kumiki), an AI-first web framework language.
+
+## Install
+
+```sh
+npm i @kumikijs/compiler
+```
+
+## Usage
+
+```ts
+import { check, compile, lex, parse } from "@kumikijs/compiler";
+
+// Type-check a .kumiki source (returns diagnostics)
+const diagnostics = check(source);
+
+// Compile a source into a runnable HTML app
+const result = compile(source);
+```
+
+To inline the runtime bundle from disk in a Node environment, use the `./node` subpath:
+
+```ts
+import { compile } from "@kumikijs/compiler";
+import { nodeRuntimeBundleReader } from "@kumikijs/compiler/node";
+
+const result = compile(source, { bundle: true, readRuntimeBundle: nodeRuntimeBundleReader });
+```
+
+## License
+
+Apache-2.0

package/dist/index.d.ts

@@ -0,0 +1,472 @@
+//#region src/ast.d.ts
+type Pos = {
+  line: number;
+  col: number;
+};
+type Token = {
+  kind: "ident";
+  value: string;
+  pos: Pos;
+} | {
+  kind: "kw";
+  value: string;
+  pos: Pos;
+} | {
+  kind: "num";
+  value: number;
+  pos: Pos;
+} | {
+  kind: "str";
+  value: string;
+  pos: Pos;
+} | {
+  kind: "op";
+  value: string;
+  pos: Pos;
+} | {
+  kind: "eof";
+  pos: Pos;
+};
+type Program = {
+  kind: "Program";
+  defs: Def[];
+};
+type Def = TypeDef | SlotDef | ReducerDef | TileDef | FnDef | EffectDef | AppDef | ThemeDef;
+type ThemeValue = string | number | {
+  [k: string]: ThemeValue;
+};
+type ThemeDef = {
+  kind: "ThemeDef";
+  name: string;
+  body: {
+    [k: string]: ThemeValue;
+  };
+  pos: Pos;
+};
+type TypeDef = {
+  kind: "TypeDef";
+  name: string;
+  params: string[];
+  body: TypeExpr;
+  pos: Pos;
+};
+type SlotDef = {
+  kind: "SlotDef";
+  name: string;
+  type: TypeExpr;
+  modifier?: "transient" | "volatile";
+  init: Expr;
+  pos: Pos;
+};
+type ReducerDef = {
+  kind: "ReducerDef";
+  name: string;
+  on: EventPattern;
+  do: Statement[];
+  pos: Pos;
+};
+type TileDef = {
+  kind: "TileDef";
+  name: string;
+  in?: TypeExpr;
+  errorBoundary?: string;
+  body: TileExpr;
+  pos: Pos;
+};
+type FnDef = {
+  kind: "FnDef";
+  name: string;
+  params: {
+    name: string;
+    type: TypeExpr;
+  }[];
+  ret?: TypeExpr;
+  body: Expr;
+  pos: Pos;
+};
+type EffectDef = {
+  kind: "EffectDef";
+  name: string;
+  cap: string;
+  inType: TypeExpr;
+  outType: TypeExpr;
+  policy?: PolicyExpr;
+  retry?: RetryExpr;
+  mapRequest?: Expr;
+  pos: Pos;
+};
+type AppDef = {
+  kind: "AppDef";
+  name: string;
+  caps: string[];
+  routes: {
+    path: string;
+    tile: string;
+  }[];
+  init: Expr[];
+  theme?: string;
+  pos: Pos;
+};
+type TypeExpr = {
+  kind: "TypePrim";
+  name: "Int" | "Text" | "Bool" | "Unit" | "Float" | "Time" | "Bytes";
+  pos: Pos;
+} | {
+  kind: "TypeRef";
+  name: string;
+  pos: Pos;
+} | {
+  kind: "TypeApp";
+  name: string;
+  args: TypeExpr[];
+  pos: Pos;
+} | {
+  kind: "TypeRecord";
+  fields: {
+    name: string;
+    type: TypeExpr;
+  }[];
+  pos: Pos;
+} | {
+  kind: "TypeUnion";
+  variants: {
+    name: string;
+    payloads: TypeExpr[];
+  }[];
+  pos: Pos;
+} | {
+  kind: "TypeNominal";
+  inner: TypeExpr;
+  refinement?: Refinement;
+  pos: Pos;
+} | {
+  kind: "TypeRefinement";
+  inner: TypeExpr;
+  refinement: Refinement;
+  pos: Pos;
+};
+type Refinement = {
+  kind: "Refinement";
+  pred: string;
+  args: (number | string)[];
+  pos: Pos;
+};
+type EventPattern = {
+  kind: "UiEvent";
+  ev: UiEventKind;
+  selector: {
+    tile: string;
+    id?: string;
+  };
+  pos: Pos;
+} | {
+  kind: "EffectEvent";
+  effect: string;
+  outcome: "ok" | "err";
+  binds: string[];
+  pos: Pos;
+} | {
+  kind: "TimerEvent";
+  intervalMs: number;
+  pos: Pos;
+} | {
+  kind: "LifecycleEvent";
+  name: string;
+  pos: Pos;
+};
+type UiEventKind = "click" | "submit" | "change" | "input" | "focus" | "blur";
+type Statement = {
+  kind: "SlotAssign";
+  lvalue: Lvalue;
+  rhs: Expr;
+  pos: Pos;
+} | {
+  kind: "LetStmt";
+  name: string;
+  rhs: Expr;
+  pos: Pos;
+} | {
+  kind: "Emit";
+  effect: string;
+  args: Expr[];
+  pos: Pos;
+} | {
+  kind: "ForStmt";
+  bind: string;
+  iter: Expr;
+  body: Statement[];
+  pos: Pos;
+} | {
+  kind: "IfStmt";
+  cond: Expr;
+  consequent: Statement[];
+  alternate: Statement[];
+  pos: Pos;
+} | {
+  kind: "MatchStmt";
+  scrutinee: Expr;
+  arms: {
+    pattern: Pattern;
+    body: Statement[];
+  }[];
+  pos: Pos;
+} | {
+  kind: "NoopStmt";
+  pos: Pos;
+};
+type Lvalue = {
+  kind: "LSlot";
+  name: string;
+  pos: Pos;
+} | {
+  kind: "LIndex";
+  base: Lvalue;
+  index: Expr;
+  pos: Pos;
+} | {
+  kind: "LField";
+  base: Lvalue;
+  field: string;
+  pos: Pos;
+};
+type Expr = {
+  kind: "Num";
+  value: number;
+  pos: Pos;
+} | {
+  kind: "Str";
+  value: string;
+  pos: Pos;
+} | {
+  kind: "Bool";
+  value: boolean;
+  pos: Pos;
+} | {
+  kind: "Unit";
+  pos: Pos;
+} | {
+  kind: "Ref";
+  name: string;
+  pos: Pos;
+} | {
+  kind: "BinOp";
+  op: BinOp;
+  lhs: Expr;
+  rhs: Expr;
+  pos: Pos;
+} | {
+  kind: "UnaryOp";
+  op: "-" | "!";
+  rhs: Expr;
+  pos: Pos;
+} | {
+  kind: "FieldAccess";
+  base: Expr;
+  field: string;
+  pos: Pos;
+} | {
+  kind: "Index";
+  base: Expr;
+  index: Expr;
+  pos: Pos;
+} | {
+  kind: "Call";
+  callee: string;
+  args: Expr[];
+  pos: Pos;
+} | {
+  kind: "MethodCall";
+  receiver: Expr;
+  method: string;
+  args: Expr[];
+  pos: Pos;
+} | {
+  kind: "RecordLit";
+  fields: {
+    name: string;
+    value: Expr;
+  }[];
+  pos: Pos;
+} | {
+  kind: "ListLit";
+  items: Expr[];
+  pos: Pos;
+} | {
+  kind: "MapLit";
+  entries: {
+    key: Expr;
+    value: Expr;
+  }[];
+  pos: Pos;
+} | {
+  kind: "MatchExpr";
+  scrutinee: Expr;
+  arms: MatchArm[];
+  pos: Pos;
+} | {
+  kind: "IfExpr";
+  cond: Expr;
+  consequent: Expr;
+  alternate: Expr;
+  pos: Pos;
+} | {
+  kind: "LetIn";
+  name: string;
+  value: Expr;
+  body: Expr;
+  pos: Pos;
+} | {
+  kind: "Variant";
+  name: string;
+  payload: Expr[];
+  pos: Pos;
+};
+type MatchArm = {
+  pattern: Pattern;
+  body: Expr;
+};
+type Pattern = {
+  kind: "PVariant";
+  name: string;
+  binds: string[];
+  pos: Pos;
+} | {
+  kind: "PWildcard";
+  pos: Pos;
+} | {
+  kind: "PBind";
+  name: string;
+  pos: Pos;
+} | {
+  kind: "PLiteral";
+  value: number | string | boolean;
+  pos: Pos;
+};
+type BinOp = "+" | "-" | "*" | "/" | "%" | "==" | "!=" | "<" | ">" | "<=" | ">=" | "&" | "|";
+type PolicyExpr = {
+  kind: "PolLatest";
+} | {
+  kind: "PolLatestKey";
+  key: Expr;
+} | {
+  kind: "PolQueue";
+} | {
+  kind: "PolDebounce";
+  ms: number;
+} | {
+  kind: "PolThrottle";
+  ms: number;
+} | {
+  kind: "PolOnce";
+};
+type RetryExpr = {
+  kind: "RetryNone";
+} | {
+  kind: "RetryLinear";
+  n: number;
+  ms: number;
+} | {
+  kind: "RetryExp";
+  n: number;
+  ms: number;
+  factor: number;
+};
+type TileExpr = {
+  kind: "TileCall";
+  name: string;
+  args: TileArg[];
+  props: TileProp[];
+  pos: Pos;
+} | {
+  kind: "TileFor";
+  bind: string;
+  iter: Expr;
+  body: TileExpr;
+  pos: Pos;
+} | {
+  kind: "TileWhen";
+  cond: Expr;
+  body: TileExpr;
+  pos: Pos;
+} | {
+  kind: "TileIf";
+  cond: Expr;
+  consequent: TileExpr;
+  alternate: TileExpr;
+  pos: Pos;
+} | {
+  kind: "TileMatch";
+  scrutinee: Expr;
+  arms: TileMatchArm[];
+  pos: Pos;
+};
+type TileMatchArm = {
+  pattern: Pattern;
+  body: TileExpr;
+};
+type TileArg = {
+  kind: "TileArg";
+  name?: string;
+  value: Expr | TileExpr;
+};
+type TileProp = {
+  kind: "TileProp";
+  name: string;
+  value: Expr;
+};
+//#endregion
+//#region src/codegen.d.ts
+type CodegenOptions = {
+  runtimeSpecifier: string;
+};
+declare function codegen(program: Program, opts: CodegenOptions): string;
+declare const RUNTIME_HELPERS = "\nfunction _setPath(obj, path, value) {\n  if (path.length === 0) return value;\n  const [head, ...rest] = path;\n  const cur = obj ?? {};\n  return { ...cur, [head]: _setPath(cur[head], rest, value) };\n}\nfunction _children(...xs) {\n  const out = [];\n  for (const x of xs) {\n    if (x === null || x === undefined) continue;\n    if (Array.isArray(x)) {\n      for (const y of x) if (y !== null && y !== undefined) out.push(y);\n    } else {\n      out.push(x);\n    }\n  }\n  return out;\n}\nfunction _attachProps(node, props) {\n  if (!node || !props) return node;\n  return { ...node, props: { ...(node.props || {}), ...props } };\n}\n";
+//#endregion
+//#region src/typecheck.d.ts
+type KumikiError = {
+  code: string;
+  kind: string;
+  message: string;
+  pos: Pos;
+};
+/** Returns errors with a11y warnings filtered out (unless strict). */
+declare function check(program: Program, opts?: {
+  strictA11y?: boolean;
+}): KumikiError[];
+//#endregion
+//#region src/compile.d.ts
+type CompileOk = {
+  kind: "ok";
+  js: string;
+  program: Program;
+};
+type CompileFail = {
+  kind: "fail";
+  errors: KumikiError[];
+};
+type CompileResult = CompileOk | CompileFail;
+type ExtendedCodegenOptions = CodegenOptions & {
+  /** Inline the runtime source into the output so the generated module needs no external import. */bundle?: boolean;
+  /**
+   * Returns the prebuilt runtime bundle JS. Required when `bundle` is true.
+   * This is injected (rather than read here) to keep the compiler free of any
+   * Node-only imports, so it can run unchanged in the browser. Node callers can
+   * use `nodeRuntimeBundleReader` from `@kumikijs/compiler/node`.
+   */
+  readRuntimeBundle?: () => string;
+};
+/** Inline a runtime bundle into generated module code, stripping the bridging import/export lines. */
+declare function inlineRuntime(generatedJs: string, runtimeBundleJs: string): string;
+declare function compile(source: string, opts: ExtendedCodegenOptions): CompileResult;
+//#endregion
+//#region src/lexer.d.ts
+declare function lex(source: string): Token[];
+//#endregion
+//#region src/parser.d.ts
+declare class ParseError extends Error {
+  pos: Pos;
+  constructor(message: string, pos: Pos);
+}
+declare function parse(tokens: Token[]): Program;
+//#endregion
+export { type AppDef, type BinOp, type CodegenOptions, type CompileFail, type CompileOk, type CompileResult, type Def, type EffectDef, type EventPattern, type Expr, type ExtendedCodegenOptions, type FnDef, type KumikiError, type Lvalue, type MatchArm, ParseError, type Pattern, type PolicyExpr, type Pos, type Program, RUNTIME_HELPERS, type ReducerDef, type Refinement, type RetryExpr, type SlotDef, type Statement, type ThemeDef, type ThemeValue, type TileArg, type TileDef, type TileExpr, type TileMatchArm, type TileProp, type Token, type TypeDef, type TypeExpr, type UiEventKind, check, codegen, compile, inlineRuntime, lex, parse };