semantifold 0.1.0

package/docs/architecture.md

@@ -0,0 +1,39 @@
+# Architecture
+
+Semantifold has three explicit layers.
+
+1. Frontend adapters in `src/frontends/` invoke mature language parsers and translate only recognized syntax. Babel owns JavaScript and TypeScript parsing, `php-parser` owns PHP, Prism owns Ruby, and Lezer owns Java. Their AST/CST objects never appear in the public API. Adapters enumerate supported children and reject every other parser node; filtering syntax away is not a normalization strategy. Prism node offsets and comment byte ranges are converted from UTF-8 to JavaScript UTF-16 offsets before semantic location construction and metadata source slicing.
+2. `src/semantic/` defines the shared JSDoc-typed discriminated representation and one-based, filename-bearing UTF-16 source locations. `provenance.js` indexes exact source content, deterministic semantic paths/node IDs, resolved symbol IDs, parser-token subranges, and closed source/derived/synthetic origins without exposing parser objects. Scalar types are exact `integer`, `boolean`, or `string` references. Literal nodes carry JavaScript-safe integer, primitive boolean, or parser-decoded Unicode scalar values. Unary and binary expressions carry a closed semantic `operation` and explicit result `type`, never a source operator symbol. Every function, entry point, consequent, and alternate owns a located `Block` containing ordered `Statement` nodes. Statements are local declarations, assignments, conditionals, explicit returns, or prints; an `IfStatement` has a Boolean condition, a consequent block, and an optional alternate block. Source-spelled `else if`, `elsif`, and `elseif` normalize to an alternate block containing one nested conditional.
+3. Source backends in `src/backends/` validate their semantic capabilities before emitting target syntax. Shared validation owns recursive block shape, reachability and all-path return analysis, recursively complete expressions, exhaustive operation/type signatures, function signatures, lexical binding scopes, mutability, declaration-before-use, and strict condition/return/argument/initializer/assignment types. Target-specific validation adds identifier rules, entry-scaffolding name collisions, Java's signed 32-bit `int` literal and compile-time-known arithmetic range, and target string escaping. Every emitter recursively writes blocks and statements through `SourceWriter`; semantic tokens, target anchors, and synthetic layout are mapped as they are emitted. A backend either returns a complete executable program or raises `UNSUPPORTED_CAPABILITY`; it never silently drops nodes or lets an emitter discover malformed shape through a `TypeError`.
+
+`index.js` is the public boundary. `parse({language, filename, source})` dispatches to an adapter. `generate({language, module})` validates and returns the compatibility source string. `generateArtifact(...)` uses the same emission path and returns code plus rich and v3 mappings. `src/mapping.js` owns validated lookup, deterministic serialization, mapping import/composition, and diagnostic remapping.
+
+## Round trips
+
+The tested semantic round trip is source → semantic module → generated source → equivalent semantic module. It preserves modeled meaning, not original spelling, string quotes/escapes, comments, whitespace, visibility, braces, or formatting. Parsed generated-source locations still refer to generated source, while `SemantifoldMapping` explicitly relates generated ranges back to semantic and original ranges. `number` in JS/TypeScript remains deliberately narrowed to semantic `integer` even though those languages permit fractional and special numeric values; only safe integer literals can enter the representation. String values contain complete Unicode scalar values, never source interpolation or lone UTF-16 surrogates, and each backend escapes that value without concatenating source fragments.
+
+Frontend source capabilities and backend target capabilities are intentionally separate. Adapters recognize parser-native syntax and retain a transient parser-neutral operation intent only until shared validation resolves identifier and call types. Successful parsing replaces that intent with one of the closed typed operations below before the public module is returned. Invalid operands point to the offending nested expression; mismatched equality points to the unequal operand; and a non-Boolean condition has its own stable diagnostic.
+
+| Result | Closed semantic operations |
+| --- | --- |
+| `integer` | `IntegerAdd`, `IntegerSubtract`, `IntegerMultiply`, `IntegerNegate` |
+| `boolean` from integers | `IntegerEqual`, `IntegerNotEqual`, `IntegerLessThan`, `IntegerLessThanOrEqual`, `IntegerGreaterThan`, `IntegerGreaterThanOrEqual` |
+| `boolean` from booleans | `BooleanNot`, `BooleanAnd`, `BooleanOr`, `BooleanEqual`, `BooleanNotEqual` |
+| `boolean` from strings | `StringEqual`, `StringNotEqual` |
+| `string` | `StringConcat` |
+
+Binary operands evaluate left to right. `BooleanAnd` and `BooleanOr` are short-circuit operations. Equality accepts only two operands of the same supported scalar type and means scalar value equality. Semantic integers are mathematical integers with one unsigned zero; IEEE-754 signed zero is not a distinct semantic value. Backends map meaning rather than copying syntax: PHP concatenation is `.`, Java string equality is `.equals`, JavaScript/TypeScript/PHP equality is strict, and other operations use their target's matching native construct. Because supported operations cannot otherwise distinguish signed zero, JavaScript and TypeScript canonically stringify observable scalar output when a module contains integer negation or multiplication. Their frontends unwrap that exact parser-native output scaffold during generated-source reparse, retaining the original operation tree without constant folding. Every emitted operation is conservatively parenthesized; generated-source reparsing reconstructs the same semantic tree.
+
+A source-valid semantic name can be rejected for a target reserved word, and a safe semantic integer can be rejected by Java's narrower `int` range. Java validates literal-only integer operation trees with exact mathematical integers without folding the IR, rejecting known results outside signed 32-bit `int`; unknown runtime overflow remains outside the portable guarantee.
+
+## Blocks, flow, and bindings
+
+Blocks preserve source order, evaluation order, and lexical nesting. Validation walks each statement once in order: an unconditional return makes every following statement in that block unreachable, and an `if` returns on all paths only when both its consequent and present alternate do. A non-void function must end every reachable path in an explicit return; optional alternates and empty blocks are valid only when later control flow remains complete. Entry points may not return a value.
+
+Binding identity is resolver-owned and exposed as deterministic module-local string IDs, never parser objects or trusted caller numeric IDs. Each validation/provenance pass creates symbol records for functions, parameters, and locals and resolves identifier reads, assignment targets, and calls through lexical function/branch/entry scopes. Module callables, parameters, and locals share one no-shadowing namespace; repeated names are rejected even across disjoint branches in this initial capability. Nested-block declarations do not escape their block. Initializers are validated before declaration and assignment right-hand expressions before the target update, preserving evaluation order and making self-reference a use-before-declaration error.
+
+## Provenance and generated mappings
+
+Frontend offsets remain parser-owned. Babel token positions, php-parser nodes/tokens, Prism byte locations/comment carriers, and Lezer syntax nodes provide exact function, parameter, local, type, assignment, literal, call, and operator ranges. The JavaScript/TypeScript adapter indexes Babel tokens once by start offset, using direct identifier lookup and bounded binary-search token lookup instead of rescanning the full token stream per semantic node. Source normalization converts only coordinates; it never normalizes source content. CRLF and lone CR count as line breaks and Ruby byte offsets become UTF-16 offsets.
+
+Each semantic node carries a JSON-safe source-provenance association through reorder, insertion, deletion, cloning, and serialization. Generation rebuilds canonical paths and node/symbol identities from current traversal and validates any serialized caller provenance before use; aggregate path/kind coincidence is never used to associate a different node. Shared caller objects receive deterministic occurrence records keyed by current JSON Pointer, so reused parameters, types, expressions, and valid statements do not collapse distinct emitted locations. Malformed caller registries, including empty source filenames, are discarded before canonical source fallback. This permits legacy and multi-source caller IR while preventing duplicate/stale IDs, mismatched source ownership, or out-of-bounds ranges from becoming semantic authority. The source-aware writer makes all output spans explicit, retains every contextual origin range across composition boundaries, and leaves no coarse legacy emitter path. Rich maps are frozen and indexed after validation; generated, original, node, and symbol queries include contextual related provenance without duplicate spans. See [source provenance and mappings](source-maps.md).

