perf: pre-transpile .rules.ts files to avoid per-run dynamic import overhead

[rhuanbarreto]

Context

Each archgate check invocation dynamically imports every .rules.ts file via:

// src/engine/loader.ts, line 314-315
const rulesUrl = `${pathToFileURL(rulesFile).href}?t=${Date.now()}`;
const mod = await import(rulesUrl);

The ?t=${Date.now()} cache-buster forces Bun to re-parse and re-evaluate each rule file on every run. This is necessary because Bun caches import() per-process, and rules may have changed between invocations.

For projects with many ADRs (10–30+), this means 10–30 separate dynamic imports per check, each requiring:

1. File read from disk
2. TypeScript transpilation
3. Module evaluation
4. Zod schema validation of the exported RuleSet

Proposal

Approach: Hash-based caching

Instead of always cache-busting, compute a content hash of each .rules.ts file and only re-import when the hash changes:

1. On archgate check, compute hash(file_content) for each .rules.ts
2. Compare against a cached hash (in-memory or on disk at .archgate/.cache/rules-hash.json)
3. If unchanged, reuse the previously loaded RuleSet (skip import + parse + validate)
4. If changed, import fresh and update the cache

This preserves correctness (rules always reflect the latest file content) while skipping redundant work in the common case where rules haven't changed since the last check.

Alternative: Pre-bundle at archgate init time

Bundle all .rules.ts into a single module during archgate init or a new archgate compile-rules command. The check command would import one file instead of N. Downside: requires a build step and introduces staleness risk.

Considerations

• The security scanner (scanRuleFile) runs before import — its results could also be cached by hash
• RuleSetSchema.safeParse() validation could be skipped for cached modules
• Watch mode (if added later) would invalidate the cache on file change events

Impact

• Primary beneficiary: Projects with many ADRs/rules (10+ rule files)
• Expected improvement: ~50–200ms reduction in check latency (depending on rule count and file sizes)
• Risk: Medium — cache invalidation bugs could cause stale rules to run. Mitigate with hash verification.

Files to modify

• src/engine/loader.ts — add hash-based caching around the import() call
• Possibly src/helpers/paths.ts — add cache directory path

[rhuanbarreto]

Closing this — the optimization isn't warranted given current performance characteristics.

The numbers

Metric	Value
Total wall-clock time (archgate check)	~850ms
Rule execution time (all 27 rules)	~187ms
Rule files	20
Proposed savings	50–200ms (issue's own estimate)

~850ms → ~650ms for a CLI command that runs occasionally is not a perceptible difference.

The cache-buster was a vestige of the MCP server era

The ?t=${Date.now()} cache-buster was introduced in the initial release when archgate ran as a long-lived MCP server — the comment originally said "critical for MCP server". In that architecture, loadRuleAdrs() was called multiple times within the same process, so Bun's per-process module cache needed busting.

When PR #50 removed the MCP server, the comment was updated to "critical for repeated invocations" but no one questioned whether the code was still necessary. It wasn't — each archgate check is a fresh Bun process with no module cache to bust.

The cache-buster has been removed as dead code (it was a no-op for single-process CLI invocations).

Why not add hash-based caching anyway?

1. Complexity vs. gain — Hash computation, cache files, invalidation logic, corruption handling, and test coverage — all for ~50–200ms on a tool that runs a few times per session.
2. Cache invalidation risk — A stale cache means .rules.ts changes go undetected and ADR violations silently pass. That directly undermines the tool's core value proposition.
3. Wrong bottleneck — The ~660ms overhead is dominated by Bun process startup, CLI framework init, and git operations — not dynamic imports.
4. No user demand — No complaints about check latency.

If check latency ever becomes a real problem (50+ rule files, multi-second checks), the right move is to profile first and target the actual bottleneck.