chore: prepare Release D (v2.9.1)

.github/workflows/ci.yml

@@ -40,6 +40,28 @@ jobs:
     timeout-minutes: 30
     if: github.ref == 'refs/heads/release-c-layout-order-planner' || github.event.pull_request.base.ref == 'main'
     steps:
+      - name: Print GitHub event context (for debug)
+        run: |
+          echo "GITHUB_REF: $GITHUB_REF"
+          echo "GITHUB_EVENT_NAME: $GITHUB_EVENT_NAME"
+          echo "GITHUB_HEAD_REF: $GITHUB_HEAD_REF"
+          echo "GITHUB_BASE_REF: $GITHUB_BASE_REF"
+          echo "github.ref: ${{ github.ref }}"
+          echo "github.event_name: ${{ github.event_name }}"
+          echo "github.head_ref: ${{ github.head_ref }}"
+          echo "github.base_ref: ${{ github.base_ref }}"
+          echo "github.event.pull_request.base.ref: ${{ github.event.pull_request.base.ref }}"
+          echo "github.sha: ${{ github.sha }}"
+          echo "github.repository: ${{ github.repository }}"
+          echo "github.actor: ${{ github.actor }}"
+          echo "github.workflow: ${{ github.workflow }}"
+          echo "github.run_id: ${{ github.run_id }}"
+          echo "github.run_number: ${{ github.run_number }}"
+          echo "github.job: ${{ github.job }}"
+          echo "github.ref_name: ${{ github.ref_name }}"
+          echo "github.ref_type: ${{ github.ref_type }}"
+          echo "github.event: $(cat $GITHUB_EVENT_PATH)"
+        shell: bash
       - uses: actions/checkout@v4
       - name: Set up Node.js
         uses: actions/setup-node@v4
@@ -69,3 +91,26 @@ jobs:
         run: |
           node -e "const r=require('./packages/tempo/bench-output.json');if(!r.success){console.error('Benchmark failed:',r.errors);process.exit(1)}else{console.log('Benchmark passed.')}"
         working-directory: ${{ github.workspace }}
+      - name: Install monorepo dependencies
+        run: npm ci
+        working-directory: ${{ github.workspace }}
+      - name: Run all tests with parse.preFilter
+        run: npm test
+        working-directory: packages/tempo
+        env:
+          TEMPO_PREFILTER_CI: 'true'
+      - name: Run end-to-end benchmark
+        run: npx tsx --conditions=development bench/bench.parse.prefilter.e2e.ts > bench-output.json 2> bench-error.log
+        working-directory: packages/tempo
+      - name: Upload benchmark output
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: bench-parse-prefilter-e2e
+          path: |
+            packages/tempo/bench-output.json
+            packages/tempo/bench-error.log
+      - name: Validate benchmark output
+        run: |
+          node -e "const r=require('./packages/tempo/bench-output.json');if(!r.success){console.error('Benchmark failed:',r.errors);process.exit(1)}else{console.log('Benchmark passed.')}"
+        working-directory: ${{ github.workspace }}

package.json

