kopscript 0.7.2 → 0.9.0

package/LLM.md

@@ -11,8 +11,8 @@ 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 build <file.ks>          # type-check + emit <file>.js and <file>.js.map next to the source
+ks run <file.ks>            # build, then execute with node --enable-source-maps
 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
@@ -21,13 +21,18 @@ ks build|check <file.ks> --json   # single JSON object on stdout instead of huma
 `--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": [] }
+{ "success": false, "diagnostics": [{ "code": "KS4065", "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
+failed `build` writes nothing; `.js.map` paths aren't listed separately, one is written next
+to each `.js` path in `written`). Exit code is `0` iff `success` is `true`. A missing entry
 file yields `{ success: false, diagnostics: [], written: [], error: "cannot find file '...'" }`.
 
+Source maps are statement-level, not column-level (see `src/sourcemap.ts`, hand-rolled VLQ,
+zero added dependencies) — a thrown/uncaught error resolves to the right `.ks` line, but a
+specific sub-expression within one line isn't separately mapped.
+
 ## File shape
 
 ```ks
@@ -541,7 +546,11 @@ Real, observed cases where a plausible-looking guess was wrong — not hypotheti
 
 ## 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.
+Every compiler error/warning is `{ code, severity, message, line, col }` (1-based).
+`code` is `KS` + a number, stable across compiler versions even when `message`'s wording
+changes — match on `code` in tooling, not on `message` text. Ranges by pipeline stage,
+never reused once assigned: `KS1xxx` lexer, `KS2xxx` parser, `KS3xxx` module/`using`
+resolution, `KS4xxx` checker (the large majority of real errors), `KS5xxx` templates.
+CLI output format: `` file:line:col - severity code: 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

@@ -54,6 +54,10 @@ LLM's context, as opposed to this README's narrative explanation.
   file — interpolation, event/property bindings, `*if`/`*for` — down to the exact same
   AST a hand-written `Render()` would produce, with auto-`Subscribe` wiring for state
   referenced directly in the markup. See [Templates](#templates).
+- **Real debugging, not just readable output**: `ks build` emits a real source map next to
+  every `.js` file (original `.ks` embedded, no separate file to ship), and `ks run` enables
+  it automatically — an uncaught exception names the real `.ks` file and line, not the
+  generated JS. Hand-rolled VLQ encoder, zero added dependencies. See "Source maps" below.
 - **A companion framework, [Kopular](https://dev.azure.com/koppinator/Koppindependence/_git/Kopular)**:
   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
@@ -741,8 +745,8 @@ runtime representation at all and are dropped from the emitted JS entirely.
 ## CLI
 
 ```
-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 build <file.ks>   # type-check and emit <file>.js (+ <file>.js.map) next to the source
+ks run <file.ks>     # build, then execute the emitted JS with node --enable-source-maps
 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
 ```
@@ -755,7 +759,7 @@ programmatically instead of scraping formatted text:
 {
   "success": false,
   "diagnostics": [
-    { "severity": "error", "message": "Argument 2 has type 'string', expected 'number'", "line": 2, "col": 14, "file": "/abs/path/to/file.ks" }
+    { "code": "KS4065", "severity": "error", "message": "Argument 2 has type 'string', expected 'number'", "line": 2, "col": 14, "file": "/abs/path/to/file.ks" }
   ],
   "written": []
 }
@@ -767,6 +771,28 @@ 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`.
 
+Every diagnostic carries a stable `code` (`KS` + a number) alongside its human-readable
+`message` — meant for a tool/agent to pattern-match reliably (`code === "KS4065"`) instead
+of parsing prose that can be reworded between versions. Codes are grouped by pipeline stage
+and never reused once assigned: `KS1xxx` lexer, `KS2xxx` parser, `KS3xxx` module/`using`
+resolution, `KS4xxx` the checker (by far the largest category — most real type errors live
+here), `KS5xxx` templates. There's no generated reference doc mapping every code to an
+explanation yet — for now, `message` is still the primary explanation; `code` is for
+matching, not (yet) for looking up docs.
+
+**Source maps**: `build` writes a real source-map v3 `<file>.js.map` alongside every
+`<file>.js`, with the original `.ks` source embedded (`sourcesContent`) so a deployed app
+doesn't need to ship its `.ks` files for devtools/stack traces to show real source. `run`
+passes Node's own `--enable-source-maps` flag automatically, so an uncaught exception
+during `ks run` names the real `.ks` file and line, not the generated `.js`. Hand-rolled
+(base64 VLQ), not the `source-map` npm package — kopscript has zero runtime dependencies
+and this keeps it that way (see `src/sourcemap.ts`). **Scope**: statement-level, not full
+expression/column-level — every statement (a class member, a block statement, a top-level
+declaration) gets its own mapping, but a specific sub-expression *within* one line doesn't.
+This is a deliberate v1 cut, the same spirit as generics/nullable types/templates: real,
+useful debugging (correct stack-trace lines, working breakpoints) without a full rewrite of
+codegen's string-concatenation architecture into a position-tracking writer.
+
 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.