j2py-converter 0.1.0a1__tar.gz

j2py_converter-0.1.0a1/.gitignore

@@ -0,0 +1,17 @@
+.venv/
+.env
+__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+dist/
+*.egg-info/
+.eggs/
+build/
+*.so
+.DS_Store
+.corpus/
+corpus-reports/

j2py_converter-0.1.0a1/CHANGELOG.md

@@ -0,0 +1,132 @@
+# Changelog
+
+All notable changes to j2py will be documented in this file.
+
+The format follows the repository commit types: `feat`, `fix`, `refactor`, `test`,
+`docs`, `chore`, and `adr`.
+
+## Unreleased
+
+No changes yet.
+
+## 0.1.0a1 - 2026-06-11
+
+### Added
+- GitHub Actions corpus workflow (`.github/workflows/corpus.yml`) comparing the pinned
+  Spring sample against the committed baseline on translation/corpus path changes.
+- `j2py analyze` dependency graph and translation-order output for file and directory modes.
+- Skeleton translator tests split under `tests/translate/skeleton/` by concern (#69).
+- ADR 0010: `synchronized(this)` translates to `self._j2py_lock` with `threading.Lock()`
+  initialization in constructors or synthetic `__init__`.
+- Preferred dense Spring + curated-construct corpus baseline workflow:
+  `corpus-spring-dense-check`, `corpus-spring-dense-update-baseline`, and
+  `tests/fixtures/corpus/spring-dense-baseline.json`.
+- Future corpus target for `super.method(...)` receiver calls identified by the dense
+  Spring corpus.
+- Shared `tests/conftest.py` with session `cfg` fixture and fixture path constants.
+- `TranslationDiagnostics.semantic_warning_count` and `rule_coverage` alias documenting
+  that warnings do not reduce node coverage.
+- Strict xfail `FUTURE_TARGETS` for two corpus constructs still below full rule coverage
+  (`AdvancedStreams`, `SuperMethodCalls`).
+- Graduated corpus construct regression tests in `make check` for eight constructs that
+  reach full skeleton coverage (`AdvancedEnum`, `ComplexRecords`, `InterfaceDefaults`,
+  `SealedClasses`, `TextBlocks`, `VarKeyword`, `SwitchFallthrough`, `AnonymousAndInner`).
+- Record declarations (`record_declaration`) in the symbol table: component fields,
+  body methods, inner records, and `is_record` on `ClassSymbol`.
+- `TranslationResult.parse_ok` and `PARSE_ERROR_LLM_SKIP_MSG`: malformed Java with
+  tree-sitter `ERROR`/`MISSING` nodes skips LLM completion and reports `confidence=0.0`.
+
+### Changed
+- Anonymous class instance fields translate to helper-class `__init__` assignments with
+  `self.` field access in methods (#74).
+- Switch fall-through translates to reviewable prefix `elif`/`if` chains with explicit
+  default guards (`elif subject not in (...)` after fall-through blocks) (#73).
+- Local `var` declarations infer Python types from initializers; enhanced-for `var` binds
+  element types from iterable annotations (#72).
+- Prepared the first MIT-licensed PyPI alpha release as distribution `j2py-converter`
+  with import package and CLI name `j2py`.
+- README known gaps refreshed to match graduated targets/corpus constructs and remaining
+  `FUTURE_TARGETS` xfail items (#69).
+- Non-`this` synchronized blocks keep `with <expr>:` but warn that lock semantics need review.
+- LLM system prompt aligned with the `_j2py_lock` instance-monitor pattern.
+- Dependency graph resolves simple type names only when unambiguous; ambiguous `User`-style
+  collisions no longer pick an arbitrary file.
+- `j2py analyze` prints class inventory plus dependency graph and translation order (#69).
+- `TranslationResult.confidence` documented as rule-layer coverage (unchanged after LLM).
+- Agent docs (`AGENTS.md`, `CLAUDE.md`) updated for graduated vs xfail test tiers.
+- Graduated target fixtures (`tests/fixtures/java/targets/`) now run in `make check` and
+  CI; `make test-targets` is reserved for strict `xfail` entries in `FUTURE_TARGETS`.
+- CLI `analyze` reports record types, nested declarations, and parse-error status.
+- CLI translate summaries surface `parse_ok=False` and parse-error warnings.
+- Directory translation aggregates per-file parse-error warnings in `batch.warnings`.
+
+### Added
+- Two-tier overload translation (ADR 0009, issue #44): chained `this(...)`
+  constructor delegation and builder-style forwarding method overloads now merge
+  into default parameters (immutable literals inline; constructed values become
+  `None` sentinels with normalization lines). Overload groups that genuinely
+  dispatch on parameter types emit each Java overload as a same-named def behind
+  a vendored `@overloaded` runtime dispatcher (`j2py_runtime.py`, stdlib-only,
+  written next to translated output by the CLI). The manual-dispatch
+  `NotImplementedError` fallback now only remains for static overload groups and
+  erased-signature collisions (e.g. `int` vs `long`).
+- Java varargs parameters (`Type... name`) now translate to `*name: Type` in
+  method signatures instead of being dropped.
+- Deterministic translation for `instanceof` expressions, `instanceof` pattern
+  variable bindings, cast expressions with review warnings, and bitwise/shift
+  operators including compound bitwise assignment.
+- Block lambdas (`x -> { statements; return v; }`) are now supported deterministically. They are turned into a local nested helper (`_j2py_lambda_N`) emitted near the top of the enclosing method; the helper name is used at the call site. The block body structure is preserved for reviewability.
+- Complex stream pipelines/collectors: extended deterministic support for toSet, basic joining, .distinct(), .sorted() (simple or with key via method ref), and basic groupingBy (via emitted accumulation helpers using defaultdict). Builds on prior block lambda work; many cases now rewrite to clean comps or stdlib helpers (per review feedback favoring itertools/functools where used).
+
+### Fixed
+- Constructor overload merging no longer emits invalid self-referential defaults
+  (`name: str = name`) or raw Java generic types in annotations when a delegating
+  constructor passes its own parameters through alongside constructed values; the
+  pass-through prefix rule in ADR 0009 rejects or correctly composes these.
+- `_stream_item_name`: improved plural stripping with explicit map for common cases ("statuses"→"status", "types"→"type", "classes"→"class" etc.) to avoid "statu"/"addres"/"typ" etc. in stream listcomps.
+- Integer division (`int / int`): now uses `diagnostics.warn()` (visible for review) instead of `record(supported=False)`. Correct `//` output no longer forces LLM or lowers coverage.
+- Lambda/alias context in expressions: added `try/finally` around mutable `TranslationContext` updates (`local_names`, `variable_types`, `expression_aliases`) so exceptions during body translation cannot leak state to callers.
+- Overload merge paths: no longer downgrade `class_field_types` to all `"object"`. Real field types (including collections) are now preserved in the shared implementation body, enabling correct specializations (e.g. list `get`).
+- Removed misleading claim that the `switch_expression` dispatch in `translate_statement` was dead; kept it (with expanded comment) because tree-sitter-java uses the same node type for traditional colon switch *statements*. Added clarifying comments + tests.
+
+### Added (historical)
+
+- Initial deterministic skeleton translator for simple Java classes.
+- Structured rule-layer diagnostics and coverage reporting.
+- Spring corpus scoreboard with a pinned baseline.
+- Roadmap target tests for unsupported Java-to-Python constructs.
+- Dependency-ordered directory translation with package-relative output paths.
+- Config-driven import emission, type maps, collection maps, exception maps, and
+  translation flags.
+- Deterministic translation for common control flow, exception handling, comments,
+  nested type declarations, overload stubs, constructor delegation, and common
+  expression shapes.
+- Deterministic translation for standalone expression lambdas and basic method
+  references, with block lambdas kept as explicit unresolved regions.
+- Deterministic translation for safe traditional switch cases and switch expressions,
+  with fall-through and complex switch blocks left as diagnostics.
+- Deterministic translation for simple stream `map`/`filter`/`toList` pipelines when
+  mapper and predicate expressions are supported.
+- LLM prompt context for project symbols, rule diagnostics, config fingerprints, and
+  validation feedback.
+- On-demand LLM exploration helper for manually inspecting the tree-sitter skeleton,
+  diagnostics, final LLM output, and validation results outside the normal test suite.
+
+### Changed
+
+- Clarified the target-test workflow: current roadmap fixtures now run as graduated
+  deterministic regression checks, while future unsupported targets remain strict xfails.
+- Split skeleton translation into class, statement, expression, diagnostic, and node helper
+  modules.
+- Updated contributor and architecture docs to describe the implemented deterministic
+  visitor layer and the remaining unsupported constructs.
+- Generalized CLI help text for configured LLM usage without changing the Anthropic
+  backend contract.
+
+### Fixed
+
+- Preserved Java `Map.get` missing-key semantics, translated `.equals(...)`, and made
+  integer division and ambiguous `get` calls honest through diagnostics.
+- Preserved Java left-to-right evaluation for string concatenation with leading numeric
+  operands.
+- Removed tracked `.pyc` and `__pycache__` files from version control.

j2py_converter-0.1.0a1/CONTRIBUTING.md

@@ -0,0 +1,121 @@
+# Contributing to j2py
+
+## Setup
+
+```bash
+git clone git@github.com:tomanizer/j2py.git
+cd j2py
+uv sync --locked
+```
+
+Python 3.11 required. `uv` manages the virtualenv automatically.
+
+## Workflow
+
+1. **Branch from `main`**: `git checkout -b feat/my-feature`
+2. **Run checks before committing**: `make check` (lint + typecheck + test)
+3. **Run `make ci-local-pr`** before pushing — this is what CI runs
+4. **Open a PR** using the template — fill every section
+
+### Commit style
+
+```
+<type>: <short imperative summary>
+
+<optional body — why, not what>
+```
+
+Types: `feat` · `fix` · `refactor` · `test` · `docs` · `chore` · `adr`
+
+Examples:
+```
+feat: translate enhanced for-loops to Python for comprehensions
+fix: preserve Optional<T> in nested generic types
+adr: document choice of tree-sitter over javalang (ADR 0002)
+```
+
+## Adding a translation rule
+
+Every new Java construct translation needs:
+
+1. **Java fixture** — `tests/fixtures/java/<Feature>.java`
+2. **Expected Python fixture** — `tests/fixtures/python/<Feature>.py`
+3. **Test** — parametrised entry in `tests/translate/` (or a new test file)
+4. **Implementation** — rule in `j2py/translate/rules/` or `skeleton.py`
+
+The fixture pair is the contract. CI runs exact fixture equality tests in `make check`.
+
+For unsupported but planned Java constructs, add or update a roadmap target test first.
+Graduated target tests live under `tests/targets/` and run in `make check`. Future
+`xfail` roadmap contracts use the `target_translation` marker and run with:
+
+```bash
+make test-targets
+```
+
+Once a target is supported, remove it from `FUTURE_TARGETS` so it runs in the graduated
+target check, or move the behavior into the normal fixture suite. See
+[Translation Target Tests](docs/TRANSLATION_TARGETS.md) for the target-test workflow and
+graduation rules.
+
+For real-corpus progress checks, run the preferred dense Spring + curated-construct
+scoreboard:
+
+```bash
+make corpus-spring-dense-check
+```
+
+See [Spring Corpus Scoreboard](docs/CORPUS_SCOREBOARD.md) for the preferred dense
+baseline, historical lexical baseline, comparison mode, and intentional baseline refresh
+workflow.
+
+## Material changes
+
+A **material change** is any of:
+- Changing how a Java construct is translated (different Python idiom)
+- Adding a new pipeline stage
+- Changing the LLM model or prompt structure
+- Changing the Python output version target
+- Breaking the `translate_file()` public API
+
+Material changes require:
+1. A new ADR in `docs/decisions/` ([template](docs/decisions/0001-record-architecture-decisions.md))
+2. Updated `docs/ARCHITECTURE.md` if the pipeline shape changes
+3. Explicit note in the PR body linking the ADR
+4. A `CHANGELOG.md` entry when the change affects user-visible behavior or project
+   workflow
+
+## PR rules
+
+- One concern per PR — translation rules, refactor, or docs; not all three
+- `Closes #N` in the PR body to auto-close issues (checkboxes in the issue do **not** close it)
+- `make ci-local-pr` must pass before requesting review
+- No version bumps on feature PRs — version is bumped in a dedicated release PR
+
+## Release
+
+Alpha releases are published to PyPI as the `j2py-converter` distribution. The import
+package and console script remain `j2py`; the `j2py` PyPI project name is already owned
+by an unrelated project.
+
+Releases are tagged `vX.Y.Z` on `main`; pre-releases use PEP 440 suffixes such as
+`v0.1.0a1`. Versioning follows [SemVer](https://semver.org/) for stable releases:
+
+- `MAJOR` — breaking change to `translate_file()` API or output format
+- `MINOR` — new Java construct support, new CLI flag
+- `PATCH` — bug fix, doc fix, test improvement
+
+Update `CHANGELOG.md`, `pyproject.toml`, and `j2py/__init__.py` in the release PR.
+Feature and fix PRs should add notes under `## Unreleased`; the release PR moves those
+notes under the tagged version.
+
+Before publishing:
+
+```bash
+make release-check
+```
+
+The release workflow builds the wheel/sdist and publishes through PyPI trusted
+publishing when a GitHub release is published. PyPI trusted publishing is configured for
+repository `tomanizer/j2py`, workflow `.github/workflows/publish.yml`, environment
+`pypi`, and project `j2py-converter`.

j2py_converter-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thomas Haederle
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

j2py_converter-0.1.0a1/Makefile

@@ -0,0 +1,81 @@
+.PHONY: check lint format typecheck test test-behavior test-targets test-llm-e2e test-cov corpus-spring corpus-spring-smoke corpus-spring-update-baseline corpus-spring-dense corpus-spring-dense-check corpus-spring-dense-update-baseline corpus-spring-broad clean ci-local-pr ci-local-governance build dist-check release-check
+
+SPRING_DENSE_BASELINE := tests/fixtures/corpus/spring-dense-baseline.json
+SPRING_DENSE_ARGS := --strategy density --max-loc 250 --min-constructs 5 --include-constructs --baseline $(SPRING_DENSE_BASELINE)
+
+# ── Primary targets ──────────────────────────────────────────────────────────
+
+check: lint typecheck test  ## Run all checks (alias for ci-local-pr)
+
+lint:  ## Lint with ruff
+	uv run --extra dev ruff check j2py/ tests/
+
+format:  ## Format with ruff
+	uv run --extra dev ruff format j2py/ tests/
+
+typecheck:  ## Type-check with mypy (strict)
+	uv run --extra dev mypy j2py/
+
+test:  ## Run test suite
+	uv run --extra dev pytest -m "not behavior and not live_llm"
+
+test-behavior:  ## Run Java/Python behavior-equivalence tests (requires a local JDK)
+	uv run --extra dev pytest tests/behavior -m behavior
+
+test-targets:  ## Run future Java-to-Python roadmap xfail targets only
+	uv run --extra dev pytest tests/targets -m target_translation -rxXs
+
+test-llm-e2e:  ## Run the on-demand live-LLM exploratory test (requires ANTHROPIC_API_KEY)
+	@echo "Running live LLM exploratory test. This is excluded from normal make check."
+	uv run --extra dev pytest -m live_llm tests/llm/test_e2e_llm.py -v -s
+
+test-cov:  ## Run tests with coverage report
+	uv run --extra dev pytest --cov=j2py --cov-report=term-missing --cov-report=xml
+
+corpus-spring:  ## Compare the Spring corpus sample against the committed baseline
+	uv run python scripts/corpus/translate_spring_sample.py --compare-baseline
+
+corpus-spring-smoke:  ## Run a quick 25-file Spring corpus smoke sample without baseline comparison
+	uv run python scripts/corpus/translate_spring_sample.py --limit 25
+
+corpus-spring-update-baseline:  ## Regenerate the committed Spring corpus baseline intentionally
+	uv run python scripts/corpus/translate_spring_sample.py --update-baseline --compare-baseline
+
+corpus-spring-dense:  ## Run the preferred dense Spring + curated-construct corpus without comparing the baseline
+	uv run python scripts/corpus/translate_spring_sample.py $(SPRING_DENSE_ARGS)
+
+corpus-spring-dense-check:  ## Compare the preferred dense Spring + curated-construct corpus against its baseline
+	uv run python scripts/corpus/translate_spring_sample.py $(SPRING_DENSE_ARGS) --compare-baseline --fail-on-regression
+
+corpus-spring-dense-update-baseline:  ## Regenerate the preferred dense Spring + curated-construct corpus baseline intentionally
+	uv run python scripts/corpus/translate_spring_sample.py $(SPRING_DENSE_ARGS) --update-baseline
+
+corpus-spring-broad:  ## Broader + more extensive sample (more modules + curated construct files for the new roadmap items)
+	# Note: does not compare to the default baseline (different sampling parameters)
+	uv run python scripts/corpus/translate_spring_sample.py \
+		--module spring-context/src/main/java \
+		--include-constructs \
+		--limit 150 \
+		--strategy density
+
+# ── CI local presets ─────────────────────────────────────────────────────────
+# These mirror exactly what GitHub Actions runs. If make ci-local-pr passes,
+# CI will pass.
+
+ci-local-pr: check  ## For code/test/docs PRs — lint + typecheck + test
+
+ci-local-governance: check  ## For CI/tooling/dependency PRs — same gates, explicit label
+
+# ── Utility ──────────────────────────────────────────────────────────────────
+
+clean:  ## Remove build artifacts and caches
+	rm -rf dist/ .mypy_cache/ .ruff_cache/ .pytest_cache/ htmlcov/ .coverage coverage.xml corpus-reports/
+	find . -type d -name __pycache__ -not -path './.venv/*' -exec rm -rf {} +
+
+build:  ## Build wheel and sdist
+	uv build
+
+dist-check: build  ## Validate built distributions with twine
+	uv run --extra dev twine check dist/*
+
+release-check: check test-targets test-behavior dist-check  ## Run alpha release readiness checks

j2py_converter-0.1.0a1/PKG-INFO

@@ -0,0 +1,199 @@
+Metadata-Version: 2.4
+Name: j2py-converter
+Version: 0.1.0a1
+Summary: Java to Python source converter with line-level semantic equivalence
+Project-URL: Homepage, https://github.com/tomanizer/j2py
+Project-URL: Repository, https://github.com/tomanizer/j2py
+Project-URL: Issues, https://github.com/tomanizer/j2py/issues
+Project-URL: Changelog, https://github.com/tomanizer/j2py/blob/main/CHANGELOG.md
+Author-email: Thomas Haederle <thomas.haederle@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: java,python,source-conversion,translation,tree-sitter
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Java
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: anthropic>=0.30
+Requires-Dist: diskcache>=5.6
+Requires-Dist: networkx>=3.3
+Requires-Dist: pydantic>=2.7
+Requires-Dist: rich>=13.7
+Requires-Dist: tenacity>=8.3
+Requires-Dist: tree-sitter-java>=0.23
+Requires-Dist: tree-sitter>=0.23
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest-snapshot>=0.9; extra == 'dev'
+Requires-Dist: pytest>=8.2; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# j2py
+
+j2py converts Java source to reviewable Python with line-level structural
+correspondence. The goal is not a fully idiomatic rewrite; the goal is Python that a
+reviewer can compare against the original Java side by side.
+
+## Current Status
+
+j2py is a rule-development and measurement harness for Java-to-Python translation. It is
+not yet a production Spring porting tool.
+
+Current deterministic rule support includes:
+
+- tree-sitter Java parsing and symbol extraction
+- class, nested class, basic local/anonymous class helpers, interface,
+  basic and constructor-backed enum, and record skeletons
+- interface abstract methods, default methods, and static methods
+- fields, constructors, methods, and overloads: chained constructor delegation and
+  builder-style forwarding merge into default parameters; type-dispatch overload
+  groups emit same-named defs behind a vendored `@overloaded` runtime dispatcher
+  (ADR 0009)
+- common expressions: literals, identifiers, field access, arrays, class literals,
+  assignments, updates, ternaries, null checks, common collection calls, and string concat
+- common stream pipelines: `map`, `filter`, `distinct`, `sorted`, simple collectors
+  such as `toList`, `toSet`, `joining`, basic `groupingBy`/`toMap`, and supported
+  block lambdas
+- control flow: `if`/`else`, enhanced and classic `for`, `while`, `do while`,
+  safe `switch` forms, `try`/`catch`/`finally`, `throw`, `break`, and `continue`
+- configured import emission, naming policy, type maps, exception maps, and comment flags
+- dependency-ordered directory translation
+- structured diagnostics, confidence, default validation, post-LLM structural
+  verification, and optional Anthropic completion for partial translations
+- side-by-side Java/Python review through the `j2py compare` CLI command
+
+Known gaps include:
+
+- two corpus constructs still tracked as strict xfail targets: advanced stream collectors
+  and long chains (`AdvancedStreams`), and `super.method(...)` receiver calls
+  (`SuperMethodCalls`)
+- overload groups whose erased Python signatures collide (e.g. `int` vs `long`)
+  and static-method overload groups still fall back to manual-dispatch TODOs
+- enum constant class bodies, complex enum static initialization, and annotation semantics
+- behavioral equivalence testing between Java and Python
+- framework semantics such as Spring dependency injection or Hibernate mappings
+
+Graduated in `make check` (no longer listed as gaps): common switch forms, interface
+defaults/statics, text blocks, sealed classes, records, instance `synchronized(this)`,
+local `var` inference, switch fall-through, and anonymous class instance fields.
+
+## Quick Start
+
+Install the alpha from PyPI:
+
+```bash
+pip install --pre j2py-converter
+j2py --help
+```
+
+The PyPI distribution is `j2py-converter`; the import package and console command remain
+`j2py`.
+
+For local development:
+
+```bash
+uv sync --locked
+make check
+```
+
+Translate a fixture without LLM completion:
+
+```bash
+uv run j2py translate tests/fixtures/java/HelloWorld.java --no-llm --no-validate --dry-run
+```
+
+Translate a directory in dependency order:
+
+```bash
+uv run j2py translate path/to/java/root --output translated_py --no-llm
+```
+
+Open a side-by-side Java/Python diff in VS Code, generating the Python file first if
+needed:
+
+```bash
+uv run j2py compare tests/fixtures/java/HelloWorld.java --no-llm
+```
+
+Print the compare paths without opening an editor:
+
+```bash
+uv run j2py compare tests/fixtures/java/HelloWorld.java --no-open --no-llm
+```
+
+Use LLM completion only when `ANTHROPIC_API_KEY` is set:
+
+```bash
+ANTHROPIC_API_KEY=... uv run j2py translate SomeClass.java
+```
+
+## Quality Gates
+
+```bash
+make check         # ruff + mypy strict + normal pytest suite (excludes behavior, live_llm)
+make test-behavior # Java/Python stdout/stderr/exit-code equivalence tests (requires a JDK)
+make test-targets  # future xfail roadmap targets only (graduated targets run in make check)
+make release-check # alpha release gate: check + targets + behavior + distribution check
+make corpus-spring-dense-check # preferred Spring + curated-construct corpus comparison
+make corpus-spring # historical lexical Spring-only corpus comparison
+
+# Corpus modes:
+make corpus-spring-dense  # preferred density-based Spring + curated-construct sample
+make corpus-spring-broad  # extra modules + curated constructs/ mini-corpus
+
+# On-demand only (requires ANTHROPIC_API_KEY):
+make test-llm-e2e  # exploratory live-LLM test of current skeleton quality
+# or: ANTHROPIC_API_KEY=... uv run pytest -m live_llm tests/llm/test_e2e_llm.py -v -s
+```
+
+The preferred dense corpus baseline includes Spring files plus curated non-Spring
+construct fixtures and is stored at `tests/fixtures/corpus/spring-dense-baseline.json`.
+
+The historical lexical Spring-only baseline is:
+
+- parse success: 100.00%
+- generated Python syntax success: 93.00%
+- average skeleton coverage: 94.71% across 92 coverage-bearing files
+- full-coverage files: 65 of 92 coverage-bearing files
+- files with unhandled constructs: 27 of 100
+- files below 80% coverage: 4 of 92 coverage-bearing files
+- sample size: 100 files with committed per-file failure metrics
+
+See [docs/CORPUS_SCOREBOARD.md](docs/CORPUS_SCOREBOARD.md) and
+[docs/TRANSLATION_TARGETS.md](docs/TRANSLATION_TARGETS.md) for the implementation
+workflow.
+
+## Adding Translation Support
+
+1. Add or update a target fixture if the construct is not yet supported.
+2. Implement the smallest deterministic rule in `j2py/translate/`.
+3. Graduate the behavior into normal tests once it passes.
+4. Run `make check`, `make test-targets`, and `make corpus-spring-dense-check`.
+5. Update the dense corpus baseline only when the comparison has no regressions.
+
+Material translation policy changes should get an ADR under `docs/decisions/`.
+
+## Alpha Release Notes
+
+`j2py-converter` is published as an alpha package. Expect incomplete Java construct
+coverage, diagnostics for unsupported regions, and non-production behavior on large
+framework-heavy codebases. The existing `j2py` PyPI name is owned by an unrelated
+Jupyter notebook converter, so this project uses the distinct distribution name
+`j2py-converter`.
+
+See [docs/RELEASING.md](docs/RELEASING.md) for the alpha release checklist.
+
+## License
+
+MIT. See [LICENSE](LICENSE).