package/docs/coding-standards.md

@@ -0,0 +1,7 @@
+# Coding standards
+
+Production code is ESM JavaScript with `// @ts-check` and concrete JSDoc contracts. TypeScript runs with `allowJs`, `checkJs`, declaration emission, NodeNext resolution, and strict checking. Parser values may use an opaque external type only at an immediate narrowing boundary; semantic and public values use named concrete types.
+
+Formatting follows the sibling Velocious conventions: no semicolons, double-quoted strings, two-space JavaScript indentation, spaces inside named imports, one expression per readable chain line, and descriptive JSDoc including parameter and return descriptions. ESLint uses the flat configuration with recommended JavaScript, JSDoc, JSDoc inline-cast, and JSDoc tag-line rules.
+
+Keep adapters, semantic types, and backends separate. Never parse source with regex fallbacks. Unsupported syntax and capabilities must be visible diagnostics. Each spec file has one top-level `describe`; generated build/declaration files are never hand-edited.

package/docs/goals.md

@@ -0,0 +1,7 @@
+# Goals
+
+Semantifold's long-term goal is a language-neutral toolkit for understanding, transforming, generating, and eventually executing programs through a shared high-level semantic representation. The representation should make types, control flow, calls, declarations, diagnostics, and source provenance understandable without exposing a language parser's private tree.
+
+The current release candidate proves one minimal vertical slice across PHP, Ruby, JavaScript, TypeScript, and Java. It includes versioned source provenance, deterministic semantic node/symbol identity, range-based generated mappings, Source Map v3 interop, composition, and diagnostic remapping across that slice. It does not yet provide a general analyzer, transformation API, interpreter, optimizer, project graph, debugger integration, coverage remapping, or lossless formatter.
+
+Roadmap candidates include a versioned full semantic schema, more scalar and compound types, expressions and statements, user-authored transformations, richer backend capability negotiation, multi-file modules, cross-language stack/coverage presentation, and a semantic interpreter. LLVM, Wasm, JVM bytecode, package publication automation, and production TensorBuzz changes are explicitly outside this candidate.

package/docs/language-support.md

