kopscript 0.2.0 → 0.3.0

package/LLM.md

@@ -0,0 +1,377 @@
+# KopScript — LLM reference
+
+Complete, dense reference for generating correct KopScript (`.ks`) code. This is a spec,
+not a tutorial — see `README.md` for narrative explanation and rationale. Every construct
+below is exhaustive: if something isn't listed here, it doesn't exist in the language.
+Read the "Does not exist" section before assuming any feature from another language
+carries over.
+
+Compiles to plain ES modules.
+
+## CLI
+
+```
+ks build <file.ks>          # type-check + emit <file>.js next to the source
+ks run <file.ks>            # build, then execute with node
+ks watch <file.ks>          # build, then rebuild on every change to any file in the graph
+ks check <file.ks>          # type-check only, no output files
+ks build|check <file.ks> --json   # single JSON object on stdout instead of human text
+```
+
+`--json` output shape (also what a tool/agent should parse instead of scraping text):
+
+```json
+{ "success": false, "diagnostics": [{ "severity": "error", "message": "...", "line": 2, "col": 14, "file": "/abs/path.ks" }], "written": [] }
+```
+
+`written` is the absolute paths actually written (`build` only, and only on success — a
+failed `build` writes nothing). Exit code is `0` iff `success` is `true`. A missing entry
+file yields `{ success: false, diagnostics: [], written: [], error: "cannot find file '...'" }`.
+
+## File shape
+
+```ks
+using "./other_file";       // 0+ usings, must be a contiguous prefix at the top
+using "../lib/thing";       // relative only ("./" or "../"), no bare package names
+
+// then any number of top-level statements/declarations, in any order
+```
+
+`using` resolves `<path>.ks` relative to the current file and pulls its `public`
+top-level classes/interfaces/enums/functions/extern-decls into unqualified scope. No
+package-import mechanism — cross-package consumption goes through `extern` instead (see
+below). No circular `using` (compile error).
+
+## Types
+
+| Type | Notes |
+|---|---|
+| `number` | one numeric type, no int/float split |
+| `string` | |
+| `bool` | `true` / `false` |
+| `void` | function/method return type only |
+| `T[]` | array of `T`; `T[][]` etc. nest freely |
+| `ClassName` / `InterfaceName` / `EnumName` | any user-declared named type |
+| `(T1, T2) => R` | function type — parenthesized param types, arrow, return type |
+| `task` / `task<T>` | see Async below |
+| `state<T>` | see Reactive state below |
+| `T?` | nullable — see Nullable types below |
+
+**Does not exist**: generics (no `class Foo<T>`, no `T Resolve<T>()`), `any`/`unknown` as
+a writable annotation, a `let`/`var` keyword (see Declarations below — there isn't one),
+type inference for declarations (every local/`const`/param/field/return type is written
+out explicitly), union types, tuples, structural/duck typing (all typing is nominal).
+
+## Declarations
+
+```ks
+number x = 5;                 // type-first local var (mutable)
+const string name = "Joe";    // type-first const
+```
+
+Top-level declarations (function/class/interface/enum/extern/raw-string) default to
+**exported** (visible via `using`) unless marked `private`. A top-level bare `number x = 5;`
+is a plain statement, not exportable — `using` only pulls in types and functions, never
+values.
+
+```ks
+private void Helper() { }     // file-local, not visible via `using`
+void Exported() { }           // default: visible via `using`
+```
+
+### Functions
+
+```ks
+number Add(number a, number b) {
+  return a + b;
+}
+async task<number> FetchValue() { return 1; }   // see Async
+```
+
+### Classes
+
+```ks
+class Dog : Animal, IBark {          // 0-1 base class + 0+ interfaces, comma-separated
+  private string name;               // field: no initializer syntax — set in constructor
+  public static number InstanceCount = 0;   // static field: initializer REQUIRED (no ctor runs for it)
+
+  public string Name { get; set; }   // auto-property, get-only or get+set
+  public string ReadOnly { get; }    // settable only within this class's own constructor
+
+  constructor(string name) : base(/* base ctor args */) {
+    this.name = name;
+  }
+
+  public virtual string Speak() { return "..."; }     // overridable
+  public override string Speak() { return "Woof"; }   // in a subclass
+  public static Dog Create(string name) { return new Dog(name); }
+}
+
+Dog d = new Dog("Rex");
+```
+
+- Visibility on members: `public` / `private` / `protected` (default when omitted: `public`).
+- `virtual`/`override` only on instance methods, not static, not fields/properties.
+- No interface-implementation keyword — implementing is structural-by-declaration: list
+  the interface in the base list and provide matching public methods, checked at compile time.
+- No nested classes/functions.
+- No multiple inheritance (at most one class in the base list; the rest must be interfaces).
+
+### Interfaces
+
+```ks
+interface IShape {
+  number Area();               // method signatures only — no fields/properties in v1
+}
+interface INamedShape : IShape { // interfaces can extend other interfaces (not classes)
+  string GetName();
+}
+```
+
+### Enums
+
+```ks
+enum Color { Red, Green, Blue }
+Color c = Color.Red;
+```
+
+No custom values, no methods on enums.
+
+### `match` expression
+
+```ks
+string Classify(string input) {
+  return match input {
+    "cat", "dog" => "animal",     // comma = OR within one arm
+    r"^[0-9]+$" => "number",      // regex pattern, r"..."
+    _ => "unknown"                // wildcard REQUIRED — exhaustiveness-checked
+  };
+}
+```
+
+`match` is an expression (has a value), matches on literal/regex patterns only (not
+type patterns, not destructuring), and always requires a trailing `_` arm.
+
+## Statements
+
+```ks
+if (cond) { } else if (cond2) { } else { }
+while (cond) { }
+for (number i = 0; i < n; i = i + 1) { }
+foreach (number x in items) { }              // arrays only
+break; continue; return; return expr;
+try { } catch (string e) { } finally { }     // at most one catch clause; param type is your choice
+throw "message";                              // throw takes any expression, not just string
+```
+
+`throw` accepts any expression (no base exception/error type to conform to), and a
+`catch (T e)` param's type `T` is **not checked against what's actually thrown** — it
+compiles to a plain JS `catch (e) { ... }` with zero runtime type discrimination. The
+type annotation only affects what `e` type-checks as *inside* the catch block. There's
+no way to have multiple catch clauses per type (only one `catch` per `try`), and no
+built-in exception hierarchy — `catch (string e)` (matching `throw "message";`) is the
+conventional shape used throughout this codebase, but any type is legal.
+
+There is **no ternary/conditional expression** (`if` is a statement only). To get a
+conditional *value* inline, use a `match` on a `bool`-shaped case set, or (in Kopular UI
+code) the `If()` helper — see the Kopular reference.
+
+## Expressions
+
+Precedence, low → high: `=` (right-assoc) → `||` → `&&` → `==` `!=` → `<` `>` `<=` `>=`
+→ `+` `-` → `*` `/` `%` → unary `-` `!` → postfix (`.member`, `(call)`, `[index]`) → primary.
+
+```ks
+this
+new ClassName(args)
+obj.Member
+obj.Method(args)
+arr[index]
+await someTask            // only inside an async function/method body
+state(0)                  // constructs a state<T> — see below
+$"Hello {name}, you are {age} years old"   // interpolated string
+r"^[a-z]+$"               // regex literal (only meaningful as a match pattern)
+```
+
+### Lambdas
+
+```ks
+(number x) => x * x                          // expression body
+(number x, number y) => { return x + y; }    // block body
+() => this.DoThing()
+```
+
+**Every lambda parameter type is required — no inference, no bare `(x) => ...`.** A
+lambda's own first parameter cannot itself be a function type (a rare v1 parser
+limitation, not a semantic one).
+
+### Arrays
+
+```ks
+number[] xs = [1, 2, 3];
+xs.Length
+xs.Push(4)                    // NON-mutating — returns a new array, doesn't modify xs
+xs.Map((number x) => x * 2)   // -> array of whatever the callback returns
+xs.Filter((number x) => x > 1)
+xs.ForEach((number x) => { print(x); })
+```
+
+### Strings
+
+```ks
+s.Length
+s.Contains(other) / s.StartsWith(other) / s.EndsWith(other)
+s.Replace(from, to)
+s.Split(sep)          // -> string[]
+s.Trim() / s.ToUpper() / s.ToLower()
+"a" + "b"             // + is also string concatenation
+```
+
+### Async
+
+```ks
+async task<number> FetchValue() {
+  number x = await SomeOtherAsyncFn();
+  return x;
+}
+async task DoThing() { }   // bare task = "async void" with a value you can await
+```
+
+`async` requires (and is required by) a `task`/`task<T>` return type. `await` only
+legal inside an async function/method body. No async lambdas. No way to construct a
+`task` value from outside an async function body.
+
+### Reactive state — `state<T>`
+
+```ks
+state<number> count = state(0);
+count.Value                          // read/write the current value
+count.Value = count.Value + 1;
+count.Subscribe((number v) => { ... }); // called on every future .Value assignment
+```
+
+Not a generic type parameter — `state<T>` is one of exactly two hardcoded parametrized
+forms in the type system (the other is `task<T>`).
+
+## Nullable types — `T?`
+
+```ks
+string? maybeName = null;               // null literal, any type-position postfix `?`
+string?[] arrOfNullable = [null, "x"];  // array OF nullable strings
+string[]? nullableArr = null;            // NULLABLE array of strings — order matters
+```
+
+`?` is a postfix modifier on any type, erased at codegen (JS already has native `null` —
+this is purely a compile-time distinction). Assignability is one-directional: a plain `T`
+is always usable where `T?` is expected (widening), but a `T?` is **never** usable where
+`T` is expected without narrowing first — accessing a member or index on an un-narrowed
+`T?` is a compile error:
+
+```ks
+void F(string? s) {
+  print(s.Length);      // ERROR: possibly-null type 'string?'
+  if (s != null) {
+    print(s.Length);     // OK — s is string here, not string?
+  }
+  print(s.Length);        // ERROR again — narrowing doesn't survive past the if
+}
+```
+
+**Narrowing is recognized in exactly these shapes** (anything else doesn't narrow):
+- `if (x != null) { ... }` — narrows `x` inside the then-branch.
+- `if (x == null) { ... } else { ... }` — narrows `x` inside the else-branch.
+- `cond1 && x.Foo` where `cond1` is `x != null` — narrows `x` for the right operand only.
+- `cond1 || x.Foo` where `cond1` is `x == null` — narrows `x` for the right operand only
+  (De Morgan's: reaching the right side of `||` means the left was false).
+- Either operand order works (`x != null` and `null != x` both narrow `x`).
+
+**Narrowing does NOT handle** (a common instinct from other languages — don't rely on
+these): an early-return guard clause (`if (x == null) { return; } use(x);` — `x` is
+*not* narrowed after the `if`, since that needs control-flow reachability analysis, not
+just scope); narrowing a member/property path (`if (this.Field != null)` narrows
+nothing — only a bare local/parameter identifier narrows); narrowing surviving
+reassignment (assigning a new value to a narrowed variable inside the narrowed block
+doesn't invalidate or restore narrowing — avoid reassigning a narrowed variable within
+the block). `x` stays narrowed for the rest of a narrowed block, including nested blocks
+inside it, since narrowing is scope-based.
+
+Comparing a value to `null` when its type **can't** be null is a compile error, not a
+silently-always-false comparison — this is a real bug-catching check, not just a style
+rule:
+
+```ks
+class Dog { }
+Dog d = new Dog();
+bool x = d == null;   // ERROR: Type 'Dog' can never be null
+```
+
+## `extern` — describing existing JS/npm code
+
+Three forms, always terminated with `;` after the closing brace for the class form:
+
+```ks
+extern number ParseFloat(string s) from "npm-package" as "parseFloat"; // `from` before `as`; omit `from` for an ambient global
+extern SomeType globalThing as "actualJsName";                          // extern value, ambient
+extern class Widget {
+  constructor();
+  string label { get; set; }         // property sig — get / get+set
+  static number Count { get; }
+  void Render();
+  virtual void Update();              // lets a real subclass `override` it
+} from "npm-package";
+```
+
+Clause order is always `from "<path>"` then `as "<jsName>"` (both optional, `from`
+first if both are present). `from "..."` omitted = ambient global (assumed to already
+exist at runtime, e.g. `document`). `as "..."` omitted = the JS-side name matches the
+KopScript-declared name exactly. Extern class members use real JS member names verbatim
+(camelCase, no rename mechanism). No inheritance modeling between two `extern class`
+declarations — each stands alone.
+
+## `raw string` — compile-time file embedding
+
+```ks
+raw string HeroHtml from "./hero.html";   // reads the file at compile time, type is always string
+```
+
+## Keywords (reserved, lowercase, exact match)
+
+`using extern raw from as const class interface enum constructor public private
+protected static virtual override get set return if else while for foreach in break
+continue match this base new void true false null task state async await try catch
+finally throw`
+
+Anything else (including PascalCase versions of the above, e.g. `If`, `Match`) is a
+valid identifier.
+
+## Naming convention used throughout the ecosystem
+
+Types, methods, and properties: **PascalCase** (`Speak()`, `Render()`, `Name`).
+Locals/params: **camelCase**. This is convention, not enforced by the compiler.
+
+## Does not exist (don't reach for these)
+
+Generics · `any`/`unknown` annotations ·
+a `let`/`var` keyword (locals are just `Type name = value;`) · decorators/annotations ·
+reflection · type inference on declarations · ternary expression · union/tuple types ·
+structural typing · multiple class inheritance ·
+nested classes/functions · method overloading · default/optional parameters · varargs ·
+static properties with accessors (static fields only) · interface properties (interface
+*methods* only) · a real exception hierarchy or multi-type `catch` (one `catch` per
+`try`, its param type is unchecked against what's actually thrown) · a package-import
+mechanism (`using` is same-project only; cross-package = `extern`).
+
+**Sharp edge, not just "unsupported":** declaring two methods with the same name in one
+class is **not a compile error** — the second declaration silently replaces the first in
+the checker's method table, so call sites resolve against whichever was declared last
+(and its body is the only one ever emitted). If you want to offer more than one
+signature, use different names, not overloading. (Nested function/class/interface/enum
+declarations, by contrast, *are* a clean compile error: "Nested ... declarations are not
+supported".)
+
+## Diagnostics
+
+Every compiler error/warning is `{ severity, message, line, col }` (1-based). CLI output
+format: `` file:line:col - severity: message `` plus a source line and a `^` pointer.
+`DiagnosticBag.hasErrors` gates whether codegen runs at all — a program with any error
+produces no output.

package/README.md

@@ -11,6 +11,10 @@ auto-properties, enums) rather than TypeScript ones.
 Because KopScript compiles to plain JavaScript and runs on Node, it runs identically on Windows,
 macOS, and Linux — there's no native toolchain to maintain.
 
+Generating KopScript with an AI coding assistant? Point it at **[`LLM.md`](./LLM.md)** —
+a dense, complete, example-driven language spec designed to be loaded straight into an
+LLM's context, as opposed to this README's narrative explanation.
+
 ## Highlights
 
 - **Object-oriented, C#-flavored**: type-first declarations (`string Name;`, not `name: string`),
@@ -18,6 +22,10 @@ macOS, and Linux — there's no native toolchain to maintain.
   explicit `virtual`/`override` dispatch (methods are sealed unless marked `virtual`), and a full
   `public`/`protected`/`private` access model enforced at compile time.
 - **Strongly typed**: every declaration is explicitly typed and checked at compile time.
+- **Nullable types with compiler-enforced null-checking**: `T?` (`string?`, `Dog?`,
+  `number[]?`) — a `T?` can't be used where a `T` is expected without an `if (x != null)`
+  check first (checked statically, not just at runtime), and comparing a value that can
+  never be null to `null` is itself a compile error.
 - **Built-in string pattern matching**: a `match` expression over strings supporting literal,
   wildcard, and regex patterns — no `if`/`else` chains required.
 - **Real multi-file programs**: `using "./shapes";` compiles a whole dependency graph
@@ -40,9 +48,9 @@ macOS, and Linux — there's no native toolchain to maintain.
   `.Subscribe((T) => void)`) for holding state and reacting to it changing — no
   Observables, no operators, no manual unsubscribe bookkeeping.
 - **A companion framework, [Kopular](https://dev.azure.com/koppinator/Koppindependence/_git/Kopular)**:
-  components, constructor-injected services (no DI container), and hash-based routing (no
-  config DSL) — built entirely on the features above, in a separate repo consumed as a
-  real package. [KopularDemo](https://dev.azure.com/koppinator/Koppindependence/_git/KopularDemo)
+  components, constructor-injected services via a composition root (no DI container), and
+  real-URL routing (no config DSL) — built entirely on the features above, in a separate
+  repo consumed as a real package. [KopularDemo](https://dev.azure.com/koppinator/Koppindependence/_git/KopularDemo)
   is a real app built on both.
 
 ## Getting started
@@ -513,8 +521,40 @@ foreach (number item in items) {
 ### Types (v1 scope)
 
 `number`, `string`, `bool`, `void`, `T[]` (arrays), class types, interface types, enum
-types, and function types (`(T, ...) => R`). No generics or nullable types yet — a
-possible future extension.
+types, function types (`(T, ...) => R`), and nullable types (`T?`, with `null` and
+compiler-enforced null-checking — see "Nullable types" below). No generics yet.
+
+### Nullable types — `T?`
+
+```ks
+string? maybeName = null;
+void Greet(string? name) {
+  if (name != null) {
+    print("Hello, " + name);   // name is `string` here, not `string?`
+  } else {
+    print("Hello, stranger");
+  }
+}
+```
+
+`?` is a postfix modifier on any type (`Dog?`, or an array either way — `string?[]` is an
+array of nullable strings, `string[]?` is a nullable array of strings; order matters).
+It's purely a compile-time distinction — erased at codegen, since JS already has native
+`null`. The compiler enforces it in both directions:
+
+- A `T?` can never be used where a `T` is expected — accessing a member or index on one
+  is a compile error — **unless** it's been narrowed by an `if (x != null)` /
+  `if (x == null) {...} else {...}` check (either operand order, and inside a `&&`/`||`
+  short-circuit) on that exact local/parameter. Narrowing doesn't survive past the
+  checked block, doesn't follow a `this.Field` path (locals/params only), and doesn't
+  understand an early-return guard clause (`if (x == null) { return; }`) — each of those
+  would need real control-flow analysis, deliberately not taken on in v1.
+- Comparing a value to `null` when its type *can't* be null (i.e. isn't itself a `T?`) is
+  a compile error, not a silently-always-false comparison — a real static check, not
+  just a style rule.
+
+See `LLM.md`'s "Nullable types" section for the exhaustive rules if you're generating
+code against this.
 
 ### Built-ins
 
@@ -534,7 +574,7 @@ src/
   codegen.ts     AST -> JavaScript source string (readable ES2020 output)
   modules.ts     multi-file orchestration: resolves the `using` graph, checks
                  modules in dependency order, drives codegen across all of them
-  cli.ts         `ks build <file>` / `ks run <file>` entry point
+  cli.ts         `ks build|run|watch|check <file>` entry point
 examples/        sample .ks programs (examples/modules/ is a multi-file one)
 test/            vitest unit and end-to-end tests
 ```
@@ -561,11 +601,32 @@ runtime representation at all and are dropped from the emitted JS entirely.
 ks build <file.ks>   # type-check and emit <file>.js next to the source
 ks run <file.ks>     # build, then execute the emitted JS with node
 ks watch <file.ks>   # build, then rebuild on every change to any file in the graph
+ks check <file.ks>   # type-check only — no output files written
+```
+
+`build` and `check` both accept `--json`, which replaces all human-readable output with a
+single JSON object on stdout — meant for CI or a tool/agent parsing the result
+programmatically instead of scraping formatted text:
+
+```json
+{
+  "success": false,
+  "diagnostics": [
+    { "severity": "error", "message": "Argument 2 has type 'string', expected 'number'", "line": 2, "col": 14, "file": "/abs/path/to/file.ks" }
+  ],
+  "written": []
+}
 ```
 
-During development, use `npm run ks -- <build|run|watch> <file.ks>` (backed by `tsx`),
-or run `npm run build` to compile the TypeScript compiler itself to `dist/` and use `node
-dist/cli.js` directly.
+`written` lists the absolute paths of every `.js` file actually written (always empty for
+`check`, and for `build` on failure — nothing is written unless the whole graph is
+error-free). A missing entry file reports `{ "success": false, "diagnostics": [],
+"written": [], "error": "cannot find file '...'" }` instead of throwing. Exit code is 0
+exactly when `success` is `true`, both with and without `--json`.
+
+During development, use `npm run ks -- <build|run|watch|check> <file.ks>` (backed by
+`tsx`), or run `npm run build` to compile the TypeScript compiler itself to `dist/` and
+use `node dist/cli.js` directly.
 
 `watch` rebuilds on a save to *any* `.ks` file it reached while compiling — the entry and
 everything it (transitively, non-transitively per-file) `using`s — not just the entry
@@ -588,25 +649,29 @@ into your extensions folder).
 
 ## Status
 
-This is a v1 / hobby-project scope. Not yet supported: generics, nullable types, static
-auto-properties, interface properties (methods only), and nested functions/classes.
-Generics and nullable types in particular are a substantially bigger undertaking than
-everything else here — they touch the type system's core (type parameters, variance,
-constraint checking) rather than being additive features, so they're deliberately left
-for a dedicated future pass rather than bolted on.
+This is a v1 / hobby-project scope. Nullable types (`T?`) shipped — see above. Not yet
+supported: generics, static auto-properties, interface properties (methods only), and
+nested functions/classes. Generics in particular is a substantially bigger undertaking
+than everything else here — it touches the type system's core (type parameters,
+variance, constraint checking) rather than being an additive feature, so it's
+deliberately left for a dedicated future pass rather than bolted on. Nullable types
+turned out to fit that "additive feature" shape after all: no variance or constraint
+solving involved, so it landed as a normal-sized change — a lesson for scoping generics
+itself, not evidence generics will be similarly sized.
 
 `async`/`await`, `task<T>`, and `try`/`catch`/`finally`/`throw` are now in place (see the
 language tour above) — the ceiling that's left is what's *inside* those: no async lambdas,
 and no way to build a `task` value by hand outside an `async` function body.
 
-### Toward a frontend framework: Kopular
+### A frontend framework: Kopular
 
 The language shape — modules, closures, DOM interop, `state<T>`, and `extern`/`virtual`
 subclassing across a package boundary — exists to support real UI components, not just
 scripts. That framework itself, [Kopular](https://dev.azure.com/koppinator/Koppindependence/_git/Kopular),
-lives in its own repo now rather than in `examples/` here, consumed as a real package
-(currently via a `file:` dependency, pending an npm publish of both). A real app built on
-both lives in [KopularDemo](https://dev.azure.com/koppinator/Koppindependence/_git/KopularDemo) —
-components, `state<T>`-driven reactivity, a constructor-injected service, and
-hash-based routing between two pages, verified against a real DOM via jsdom and in an
-actual browser.
+lives in its own repo, published to npm as `kopular` and consumed like any other package
+(no local checkout or `file:` dependency needed). A real app built on both lives in
+[KopularDemo](https://dev.azure.com/koppinator/Koppindependence/_git/KopularDemo) — several
+routed pages, `state<T>`-driven reactivity, constructor-injected services via a
+composition root (no DI container), structural-directive equivalents for `*ngIf`/`*ngFor`/
+`*ngSwitch`, and real-URL (History API) routing — verified against a real DOM via jsdom
+and in an actual browser.