@llm4ts/shell 2.36.0 → 2.37.0

package/kits/port/README.md

@@ -26,9 +26,10 @@ another pair copies one of these and replaces the rulebook, the pitfall card,
 `target:`, the diagnostics command, the ledger regex and the two test
 commands.
 
-| Pack       | Source → target                 | Diagnostics                         | Ledger units             |
-| ---------- | ------------------------------- | ----------------------------------- | ------------------------ |
-| `zig-rust` | Zig → Rust                      | `cargo check --message-format=json` | pointer and slice fields |
-| `scala-ts` | Scala 3 / ZIO 2 → TS / Effect 4 | `tsc --pretty false`                | classes, objects, traits |
+| Pack                    | Source → target                                                                                          | Diagnostics                             | Ledger units                      |
+| ----------------------- | -------------------------------------------------------------------------------------------------------- | --------------------------------------- | --------------------------------- |
+| `zig-rust`              | Zig → Rust                                                                                               | `cargo check --message-format=json`     | pointer and slice fields          |
+| `scala-ts`              | Scala 3 / ZIO 2 → TS / Effect 4                                                                          | `tsc --pretty false`                    | classes, objects, traits          |
+| `cobol-springboot-port` | COBOL → Java / Spring Boot 3 (file by file; the clean-room sibling is `mainframe-java/cobol-springboot`) | `mvn -q -B -DskipTests compile` (javac) | level-01 records, FDs, paragraphs |
 
 `## Diagnostics` reads `json` (one object per line), `cargo` (`--message-format=json`), `tsc` (`--pretty false`) or `javac` (javac's and Maven's error lines, the Maven module as the unit).

package/kits/port/packs/cobol-springboot-port/pack.md