@@ -0,0 +1,69 @@
+# Language support
+
+## Implemented subset
+
+| Language | Exact frontend scalar types | Generated entry point |
+| --- | --- | --- |
+| PHP | `int`, `bool`, and `string` declarations; local `@var` carriers; optional exact `declare(strict_types=1)` | `echo …, PHP_EOL` |
+| Ruby | immediately associated Prism-recognized `[Integer]`, `[bool]`, and `[String]` function/local comments | `puts …` |
+| JavaScript | JSDoc `number`, `boolean`, and `string` on synchronous, non-generator functions and locals | `console.log(…)` |
+| TypeScript | exact `number`, `boolean`, and `string` keyword annotations on synchronous, non-generator functions and locals | `console.log(…)` |
+| Java | primitive `int`/`boolean` and exact `String` or `java.lang.String` declarations, plus a sequenced `public static void main` | `System.out.println(…)` in `Main` |
+
+Across every language, a module contains at least one function with exactly two required parameters and a scalar return. Function bodies, entry points, and conditional branches are ordered lexical blocks. They may contain supported local declarations, plain assignments, nested conditionals, explicit returns, and prints in source order. Conditions require semantic `boolean`. An alternate is optional, and source `else if`/`elsif`/`elseif` normalizes to one nested conditional inside the alternate block. Non-void functions must explicitly return on every reachable path; an optional alternate is therefore accepted only when a later statement completes the fallthrough path. A statement following an unconditional return or an exhaustive returning conditional in the same block is unreachable and rejected. Entry points cannot return values.
+
+Frontend conditional forms remain deliberately bounded:
+
+- JavaScript and TypeScript accept `if` with a block or one supported statement and normalize either to `Block`; directives, switch, labels, conditional expressions, and unmodeled executable/type-only statements are rejected.
+- PHP accepts braced `if`/`elseif`/`else`; alternative colon syntax, `switch`, `match`, inline HTML, and truthy conditions are rejected.
+- Ruby accepts ordinary `if`/`elsif`/`else` with explicit `return`; modifier conditionals, `unless`, `case`, implicit method returns, and truthy conditions are rejected.
+- Java requires braced ordinary branches while accepting a direct `else if`; switch forms, labels, assertions, synchronized blocks, local classes, and recovered grammar nodes are rejected.
+
+Every local is an explicitly typed simple identifier with an initializer. Parameters are immutable. Initializers are checked before their new binding becomes visible; assignment right-hand expressions are checked before the target update. Exact scalar types are preserved. Lexical function, branch, and entry scopes reject duplicate declarations, use before declaration, unresolved reads/writes, assignment to immutable bindings, type mismatch, and all shadowing or repeated local spellings in this initial capability. Module function names participate in the same no-shadowing contract, so no parameter or local may capture a callable name. Destructuring, multiple/uninitialized declarations, inferred types, arbitrary lvalues, compound/update assignment, globals/fields/constants, and parameter reassignment are unsupported.
+
+Local source profiles are exact:
+
+- JavaScript accepts only immediately associated `/** @type {string} */`-style JSDoc followed by one initialized `let` or `const`; `let` is mutable and `const` immutable.
+- TypeScript accepts one initialized `let` or `const` identifier with an exact scalar annotation.
+- Java accepts one initialized explicit scalar declarator; `final` is immutable and an unmodified local is mutable.
+- Ruby requires an immediately associated `# @type [String]`-style comment whose first metadata token is exactly `@type`. Profile-like misspellings such as `@typex` are malformed metadata, not declarations or ordinary comments. Ruby locals default to mutable. An immutable declaration uses the same contiguous carrier block with a separate exact `# @semantifold-immutable` line.
+- PHP requires an immediately associated exact `/** @var string $name */` carrier. PHP locals default to mutable. An immutable declaration uses a docblock containing both exact tags:
+
+```php
+/**
+ * @var string $name
+ * @semantifold-immutable
+ */
+$name = "value";
+```
+
+The Ruby/PHP tags are Semantifold source-profile metadata, not native runtime immutability. Their adapters validate the exact tag shape, semantic validation rejects later writes, and generators reproduce the metadata so mutability round-trips.
+
+Expressions contain parameter/local identifiers, scalar literals, two-argument unqualified calls, and the following typed operations. Every operation node records its result type, and identifier/call operands are resolved before an operation is selected.
+
+| Meaning | Ruby | JavaScript / TypeScript | PHP | Java |
+| --- | --- | --- | --- | --- |
+| Integer add, subtract, multiply | `+`, `-`, `*` | `+`, `-`, `*` | `+`, `-`, `*` | `+`, `-`, `*` |
+| Integer negate | unary `-` | unary `-` | unary `-` | unary `-` |
+| Boolean not, short-circuit and/or | `!`, `&&`, `\|\|` | `!`, `&&`, `\|\|` | `!`, `&&`, `\|\|` | `!`, `&&`, `\|\|` |
+| Same-type scalar equality/inequality | `==`, `!=` | `===`, `!==` | `===`, `!==` | `==`, `!=` for integer/Boolean; `.equals` and `!…equals` for strings |
+| Integer ordering | `<`, `<=`, `>`, `>=` | `<`, `<=`, `>`, `>=` | `<`, `<=`, `>`, `>=` | `<`, `<=`, `>`, `>=` |
+| String concatenation | `+` | `+` | `.` | `+` |
+
+Operands evaluate left to right, and Boolean and/or short-circuit. Conditions require semantic `boolean`; Ruby, PHP, and JavaScript truthiness is not normalized. Equality is scalar value equality only, requires matching operand types, and never coerces. Java reference `==`/`!=` on strings is rejected; generated Java uses `.equals`. Return values, call arguments, initializers, assignments, and explicit operation result types must exactly match their declared scalar types. Generated operations are parenthesized so reparsing preserves the expression tree rather than relying on coincident target precedence.
+
+Integer literals are restricted to JavaScript's safe integer range, `Number.MIN_SAFE_INTEGER` through `Number.MAX_SAFE_INTEGER`, and semantic integers have one unsigned mathematical zero. JavaScript and TypeScript can form IEEE-754 `-0` through negation or multiplication, so generated modules containing either operation stringify their scalar print argument to render both zero signs as `0`; the parser recognizes and removes only this exact entry-point scaffold during reparse. Supported operations cannot otherwise observe a zero sign, and the semantic expression tree is neither rewritten nor folded. Java generation additionally requires primitive-`int` literals and rejects compile-time-known add/subtract/multiply/negate results outside `-2147483648` through `2147483647`. This validation uses exact arithmetic without replacing the semantic expression tree. Runtime arithmetic overflow for non-literal expressions is not a portable guarantee.
+
+String literals normalize to their parser-decoded Unicode scalar value. Original quotes and escapes are not retained. PHP and Ruby interpolation, JavaScript/TypeScript template substitution, Java text blocks, PHP heredoc/nowdoc, invalid source encodings, and lone surrogate values are rejected. Backends use target-specific escaping for quotes, backslashes, controls, Unicode, and interpolation introducers. Generated source reparses to the same value.
+
+Ruby accepts exactly two required positional parameters. Optional, rest, post, keyword, keyword-rest, and block parameters remain unsupported. Its three annotation comments must form the contiguous block immediately before their function. PHP rejects every `declare` form other than one optional exact `declare(strict_types=1)`. Java calls remain unqualified and `main` may not contain ignored statements.
+
+Backends retain narrow ASCII identifier rules and reject target reserved words for function names, parameter names, local declarations, assignment targets, call targets, and identifier references before emission. Bindings are never renamed. TypeScript rejects `arguments` and `eval` for function, parameter, local-declaration, and assignment-target bindings because generated modules are strict mode. PHP rejects exact `GLOBALS`, `_SERVER`, `_GET`, `_POST`, `_FILES`, `_COOKIE`, `_SESSION`, `_REQUEST`, `_ENV`, and `this` parameter bindings; only exact `GLOBALS` and `this` are also rejected for local declarations and assignment targets. PHP function/call names, lowercase near-collisions, assignable non-`GLOBALS` superglobals, and ordinary predefined variables retain their legal roles. Ruby rejects exact `_1` through `_9` function, parameter, local-declaration, and assignment-target bindings while retaining `_10`; references and callees keep their general target identifier policy. JavaScript and other targets retain their own identifier policies. Names owned by generated scaffolding are role-specific: entry locals cannot be `console` in JavaScript/TypeScript or `args`/`System` in Java; function parameters and locals cannot be the generated print receiver `console` in JavaScript/TypeScript or `System` in Java; and module functions cannot be `console` in JavaScript/TypeScript or `puts` in Ruby. Ruby locals named `puts` and PHP locals named `PHP_EOL` remain valid because the generated print forms do not resolve them as local bindings. Java method names and PHP function names occupy namespaces that do not capture their entry scaffolding. PHP boolean printing differs from the other targets; the cross-language execution contract therefore compares a string result rather than claiming portable boolean display formatting.
+
+## Diagnostics and limitations
+
+All five frontends preserve exact input content and parser-backed semantic token ranges in module provenance. All 25 input-to-output combinations produce range-based rich maps and Source Map v3 sidecars with UTF-16 coordinates and symbol names. Output code uses LF deterministically. Only JavaScript and TypeScript may opt into inline or external `sourceMappingURL` directives; other targets consume sidecars through Semantifold APIs. Mapping does not imply lossless formatting or support for syntax outside the semantic subset. See [source provenance and mappings](source-maps.md).
+
+`UNSUPPORTED_SYNTAX` reports parsed constructs outside the subset with the best parser-provided source location. `MISSING_TYPE` reports missing or unsupported atomic annotations and identifies integer, boolean, and string as the supported scalar set. Parser failures use `PARSE_ERROR`. Semantic resolution/type failures use `DUPLICATE_BINDING`, `UNRESOLVED_BINDING`, `USE_BEFORE_DECLARATION`, `IMMUTABLE_ASSIGNMENT`, and `TYPE_MISMATCH`; flow failures use `NON_BOOLEAN_CONDITION`, `MISSING_RETURN`, `UNREACHABLE_STATEMENT`, `ILLEGAL_RETURN_CONTEXT`, and `UNSUPPORTED_STATEMENT`. Backends validate complete recursive block shape, flow, scalar payloads, binding/type agreement, mutability, identifiers, target bounds, and Java's fixed `Main.java` artifact basename before emission. Missing or structurally invalid blocks, statement arrays/elements, declaration names, mutability, type references, initializers, assignment targets/names, assigned expressions, conditional branches, and call-expression fields in caller-supplied IR use their nearest owning node location and report `UNSUPPORTED_CAPABILITY` rather than leaking a native error or producing partial source. A non-`Main.java` Java basename uses the same located capability diagnostic contract.
+
+Boxed or coercive types, inferred public types, TypeScript literal/enum/`any`/`unknown`/union types, PHP aliases/nullable declarations, Ruby `boolish`, Java `Boolean`/`char`, null values, floating point, decimal, bigint, symbols, regex values, byte strings, and interpolation are unsupported. Division, remainder, exponentiation, bitwise/shift/update/compound operations, Ruby/PHP `and`/`or`, loose equality, ternary/nullish forms, optional/safe navigation, ranges, casts/assertions, collection/object equality, operator overloading, implicit coercion, and constant folding are also excluded. There is no truthiness, implicit-return or statement-value model, void call statement (roadmap task 005), optional-value model, async/generator model, qualified calls other than Java string `.equals`, classes in the semantic representation, imports, loops, switches, exceptions, overloads, generics, packages, or source-format preservation. Ruby type comments remain a bounded RBS-style convention rather than a full signature parser, and Java generation retains the fixed `Main.java` contract.

