chore: prepare Release D (v2.9.1)

.github/workflows/ci.yml

@@ -69,3 +69,4 @@ 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 }}
+

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)
 

packages/tempo/plan/RELEASE-D.md

@@ -0,0 +1,171 @@
+# Release D: Deeper Decomposition Cleanup
+
+## Overview
+This release focuses on modularizing and refactoring the parsing and pattern-matching internals of Tempo for improved maintainability, testability, and extensibility. The goal is to extract tightly-scoped modules for pattern compilation, alias resolution, guard building, and result normalization, with clear boundaries and robust test coverage.
+
+## Task Breakdown & Tracking
+
+### Pattern Compiler + Cache Extraction
+- [ ] Extract `compileRegExp`, `setPatterns`, and helpers to new module
+- [ ] Integrate memoization/caching logic as needed
+- [ ] Refactor engine and consumers to use new module
+- [ ] Ensure compatibility with snippet/layout definitions
+- [ ] Add/expand unit tests for pattern logic and cache
+- [ ] Update documentation and references
+
+### Alias Resolution Engine Extraction
+- [ ] Extract alias resolution logic to new module
+- [ ] Define interfaces for registration, lookup, collision
+- [ ] Refactor engine and plugins to use new APIs
+- [ ] Add/expand unit tests for alias/collision
+- [ ] Update documentation and references
+
+### Guard Builder Extraction (Assessment)
+- [ ] Identify all guard-building/token-ingestion logic
+- [ ] Assess complexity/reuse for extraction
+- [ ] Outline module boundaries if justified
+- [ ] Document reasons if not extracted
+
+### Parse Result Normalizer Extraction (Assessment)
+- [ ] Identify all result normalization/trace logic
+- [ ] Assess complexity/reuse for extraction
+- [ ] Outline module boundaries if justified
+- [ ] Document reasons if not extracted
+
+## Expected Improvements and Risks
+
+**Expected Improvements:**
+- Lower cyclomatic complexity and improved maintainability in the main engine.
+- Clearer separation of concerns between parsing, pattern compilation, alias resolution, guard building, and result normalization.
+- Easier to test, extend, and debug individual modules.
+- More robust and explicit cache management.
+- Improved reliability and correctness through focused unit and regression tests.
+- Smoother onboarding for new contributors due to modular structure and documentation.
+
+**Risks:**
+- Potential for subtle integration bugs during refactor, especially in recursive expansion, alias resolution, or cache invalidation.
+- Temporary performance regressions if cache or pattern compilation is not optimized.
+- Over-extraction of simple logic could increase codebase complexity without clear benefit.
+- Increased review and testing overhead for each extraction step.
+
+**Mitigations:**
+- Incremental, well-documented releases with dedicated tests at each step.
+- Benchmarking and profiling before/after major changes.
+- Only extract modules where complexity or reuse justifies it.
+- Maintain clear interfaces and documentation for all new modules.
+
+## Affected Files and Modules
+
+The following files and modules are likely to be affected by the decomposition and extractions in Release D:
+
+- `src/tempo.class.ts` — Main engine logic, source of most extraction candidates.
+- `src/support/tempo.util.ts` — Utility functions for pattern, guard, and normalization logic.
+- `src/support/tempo.default.ts` — Core snippet, layout, and pattern definitions.
+- `src/tempo.type.ts` — Type definitions for parse, pattern, and result structures.
+- `src/support/tempo.register.ts` — May require updates for cache/registry management.
+- `library/src/common/function.library.ts` — Memoization and cache utilities.
+- `src/parse/parse.layout.ts` — Layout order and planner logic (if not already modularized).
+- Any new modules created for: Pattern Compiler + Cache, Alias Resolution Engine, Guard Builder, Parse Result Normalizer.
+- Test files covering parsing, pattern matching, event/period handling, and normalization.
+
+## Detailed Outlines
+
+### 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.
+
+**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.
+
+### 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., `alias.engine.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.
+
+**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.
+
+### Guard Builder Extraction — Assessment Outline
+**Purpose:**
+Evaluate the value and feasibility of extracting all logic related to token ingestion and fast-fail guard rebuild lifecycle into a dedicated module.
+
+**Boundaries & Responsibilities:**
+- Would own the process of ingesting tokens and rebuilding fast-fail guards for parsing.
+- Would expose APIs for guard construction, update, and validation.
+- Should integrate with the main engine’s parse pipeline and pattern system.
+
+**Assessment Steps:**
+1. Identify all guard-building and token-ingestion 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.
+
+**Risks & Mitigations:**
+- Risk: Over-extraction of simple logic. Mitigation: Only extract if complexity or reuse warrants.
+- Risk: Integration issues with parse pipeline. Mitigation: Careful interface design and incremental refactor.
+
+**Expected Improvements (if extracted):**
+- Cleaner separation of guard logic.
+- Easier to test and update guard-building behavior.
+
+### 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.
+
+**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.