@@ -1,6 +1,6 @@
 {
   "name": "tempo-monorepo",
-  "version": "2.8.0",
+  "version": "2.9.1",
   "private": true,
   "description": "Magma Computing Monorepo",
   "repository": {

packages/library/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@magmacomputing/library",
-  "version": "2.8.0",
+  "version": "2.9.1",
   "description": "Shared utility library for Tempo",
   "author": "Magma Computing Solutions",
   "license": "MIT",
@@ -88,7 +88,7 @@
     "test": "vitest run",
     "build": "tsc -b",
     "clean": "tsc -b --clean",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "if [ $(git rev-parse --abbrev-ref HEAD) != main ]; then echo 'ERROR: Must be on main branch to publish.'; exit 1; fi && npm run build"
   },
   "dependencies": {
     "tslib": "^2.8.1"

packages/tempo/.vitepress/config.ts

@@ -12,6 +12,7 @@ export default defineConfig({
   base: '/magma/',
   title: "Tempo",
   description: "The Professional Date-Time Library for Temporal",
+  srcDir: './doc',
   markdown: {
     math: true
   },

packages/tempo/archive/tempo.api.md

@@ -5,7 +5,7 @@ This document provides a comprehensive technical reference for the `Tempo` class
 ---
 
 - [TypeScript Types Reference](./tempo.types.md)
-- [Tempo Cookbook](./tempo.cookbook.md)
+- [Tempo Cookbook](../doc/tempo.cookbook.md)
 
 ---
 
@@ -67,7 +67,7 @@ Retrieves or registers a `Symbol` for internal token mapping.
 ### `Tempo.ticker(arg1?, arg2?)`
 (Plugin required) Creates a reactive stream of `Tempo` instances at regular intervals. 
 - **Returns:** An `AsyncGenerator` (if no callback) or a `stop` function (if callback provided).
-- **See:** [Tempo Ticker Guide](./tempo.ticker.md) for the full polymorphic signature and usage patterns.
+- **See:** [Tempo Ticker Guide](../doc/tempo.ticker.md) for the full polymorphic signature and usage patterns.
 
 ### `Tempo.regexp(layout, snippet?)`
 Translates a Tempo layout string into a compiled `RegExp`.
@@ -201,5 +201,5 @@ Returns a `Temporal.PlainDateTime` representation.
 
 ::: tip
 **Looking for the full technical details?**  
-For an exhaustive, auto-generated reference of every property, internal type, and class member, see our [Full Technical API Reference](./api/README.md).
+For an exhaustive, auto-generated reference of every property, internal type, and class member, see our [Full Technical API Reference](../doc/api/index.md).
 :::

packages/tempo/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@magmacomputing/tempo",
-  "version": "2.8.0",
+  "version": "2.9.1",
   "description": "The Tempo core library",
   "author": "Magma Computing Solutions",
   "license": "MIT",
@@ -223,7 +223,7 @@
     "build:resolve": "tsx bin/resolve-types.ts",
     "clean": "rm -rf dist && (tsc -b --clean || true)",
     "publish": "npm publish --access public",
-    "prepublishOnly": "npm run build",
+    "prepublishOnly": "if [ $(git rev-parse --abbrev-ref HEAD) != main ]; then echo 'ERROR: Must be on main branch to publish.'; exit 1; fi && npm run build",
     "docs:api": "typedoc",
     "docs:dev": "npm run build && npm run docs:api && vitepress dev",
     "docs:build": "npm run build && npm run docs:api && vitepress build",
@@ -238,7 +238,7 @@
   },
   "devDependencies": {
     "@js-temporal/polyfill": "^0.5.1",
-    "@magmacomputing/library": "2.8.0",
+    "@magmacomputing/library": "2.9.1",
     "@rollup/plugin-alias": "^6.0.0",
     "cross-env": "^7.0.3",
     "magic-string": "^0.30.21",

packages/tempo/plan/.WISHLIST.md

@@ -155,13 +155,128 @@ Exit criteria:
 
 ### Release D: deeper decomposition cleanup
 
-- [ ] Extract Pattern Compiler + Cache module.
-- [ ] Extract Alias Resolution Engine module.
-- [ ] Optional: extract Guard Builder and Parse Result Normalizer if churn justifies.
+---
+
+#### Parse Result Normalizer Extraction — Assessment Outline
+
+**Purpose:**
+Evaluate the value and feasibility of extracting all logic related to match accumulation and parse-result shaping/trace output into a dedicated module.
+
+**Boundaries & Responsibilities:**
+- Would own the process of normalizing parse results and shaping trace/debug output.
+- Would expose APIs for result normalization and trace formatting.
+- Should integrate with the main engine’s parse and debug systems.
+
+**Assessment Steps:**
+1. Identify all result normalization and trace output logic in `tempo.class.ts` and helpers.
+2. Determine if the logic is sufficiently complex or reused to justify extraction.
+3. If justified, outline module boundaries and migration steps similar to previous extractions.
+4. If not, document reasons for keeping logic inline.
 
-Exit criteria:
-- Reduced cyclomatic complexity in primary class engine.
-- Internal module contracts documented and covered by focused unit tests.
+**Potential Affected Files:**
+- `src/tempo.class.ts`
+- `src/support/tempo.util.ts`
+- `src/tempo.type.ts`
+
+**Risks & Mitigations:**
+- Risk: Over-extraction of simple logic. Mitigation: Only extract if complexity or reuse warrants.
+- Risk: Integration issues with parse/trace systems. Mitigation: Careful interface design and incremental refactor.
+
+**Expected Improvements (if extracted):**
+- Cleaner separation of result normalization logic.
+- Easier to test and update parse-result shaping and trace output.
+
+#### Alias Resolution Engine Extraction — Detailed Outline
+
+**Purpose:**
+Modularize all logic related to event/period alias resolution, collision policy, and snippet rebinding into layout-aware groups for clarity, maintainability, and extensibility.
+
+**Boundaries & Responsibilities:**
+- Accepts event/period definitions and manages alias mapping and collision detection.
+- Handles rebinding of snippets into layout-aware groups.
+- Exposes clear APIs for resolving aliases and reporting collisions.
+- Integrates with the main engine to ensure correct event/period resolution during parsing.
+
+**Migration Steps:**
+1. Identify and extract all alias resolution logic from `tempo.class.ts` and related helpers into a new module (e.g., `engine.alias.ts`).
+2. Define clear interfaces for alias registration, lookup, and collision reporting.
+3. Refactor the main engine and plugin system to use the new module’s APIs.
+4. Add/expand unit tests for alias resolution, collision handling, and rebinding.
+5. Document the new module’s API and update internal references.
+
+**Affected Files:**
+- `src/tempo.class.ts` (extraction and refactor)
+- `src/support/tempo.util.ts` (if helpers are involved)
+- `src/tempo.type.ts` (type updates if needed)
+
+**Risks & Mitigations:**
+- Risk: Incorrect alias resolution or missed collisions. Mitigation: Add focused unit tests and regression tests.
+- Risk: Integration issues with plugin/event/period systems. Mitigation: Incremental refactor and thorough testing.
+
+**Expected Improvements:**
+- Cleaner separation of concerns for alias logic.
+- Easier to extend and maintain event/period handling.
+- Improved testability and reliability of alias resolution.
+
+
+#### Pattern Compiler + Cache Extraction Plan (to be detailed)
+
+*Purpose*: Modularize all logic related to snippet/layout expansion, regex compilation, and cache invalidation.
+
+*Outline (to be expanded):*
+1. Identify all code responsible for pattern expansion and regex compilation.
+2. Define clear module boundaries and interfaces for the compiler and cache.
+3. Move related logic from the main engine/class to the new module.
+4. Implement cache invalidation and update mechanisms.
+5. Add focused unit tests for the new module.
+6. Update documentation and internal references.
+
+---
+
+#### Pattern Compiler + Cache Extraction — Detailed Outline
+
+**Purpose:**
+Modularize all logic related to snippet/layout expansion, regex compilation, and pattern cache management for clarity, testability, and maintainability.
+
+**Boundaries & Responsibilities:**
+- Accepts layout/snippet definitions and returns compiled RegExp objects.
+- Handles recursive expansion of layout placeholders (e.g., `{yy}`, `{mm}`) using snippet registries.
+- Manages a cache of compiled patterns for performance.
+- Exposes cache invalidation/refresh methods for dynamic config changes.
+- Provides a clear interface for the rest of the Tempo engine to request compiled patterns.
+
+**Migration Steps:**
+1. Extract `compileRegExp`, `setPatterns`, and related helpers from `tempo.util.ts` into a new module (e.g., `pattern.compiler.ts`).
+2. Move or wrap memoization/caching logic (from `function.library.ts`) as needed for pattern compilation.
+3. Refactor `tempo.class.ts` and other consumers to use the new module’s interface.
+4. Ensure all pattern/snippet/layout definitions in `tempo.default.ts` are compatible with the new module.
+5. Add/expand unit tests for pattern expansion, compilation, and cache behavior.
+6. Document the new module’s API and update internal references.
+
+**Affected Files:**
+- `src/support/tempo.util.ts` (extraction)
+- `src/tempo.class.ts` (refactor to use new module)
+- `src/support/tempo.default.ts` (ensure compatibility)
+- `src/tempo.type.ts` (type updates if needed)
+- `library/src/common/function.library.ts` (cache/memoization logic)
+
+**Risks & Mitigations:**
+- Risk: Subtle bugs in recursive expansion or cache invalidation. Mitigation: Add focused unit tests and regression tests.
+- Risk: Performance regressions if cache is not used correctly. Mitigation: Benchmark before/after and optimize cache usage.
+
+**Expected Improvements:**
+- Lower cyclomatic complexity in the main engine.
+- Easier to test and reason about pattern expansion and compilation.
+- Clearer cache management and invalidation.
+
+### Release D: Recommended Release Strategy
+
+To balance safety and efficiency:
+
+- Release the two major extractions (Pattern Compiler + Cache, Alias Resolution Engine) as separate point-releases for focused testing and easier rollback.
+- Batch the assessment/documentation steps (Guard Builder, Parse Result Normalizer, affected files/modules, improvements/risks) into a single follow-up release if they are lightweight.
+
+This approach allows for incremental progress, clear regression points, and manageable review cycles.
 
 ## Next sequence kickoff (start now)