package/docs/plans/2026-09-02-initial-toolchain.md

@@ -0,0 +1,54 @@
+# Initial toolchain plan
+
+Date: 2026-09-02
+
+## Narrow release-candidate scope
+
+Build one honest vertical slice: a module containing a typed two-integer function, a comparison with two return branches, integer arithmetic and a call from an entry point that prints the result. PHP, Ruby, JavaScript with JSDoc, TypeScript, and Java fixtures must normalize to the same semantic meaning. Anything outside the explicitly modeled nodes fails with an unsupported-syntax or unsupported-capability diagnostic.
+
+## Architecture and files
+
+- `src/semantic/`: JSDoc-typed discriminated semantic nodes, validation, and diagnostics. Parser-specific AST values never cross this boundary.
+- `src/frontends/`: one adapter per language plus a registry. Mature parsers provide syntax trees and source locations; adapters normalize only the release-candidate subset.
+- `src/backends/`: one source generator per language plus a registry. Each backend declares and checks its supported semantic capabilities.
+- `index.js`: small public API for parsing, validation, generation, and language discovery.
+- `spec/fixtures/`: equivalent source programs in all five languages.
+- `spec/`: focused frontend-equivalence, diagnostics, backend-generation/execution, public API, and repository-contract specs; each file has one top-level `describe`.
+- Root package/build/lint/container/CI files and project documentation describe the implemented subset separately from roadmap goals.
+
+## Strict TDD order
+
+1. RED: fixtures parsed through the public API cannot yet produce one location-bearing shared semantic module.
+2. GREEN: implement the semantic model and five parser-backed frontend adapters; REFACTOR shared traversal and diagnostics without exposing parser ASTs.
+3. RED: one shared semantic module cannot yet generate and execute exact-output programs in all five target languages.
+4. GREEN: implement capability-checked source backends and isolated temporary-directory execution tests; REFACTOR shared emitter helpers only where semantics stay obvious.
+5. RED/GREEN: add explicit unsupported-syntax, public API, package, TensorBuzz-only, and development-environment contracts.
+
+Exact focused RED commands and their observed failures will be retained for the final handoff.
+
+## Validation
+
+Run focused specs while iterating, then `npm test`, `npm run lint`, `npm run typecheck`, `npm run build`, `npm audit --audit-level=high`, `npm ls --omit=dev --all`, `npm pack --dry-run --json`, `git diff --check`, and available Dockerfile/Compose static validation. Runtime tests must invoke `php`, `ruby`, `node`, `tsc` plus `node`, and `javac` plus `java`; a missing executable is a test failure, never a skip.
+
+## Risks and controls
+
+- Parser ASTs differ significantly: keep traversal local to each adapter and cover fixtures plus unsupported nodes.
+- Language type systems do not align perfectly: use the single semantic `integer` type now and document lossy normalization and generation.
+- Source locations have different coordinate conventions: normalize to one-based line/column spans and preserve the originating filename/language.
+- Ruby lacks enforced parameter/return annotations in the chosen subset: accept explicit RBS-style `# @param`/`# @return` comments in the fixture and reject missing declarations.
+- Generated Java needs a class/file contract: emit `Main.java`; other backends use fixed documented filenames.
+- Tool availability can hide false confidence: execute real toolchains and fail with the missing command named in the diagnostic.
+
+## Deliberate non-goals
+
+No general-purpose parsing, comments/formatting round trips, classes, mutable variables, loops, exceptions, imports/packages, overloads, optimization, interpreter, LLVM, Wasm, JVM bytecode, or publication. Semantic round-trip means equivalent modeled meaning, not reproduction of original source text.
+
+## Bounded correction status
+
+The 2026-09-02 independent correction pass tightened the frozen candidate without broadening the semantic model:
+
+- Frontends now reject non-safe integer literals before construction, JS/TS async or generator flags, Java syntax that would otherwise be filtered, non-local Ruby annotations and non-required parameter forms, and PHP declarations other than optional exact `strict_types=1`.
+- Backends now validate target lexical/reserved identifiers at every semantic name use, Java signed 32-bit integer bounds, exactly one return per branch, exactly one entry print, and two arguments per call before emitters run.
+- The Velocious-compatible inline-JSDoc-cast ESLint plugin is pinned to immutable commit `441b6c5ca335a115a75d9f050134357ddb0a61d1`, with package and lockfile contract coverage.
+
+Each accepted review finding has a focused regression spec. The complete original fixture-equivalence and real five-runtime execution coverage remains the release gate.

