parser-lr 0.6.1 → 0.8.0

package/docs/parser-lr-browser-lib-split.md

@@ -0,0 +1,174 @@
+# parser-lr: browser-safe library / Node CLI split
+
+**Audience:** agent working on [parser-lr](https://github.com/adamrmoss/parser-lr)  
+**Consumer:** [edu-basic](https://github.com/adamrmoss/edu-basic) (`parser-lr@0.6.1`)
+
+## Required architecture
+
+| Artifact | Node dependencies | Runs in browser |
+|----------|-------------------|-----------------|
+| **Library** (`parser-lr` package entry, `dist/lib/`) | **None** | **Yes** |
+| **CLI** (`bin/parser-lr.js`) | **All** (`fs`, `path`, `url`, grammar reading, `import.meta`) | No |
+
+The CLI is a bundled binary that includes everything it needs. The library is a parse runtime only: load a pre-generated table JSON, lex, parse, return AST.
+
+Grammar-file reading and table generation belong in the CLI (and optionally a separate Node-only subpath). They must not be on the main library import graph.
+
+## Current failure
+
+`ng build` in edu-basic fails:
+
+```text
+Could not resolve "node:fs"
+Could not resolve "node:path"
+Could not resolve "node:url"
+```
+
+Import chain from `import { ParseContext } from 'parser-lr'`:
+
+```text
+dist/lib/index.js
+  → grammar/index.js
+    → read-grammar.js
+      → meta-grammar-table.js      (readFileSync)
+        → grammar-json-path.esm.js (import.meta.url)
+```
+
+Also: `dist/lib/parse-context.js` has a **top-level** `import { readGrammar } from './grammar/read-grammar.js'`, so `ParseContext.fromTableJson` still pulls grammar code even though edu-basic never calls `fromGrammar`.
+
+Edu-basic runtime use: `ParseContext.fromTableJson(prebuiltTableJson)` → `lex` / `parseSource`. No `.grammar` files at runtime.
+
+## Required changes
+
+### 1. Library entry has no Node imports
+
+`dist/lib/index.js` (and CJS twin) must not statically import:
+
+- `read-grammar.js`
+- `meta-grammar-table.js`
+- `grammar-json-path*.js`
+- any `node:*` module
+
+### 2. `ParseContext` must not statically import grammar
+
+`fromTableJson` / table branch of `fromSources` must work without loading grammar modules.
+
+Options (pick one):
+
+- Remove `fromGrammar` from the main library export; grammar construction lives in CLI only.
+- Keep `fromGrammar` but implement it with **lazy** `import()` inside the method so it is not in the static graph.
+
+### 3. Grammar APIs off the main entry
+
+If Node consumers still need grammar-file APIs, expose them on a **separate** subpath only, e.g. `parser-lr/grammar`:
+
+- `readGrammar`
+- `validateGrammarTable`
+- `formatTableValidationIssues`
+- `Grammar`, `AstSchema`, `TransformSchema`
+
+Do not re-export these from the main `parser-lr` entry.
+
+### 4. CLI bundles all Node code
+
+`bin/parser-lr.js` must include grammar reading, meta-grammar bootstrap, and filesystem path resolution. Fix the existing bug where CLI looks for `bin/grammar.json` instead of `dist/lib/grammar/grammar.json` (see symptom below).
+
+### 5. Lazy meta-grammar on grammar path
+
+Even on the grammar/CLI path, do not load `grammar.json` or evaluate `import.meta` at module evaluation time. Load on first `readGrammar()` / `metaGrammarTable()` call.
+
+## Library exports (minimum for edu-basic)
+
+Main entry must export at least:
+
+- `ParseContext`
+- `AstNode`
+- `Token` (type)
+- `isEofToken`
+
+Add other runtime symbols only if existing parser-lr tests require them on the main entry.
+
+## Acceptance tests
+
+Run all of these against **`npm pack` output**, not only the dev tree.
+
+### A. Browser bundle
+
+esbuild must succeed:
+
+```javascript
+// entry.mjs
+import { ParseContext } from 'parser-lr';
+```
+
+```bash
+esbuild entry.mjs --bundle --platform=browser --outfile=/tmp/out.js
+```
+
+Exit 0. No `node:fs`, `node:path`, or `node:url` resolution errors.
+
+### B. Table-only runtime (ESM)
+
+```javascript
+import { ParseContext } from 'parser-lr';
+import { readFileSync } from 'node:fs';
+
+const table = JSON.parse(readFileSync('grammars/calc.table.json', 'utf8'));
+const ctx = ParseContext.fromTableJson(JSON.stringify(table));
+const ast = ctx.parseSource('1 + 2');
+if (!ast) throw new Error('parse failed');
+```
+
+Must not throw `import.meta` errors. Must not require `grammar.json` on disk for this import.
+
+### C. Table-only runtime (CJS)
+
+```javascript
+const { ParseContext } = require('parser-lr');
+// same table smoke as B
+```
+
+### D. CLI from tarball
+
+```bash
+npm pack
+tmpdir=$(mktemp -d)
+tar -xzf parser-lr-*.tgz -C "$tmpdir"
+cd "$tmpdir/package"
+node bin/parser-lr.js table validate -g grammars/calc.grammar
+node bin/parser-lr.js table generate -g grammars/calc.grammar -o /tmp/calc.json -a lalr
+```
+
+Both exit 0.
+
+### E. Grammar subpath (if implemented)
+
+```bash
+node -e "import('parser-lr/grammar').then(m => console.log(typeof m.readGrammar))"
+```
+
+Must not be required for tests A–C.
+
+## Known CLI bug (fix while here)
+
+```bash
+npx parser-lr table validate -g grammars/calc.grammar
+# ENOENT: .../node_modules/parser-lr/bin/grammar.json
+```
+
+`grammar.json` exists under `dist/lib/grammar/` but CLI resolves relative to `bin/`.
+
+## After release
+
+edu-basic will:
+
+1. Bump `parser-lr` to the new version.
+2. Re-run `npm run build` (Angular) and `npm test`.
+3. No browser polyfills for Node built-ins.
+
+Target version: **0.7.0** (export map changes, ESM-only, grammar subpath).
+
+## Non-goals
+
+- No change to parse semantics, table JSON format, or identity AST shape.
+- No requirement for edu-basic to stub `node:*` in the browser bundle.

package/grammars/6502.grammar

@@ -112,7 +112,7 @@ grammar
 
 ast
     program =
-        { line }
+        #program { line }
     ;
 
     line =
@@ -122,7 +122,7 @@ ast
     ;
 
     directive =
-        [dotTok]:dot
+        #directive [dotTok]:dot
         [sym]:identifier
         [value]:hex_number
     ;

package/grammars/ferrite.grammar

@@ -1,24 +1,28 @@
-// Ferrite — a C-like language with C#-style structs, namespaces, and pointer semantics.
-// No preprocessor; sources compile as single units (namespaces + using, like C# assemblies).
+// Ferrite — a C-like language with C#-style structs, file-scoped namespaces, and pointer semantics.
+// No preprocessor; sources compile as single units (namespaces + using).
+// Naming convention (not enforced by the grammar): PascalCase types, camelCase functions and variables.
 //
 // Example:
 //
-//   namespace Ferrite.Math {
-//       struct Vec2 {
-//           float32 x;
-//           float32 y;
-//           float32 dot(Vec2* other) {
-//               return x * other->x + y * other->y;
-//           }
-//       }
-//   }
+//   namespace Ferrite.Math;
 //
-//   using Ferrite.Math;
+//   using Ferrite.Core;
 //
-//   int32 main() {
+//   public struct Vec2
+//   {
+//       Float32 x;
+//       Float32 y;
+//       Float32 dot(Vec2* other)
+//       {
+//           return x * other->x + y * other->y;
+//       }
+//   };
+//
+//   public Int32 main()
+//   {
 //       Vec2 a = { 1.0, 2.0 };
 //       Vec2* p = &a;
-//       return (int32)p->dot(&a);
+//       return (Int32)p->dot(&a);
 //   }
 
 name "ferrite" ;
@@ -27,6 +31,8 @@ tokens
     kw_struct = /struct/ ;
     kw_namespace = /namespace/ ;
     kw_using = /using/ ;
+    kw_public = /public/ ;
+    kw_private = /private/ ;
     kw_if = /if/ ;
     kw_else = /else/ ;
     kw_while = /while/ ;
@@ -38,19 +44,19 @@ tokens
     kw_null = /null/ ;
     kw_true = /true/ ;
     kw_false = /false/ ;
-    kw_void = /void/ ;
-    kw_bool = /bool/ ;
-    kw_int8 = /int8/ ;
-    kw_int16 = /int16/ ;
-    kw_int32 = /int32/ ;
-    kw_int64 = /int64/ ;
-    kw_uint8 = /uint8/ ;
-    kw_uint16 = /uint16/ ;
-    kw_uint32 = /uint32/ ;
-    kw_uint64 = /uint64/ ;
-    kw_float32 = /float32/ ;
-    kw_float64 = /float64/ ;
-    kw_char = /char/ ;
+    kw_void = /Void/ ;
+    kw_bool = /Bool/ ;
+    kw_int8 = /Int8/ ;
+    kw_int16 = /Int16/ ;
+    kw_int32 = /Int32/ ;
+    kw_int64 = /Int64/ ;
+    kw_uint8 = /UInt8/ ;
+    kw_uint16 = /UInt16/ ;
+    kw_uint32 = /UInt32/ ;
+    kw_uint64 = /UInt64/ ;
+    kw_float32 = /Float32/ ;
+    kw_float64 = /Float64/ ;
+    kw_char = /Char/ ;
 
     identifier = /[A-Za-z_][A-Za-z0-9_]*/ ;
     int_literal = /0x[0-9A-F]+|0b[01]+|[0-9]+/i ;
@@ -112,28 +118,27 @@ start program ;
 
 grammar
     program =
+        [ [ns]:file_namespace ]
+        { [use]:using_directive }
         { [decl]:top_decl }
     ;
 
-    top_decl =
-        #namespace [nsKw]:kw_namespace [qname]:qualified_name [body]:namespace_body
-      | #using [useKw]:kw_using [qname]:qualified_name [semi]:semicolon
-      | #struct struct_decl
-      | #function function_decl
+    file_namespace =
+        [nsKw]:kw_namespace [qname]:qualified_name [semi]:semicolon
     ;
 
-    namespace_body =
-        [open]:lbrace
-        { [member]:namespace_member }
-        [close]:rbrace
+    using_directive =
+        [useKw]:kw_using [qname]:qualified_name [semi]:semicolon
     ;
 
-    namespace_member =
+    top_decl =
         #struct struct_decl
       | #function function_decl
-      | #namespace [nsKw]:kw_namespace [qname]:qualified_name [body]:namespace_body
-      | #using [useKw]:kw_using [qname]:qualified_name [semi]:semicolon
-      | #statement [stmt]:statement
+    ;
+
+    access_modifier =
+        #public [keyword]:kw_public
+      | #private [keyword]:kw_private
     ;
 
     qualified_name =
@@ -145,6 +150,7 @@ grammar
     ;
 
     struct_decl =
+        [access]:access_modifier
         [structKw]:kw_struct
         [sym]:identifier
         [body]:struct_body
@@ -186,12 +192,14 @@ grammar
 
     function_decl =
         #defined
+        [access]:access_modifier
         [type]:type_spec
         [sym]:identifier
         [open]:lpar
         [close]:rpar
         [body]:block
       | #definedParams
+        [access]:access_modifier
         [type]:type_spec
         [sym]:identifier
         [open]:lpar
@@ -199,12 +207,14 @@ grammar
         [close]:rpar
         [body]:block
       | #prototype
+        [access]:access_modifier
         [type]:type_spec
         [sym]:identifier
         [open]:lpar
         [close]:rpar
         [semi]:semicolon
       | #prototypeParams
+        [access]:access_modifier
         [type]:type_spec
         [sym]:identifier
         [open]:lpar
@@ -273,7 +283,7 @@ grammar
     ;
 
     expr_sep =
-        [commaTok]:comma [rest]:expression
+        #sep [commaTok]:comma [rest]:expression
     ;
 
     for_init =
@@ -425,39 +435,45 @@ grammar
 
 ast
     program =
-        { top_decl }
+        #program [ [ns]:file_namespace ] [usings]:using_list [decls]:decl_list
     ;
 
-    top_decl =
-        #namespace [nsKw]:kw_namespace [qname]:qualified_name [body]:namespace_body
-      | #using [useKw]:kw_using [qname]:qualified_name [semi]:semicolon
-      | #struct struct_decl
-      | #function function_decl
+    using_list =
+        #list { using_directive }
     ;
 
-    namespace_body =
-        [open]:lbrace
-        { [member]:namespace_member }
-        [close]:rbrace
+    decl_list =
+        #list { top_decl }
+    ;
+
+    file_namespace =
+        #file_namespace [nsKw]:kw_namespace [qname]:qualified_name [semi]:semicolon
+    ;
+
+    using_directive =
+        #using_directive [useKw]:kw_using [qname]:qualified_name [semi]:semicolon
     ;
 
-    namespace_member =
+    top_decl =
         #struct struct_decl
       | #function function_decl
-      | #namespace [nsKw]:kw_namespace [qname]:qualified_name [body]:namespace_body
-      | #using [useKw]:kw_using [qname]:qualified_name [semi]:semicolon
-      | #statement [stmt]:statement
+    ;
+
+    access_modifier =
+        #public [keyword]:kw_public
+      | #private [keyword]:kw_private
     ;
 
     qualified_name =
-        [head]:identifier { name_part }
+        #qualified_name [head]:identifier { name_part }
     ;
 
     name_part =
-        [dotTok]:dot [part]:identifier
+        #part [dotTok]:dot [part]:identifier
     ;
 
     struct_decl =
+        #struct_decl [access]:access_modifier
         [structKw]:kw_struct
         [sym]:identifier
         [body]:struct_body
@@ -465,7 +481,7 @@ ast
     ;
 
     struct_body =
-        [open]:lbrace
+        #struct_body [open]:lbrace
         { [member]:struct_member }
         [close]:rbrace
     ;
@@ -476,7 +492,7 @@ ast
     ;
 
     field_decl =
-        [type]:type_spec
+        #field_decl [type]:type_spec
         [sym]:identifier
         [semi]:semicolon
     ;
@@ -499,12 +515,14 @@ ast
 
     function_decl =
         #defined
+        [access]:access_modifier
         [type]:type_spec
         [sym]:identifier
         [open]:lpar
         [close]:rpar
         [body]:block
       | #definedParams
+        [access]:access_modifier
         [type]:type_spec
         [sym]:identifier
         [open]:lpar
@@ -512,12 +530,14 @@ ast
         [close]:rpar
         [body]:block
       | #prototype
+        [access]:access_modifier
         [type]:type_spec
         [sym]:identifier
         [open]:lpar
         [close]:rpar
         [semi]:semicolon
       | #prototypeParams
+        [access]:access_modifier
         [type]:type_spec
         [sym]:identifier
         [open]:lpar
@@ -531,16 +551,17 @@ ast
     ;
 
     param_sep =
-        [commaTok]:comma [rest]:param
+        #sep [commaTok]:comma [rest]:param
     ;
 
     param =
-        [type]:type_spec
+        #param [type]:type_spec
         [sym]:identifier
     ;
 
     type_spec =
-        #voidType [voidKw]:kw_void { [ptr]:star }
+        #pointers { [ptr]:star }
+      | #voidType [voidKw]:kw_void { [ptr]:star }
       | #bool [boolKw]:kw_bool { [ptr]:star }
       | #int8 [int8Kw]:kw_int8 { [ptr]:star }
       | #int16 [int16Kw]:kw_int16 { [ptr]:star }
@@ -559,7 +580,7 @@ ast
     ;
 
     block =
-        [open]:lbrace
+        #block [open]:lbrace
         { statement }
         [close]:rbrace
     ;
@@ -586,7 +607,7 @@ ast
     ;
 
     expr_sep =
-        [commaTok]:comma [rest]:expression
+        #sep [commaTok]:comma [rest]:expression
     ;
 
     for_init =
@@ -738,41 +759,39 @@ ast
 
 transform
     program ->
-        #main pass(program$repeat_0) ;
+        #main program.#program(ns, program$repeat_0, program$repeat_1) ;
 
     program$repeat_0 ->
-        #main flatten(program.#program, decl, program$repeat_0) ;
+        #main flatten(using_list.#list, use, program$repeat_0) ;
 
-    top_decl ->
-        #namespace top_decl.#namespace(nsKw, qname, body)
-      | #using top_decl.#using(useKw, qname, semi)
-      | #struct pass(struct_decl)
-      | #function pass(function_decl) ;
+    program$repeat_1 ->
+        #main flatten(decl_list.#list, decl, program$repeat_1) ;
 
-    namespace_body ->
-        #main namespace_body.#namespace_body(open, namespace_body$repeat_0, close) ;
+    file_namespace ->
+        #main file_namespace.#file_namespace(nsKw, qname, semi) ;
 
-    namespace_body$repeat_0 ->
-        #main flatten(namespace_body.#namespace_body, member, namespace_body$repeat_0) ;
+    using_directive ->
+        #main using_directive.#using_directive(useKw, qname, semi) ;
 
-    namespace_member ->
+    top_decl ->
         #struct pass(struct_decl)
-      | #function pass(function_decl)
-      | #namespace namespace_member.#namespace(nsKw, qname, body)
-      | #using namespace_member.#using(useKw, qname, semi)
-      | #statement pass(stmt) ;
+      | #function pass(function_decl) ;
+
+    access_modifier ->
+        #public access_modifier.#public(keyword)
+      | #private access_modifier.#private(keyword) ;
 
     qualified_name ->
-        #main qualified_name.#qualified_name(head, qualified_name$repeat_1) ;
+        #main qualified_name.#qualified_name(head, qualified_name$repeat_0) ;
 
-    qualified_name$repeat_1 ->
-        #main flatten(qualified_name.#qualified_name, name_part, qualified_name$repeat_1) ;
+    qualified_name$repeat_0 ->
+        #main flatten(qualified_name.#qualified_name, name_part, qualified_name$repeat_0) ;
 
     name_part ->
         #main name_part.#part(dotTok, part) ;
 
     struct_decl ->
-        #main struct_decl.#struct_decl(structKw, sym, body, semi) ;
+        #main struct_decl.#struct_decl(access, structKw, sym, body, semi) ;
 
     struct_body ->
         #main struct_body.#struct_body(open, struct_body$repeat_0, close) ;
@@ -792,17 +811,14 @@ transform
       | #methodParams method_decl.#method(type, sym, open, params, close, body) ;
 
     function_decl ->
-        #defined function_decl.#defined(type, sym, open, close, body)
-      | #definedParams function_decl.#defined(type, sym, open, params, close, body)
-      | #prototype function_decl.#prototype(type, sym, open, close, semi)
-      | #prototypeParams function_decl.#prototype(type, sym, open, params, close, semi) ;
+        #defined function_decl.#defined(access, type, sym, open, close, body)
+      | #definedParams function_decl.#defined(access, type, sym, open, params, close, body)
+      | #prototype function_decl.#prototype(access, type, sym, open, close, semi)
+      | #prototypeParams function_decl.#prototype(access, type, sym, open, params, close, semi) ;
 
     param_list ->
         #main flatten(param_list.#list, first, param_list$repeat_0) ;
 
-    param_list$repeat_0 ->
-        #main flatten(param_list.#list, param_sep, param_list$repeat_0) ;
-
     param_sep ->
         #main param_sep.#sep(commaTok, rest) ;
 
@@ -854,9 +870,6 @@ transform
     init_list ->
         #main flatten(init_list.#list, first, init_list$repeat_0) ;
 
-    init_list$repeat_0 ->
-        #main flatten(init_list.#list, expr_sep, init_list$repeat_0) ;
-
     expr_sep ->
         #main expr_sep.#sep(commaTok, rest) ;
 
@@ -974,9 +987,6 @@ transform
     arg_list ->
         #main flatten(arg_list.#list, first, arg_list$repeat_0) ;
 
-    arg_list$repeat_0 ->
-        #main flatten(arg_list.#list, expr_sep, arg_list$repeat_0) ;
-
     primary_expr ->
         #ident pass(sym)
       | #int pass(value)