Contributing

Contributing and tests

Build

npm i lix
npx lix download
npx haxe build.hxml

npx haxe run.hxml also builds run.n, which haxelib run ax4 needs when the clone is installed with haxelib dev ax4 ..

Run converter on test workspace

java -jar converter.jar tests/config.json

Compatibility tests

npx haxe test-compat.hxml

compat/ is the runtime compatibility layer used by converted projects. compat-test/ is its test suite, run on JS (Node), C++ (hxcpp) and Flash (test.swf, opened with the system's Flash Player). When you change anything in compat/, update tests in compat-test/ and run npx haxe test-compat.hxml.

Test case conventions

• Put AS3 input in tests/src/.
• Generated Haxe goes to tests/out/.
• Every test source file should explain case and expected behavior in comments.
• Filter tests naming convention:
  • TestFilter{FilterName}.as
  • Example: RewriteAs.hx -> TestFilterRewriteAs.as
• Other tests can use Test{Feature}.as.

Current state:

• Most converter tests are still manual/inspection-based (tests/src -> run converter -> inspect tests/out).

Future direction:

• Move toward automated checks (expected output diff, compile smoke tests, and execution tests where relevant) so regressions are caught in CI.

Error coverage policy

• Non-blocking reportError paths should be intentionally covered by tests.
• Do not trigger throwError in normal conversion/regression suites because it aborts the converter.
• Add dedicated negative tests for throwError paths only when you are explicitly working on that specific failure mode.
• If a reportError path effectively throws in practice, treat it as a throw case.

Suggested workflow for a bug fix

1. Reproduce with smallest possible AS3 sample under tests/src/.
2. Run converter and inspect tests/out/.
3. Implement filter/typer/gen fix.
4. Re-run converter.
5. Run npx haxe test-compat.hxml if compat/runtime was touched.

Auditing compat calls in a converted project

tools/CompatAudit.hx counts the ASCompat/ASAny calls of a converted project by static argument types, so coercions on already-typed values (toInt(Int), toNumber(Float)...) show up as converter work. Usage is in its header comment.

Releasing

Set version and releasenote in haxelib.json, commit, then push a matching vX.Y.Z tag. The Release workflow rebuilds converter.jar and run.n, converts the test workspace, submits the package to lib.haxe.org (repository secret HAXELIB_PASSWORD) and attaches it to a GitHub release. Running the workflow by hand builds the package without publishing it.