package/docs/source-maps.md

@@ -0,0 +1,134 @@
+# Source provenance and mappings
+
+Semantifold keeps one authoritative, language-neutral provenance chain:
+
+```text
+generated UTF-16 range -> semantic node/symbol -> original UTF-16 range
+```
+
+This works for PHP, Ruby, JavaScript, TypeScript, and Java inputs and outputs. It is not limited to JavaScript `sourceMappingURL` comments. `SemantifoldMapping` v1 is the authoritative range model; every generated artifact also includes an ECMA-426/Source Map v3 projection for existing tooling.
+
+## Parsing and semantic provenance
+
+`parse()` preserves the existing `location.filename/start/end` shape. Lines and columns are one-based, ranges are half-open, and offsets and columns count UTF-16 code units. CRLF is one line break, a lone CR is one line break, and astral characters occupy two columns and offsets. A CRLF start-of-line coordinate resolves after both code units; the interior offset remains a unique position on the preceding line rather than aliasing the next line. Source content and its original newlines are preserved exactly.
+
+Parsed modules additionally have a JSON-safe `provenance` value:
+
+```js
+const module = parse({
+  filename: "choose.ts",
+  language: "typescript",
+  source
+})
+
+module.provenance // {
+//   schema: "SemantifoldProvenance",
+//   version: 1,
+//   coordinateSystem: "utf16",
+//   sources: [{id: "source:0", filename: "choose.ts", content: source, language: "typescript"}],
+//   nodes: [{id: "node:0", path: "", kind: "Module", origin, ranges: {}}],
+//   symbols: [{id: "symbol:0", kind: "function", declarationNodeId: "node:1", ...}]
+// }
+```
+
+Node IDs follow deterministic semantic occurrence order, node paths are JSON Pointers, and symbol IDs identify validated function, parameter, and local bindings. Reusing one caller-assembled semantic object at multiple paths produces one record and identity per occurrence rather than overwriting earlier paths; generation selects shared signature and local type occurrences by their current path in every backend. Object-only provenance queries remain intentionally unambiguous and require an ID when the object occurs more than once. Declaration records and resolved identifier/call records share a symbol ID. `ranges` contains parser-owned semantic tokens such as `name`, `type`, `callee`, `literal`, and `operator`. Babel identifier ranges use token offsets, including the complete source spelling of escaped identifiers while excluding TypeScript annotations. Parser AST/CST values never enter the public object.
+
+Each semantic node also carries its own JSON-safe `sourceProvenance` record. That object association—not an array position, old JSON Pointer, or caller-controlled ID—is the source of provenance after a semantic transformation. Reordering, inserting, deleting, serializing, or cloning nodes therefore moves their source ranges with them. Generation rebuilds current paths and registry-local node/symbol IDs; cloned nodes receive distinct generated identities even when they intentionally share one original origin.
+
+Origins are a closed union:
+
+```js
+{kind: "source", sourceId: "source:0", location}
+{kind: "derived", origins: [{sourceId: "source:0", location, role: "desugared-from"}]}
+{kind: "synthetic", reason: "Java class scaffolding", relatedOrigins: []}
+```
+
+`primaryLocation(origin)` returns the direct location, the first derived origin, the first related synthetic origin, or `undefined`. `getNodeProvenance(module, nodeOrId)` and `getSymbolProvenance(module, symbolId)` query parsed-module identities.
+
+Provenance is mutable JSON because semantic transformations need ordinary data. Generation therefore treats caller metadata as evidence, never authority: it validates node association, ranges, source bounds, coordinate consistency, and that a claimed `sourceId` actually owns its location, then rebuilds all paths and node/symbol IDs. Aggregate records are never reassigned to nodes merely because an old path and kind happen to match. Missing, malformed, duplicate, or stale metadata falls back safely to semantic `location` values; a malformed source registry, including any empty filename, is discarded before fallback rather than copied into a generated mapping. Independently attached node origins and ranges survive only when exact source content can still verify their coordinates, including through explicitly provided sources; otherwise generation uses the node's current location. Legacy caller-authored modules without provenance remain accepted. If caller-authored IR reuses one expression or valid statement object at multiple structural occurrences, generation maps each occurrence through its exact JSON Pointer and assigns distinct canonical node IDs.
+
+## Generated artifacts
+
+`generate()` remains the compatibility API and returns exactly the same source bytes as before this feature. `generateArtifact()` is additive:
+
+```js
+const artifact = generateArtifact({
+  filename: "Main.java",
+  language: "java",
+  module
+})
+
+artifact.code
+artifact.filename
+artifact.language
+artifact.mapping       // SemantifoldMapping v1
+artifact.sourceMap     // encoded Source Map v3 object
+artifact.sourceMapFilename
+```
+
+Default filenames are `program.php`, `program.rb`, `program.js`, `program.ts`, and `Main.java`. Java artifacts may include directories but must retain the basename `Main.java`, matching the generated public class and making the returned filename directly compilable; any other basename is a located `UNSUPPORTED_CAPABILITY` diagnostic for the Java backend. `sources` may supply exact content for legacy or caller-assembled multi-source IR:
+
+```js
+generateArtifact({
+  language: "ruby",
+  module: assembledModule,
+  sources: [
+    {filename: "first.ts", language: "typescript", content: firstSource},
+    {filename: "second.java", language: "java", content: secondSource}
+  ]
+})
+```
+
+This single-artifact envelope is intentionally reusable as an element in task 010's future ordered artifact set. Generation never writes files.
+
+All outputs have deterministic LF newlines. Returned rich mappings are detached from caller-owned semantic locations and provenance before they are deeply frozen and internally indexed after trust-boundary validation. Freezing an artifact mapping therefore never freezes the mutable semantic module used to generate it. The rich map's `generated.content` is the exact returned code and its ordered, non-empty spans cover every UTF-16 code unit without gaps or overlaps:
+
+- `exact` maps a generated semantic token to an exact parser token/range.
+- `anchor` maps target syntax such as a keyword or delimiter to the owning semantic origin.
+- `synthetic` marks formatting, comments, entry wrappers, and target scaffolding, optionally with related origins. Writer context expands every direct, derived, or synthetic-related range from its semantic nodes and removes only deterministic duplicates.
+
+Every span may carry a canonical `nodeId`, `symbolId`, semantic `role`, and Source Map `name`. Sources retain filenames, exact `sourcesContent` when available, and independent registry identity. Rich mappings are the serialization and interchange contract because v3 represents points rather than ranges and cannot retain semantic roles or the closed derived/synthetic model.
+
+## Source Map v3 and directives
+
+`artifact.sourceMap` exists for all five targets and is generated with `@jridgewell/gen-mapping`; lookup and import use `@jridgewell/trace-mapping`. Semantifold does not hand-code VLQ or tracing. The v3 map contains deterministic `file`, `sources`, `sourcesContent`, `names`, and `mappings` fields.
+
+Directives are opt-in and only valid for JavaScript and TypeScript:
+
+```js
+generateArtifact({language: "javascript", module, mapDirective: "external"})
+generateArtifact({language: "typescript", module, mapDirective: "inline"})
+```
+
+`external` appends `//# sourceMappingURL=<relative-map-url>`. `artifact.sourceMapFilename` remains the map artifact's literal logical filename, while the directive is relative to `artifact.filename`'s directory and URL-encodes each filesystem path segment without encoding structural slashes. Both logical paths resolve against one synthetic artifact root before relativization, so mixed leading-parent depths do not become false common segments; for example, generated `../../dist/out.js` and map `../maps/out.js.map` emit `../maps/out.js.map`. `dist/program.js` still advertises `dist/program.js.map` and emits `sourceMappingURL=program.js.map`; a literal `#` or `?` in the sidecar filename is emitted as `%23` or `%3F`. Names containing any ECMAScript line terminator—LF, CR, U+2028, or U+2029—are rejected before emission. `inline` appends a UTF-8 base64 data URL. The default is `none`. PHP, Ruby, and Java still receive sidecar map objects but never receive non-native map comments. Native Java debugger mapping such as JSR-45 would require class-file/toolchain integration and is not part of v1.
+
+The directive itself is an unmapped synthetic rich-map span. `artifact.sourceMap` is computed for the program before that self-referential comment is appended; this is required for a stable inline data URL and is the conventional v3 behavior. Use the rich mapping when the directive span itself matters. Rich registries may distinguish same-named sources by `sourceId`; Source Map v3 identifies sources by filename, so callers should use unique filenames when exporting such an assembled registry to v3.
+
+## Queries, serialization, composition, and diagnostics
+
+```js
+const original = originalPositionFor(artifact.mapping, {offset: generatedOffset})
+const generated = generatedPositionFor(artifact.mapping, {filename: "choose.ts", offset: originalOffset})
+const unambiguous = generatedPositionFor(artifact.mapping, {sourceId: "source:0", offset: originalOffset})
+const nodeSpans = spansForNode(artifact.mapping, original.nodeId)
+const symbolSpans = spansForSymbol(artifact.mapping, original.symbolId)
+
+const json = stringifyMapping(artifact.mapping)
+const restored = parseMapping(json)
+```
+
+Reverse lookup indexes every source range in direct, derived, and synthetic-related origins. Zero-length original locations are indexed as exact points, including valid content-backed Source Map anchors at EOF; they match only their precise offset and do not change ordinary half-open range containment. Node and symbol queries likewise index span-level identities plus identities carried by derived and synthetic related origins. Each query preserves generated-span order and returns a span once even when its identity appears through multiple associations.
+
+Rich positions accept zero-based UTF-16 offsets or one-based line/column pairs. Serialization recursively sorts object keys and preserves semantically ordered arrays. Parsing rejects the wrong schema/version, malformed identities, unknown source references, stale source coordinates, non-LF generated content, and span gaps/overlaps.
+
+`composeMappings(outer, inner)` composes generated ranges through an intermediate rich mapping. It preserves the inner source registry IDs used by retained node, symbol, and span origins. Every related origin is resolved independently by `sourceId`: origins whose registered source has the inner artifact's filename, exact generated content, and no contradictory known language are traced through every covered inner span, while unrelated origins are retained in deterministic order. Selection scans past matching but untraced origins until it finds an actual inner span. An intermediate EOF point has no containing half-open generated span, so composition preserves that untraced point and retains its intermediate source instead of assigning it to the last span or dropping its registry entry. Derived origins remain derived when at least one original range survives; if their only intermediate range resolves to an unmapped inner synthetic span with no related original range, composition adopts that valid synthetic origin and its stable reason instead of constructing an empty derived origin. Outer synthetic spans remain synthetic, retain their stable reason/context, and translate intermediate context into all related original provenance instead of falsely mapping scaffolding as an anchor. Exact equal-length outer ranges are split at every inner mapping boundary. A strict subrange that cannot carry a correspondingly sliced inner origin is conservatively anchored, as are other ranges without a provable one-to-one subdivision; when such an unsplit range crosses multiple inner spans, its derived origin retains every overlapping original range for forward and reverse lookup. `mappingFromSourceMap(v3, generated)` imports a point map as anchor/synthetic ranges, terminates each segment at its generated line end, explicitly represents unmapped prefixes, newlines, and lines as synthetic, and registers `sourceRoot` inputs by TraceMap's resolved source names. Content-backed anchors at EOF remain zero-length point origins and round-trip through both lookup directions, including for empty sources. Each source referenced by a mapped segment must have exact content in `sourcesContent` or a `generated.sources` override; contentless mapped positions are rejected instead of fabricating offsets, so reverse lookup remains indexable and coordinate-correct. Caller source-content overrides prefer exact V3 source names; a suffix override is accepted only when it identifies one map source, and ambiguous suffixes fail loudly before any registry entry is renamed. `composeSourceMaps(outerV3, innerV3)` composes v3 maps using the maintained mapping libraries. It registers both maps' resolved source names in deterministic input order and pairs `sourcesContent` by raw source index, so `sourceRoot` cannot create unused raw-name sources or duplicate content. Because v3 has filenames but no rich registry IDs or generated content identity, V3 composition traces only when exactly one resolved outer source equals the inner map's `file`; basename or suffix matches are not inferred. The test suite compiles a generated TypeScript artifact with real `tsc`, then verifies both JavaScript -> generated TypeScript -> original Ruby compositions.
+
+Validation constructs source line starts once, verifies ranges in linear passes, and creates binary-search/interval indexes for generated and original positions. Immutable mappings produced by Semantifold reuse that validated index for subsequent queries. Mutable caller mappings are deliberately revalidated on every public operation so cache reuse never weakens the trust boundary.
+
+`remapLocation(generatedLocation, mapping)` returns the complete lookup result. `remapDiagnostic(diagnostic, mapping)` returns a `SemantifoldDiagnostic` at the original location while preserving the prior range as `generatedLocation` and the original diagnostic as `cause`.
+
+## Compatibility and release recommendation
+
+The feature is source-compatible and additive: `generate()` bytes are characterized for both existing fixture profiles, legacy semantic modules remain valid, and existing `location` fields are unchanged. Parsed modules now serialize an additional enumerable `provenance` property, so consumers that compare or persist entire module JSON should consciously include or omit it.
+
+Semantifold is pre-1.0. The recommended release is a minor bump from `0.1.x` to `0.2.0`, with no npm publication as part of this implementation. A future incompatible provenance or mapping representation must use a new schema version rather than reinterpret version 1.