@@ -0,0 +1,48 @@
+# Pack: cobol-springboot-port
+
+source: cobol
+sources: .*\.(cbl|cob|cpy|CBL|COB|CPY)$
+exclude: (^|/)(target|build|\.git|node_modules)/
+target: src/main/java/legacy/{{dir}}/{{base}}.java
+comment: //
+specs-dir: docs/port
+features-dir: docs/port/features
+
+## Gates
+
+- compile: mvn -q -B -DskipTests compile
+- test: mvn -q -B test
+
+## Diagnostics
+
+- command: mvn -q -B -DskipTests compile
+- format: javac
+
+## Ledger
+
+- unit: ^\s{0,7}(?:01|77)\s+([A-Z][A-Z0-9-]*)|^\s{0,7}FD\s+([A-Z][A-Z0-9-]*)|^\s{0,7}([A-Z0-9][A-Z0-9-]*)\s*(?:SECTION)?\.\s*$
+- classes: RECORD, FILE, PARAGRAPH, SQL, CICS, COPYBOOK, REPORT, UTIL, UNKNOWN
+- question: What does this COBOL unit become in a Spring Boot port? RECORD (a level-01 or 77 data item → a Java record or class with BigDecimal for numerics), FILE (an FD / SELECT → a JPA entity with a Spring Data repository, or a reader for a flat file), PARAGRAPH (a paragraph or section → a private method on the program's @Service), SQL (a paragraph whose body is EXEC SQL → a repository query), CICS (EXEC CICS send/receive → a controller endpoint or a service boundary), COPYBOOK (a shared record → a class in the copybook package, ported once), REPORT (a print layout → a formatter), UTIL (a pure routine).
+
+## Differential
+
+- tests: ^tests/.*\.(txt|dat|json)$
+- legacy: scripts/legacy-run.sh {{file}}
+- target: scripts/target-run.sh {{file}}
+- timeout: 120
+
+## Audit
+
+- dimensions: data division and record layouts, PIC clauses and numeric semantics, files and embedded SQL, control flow (PERFORM, GO TO, fall-through), copybooks and shared records, batch versus online (CICS), transaction boundaries, test idioms, what not to translate
+
+## Review rules
+
+A `double` or `float` holding money, a quantity or any `COMP-3` field is a
+finding: numerics are `BigDecimal` with the PIC's scale, or `long` for
+unsigned integer PICs. A `MOVE` whose truncation or padding the source relied
+on must be written out, not assumed. `GO TO` is flattened into structured
+control flow with a `// PORTED: GO TO` note, never a `while (true)` with a
+state variable unless the source was a state machine. Every file and SQL
+access sits behind a Spring Data repository or a dedicated reader; every
+program that commits has one `@Transactional` boundary. A paragraph the
+source has that the draft lacks is a finding.

package/kits/port/packs/cobol-springboot-port/patterns/pitfalls-cobol-springboot-port.md

@@ -0,0 +1,36 @@
+---
+title: COBOL → Java/Spring Boot pitfalls — alike on the page, different at runtime
+matches: .
+tags: port, cobol, java, spring-boot
+---
+1. **Decimal scale.** `PIC S9(7)V99 COMP-3` has an implied point: `1234567.89`
+   is stored as nine digits. A `double` loses cents; a `BigDecimal` without
+   `setScale(2)` prints `1234567.9`.
+2. **Truncation on MOVE.** Moving `PIC X(10)` into `PIC X(5)` keeps the left
+   five characters; moving `PIC 9(5)` into `PIC 9(3)` keeps the right three
+   digits. Java assignment keeps everything.
+3. **Padding.** An alphanumeric field is space-padded to its width, so
+   `"ABC" = "ABC  "` is true in COBOL and false in Java. Trim or pad at the
+   boundary, in one place.
+4. **Signed overpunch.** `PIC S9(3)` in display format carries the sign in
+   the last byte (`12}` is `-120`). Parse it; never `Long.parseLong` the raw
+   bytes.
+5. **PERFORM THRU and fall-through.** Control falls into the next paragraph
+   unless something stops it; a `PERFORM A THRU C` runs `B` too. A method per
+   paragraph needs the range written out.
+6. **GO TO out of a PERFORM.** The paragraph's exit point moves. Flatten with
+   care, and say which exit the source used.
+7. **REDEFINES.** Two layouts over the same bytes; writing one view changes
+   the other. Two Java fields are two values; make the conversion explicit.
+8. **OCCURS DEPENDING ON.** The table's length is another field's value at
+   that moment; a fixed array hides out-of-range reads the source tolerated.
+9. **88-levels and VALUE.** A condition name tests the parent's current
+   value; `SET name TO TRUE` writes the first `VALUE`. Keep both directions.
+10. **Zero-based indexing.** COBOL subscripts start at 1. Every `OCCURS`
+    access shifts by one.
+11. **ROUNDED and ON SIZE ERROR.** `COMPUTE` truncates by default and
+    rounds only with `ROUNDED`; `RoundingMode.HALF_UP` is not the default.
+12. **Dates.** `YYMMDD` with a century window, `ACCEPT FROM DATE` in local
+    time: pin the rule and the clock.
+13. **Sequential file state.** `READ ... AT END` and `FILE STATUS` codes are
+    the control flow; a reader that throws on end-of-file changes it.

package/kits/port/packs/cobol-springboot-port/prompts/porting.md

@@ -0,0 +1,92 @@
+You are translating one COBOL source unit (a program or a copybook) to Java
+on Spring Boot 3. Read this whole document before writing any code. The first
+pass is a **draft** `.java` at the path the flow gives you, that captures the
+logic faithfully; it does **not** need to compile. The compile pass makes it
+compile module by module.
+
+## Ground rules
+
+- Same unit, same names, same order. The public class is named exactly as
+  the file the flow asked for (Java requires it); paragraphs become private
+  methods in the order they appear, named in camelCase after the paragraph
+  (`2000-READ-INPUT` → `readInput2000`, the number kept as a suffix so the
+  reviewer can diff the two files side by side). Data items keep their names
+  in camelCase (`WS-TOTAL-AMT` → `wsTotalAmt`).
+- A program is one `@Service` bean. Its `PROCEDURE DIVISION` is a public
+  `run(...)` method whose parameters are the `ACCEPT`ed values and the
+  `LINKAGE SECTION` items; its `WORKING-STORAGE` becomes fields on a private
+  state class created per run, never static fields.
+- A copybook is one class in the `legacy.copybook` package, ported once and
+  imported by every program that `COPY`s it. Do not inline it.
+- Numerics are exact. `PIC S9(7)V99 COMP-3` is `BigDecimal` with scale 2;
+  `PIC 9(5)` is `long`; `PIC X(n)` is `String` with the width recorded in a
+  comment. Money is never `double`.
+- Files and SQL are repositories. An `FD` with `SELECT ... ASSIGN` becomes a
+  JPA `@Entity` plus a Spring Data repository when the file is a keyed VSAM
+  or DB table, or a dedicated reader class for a sequential flat file.
+  `EXEC SQL` becomes a repository method; the host variables are its
+  parameters. One `@Transactional` on `run` where the program `COMMIT`s at
+  the end; explicit boundaries where it commits mid-way.
+- `EXEC CICS` is the online boundary: `SEND MAP` / `RECEIVE MAP` become a
+  request and response record on a `@RestController` that calls the service;
+  `LINK` / `XCTL` become a call to the other program's service bean.
+- `DISPLAY` is a logger call at `info`; `DISPLAY` of an error is `warn`.
+  `ACCEPT FROM DATE` is `LocalDate.now(clock)` with an injected `Clock`.
+  `STOP RUN` is a `return`; `GOBACK` is a `return` from the program method.
+- Leave `// TODO(port): <reason>` for anything you cannot translate
+  confidently. Do not guess.
+- Do not translate JCL, compile options, SORT control cards or `IDENTIFICATION
+  DIVISION` metadata; note them as `// SKIPPED(port): <what>`.
+
+## Type map
+
+| COBOL                              | Java / Spring Boot                                  |
+| ---------------------------------- | --------------------------------------------------- |
+| `PIC X(n)`                         | `String` (width `n` noted; pad or trim on `MOVE`)   |
+| `PIC 9(n)`                         | `long` (`int` when `n` ≤ 9 and the source never exceeds it) |
+| `PIC S9(n)V9(m)`, `COMP-3`         | `BigDecimal` with scale `m`, `RoundingMode.DOWN` unless `ROUNDED` |
+| `COMP` / `BINARY`                  | `int` or `long` by the PIC                          |
+| level-01 record                    | a `record` when read-only after construction, else a class |
+| `OCCURS n`                         | an array or `List` sized `n`; `OCCURS DEPENDING ON` → `List` |
+| `REDEFINES`                        | a second view class with explicit conversion methods |
+| 88-level condition name            | a `boolean` method on the owning record (`isActive()`) |
+| `FD` + `SELECT`                    | `@Entity` + `JpaRepository`, or a flat-file reader   |
+| `EXEC SQL`                         | a repository method or `JdbcTemplate` call           |
+| `EXEC CICS SEND/RECEIVE MAP`       | `@RestController` request/response records           |
+| `CALL 'PROG' USING ...`            | a call to `Prog.run(...)` on the injected bean       |
+| `PERFORM para`                     | a method call                                        |
+| `PERFORM para THRU other`          | calls to each paragraph in source order, in a method named after the range |
+| `PERFORM ... UNTIL cond`           | `while (!cond) { … }` (test before) or `do { … } while` (`WITH TEST AFTER`) |
+| `PERFORM VARYING`                  | a `for` loop                                          |
+| `EVALUATE`                         | `switch` with pattern matching, or an `if` chain for `EVALUATE TRUE` |
+| `GO TO`                            | structured flow with a `// PORTED: GO TO` note        |
+| `STRING` / `UNSTRING`              | `StringBuilder` / `split` with the delimiters written out |
+| `INSPECT ... TALLYING/REPLACING`   | explicit counting / `replace`                          |
+| `SORT` / `MERGE`                   | `Comparator` on a `List`, or a stream `sorted`         |
+| `DISPLAY` / `ACCEPT`               | `log.info` / a method parameter                        |
+
+## Idiom map
+
+- A `MOVE` between items of different widths truncates on the right for
+  alphanumerics and on the left for numerics; write the truncation out
+  (`substring`, `remainder`) where the source relies on it, and say so.
+- `ON SIZE ERROR` is an explicit range check before the assignment.
+- `ADD 1 TO WS-COUNT` is `wsCount++` only when the PIC cannot overflow;
+  otherwise the modulus the PIC implies.
+- A paragraph that is both `PERFORM`ed and fallen into is split: the
+  fall-through becomes an explicit call at the end of the preceding method.
+- Dates `PIC 9(6)` `YYMMDD` become `LocalDate` with the century rule the
+  program used, written in one place.
+- `FILE STATUS` checks become typed exceptions on the reader or repository.
+
+## Output format
+
+End the file with the trailer the flow reads:
+
+```java
+// PORT STATUS
+// source: <path>.cbl
+// confidence: high | medium | low
+// todos: <count of TODO(port)>
+// notes: <one line>
+```

package/kits/port/packs/cobol-springboot-port/reviewers/spring-fidelity.md

@@ -0,0 +1,15 @@
+---
+files: \.java$
+---
+Review a Java draft against the rulebook as a port reviewer would, with the
+COBOL source in mind: the diff is the draft. Report as findings: a paragraph,
+data item or 88-level the source has that the draft lacks; a `double` or
+`float` holding a `COMP-3`, money or quantity field; a `BigDecimal` whose
+scale differs from the PIC; a `MOVE` truncation or padding the source relied
+on that the draft assumes away; a `GO TO` turned into a state variable loop
+when the flow was structured; a `PERFORM THRU` range that skips a paragraph;
+file or SQL access outside a repository or reader; a program that commits
+with no `@Transactional` boundary; `WORKING-STORAGE` turned into static
+fields; a copybook inlined instead of imported; a guessed translation where a
+`TODO(port)` was honest. Do not report imports or beans that cannot resolve
+yet: the compile pass owns those.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llm4ts/shell",
-  "version": "2.36.0",
+  "version": "2.37.0",
   "description": "Interactive shell and CLI for llm4ts: flow discovery, run-a-flow, and view",
   "license": "MIT",
   "type": "module",
@@ -52,9 +52,9 @@
   "dependencies": {
     "@effect/platform-node": "4.0.0",
     "@effect/platform-node-shared": "4.0.0",
-    "@llm4ts/runner": "2.36.0",
-    "@llm4ts/core": "2.36.0",
-    "@llm4ts/flow": "2.36.0"
+    "@llm4ts/core": "2.37.0",
+    "@llm4ts/flow": "2.37.0",
+    "@llm4ts/runner": "2.37.0"
   },
   "peerDependencies": {
     "effect": "4.0.0"