Skip to content

Latest commit

 

History

History
158 lines (116 loc) · 6.14 KB

AGENTS.md

File metadata and controls

158 lines (116 loc) · 6.14 KB

PerlOnJava Agent Guidelines

⚠️⚠️⚠️ CRITICAL WARNING: NEVER USE git stash ⚠️⚠️⚠️

╔══════════════════════════════════════════════════════════════════════════════╗
║                                                                              ║
║   DANGER: DO NOT USE `git stash` DURING ACTIVE WORK!                        ║
║                                                                              ║
║   Changes can be SILENTLY LOST when using git stash/stash pop.              ║
║   This has caused loss of completed work during debugging sessions.         ║
║                                                                              ║
║   INSTEAD:                                                                   ║
║   - Commit your changes to a WIP branch before testing alternatives         ║
║   - Use `git diff > backup.patch` to save uncommitted changes               ║
║   - Never stash to "temporarily" revert - you WILL lose work                ║
║                                                                              ║
╚══════════════════════════════════════════════════════════════════════════════╝

Project Rules

Progress Tracking for Multi-Phase Work

When working on multi-phase projects (like the Shared AST Transformer), always update the design document when completing a phase:

  1. Mark the phase as completed with date
  2. Document what was done (files changed, key decisions)
  3. Update "Next Steps" section so the user knows where to resume
  4. Note any blockers or open questions

Example format at the end of a design doc:

## Progress Tracking

### Current Status: Phase 2 in progress

### Completed Phases
- [x] Phase 1: Infrastructure (2024-03-09)
  - Created ASTAnnotation class
  - Added typed fields to AbstractNode
  - Files: AbstractNode.java, ASTAnnotation.java

### Next Steps
1. Implement VariableResolver visitor
2. Add closure capture detection
3. Run differential tests

### Open Questions
- Should we cache lvalue analysis results?

Design Documents

  • Design documents live in dev/design/
  • Each major feature should have its own design doc
  • Keep docs updated as implementation progresses
  • Reference related docs and skills at the end

Testing

ALWAYS use make commands. NEVER use raw mvn/gradlew commands.

Command What it does
make Build + run all unit tests (use before committing)
make dev Build only, skip tests (for quick iteration during debugging)
  • For interpreter changes, test with both backends: 
    ./jperl -e 'code'           # JVM backend
./jperl --int -e 'code'     # Interpreter

Git Workflow

IMPORTANT: Never push directly to master. Always use feature branches and PRs.

  1. Create a feature branch before making changes:

    git checkout -b feature/descriptive-name

  2. Make commits on the feature branch with clear messages

  3. Push the feature branch and create a PR:

    git push origin feature/descriptive-name
gh pr create --title "Title" --body "Description"

  4. Wait for review before merging

Commits

  • Reference the design doc or issue in commit messages when relevant
  • Use conventional commit format when possible

Available Skills

See .cognition/skills/ for specialized debugging and development skills:

  • debug-perlonjava - General debugging
  • interpreter-parity - JVM vs interpreter parity issues
  • debug-exiftool - ExifTool test debugging
  • profile-perlonjava - Performance profiling

Regression Tracking (feature/defer-blocks branch)

Summary

All reported regressions have been investigated. The issues fall into two categories:

  1. Fixed in this branch: goto-related issues
  2. Pre-existing on master: MethodHandle conversion errors, regex octal escape parsing

Regression Status

Test Status Details
op/die_goto.t FIXED (5/5) goto &sub in $SIG{__DIE__} handlers now works
uni/goto.t FIXED (2/4) Tests 1-2 pass (goto &{expr}). Tests 3-4 fail due to pre-existing regex octal escape bug
op/bop.t Pre-existing MethodHandle conversion error - fails on master too
op/warn.t Pre-existing MethodHandle conversion error - fails on master too
re/subst.t Pre-existing MethodHandle conversion error - fails on master too
re/pat_rt_report.t Pre-existing MethodHandle conversion error - fails on master too
lib/croak.t Pre-existing class feature incomplete

Fixes Applied in This Branch

  1. EmitControlFlow.java: Added handleGotoSubroutineBlock() for goto &{expr} tail call support
  2. CompileOperator.java: Added goto &{expr} support to bytecode interpreter
  3. RuntimeControlFlowList.java: Added validation for undefined subroutines in tail calls
  4. RuntimeCode.java: Added gotoErrorPrefix() for "Goto undefined subroutine" error messages
  5. CompileAssignment.java: Added vec lvalue support for interpreter
  6. OpcodeHandlerExtended.java: Fixed |= and ^= to use polymorphic bitwiseOr/bitwiseXor
  7. WarnDie.java: Added TAILCALL trampoline for goto &sub in $SIG{__DIE__} handlers

Pre-existing Issues (on master too)

  • MethodHandle conversion errors: Affects op/warn.t, re/subst.t, re/pat_rt_report.t, op/bop.t
  • Regex octal escapes: \345 in patterns is parsed as backreference \3 + 45
  • op/bop.t: new version ~$_ crashes in Version.java
  • String bitwise ops: Interpreter uses numeric ops instead of string ops

How to Check Regressions

# Run specific test
cd perl5_t/t && ../../jperl <test>.t

# Count passing tests
../../jperl <test>.t 2>&1 | grep "^ok" | wc -l

# Check for interpreter fallback
JPERL_SHOW_FALLBACK=1 ../../jperl <test>.t 2>&1 | grep -i fallback