package/docs/testing.md

@@ -0,0 +1,25 @@
+# Testing
+
+Specs use the released `@velocious/testing@0.0.0` framework and standalone `velocious-test` runner with one top-level `describe` per file. Direct value checks use the framework's `expect` API where it improves clarity; predicate-rich diagnostic assertions retain `node:assert/strict`. Frontend tests load real fixtures through Babel, php-parser, Prism, and Lezer and compare modeled meaning after removing source locations and the separately tested provenance index. They separately assert normalized JSDoc and TypeScript types and verify locations exist.
+
+Backend tests start from one parsed semantic module, generate every target, parse each generated program back to equivalent modeled meaning, and work in isolated `mkdtemp` directories. They invoke real commands and assert exact `5\n` output:
+
+- `php program.php`
+- `ruby program.rb`
+- `node program.js`
+- local lockfile-installed `tsc program.ts`, then `node program.js`
+- `javac Main.java`, then `java -cp … Main`
+
+Cleanup runs in `finally`. A missing tool raises the process error and fails the spec; there are no skip branches or mocked compilers. Diagnostic specs cover unsupported syntax, missing JSDoc types, and backend capability rejection.
+
+Mapping specs assert all 25 frontend/backend combinations, exact/anchor/synthetic coverage without gaps, semantic-token roles, deterministic source/node/symbol IDs, exact `sourcesContent`, independently decoded v3 maps, rich/v3 composition, malformed caller metadata repair, legacy modules, caller-assembled multi-source IR, and deterministic JSON round trips. Transformation regressions cover same-kind function reorder, insertion, deletion, cloning, ID regeneration, source ownership, shared parameter, expression, and statement occurrences, and their distinct JSON-pointer node identities. UTF-16 cases cover BMP/astral text plus LF, canonical CRLF, and lone CR; escaped Babel identifiers cover declarations, references, and calls. Imported maps are checked against TraceMap on unmapped prefixes and lines; content-backed EOF anchors, including empty sources, round-trip as exact points, while mapped imports without source content are rejected before offset construction. Composition coverage includes derived intermediate provenance that resolves only to unmapped synthetic content, untraced intermediate EOF points whose registry source must remain available, and ordering where a later range remains traceable. Identity-index coverage checks direct, derived, and synthetic-related node/symbol associations for ordered deduplication. External directive coverage includes mixed parent-relative depths and resolution to the advertised map path. A bounded 50-to-200-function scaling test guards linear validation and indexed lookups; deterministic operation-count coverage guards Babel token indexing without wall-clock thresholds. A real `tsc` map is composed through generated TypeScript to original Ruby source. A separate mapped-artifact acceptance executes PHP, Ruby, Node, TypeScript through real `tsc`/Node, and Java through real `javac`/`java`; unavailable commands fail. SHA-256 characterization checks preserve every existing base/local generated byte across all source languages and targets.
+
+Local-binding fixtures cover initialized mutable and immutable declarations, plain assignment, function/branch/entry sequencing, exact Ruby/PHP profile metadata, and source locations in all five frontends. Focused negatives cover every declaration/assignment exclusion, declaration-before-use, unresolved and duplicate bindings, callable-name and lexical no-shadowing, immutable parameters/locals, exact type preservation, and RHS-before-target validation. Ruby coverage rejects profile-like tag misspellings, places multibyte text before later function and local carrier comments, asserts their UTF-16 locations, and reparses generated Ruby with the same offset shift. Backend shape coverage applies missing, null, primitive, array, sparse, and unsupported-object values to recursive blocks, statement elements, declaration/assignment fields, and recursively nested call expressions, proving caller-supplied malformed IR receives the nearest located capability diagnostic before emitter dispatch. Backend runtime coverage regenerates and reparses the same binding/mutability semantics, then executes the result through all five real toolchains with exact `yes\n` output. Target-focused coverage rejects JavaScript/TypeScript `console` and Java `args`/`System` entry captures, JavaScript/TypeScript `console` and Java `System` function parameter/local print-receiver captures, and JavaScript/TypeScript `console` and Ruby `puts` function captures before emission. Real `tsc`, PHP, and Ruby coverage demonstrates their strict or reserved binding failures and requires located target-backend rejection for each proven declaration/assignment role. The PHP probe matrix separately covers automatic-global parameters, the narrower `GLOBALS`/`this` assignment restriction, legal function names, assignable non-`GLOBALS` superglobals, ordinary predefined variables, and exact-case near-collisions; other runtime coverage executes safe JavaScript behavior, Ruby `_10`, and TypeScript near-collisions.
+
+Statement-sequencing coverage compares all five parser-native frontends, asserts located `Block` nodes and normalized nested alternates, tests optional fallthrough branches and lexical scope, and requires stable diagnostics for truthy conditions, incomplete returns, unreachable statements, illegal entry returns, and language-specific excluded statements. Separate backend specs corrupt block shape and statement kinds before all five emitters, verify nested generated-source reparses and mappings, preserve legacy bytes for unchanged programs, and execute exact multi-line branch behavior through real PHP, Ruby, Node.js, TypeScript, and Java toolchains.
+
+Typed-operation fixtures cover all 18 closed unary/binary operations and explicit result types in every frontend. One semantic module is emitted, reparsed, compiled, and run through real `php`, `ruby`, `node`, local `tsc` plus `node`, and `javac` plus `java`, with exact `typed:operators\n` output. A recursive but side-effect-free right operand proves native short-circuit behavior by remaining unevaluated in every target. Focused negatives cover loose/mixed equality, truthiness, mixed addition, every excluded operator family, casts/assertions, object/collection equality, Java reference equality, malformed Java `.equals`, caller-authored unknown/malformed operations, and Java literal/known-expression bounds. Literal arithmetic remains an operation tree, proving validation does not constant-fold.
+
+Focused correction specs prove that unsafe numeric literals never enter the semantic tree; async/generator flags are rejected; Java receivers, unsupported arguments, and extra entry statements cannot disappear; Ruby annotations and parameter forms stay function-local; and PHP accepts only its precise strict-types declaration. Backend specs cover target reserved identifiers, Java's signed 32-bit range, and exact one-return branch cardinality. Repository-contract specs parse package metadata, Compose/TensorBuzz YAML, and the Dockerfile AST; they prove the custom ESLint plugin uses an immutable commit and TensorBuzz is the sole CI topology.
+
+Run `npx velocious-test spec/repository-contract.spec.js` for the focused repository contract and `npm test` for framework-native discovery of `.spec.js` files under `spec`. An empty selection is a framework failure and exits nonzero. Run `npm run lint`, `npm run typecheck`, and `npm run build` for source quality and declaration generation. Packaging validation is documented in the root README and `AGENTS.md`.

