Imhotep/CHANGELOG.md

# Changelog

## [1.1.0] - 2026-05-21

### Added

- **ContextPool, PagePool, Semaphore**: pooled runtime architecture for multi-worker property testing.
- **Parallel Property Runner**: worker-scoped fixtures with page reuse across test cases.
- **Renderer adapters**: unified pooled runtime interface for custom renderers.
- **External smoke test**: end-to-end CI gate in a clean temp directory (`scripts/external-smoke.mjs`).
- **Pooling benchmarks**: comprehensive contention and concurrency analysis suite (`imhotep-bench`).

### Changed

- Default concurrency capped at 4 (machine-specific tuning with `DEFAULT_CONCURRENCY_CAP`).
- CSS-based `ch` unit conversion uses true font metrics instead of approximation.
- Extraction path telemetry available via `IMHOTEP_EXTRACT_STATS=1` (opt-in).
- **Architecture**: Split `public.ts` (3568 lines) into 6 focused modules: `public-types.ts`, `semantic-subjects.ts`, `llm-output.ts`, `extraction.ts`, `check-all.ts`, and `public.ts` (916 lines, −74.3%).
- **Repository**: Root package renamed to `imhotep-monorepo`; CI targets `master` branch; all repository URLs updated to Gitea.
- **Build**: 13 tsconfigs now use `noEmitOnError: true`; package descriptions added to all 14 packages; 4 package READMEs created.
- **Documentation**: Root README replaced with real project documentation; SECURITY.md updated for Gitea; RELEASE.md checklist created; BUILD.md updated with correct commands.

### Fixed

- TypeScript import extensions and missing `generateSeed` export resolution.
- Flaky performance test threshold relaxed 500ms → 800ms.
- `imhotep-core` test compilation via `tsconfig.test.json`.
- Duplicate `ComponentOptions`/`StoryOptions` declarations collapsed into single shared interface.
- Broken import path in `imhotep` meta-package test runner.
- Root `package.json` scripts: removed `test:unit` reference; aliased build to workspace target.
- Cleaned 694 generated `.js`/`.d.ts`/`.map` artifacts from `src/` directories.
- Missing `imhotep-cli` exports: `init`, `CliOptions`, and preset types added to CLI barrel.
- `.gitignore` updated for V8 heap snapshot logs.

### Test/Verification

- **1125 unit tests** passing across all packages (0 failures).
- **215 E2E tests** passing (0 failures).
- **23 benchmark tests** passing (0 failures).
- External smoke test passes in clean temp directory.
- Build succeeds for all 14 packages.
- All packages pack cleanly with no `workspace:*` protocol leakage.

---

## [1.0.0] - 2025-07-01

### Added

- **First-order logic (FOL) in dense DSL**: `forall` and `exists` quantifiers with `and`, `or`, `not`, `implies` connectives.
- **FOL predicate keywords**: `width`, `height`, `size` predicates with comparison operators (`>=`, `<=`, `==`, `!=`).
- **Variable references in domain constructors**: `descendants($var, selector)`, `children($var, selector)`, `siblings($var, selector)`.
- **Spatial relation aliases**: `beside`, `nextTo`, `adjacent`, `touching`, `near`, `under`, `within`.
- **ARIA state predicates**: `disabled`, `checked`, `expanded`, `selected`, `pressed`, `visited`.
- **Compound assertions in dense DSL**: `and` / `or` chaining for relation combinations.
- **Fluent FOL API**: `ui.quantifier()` for programmatic FOL assertions.
- **FOL AST adapter**: `adaptGrammarFormulaToLogicAst()` bridges grammar AST to solver AST shapes.
- **Geometry snapshot caching**: `cacheDir` option for disk-based extraction caching with LRU eviction.
- **Preflight validation**: `ui.validate()` method for static syntax checks without browser extraction.
- **Diagnostic Contract V1**: standardized schema with `schemaVersion`, `code`, `category`, `severity`, `message`, `metrics`, `fixHints`, `sourceRef`, and optional `suggestedFix`.
- **Dense spec error recovery**: parse rewrite suggestions for common mistakes.
- **Cardinality contracts**: `exactlyOne`, `atLeastN`, `atMostN` selector cardinality assertions.
- **LLM output mode**: `checkAll({ format: 'llm' })` produces compact JSON for automated repair loops.
- **Preset contract packs**: `touchTarget`, `toolbarAlignment`, `cardSpacing`, `formLabelAlignment`, `modalContainment`.
- **Property-run reporting**: `minimalFailingCase`, `caseIndex`, `seed`, `durationMs`, `reportMode`.
- **Semantic subject references**: `getByRole`, `getByText`, `getByLabelText`, `getByTestId`.
- **Size assertion overloads**: polymorphic `atLeast`, `atMost`, `between` with dimension-agnostic forms.
- **Normalized contract echo**: `includeNormalized` flag on `checkAll()`.
- **Canonical failure formatter**: Expected/Observed/Why/Replay/Next narrative format.
- **Pattern-matching failure analyzer**: 6 smart failure patterns with targeted fix hints.
- **CLI scaffolding**: `npx imhotep init --preset <framework>` with 7 presets (react, vue, storybook, next, nuxt, remix, astro).
- **Meta-package**: single `imhotep` npm package bundling all dependencies.
- **Storybook integration**: `imhotepStory.forAllProps()` with args via custom events.
- **Property-based testing**: `exhaustivelyForAllInputs`, `forAllProps`, deterministic seeded contexts.
- **Assertion traceability**: `sourceRef` and `clauseLabel` on clause results and diagnostics.
- **Cache management**: `ui.clearCache()` method.

