diff --git a/.cognition/skills/debug-exiftool/SKILL.md b/.cognition/skills/debug-exiftool/SKILL.md index c424b830c..49bc9d4e3 100644 --- a/.cognition/skills/debug-exiftool/SKILL.md +++ b/.cognition/skills/debug-exiftool/SKILL.md @@ -11,6 +11,17 @@ triggers: You are debugging failures in the Image::ExifTool test suite running under PerlOnJava (a Perl-to-JVM compiler/interpreter). Failures typically stem from missing Perl features or subtle behavior differences in PerlOnJava, not bugs in ExifTool itself. +## Git Workflow + +**IMPORTANT: Never push directly to master. Always use feature branches and PRs.** + +```bash +git checkout -b fix/exiftool-issue-name +# ... make changes ... +git push origin fix/exiftool-issue-name +gh pr create --title "Fix: description" --body "Details" +``` + ## Project Layout - **PerlOnJava source**: `src/main/java/org/perlonjava/` (compiler, bytecode interpreter, runtime) diff --git a/.cognition/skills/debug-perlonjava/SKILL.md b/.cognition/skills/debug-perlonjava/SKILL.md index 2c4652a07..7c26011e2 100644 --- a/.cognition/skills/debug-perlonjava/SKILL.md +++ b/.cognition/skills/debug-perlonjava/SKILL.md @@ -11,6 +11,17 @@ triggers: You are debugging failures in PerlOnJava, a Perl-to-JVM compiler with a bytecode interpreter fallback. This skill covers debugging workflows for test failures, regressions, and parity issues between backends. +## Git Workflow + +**IMPORTANT: Never push directly to master. Always use feature branches and PRs.** + +```bash +git checkout -b fix/descriptive-name +# ... make changes ... +git push origin fix/descriptive-name +gh pr create --title "Fix: description" --body "Details" +``` + ## Project Layout - **PerlOnJava source**: `src/main/java/org/perlonjava/` (compiler, bytecode interpreter, runtime) diff --git a/.cognition/skills/debugger/SKILL.md b/.cognition/skills/debugger/SKILL.md index c7912da1e..e76443d71 100644 --- a/.cognition/skills/debugger/SKILL.md +++ b/.cognition/skills/debugger/SKILL.md @@ -4,6 +4,17 @@ Continue implementing the Perl debugger (`-d` flag) for PerlOnJava. The debugger uses DEBUG opcodes injected at statement boundaries in the bytecode interpreter. +## Git Workflow + +**IMPORTANT: Never push directly to master. Always use feature branches and PRs.** + +```bash +git checkout -b feature/debugger-improvement +# ... make changes ... +git push origin feature/debugger-improvement +gh pr create --title "Debugger: description" --body "Details" +``` + ## Key Documentation ### Design Document @@ -36,7 +47,8 @@ Continue implementing the Perl debugger (`-d` flag) for PerlOnJava. The debugger | Command | Description | |---------|-------------| | `n` | Next (step over) | -| `s` | Step into | +| `s` | Step into (shows subroutine name, e.g., `main::foo(file:line)`) | +| `r` | Return (step out of current subroutine) | | `c [line]` | Continue (optionally to line) | | `q` | Quit | | `l [range]` | List source (`l 10-20` or `l 15`) | @@ -44,6 +56,9 @@ Continue implementing the Perl debugger (`-d` flag) for PerlOnJava. The debugger | `b [line]` | Set breakpoint | | `B [line]` | Delete breakpoint (`B *` = all) | | `L` | List breakpoints | +| `T` | Stack trace | +| `p expr` | Print expression (supports lexical variables) | +| `x expr` | Dump expression with Data::Dumper (supports lexical variables) | | `h` | Help | ## Comparison with System Perl Debugger @@ -65,8 +80,8 @@ Tested side-by-side with `perl -d`: | Loading message | None | Shows perl5db.pl version | OK (intentional) | ### Known Differences to Address -1. **Package prefix**: Add `main::` (or current package) to location display -2. **Prompt counter**: Change to 1-indexed (`DB<1>`) to match Perl +1. ~~**Package prefix**: Add `main::` (or current package) to location display~~ **DONE** +2. ~~**Prompt counter**: Change to 1-indexed (`DB<1>`) to match Perl~~ **DONE** 3. **`l` command**: Perl shows current line, subsequent `l` shows next 10 lines ## Source Files @@ -85,23 +100,26 @@ Tested side-by-side with `perl -d`: ## Next Steps (from design doc) -### Phase 2: Source Line Support (partially done) +### Phase 2: Source Line Support (mostly done) - [x] Store source lines during parsing - [x] Skip compile-time statements (use/no) +- [x] Display subroutine names when stepping (e.g., `main::foo(file:line)`) - [ ] Track breakable lines (statements vs comments) - [ ] Implement `@{"_<$filename"}` magical array - [ ] Implement `%{"_<$filename"}` for breakpoint storage -### Phase 3: Debug Variables -- [ ] `$DB::single`, `$DB::trace`, `$DB::signal` as tied variables -- [ ] `$DB::filename`, `$DB::line` (currently Java-only) -- [ ] `@DB::args` support in `caller()` -- [ ] `%DB::sub` for subroutine location tracking - -### Phase 4: Perl Expression Evaluation -- [ ] `p expr` - print expression value -- [ ] `x expr` - dump expression (Data::Dumper style) -- [ ] General expression evaluation in debugger context +### Phase 3: Debug Variables (partially done) +- [x] `$DB::single`, `$DB::trace`, `$DB::signal` synced from Java +- [x] `$DB::filename`, `$DB::line` set by DEBUG opcode +- [x] `@DB::args` support in `caller()` +- [x] `%DB::sub` for subroutine location tracking +- [ ] Make debug variables fully tied (Perl can modify them) + +### Phase 4: Perl Expression Evaluation (DONE) +- [x] `p expr` - print expression value +- [x] `x expr` - dump expression (Data::Dumper style) +- [x] Lexical variable access in debugger expressions +- [x] Registry deduplication to minimize memory usage ### Phase 5: perl5db.pl Compatibility - [ ] Inject `BEGIN { require 'perl5db.pl' }` when `-d` used diff --git a/.cognition/skills/interpreter-parity/SKILL.md b/.cognition/skills/interpreter-parity/SKILL.md index b989b4a80..58fffbedc 100644 --- a/.cognition/skills/interpreter-parity/SKILL.md +++ b/.cognition/skills/interpreter-parity/SKILL.md @@ -11,6 +11,17 @@ triggers: You are fixing cases where PerlOnJava's bytecode interpreter produces different results than the JVM compiler backend. The interpreter should be a drop-in replacement — same parsing, same runtime APIs, different execution engine. +## Git Workflow + +**IMPORTANT: Never push directly to master. Always use feature branches and PRs.** + +```bash +git checkout -b fix/interpreter-issue-name +# ... make changes ... +git push origin fix/interpreter-issue-name +gh pr create --title "Fix interpreter: description" --body "Details" +``` + ## Project Layout - **PerlOnJava source**: `src/main/java/org/perlonjava/` (compiler, bytecode interpreter, runtime) diff --git a/.cognition/skills/profile-perlonjava/SKILL.md b/.cognition/skills/profile-perlonjava/SKILL.md index d1a7a1665..3fd9a2e24 100644 --- a/.cognition/skills/profile-perlonjava/SKILL.md +++ b/.cognition/skills/profile-perlonjava/SKILL.md @@ -2,6 +2,17 @@ Profile and optimize PerlOnJava runtime performance using Java Flight Recorder. +## Git Workflow + +**IMPORTANT: Never push directly to master. Always use feature branches and PRs.** + +```bash +git checkout -b perf/optimization-name +# ... make changes ... +git push origin perf/optimization-name +gh pr create --title "Perf: description" --body "Details" +``` + ## When to Use - Investigating performance bottlenecks in Perl scripts running on PerlOnJava diff --git a/AGENTS.md b/AGENTS.md index 7a6774448..27a449f34 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -49,6 +49,25 @@ Example format at the end of a design doc: java -jar target/perlonjava.jar --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: + ```bash + 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: + ```bash + 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