package/index.js

@@ -0,0 +1,63 @@
+// @ts-check
+
+import {parseSource} from "./src/frontends/index.js"
+import {generateArtifactSource, generateSource} from "./src/backends/index.js"
+
+export {SemantifoldDiagnostic} from "./src/diagnostic.js"
+export {getNodeProvenance, getSymbolProvenance} from "./src/semantic/provenance.js"
+export {primaryLocation} from "./src/semantic/provenance.js"
+export {
+  composeMappings,
+  composeSourceMaps,
+  generatedPositionFor,
+  mappingFromSourceMap,
+  originalPositionFor,
+  parseMapping,
+  remapDiagnostic,
+  remapLocation,
+  spansForNode,
+  spansForSymbol,
+  stringifyMapping,
+  toSourceMapV3
+} from "./src/mapping.js"
+
+/** @type {readonly import("./src/semantic/types.js").SemanticLanguage[]} */
+export const supportedLanguages = Object.freeze(["php", "ruby", "javascript", "typescript", "java"])
+
+/**
+ * Parses source into Semantifold's shared semantic representation.
+ * @param {object} input - Parse request.
+ * @param {string} input.filename - Source filename used in diagnostics.
+ * @param {import("./src/semantic/types.js").SemanticLanguage} input.language - Source language.
+ * @param {string} input.source - Source text.
+ * @returns {import("./src/semantic/types.js").SemanticModule} Semantic module.
+ */
+export function parse(input) {
+  return parseSource(input)
+}
+
+/**
+ * Generates target-language source from a shared semantic module.
+ * @param {object} input - Generation request.
+ * @param {import("./src/semantic/types.js").SemanticLanguage} input.language - Target language.
+ * @param {import("./src/semantic/types.js").SemanticModule} input.module - Semantic module.
+ * @returns {string} Generated source.
+ */
+export function generate(input) {
+  return generateSource(input)
+}
+
+/**
+ * Generates a reusable output artifact with rich and Source Map v3 mappings.
+ * @param {object} input - Generation request.
+ * @param {import("./src/semantic/types.js").SemanticLanguage} input.language - Target language.
+ * @param {import("./src/semantic/types.js").SemanticModule} input.module - Semantic module.
+ * @param {string} [input.filename] - Output filename.
+ * @param {"none" | "external" | "inline"} [input.mapDirective] - JavaScript-family map directive.
+ * @param {string} [input.sourceMapFilename] - External map filename.
+ * @param {{filename: string, content: string, language?: import("./src/semantic/types.js").SemanticLanguage}[]} [input.sources] - Sources for caller-authored modules.
+ * @returns {import("./src/semantic/types.js").GeneratedArtifact} Generated artifact.
+ */
+export function generateArtifact(input) {
+  return generateArtifactSource(input)
+}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "semantifold",
+  "version": "0.1.0",
+  "description": "Language-neutral semantic code analysis, transformation, generation, and execution toolkit",
+  "type": "module",
+  "main": "build/index.js",
+  "types": "build/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./build/index.d.ts",
+      "import": "./build/index.js"
+    }
+  },
+  "files": [
+    "build/**",
+    "docs/**",
+    "index.js",
+    "LICENSE",
+    "README.md",
+    "src/**",
+    "tsconfig.json"
+  ],
+  "scripts": {
+    "all-checks": "npm run lint && npm test",
+    "build": "node scripts/clean-build.js && tsc",
+    "eslint": "eslint --max-warnings 0 .",
+    "lint": "npm run eslint && npm run typecheck",
+    "prepack": "npm run build",
+    "test": "velocious-test spec",
+    "typecheck": "tsc --noEmit"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kaspernj/semantifold.git"
+  },
+  "author": "kasper@diestoeckels.de",
+  "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/kaspernj/semantifold/issues"
+  },
+  "homepage": "https://github.com/kaspernj/semantifold#readme",
+  "dependencies": {
+    "@babel/parser": "^7.28.4",
+    "@babel/types": "^7.28.4",
+    "@jridgewell/gen-mapping": "^0.3.13",
+    "@jridgewell/trace-mapping": "^0.3.31",
+    "@lezer/common": "^1.2.3",
+    "@lezer/java": "^1.1.3",
+    "@ruby/prism": "^1.9.0",
+    "comment-parser": "^1.4.1",
+    "php-parser": "^3.7.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^24.3.0",
+    "@velocious/testing": "0.0.0",
+    "dockerfile-ast": "^0.7.1",
+    "eslint": "^10.0.1",
+    "eslint-plugin-jsdoc": "^64.0.2",
+    "eslint-plugin-jsdoc-inline-type-casts": "https://github.com/kaspernj/eslint-plugin-jsdoc-inline-type-casts/archive/441b6c5ca335a115a75d9f050134357ddb0a61d1.tar.gz",
+    "eslint-plugin-jsdoc-tag-lines": "^1.0.1",
+    "globals": "^17.0.0",
+    "typescript": "^7.0.0",
+    "yaml": "^2.9.0"
+  }
+}