Feature/tempo pattern compiler

doc/main_branch_protection.md

@@ -0,0 +1,126 @@
+# Preventing Writes to the Main Branch Locally
+
+To prevent accidental writes (commits and pushes) to the `main` branch on your local workstation, you can use **Git Hooks**.
+
+## Summary of Changes
+I have already set up local hooks for the `magma` repository:
+1. **`pre-commit`**: Blocks direct commits to the `main` branch.
+2. **`pre-push`**: Blocks pushing changes to the remote `main` branch.
+
+### How to Override
+If you genuinely need to write to `main` (e.g., for an urgent fix), you have two options:
+- **Environment Variable**: Prepend the command with the override flag:
+  - `ALLOW_MAIN_COMMIT=true git commit -m "Urgent fix"`
+  - `ALLOW_MAIN_PUSH=true git push`
+- **Skip Hooks**: Use the standard Git flag:
+  - `git commit --no-verify`
+  - `git push --no-verify`
+
+---
+
+## Applying This Globally (Recommended)
+If you want this protection to apply to **every repository** on your workstation, you can configure a global hooks directory.
+
+### 1. Create a Global Hooks Directory
+Choose a location (e.g., `~/.git-hooks`) and move the hook scripts there:
+
+```bash
+mkdir -p ~/.git-hooks
+# Copy the hooks I created for you
+cp /home/michael/Project/magma/.git/hooks/pre-commit ~/.git-hooks/
+cp /home/michael/Project/magma/.git/hooks/pre-push ~/.git-hooks/
+chmod +x ~/.git-hooks/*
+```
+
+### 2. Configure Git Globally
+Run this command to tell Git to use your new global hooks directory:
+
+```bash
+git config --global core.hooksPath ~/.git-hooks
+```
+
+---
+
+## Hook Implementation Details
+
+### pre-commit
+This script checks the current branch before every commit.
+
+```bash
+#!/bin/bash
+CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
+if [ "$CURRENT_BRANCH" = "main" ]; then
+  if [ "$ALLOW_MAIN_COMMIT" != "true" ]; then
+    echo "❌ ERROR: Direct commit to 'main' branch is prohibited."
+    exit 1
+  fi
+fi
+```
+
+### pre-push
+This script checks the remote branch being pushed to.
+
+```bash
+#!/bin/bash
+while read local_ref local_sha remote_ref remote_sha
+do
+    if [ "$remote_ref" = "refs/heads/main" ]; then
+        if [ "$ALLOW_MAIN_PUSH" != "true" ]; then
+            echo "❌ ERROR: Pushing to 'main' branch is prohibited."
+            exit 1
+        fi
+    fi
+done
+```
+
+---
+
+## 🆘 I'm on 'main' and have changes, what do I do?
+
+If you've already made changes on `main` and the hook blocks your commit, **don't panic and don't drop your stash!** You can easily move your work to a new branch.
+
+### The "Magic" Command: Just Create a New Branch
+Git allows you to create and switch to a new branch while keeping your uncommitted changes.
+
+```bash
+# 1. Create and switch to a new branch
+git checkout -b feature/my-cool-feature
+# OR (modern syntax)
+git switch -c feature/my-cool-feature
+
+# 2. Now you can commit normally
+git add .
+git commit -m "My feature changes"
+```
+
+### If you want to be extra safe (The Stash Method)
+If you have a lot of complex changes and want to ensure `main` stays clean:
+
+```bash
+# 1. Save your work temporarily
+git stash
+
+# 2. Create and switch to the new branch
+git checkout -b feature/my-cool-feature
+
+# 3. Bring your changes back
+git stash pop
+
+# 4. Commit
+git commit -am "My feature changes"
+```
+
+### "I accidentally committed before I added the hook!"
+If you have local commits on `main` that you haven't pushed yet, you can move them to a new branch:
+
+```bash
+# 1. Create a new branch at your current (accidental) commit
+git branch feature/my-feature
+
+# 2. Reset your local 'main' back to where it should be (the remote version)
+git reset --hard origin/main
+
+# 3. Switch to your new branch to continue working
+git checkout feature/my-feature
+```
+