### Changed

- Replaced `workspace:*` with `^1.0.0` semver ranges in all package manifests.
- `space: 'layout'` option properly forwarded from options to AST.
- Default gap bounds: directional relations default `minGap` to `0` (was `-Infinity`).
- `focus-visible` kebab-case accepted alongside `focusVisible` camelCase.
- Fixed semantic subject crash: `SubjectReference` objects convert to strings before extraction.
- Fixed property runner file URL resolution for `file://` fixture paths.
- Fixed `defaultEnvironment`: removed unsupported `pointerType` axis.
- Fixed `maxGap` diagnostic messages: correctly reports max bound failures.
- Fixed FOL formula dropping: `forall`/`exists` blocks no longer silently discarded.
- Fixed Fluent FOL AST shape: `FluentQuantifier.toFormula()` produces solver-compatible AST.

### Performance

- O(1) box lookup via cached subjectId index (`forall-10000`: 116ms → 42ms, -64%).
- Single-call browser extraction fast path for geometry-led checks.
- Parallelized CDP selector resolution: batched `DOM.querySelectorAll` and `DOM.describeNode`.
- Parallelized selector resolution in `extractWorldCdp`: 50-selector extraction ~200ms → ~18ms (-91% cumulative).
- Fixed `CDPSessionManager.attach()` race condition: concurrent callers share a single session promise.
- Fact-planning: analyzes FOL formulas to extract only required facts (10-subject extraction: 48ms → 15ms, -68%).
- Optional `trace` flag in logic engine: disabling trace events reduces overhead by 39-54%.
- Rewrote `BindingEnv` with linked-list lookup (allocation from O(n²) → O(n)).

### Test/Verification

- **667 unit tests** passing across packages.
- **123 E2E tests** passing, 11 failures (unstable selectors in framework presets).
- Missing selector batch poisoning: only the zero-match assertion fails, others continue.
- Dense DSL size assertions: unary forms no longer include empty reference selectors.

---

## [0.4.0] - 2025-05-15

### Added

- Fluent assertion execution through canonical lowering and FOL evaluation.
- FOL logic engine with quantifiers and boolean connectives.
- Property-based testing entry points for components, stories, and fixtures.
- Deterministic seeded contexts for reproducibility.
- State materialization API: `materializeState()` for ARIA and native element states.
- Semantic subject resolution APIs.
- imhotep-cdp extraction package with canonical adapters.
- imhotep-reporter diagnostics with replay and shrinking support.
- imhotep-topology for stacking-context and transform-aware evaluation.

### Changed

- Geometry world schema expanded for transform-aware evaluation.
- Prototype-era direct rect-only evaluation replaced with canonical extraction pipeline.

---

## [0.3.0] - 2025-04-01

### Added

- imhotep-solver: constraint solver with directional relations (leftOf, rightOf, above, below) and gap constraints.
- imhotep-playwright: Playwright test integration with page-based extraction.
- Fluent API: `ui.expect().to.be.leftOf()` etc. with chaining.
- Dense DSL grammar and parser for string-based assertions.
- imhotep-extractor: DOM and geometry extraction from browser pages.
- Dense DSL size assertions: `atLeast`, `atMost`, `between` with pixel units.

---

## [0.2.0] - 2025-02-15

### Added

- imhotep-dsl: grammar definition, tokenizer, and parser for the dense assertion language.
- imhotep-extractor: data extraction layer with CDP-backed DOM queries.
- imhotep-reporter: diagnostic formatting and result aggregation.
- imhotep-state: state materialization foundation.

---

## [0.1.0] - 2025-01-15

### Added

- imhotep-core: type system, AST definitions, environment configuration.
- imhotep-geometry: bounding-box computation, rect algebra, transform math.
- imhotep-cdp: Chrome DevTools Protocol session management and DOM query primitives.
- Monorepo structure with npm workspaces (14 packages).
- TypeScript build pipeline with dependency-ordered compilation.
- Unit test framework across all foundational packages.