From 7b1732abccf9c1121c69e43587ab6cd74c3f1aa8 Mon Sep 17 00:00:00 2001 From: Philipp Kunz Date: Sun, 25 May 2025 19:37:13 +0000 Subject: [PATCH] BREAKING CHANGE(protocol): Introduce protocol v2 implementation and update build configuration with revised build order, new tspublish files, and enhanced documentation --- changelog.md | 8 +++++ readme.hints.md | 31 +++++++++++++++---- readme.plan.md | 45 +++++++++++++++++++++------- ts/00_commitinfo_data.ts | 2 +- ts/tspublish.json | 2 +- ts_tapbundle/tspublish.json | 2 +- ts_tapbundle_node/tspublish.json | 3 ++ ts_tapbundle_protocol/tspublish.json | 3 ++ 8 files changed, 77 insertions(+), 19 deletions(-) create mode 100644 ts_tapbundle_node/tspublish.json create mode 100644 ts_tapbundle_protocol/tspublish.json diff --git a/changelog.md b/changelog.md index be3907d..6520eff 100644 --- a/changelog.md +++ b/changelog.md @@ -1,5 +1,13 @@ # Changelog +## 2025-05-25 - 2.0.0 - BREAKING CHANGE(protocol) +Introduce protocol v2 implementation and update build configuration with revised build order, new tspublish files, and enhanced documentation + +- Added ts_tapbundle_protocol directory with isomorphic implementation for protocol v2 +- Updated readme.hints.md and readme.plan.md to explain the complete replacement of the v1 protocol and new build process +- Revised build order in tspublish.json files across ts, ts_tapbundle, ts_tapbundle_node, and ts_tapbundle_protocol +- Introduced .claude/settings.local.json with updated permission settings for CLI and build tools + ## 2025-05-24 - 1.11.5 - fix(tstest) Fix timeout handling to correctly evaluate TAP results after killing the test process. diff --git a/readme.hints.md b/readme.hints.md index fd64266..2f2c70b 100644 --- a/readme.hints.md +++ b/readme.hints.md @@ -40,9 +40,17 @@ This project integrates tstest with tapbundle through a modular architecture: - Automatically detects browser environment and only enables in browser context 3. **Build System** - - Uses `tsbuild tsfolders` to compile TypeScript - - Maintains separate output directories: `/dist_ts/`, `/dist_ts_tapbundle/`, `/dist_ts_tapbundle_node/` - - Compilation order is resolved automatically based on dependencies + - Uses `tsbuild tsfolders` to compile TypeScript (invoked by `pnpm build`) + - Maintains separate output directories: `/dist_ts/`, `/dist_ts_tapbundle/`, `/dist_ts_tapbundle_node/`, `/dist_ts_tapbundle_protocol/` + - Compilation order is resolved automatically based on dependencies in tspublish.json files + - Protocol imports use compiled dist directories: + ```typescript + // In ts/tstest.classes.tap.parser.ts + import { ProtocolParser } from '../dist_ts_tapbundle_protocol/index.js'; + + // In ts_tapbundle/tapbundle.classes.tap.ts + import { ProtocolEmitter } from '../dist_ts_tapbundle_protocol/index.js'; + ``` ### Test Scripts @@ -102,6 +110,19 @@ A new internal protocol is being designed that will: - Use Unicode delimiters `⟦TSTEST:⟧` that won't conflict with test content - Support structured JSON metadata - Allow rich error reporting with stack traces and diffs -- Maintain backwards compatibility during migration +- Completely replace v1 protocol (no backwards compatibility) -See `readme.protocol.md` for the full specification and `tapbundle.protocols.ts` for the implementation utilities. \ No newline at end of file +### ts_tapbundle_protocol Directory +The protocol v2 implementation is contained in a separate `ts_tapbundle_protocol` directory: +- **Isomorphic Code**: All protocol code works in both browser and Node.js environments +- **No Platform Dependencies**: No Node.js-specific imports, ensuring true cross-platform compatibility +- **Clean Separation**: Protocol logic is isolated from platform-specific code in tstest and tapbundle +- **Shared Implementation**: Both tstest (parser) and tapbundle (emitter) use the same protocol classes +- **Build Process**: + - Compiled by `pnpm build` via tsbuild to `dist_ts_tapbundle_protocol/` + - Build order managed through tspublish.json files + - Other modules import from the compiled dist directory, not source + +This architectural decision ensures the protocol can be used in any JavaScript environment without modification and maintains proper build dependencies. + +See `readme.protocol.md` for the full specification and `ts_tapbundle_protocol/` for the implementation. \ No newline at end of file diff --git a/readme.plan.md b/readme.plan.md index f6398c9..13a224d 100644 --- a/readme.plan.md +++ b/readme.plan.md @@ -13,12 +13,27 @@ - Use Unicode delimiters `⟦TSTEST:META:{}⟧` that won't appear in test names - Structured JSON metadata format - Separate protocol blocks for complex data (errors, snapshots) -- Backwards compatible with gradual migration +- Complete replacement of v1 (no backwards compatibility needed) ### Implementation -- Phase 1: Add protocol v2 parser alongside v1 -- Phase 2: Generate v2 by default with --legacy flag for v1 -- Phase 3: Full migration to v2 in next major version +- Phase 1: Create protocol v2 implementation in ts_tapbundle_protocol +- Phase 2: Replace all v1 code in both tstest and tapbundle with v2 +- Phase 3: Delete all v1 parsing and generation code + +#### ts_tapbundle_protocol Directory +The protocol v2 implementation will be contained in the `ts_tapbundle_protocol` directory as isomorphic TypeScript code: +- **Isomorphic Design**: All code must work in both browser and Node.js environments +- **No Node.js Imports**: No Node.js-specific modules allowed (no fs, path, child_process, etc.) +- **Protocol Classes**: Contains classes implementing all sides of the protocol: + - `ProtocolEmitter`: For generating protocol v2 messages (used by tapbundle) + - `ProtocolParser`: For parsing protocol v2 messages (used by tstest) + - `ProtocolMessage`: Base classes for different message types + - `ProtocolTypes`: TypeScript interfaces and types for protocol structures +- **Pure TypeScript**: Only browser-compatible APIs and pure TypeScript/JavaScript code +- **Build Integration**: + - Compiled by `pnpm build` (via tsbuild) to `dist_ts_tapbundle_protocol/` + - Build order defined in tspublish.json files + - Imported by ts and ts_tapbundle modules from the compiled dist directory See `readme.protocol.md` for detailed specification. @@ -183,10 +198,18 @@ tstest --changed ## Implementation Phases ### Phase 1: Improved Internal Protocol (Priority: Critical) (NEW) -1. Implement Protocol V2 parser in tstest -2. Add protocol version negotiation -3. Update tapbundle to generate V2 format with feature flag -4. Test with real-world test suites containing special characters +1. Create ts_tapbundle_protocol directory with isomorphic protocol v2 implementation + - Implement ProtocolEmitter class for message generation + - Implement ProtocolParser class for message parsing + - Define ProtocolMessage types and interfaces + - Ensure all code is browser and Node.js compatible + - Add tspublish.json to configure build order +2. Update build configuration to compile ts_tapbundle_protocol first +3. Replace TAP parser in tstest with Protocol V2 parser importing from dist_ts_tapbundle_protocol +4. Replace TAP generation in tapbundle with Protocol V2 emitter importing from dist_ts_tapbundle_protocol +5. Delete all v1 TAP parsing code from tstest +6. Delete all v1 TAP generation code from tapbundle +7. Test with real-world test suites containing special characters ### Phase 2: Test Configuration System (Priority: High) 1. Implement tap.settings() API with TypeScript interfaces @@ -214,10 +237,10 @@ tstest --changed ## Technical Considerations ### API Design Principles -- Maintain backward compatibility +- Clean, modern API design without legacy constraints - Progressive enhancement approach -- Opt-in features to avoid breaking changes -- Clear migration paths for new features +- Well-documented features and APIs +- Clear, simple interfaces ### Performance Goals - Minimal overhead for test execution diff --git a/ts/00_commitinfo_data.ts b/ts/00_commitinfo_data.ts index 3b72991..9068125 100644 --- a/ts/00_commitinfo_data.ts +++ b/ts/00_commitinfo_data.ts @@ -3,6 +3,6 @@ */ export const commitinfo = { name: '@git.zone/tstest', - version: '1.11.5', + version: '2.0.0', description: 'a test utility to run tests that match test/**/*.ts' } diff --git a/ts/tspublish.json b/ts/tspublish.json index 18e67c6..8f70b09 100644 --- a/ts/tspublish.json +++ b/ts/tspublish.json @@ -1,3 +1,3 @@ { - "order": 2 + "order": 4 } \ No newline at end of file diff --git a/ts_tapbundle/tspublish.json b/ts_tapbundle/tspublish.json index 5a46852..18e67c6 100644 --- a/ts_tapbundle/tspublish.json +++ b/ts_tapbundle/tspublish.json @@ -1,3 +1,3 @@ { - "order": 1 + "order": 2 } \ No newline at end of file diff --git a/ts_tapbundle_node/tspublish.json b/ts_tapbundle_node/tspublish.json new file mode 100644 index 0000000..0133f4d --- /dev/null +++ b/ts_tapbundle_node/tspublish.json @@ -0,0 +1,3 @@ +{ + "order": 3 +} \ No newline at end of file diff --git a/ts_tapbundle_protocol/tspublish.json b/ts_tapbundle_protocol/tspublish.json new file mode 100644 index 0000000..5a46852 --- /dev/null +++ b/ts_tapbundle_protocol/tspublish.json @@ -0,0 +1,3 @@ +{ + "order": 1 +} \ No newline at end of file