packages/tempo/plan/RELEASE-D.md

@@ -14,11 +14,11 @@ This release focuses on modularizing and refactoring the parsing and pattern-mat
 - [ ] 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
+- [x] Extract alias resolution logic to new module
+- [x] Define interfaces for registration, lookup, collision
+- [x] Refactor engine and plugins to use new APIs
+- [x] Add/expand unit tests for alias/collision
+- [x] Update documentation and references
 
 ### Guard Builder Extraction (Assessment)
 - [ ] Identify all guard-building/token-ingestion logic

packages/tempo/src/engine/engine.pattern.ts

@@ -0,0 +1,151 @@
+// engine.pattern.ts
+// Pattern Compiler and Cache Engine for Tempo
+// Responsible for snippet/layout expansion, regex compilation, and pattern caching
+
+import { isRegExp, isNullish, isEmpty, isString } from '#library/assertion.library.js';
+import { ownEntries, ownKeys } from '#library/primitive.library.js';
+import { Match, Snippet, Layout } from '../support/tempo.default.js';
+import { getSymbol, logError } from '../support/tempo.util.js';
+import { Token } from '../support/tempo.symbol.js';
+import enums from '../support/tempo.enum.js';
+import type * as t from '../tempo.type.js';
+
+export interface PatternCompilerOptions {
+	state: t.Internal.State;
+}
+
+export class PatternCompiler {
+	#state: t.Internal.State;
+	#cache: Map<string, RegExp> = new Map();
+
+	constructor(options: PatternCompilerOptions) {
+		this.#state = options.state;
+	}
+
+	/**
+	 * Translates {layout} into an anchored, case-insensitive RegExp.
+	 * Includes recursive expansion of placeholders using snippet registries.
+	 */
+	compileRegExp(layout: string | RegExp, snippet?: Snippet): RegExp {
+		const source = isRegExp(layout) ? layout.source : layout;
+
+		// Simple cache check for the raw source
+		const cacheKey = `${source}:${snippet ? 'custom' : 'global'}`;
+		if (this.#cache.has(cacheKey)) {
+			return this.#cache.get(cacheKey)!;
+		}
+
+		const matcher = (src: string, d = 0): string => {
+			if (d > 10) return src; // prevent infinite recursion
+
+			if (src.startsWith('/') && src.endsWith('/'))
+				src = src.substring(1, src.length - 1);
+			if (src.startsWith('^') && src.endsWith('$'))
+				src = src.substring(1, src.length - 1);
+
+			return src.replace(new RegExp(Match.braces, 'g'), (match, name) => {
+				const token = getSymbol(name);
+				const customs = snippet?.[token as keyof Snippet]?.source ?? snippet?.[name as keyof Snippet]?.source;
+				const globals = this.#state.parse.snippet[token as keyof Snippet]?.source ?? this.#state.parse.snippet[name as keyof Snippet]?.source;
+				const stateLayout = this.#state.parse.layout[token as keyof Layout] ?? this.#state.parse.layout[name as keyof Layout];
+				const defaultLayout = Layout[token as keyof Layout];
+
+				let res = customs ?? globals ?? stateLayout ?? defaultLayout;
+
+				if (isNullish(res) && name.includes('.')) {
+					const prefix = name.split('.')[0];
+					const pToken = getSymbol(prefix);
+					res = snippet?.[pToken as keyof Snippet]?.source ?? snippet?.[prefix as keyof Snippet]?.source
+						?? this.#state.parse.snippet[pToken as keyof Snippet]?.source ?? this.#state.parse.snippet[prefix as keyof Snippet]?.source
+						?? this.#state.parse.layout[pToken as keyof Layout] ?? this.#state.parse.layout[prefix as keyof Layout]
+						?? Layout[pToken as keyof Layout];
+				}
+
+				if (res && name.includes('.')) {
+					const safeName = name.replace(/\./g, '_');
+					if (!res.startsWith(`(?<${safeName}>`))
+						res = `(?<${safeName}>${res})`;
+				}
+
+				return (isNullish(res) || res === match)
+					? match
+					: matcher(res, d + 1);
+			});
+		};
+
+		try {
+			const expanded = matcher(source);
+			const compiled = new RegExp(`^(${expanded})$`, 'i');
+			this.#cache.set(cacheKey, compiled);
+			return compiled;
+		} catch (e: any) {
+			const fallback = new RegExp(`^${Match.escape(layout as string)}$`, 'i');
+			this.#cache.set(cacheKey, fallback);
+			return fallback;
+		}
+	}
+
+	/**
+	 * Build RegExp patterns into the state.
+	 * Re-evaluates all snippets and layouts.
+	 */
+	setPatterns() {
+		this.clearCache();
+		const state = this.#state;
+		// ensure we have our own isolated mutable containers before mutation
+		state.parse.snippet = { ...state.parse.snippet };
+		state.parse.pattern = new Map();
+
+		const snippet = state.parse.snippet;
+
+		// 1. ensure numeric snippets are current
+		if (enums?.NUMBER) {
+			const keys = Object.keys(enums.NUMBER).map(w => Match.escape(w));
+			const nbr = new RegExp(`(?<nbr>[0-9]+|${keys.sort((a, b) => b.length - a.length).join('|')})`);
+
+			snippet[Token.nbr] = nbr;
+			snippet[Token.mod] = new RegExp(`((?<mod>${Match.modifier.source})?${nbr.source}? *)`);
+			snippet[Token.afx] = new RegExp(`((s)? (?<afx>${Match.affix.source}))?${snippet[Token.sep].source}?`);
+		}
+
+		// 2. build ignore pattern
+		const ignores = ownKeys(state.parse.ignore, true);
+
+		if (!isEmpty(ignores)) {
+			const words = ignores
+				.filter(isString)
+				.map(w => Match.escape(w.toLowerCase()))
+				.join('|');
+
+			state.parse.ignorePattern = new RegExp(`\\b(${words})\\b`, 'gi');
+		} else {
+			delete state.parse.ignorePattern;
+		}
+
+		// 3. build the patterns
+		ownEntries(state.parse.layout).forEach(([key, layout]) => {
+			const symbol = getSymbol(key);
+			const compiled = this.compileRegExp(layout, snippet);
+
+			state.parse.pattern.set(symbol, compiled);
+		});
+	}
+
+	/**
+	 * Clear the pattern cache.
+	 */
+	clearCache() {
+		this.#cache.clear();
+	}
+}
+
+/**
+ * Functional wrapper for the PatternCompiler.
+ * Handles engine instantiation and pattern building for a given state.
+ */
+export function setPatterns(state: t.Internal.State) {
+	if (!state.patternCompiler) {
+		state.patternCompiler = new PatternCompiler({ state });
+	}
+	state.patternCompiler.setPatterns();
+}

packages/tempo/src/support/support.index.ts

@@ -32,5 +32,6 @@ export { $Tempo, $Register, $Interpreter, $logError, $logDebug, $dbg, $guard, $e
 export { registryUpdate, registryReset, onRegistryReset } from './tempo.register.js';
 export { getRuntime, TempoRuntime } from './tempo.runtime.js';
 export { Match, Snippet, Layout, Event, Period, Ignore, Guard, Default } from './tempo.default.js';
-export { SCHEMA, getLargestUnit, setPatterns, logError, logWarn, logDebug } from './tempo.util.js';
+export { SCHEMA, getLargestUnit, logError, logWarn, logDebug } from './tempo.util.js';
+export { setPatterns } from '../engine/engine.pattern.js';
 export { init, extendState } from './tempo.init.js';