Imhotep/CHANGELOG.md

Changelog

[1.1.0] - 2025-08-15

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).

Fixed

• TypeScript import extensions and missing generateSeed export resolution.
• Flaky performance test threshold relaxed 500ms → 800ms.
• imhotep-core test compilation via tsconfig.test.json.

Test/Verification

• 1125 unit tests passing across all packages.
• 215 E2E 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.