feat(PARSE-02): add binding-aware compiler front end (#29)

Author: ellainng

IMPLEMENTATION_PLAN.md

@@ -370,6 +370,10 @@ Date, RegExp, Map/Set or prototype/descriptor expansion first.
 first syntax/semantic decisions and reference corpus. It does not claim that
 translation is implemented yet.
 
+[The compiler front-end API](docs/compiler-front-end.md) implements parsing,
+lexical binding, validation and immutable typed IR in the development checkout;
+JavaScript emission remains a separate milestone.
+
 ## Compiler contracts and artifacts
 
 Preserve ordinary supported Python truthiness, integers, Unicode, evaluation

README.md

@@ -88,6 +88,10 @@ globals and other unlisted APIs remain future work. Development is tracked in
 the [issues](https://github.com/outside-labs/Python-JavaScript/issues) and
 [Project](https://github.com/orgs/outside-labs/projects/11).
 
+The development checkout now includes a [binding-aware compiler front end](docs/compiler-front-end.md)
+that validates source and produces typed IR. JavaScript emission and browser
+execution remain subsequent milestones.
+
 ## Development
 
 ```sh

docs/compiler-front-end.md

@@ -0,0 +1,31 @@
+# Compiler front end
+
+The development checkout provides JavaScript.compiler.parse_source(source,
+filename=...) for the adopted python-browser/1 profile. It parses, binds and
+validates source without running target code, then returns an immutable ModuleIR.
+It does not emit or execute JavaScript yet; EMIT-01 owns that next step.
+
+The API uses only the declared Python runtime and standard library. A ModuleIR
+records profile/schema identity, SHA-256 of UTF-8 input, stable lexical binding
+IDs and typed nodes with original source spans. to_dict returns an independent
+JSON-serializable snapshot; integer constants are decimal strings tagged as
+python-int so an IR consumer cannot lose precision through JSON numbers.
+
+Bindings distinguish module constants/functions, function parameters/locals,
+builtin APIs and explicit JavaScript registry aliases. Alias resolution follows
+binding identity: a parameter named len or Array is not rewritten to a builtin
+or imported intrinsic. Branch and loop value types merge conservatively; source
+order, guards, defaults and errors remain represented for the emitter.
+
+CompileError exposes a Diagnostic with code, phase, message and SourceSpan.
+Locations use one-based character columns, converting Python AST's UTF-8 byte
+offsets. PJS100 covers syntax/features, PJS110 binding/import boundaries and
+PJS120 unsupported operations/calls. Unknown syntax/imports are refused before
+any output publication or target execution. Syntax, binding and validation
+phases remain distinct.
+
+Use the adopted language contract for supported forms. Initial module bindings
+are unconditional immutable literals; for loops are function-local with simple
+targets and no else clause. Source is UTF-8 and limited to 1 MiB. This front end
+does not load Python application imports, provide browser APIs or certify that
+arbitrary dependencies can be translated.

docs/compiler-language.md

@@ -20,7 +20,7 @@ and arbitrary user objects are outside the first profile.
 | Scalars | None, bool, arbitrary-precision int and Unicode str literals; tuples of supported values. Floats/bytes/complex wait for separate numeric/binary contracts. |
 | Bindings | Simple names, immutable module constants, ordinary local assignments and top-level plain functions. Preserve lexical binding identity and evaluation order. |
 | Functions | Positional arguments and immutable literal defaults; return, direct calls and recursion. Keyword/variadic calls, nested closures, decorators, annotations and async functions are deferred. |
-| Control flow | if/elif/else, for over approved strings/tuples, break/continue, ordinary return and expression statements. while/comprehensions/generators are deferred initially. |
+| Control flow | if/elif/else, function-local for over approved strings/tuples, break/continue, ordinary return and expression statements; loop-else is deferred. while/comprehensions/generators are deferred initially. |
 | Operations | Supported scalar arithmetic/comparisons, Python and/or/not, identity on supported values, string membership and supported indexing. Mixed or unknown operand forms need helpers or a source-located rejection. |
 | Builtins/errors | len on adopted strings/tuples, print of adopted values, approved isinstance checks and explicit builtin TypeError raising needed by the fixture. No eval/exec, reflection or undeclared I/O. |
 | JavaScript API | Resolve explicit imports/aliases through a versioned symbol/method registry. Start with Array.of and length as a binding fixture; other exports/methods need adopted signatures and parity cases before lowering. |
@@ -66,6 +66,8 @@ source-located diagnostics, not an interpreter/server fallback.
 
 ## Front end and diagnostics
 
+Source input is UTF-8 with an explicit 1 MiB front-end limit.
+
 Use ast -> bind -> validate -> typed IR -> lower -> emit. Never import or execute
 application/dependency modules to compile them. Carry original file/line/column
 spans and stable binding identities through every pass. Validate imports,