Skip to content

Refactor: dual-engine parser with runtime evaluation and diagnostics - #1

Merged
eralmansouri merged 3 commits into
mainfrom
claude/production-readiness-review-41yl8n
Jul 5, 2026
Merged

eralmansouri merged 3 commits into
mainfrom
claude/production-readiness-review-41yl8n

Conversation

@eralmansouri

Copy link
Copy Markdown
Owner

Summary

This PR restructures Stringent into a dual-engine architecture: a type-level parser (for compile-time validation of string literals) and a runtime parser (for dynamic strings with structured error reporting). Both engines are now pinned to identical behavior via a parity test suite, and a new evaluator enables post-parse computation of expression results.

Key Changes

Architecture & Testing

  • Removed src/types.test.ts (649 lines of type assertions) and src/parse/index.test.ts (141 lines)
  • Added src/types.typetest.ts (279 lines) — compile-time type assertions excluded from build, checked by tsc --noEmit
  • Added src/parser.test.ts (230 lines) — runtime AST shape and precedence tests using Vitest
  • Added src/evaluate.test.ts (111 lines) — evaluator tests covering literal/path lookup, associativity, and error cases
  • Added src/__fixtures__/grammar.ts — shared fixture grammar covering all pattern elements and both associativities
  • Added .github/workflows/ci.yml — GitHub Actions CI pipeline for Node 20 & 22

Runtime Engine

  • Added src/runtime/diagnostics.ts (175 lines) — mutable Diagnostics object threaded through parser to track furthest failure point and constraint mismatches; enables rich error reporting without affecting control flow
  • Added src/runtime/evaluate.ts (110 lines) — post-order AST evaluator that dispatches to node eval() functions and resolves identifier/path lookups against runtime values
  • Refactored src/runtime/parser.ts — now accepts trailing Diagnostics parameter; added resolvePath() and resolveIdent() helpers; updated all primitive parsers to call fail() on mismatch
  • Removed src/runtime/infer.ts — no longer needed; nodes now carry outputSchema directly

Type-Level Engine

  • Refactored src/parse/index.ts — added ResolvePath<TData, TSegs> type for dotted-path resolution; updated comments to note parity requirement with runtime engine
  • Removed src/combinators/index.ts (242 lines) — combinators merged into grammar/schema layer
  • Removed src/static/parser.ts and src/static/infer.ts — consolidated into main parse module

Schema & Primitives

  • Added path() factory and PathSchema interface — matches identifiers and dotted paths (e.g., values.password)
  • Added PathNode AST node type with path: readonly string[] and resolved outputSchema
  • Refactored src/primitive/index.ts — now documents AST node types only; removed parser combinator logic; added ToNumber<S> type utility
  • Updated src/schema/index.ts — added Associativity type ("left" | "right"), PathSchema interface, and InferValues<TSchema> type for mapping schemas to runtime value shapes
  • Updated src/grammar/index.ts — removed Hotscript dependency; added inline numeric comparison for precedence validation; enforces non-negative integer precedences

Public API

  • Refactored src/createParser.ts — now exports SafeParseResult<TAst>, InferValues<TSchema>, and AnyAstNode types; parse() accepts only validated string literals (compile-time checked); safeParse() accepts dynamic strings and returns structured errors; added evaluate() and evaluateAst() methods
  • Added StringentParseError and StringentError types in src/runtime/diagnostics.ts
  • Updated src/index.ts — exports path, PathSchema, Associativity, EvaluationError, EvaluationValues, and new result

https://claude.ai/code/session_01EzY2ZMd8jG1Pb5mSr7RPZt

claude added 3 commits July 5, 2026 05:41
…iativity, packaging fixes

Implements the production-readiness review recommendations:

Core features
- Runtime evaluator: parser.evaluate() / evaluateAst() drive the eval()
  hooks from defineNode (post-order walk; literals, identifiers, dotted
  paths, and user nodes)
- safeParse(): runtime-first API for dynamic strings — requires full
  consumption, never throws, returns structured errors (code, message,
  position, expected, found) from a furthest-failure diagnostics tracker
- Member access: new path() pattern element parses ident(.ident)* and
  resolves types against nested schemas ({ values: { password: "string" } })
  in both engines; strict whitespace rules around dots
- Left associativity: associativity: "left" on defineNode, implemented as
  an iterative fold at runtime and a tail-recursive fold at the type level
  (5-2-1 now parses/evaluates as (5-2)-1 = 2); left-assoc chains of 100+
  terms compile where 20 previously hit TS2589
- parse() now throws StringentParseError when its compile-time validation
  is bypassed instead of silently returning partial results
- createParser validates grammars up front (duplicate names, non-negative
  integer precedence, level-coherent associativity, left-pattern shape)

Bug fixes
- Type-level operand constraints were never enforced: ExtractConstraint
  matched `constraint` as a required property but ExprSchema declares it
  optional, so rhs("number") accepted anything at the type level while
  the runtime rejected it
- Runtime const nodes carried JSON-stringified outputSchema ('"+"') while
  the type level used the raw text ("+")

Packaging
- Removed hotscript (hand-rolled ComputeGrammar + vendored ToNumber):
  published d.ts no longer references a devDependency, which broke
  type-checking for all consumers
- Removed unused arktype dependency; removed legacy exports (combinators,
  primitive classes shadowing Number/String globals, static/ dir, dead
  runtime/infer.ts, configure hook)
- exports map: "types" first + "default" condition; sideEffects: false;
  repository URLs corrected to eralmansouri/stringent; LICENSE file added;
  version 0.1.0 (npm already has 0.0.4)

Infrastructure
- vitest suite (46 tests) + type-level tests checked by tsc (typetest.ts),
  including engine-parity assertions mirrored across both
- Fixed broken test script (pointed at nonexistent src/test.ts)
- GitHub Actions CI: typecheck, test, build, publint, arethetypeswrong
- README rewritten to match actual behavior (evaluation, safeParse, paths,
  associativity, error handling, type-level depth limits)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EzY2ZMd8jG1Pb5mSr7RPZt
…, review fixes

Addresses the design critique (static resultType, homogeneous operands,
stringly-typed schemas) and all findings from the adversarial review.

Type system redesign — polymorphism via declarative derivation:
- Union constraints: lhs(["number","string"]) — operator overloading in
  one node (add is now numeric add AND string concat)
- sameAs(binding): an operand must match an earlier operand's parsed
  type, whatever it was (eq/ternary branches agree without pinning a type)
- fromBinding(binding) result types: a node's outputSchema derives
  per-parse from a named operand (polymorphic parens/ternary; evaluate()
  returns string for "'a'+'b'" and number for "1+2")
- resultType now optional where derivable (passthrough atoms omit it)
- Both engines resolve constraints against already-parsed siblings; the
  left-fold seeds the resolution with the folded operand

Closed type vocabulary (kills the stringly-typed hole):
- createParser derives the vocabulary (resultTypes + builtins +
  options.types) and rejects unknown constraint strings at construction
- Schema leaves are validated at compile time (SchemaShapeOf<TVocab>
  bound: typos error at the leaf with the valid names) and at runtime
- parser.typeNames exposes the vocabulary

Evaluation:
- lazy: true nodes receive memoized thunks — ternary/&&/|| short-circuit
  (untaken branches never evaluate)
- All identifier/path lookups use Object.hasOwn: __proto__/constructor
  never leak prototype internals (parse-time and eval-time)

Review findings fixed:
- Reserved node names (literal/identifier/path/const) rejected — user
  eval can no longer be silently bypassed
- rhs()/expr() at pattern position 0 rejected (was: stack overflow);
  atoms starting with expression elements rejected; constVal("") rejected
- Left-fold constraint mismatches now recorded in diagnostics with spans;
  error ranking prefers a mismatch only when its span reaches both the
  stuck position and the furthest token failure
- Type-level BuildNodeResult mirrors runtime for const-only and
  multi-unnamed patterns (was: never, which vacuously satisfied every
  constraint); const-only atoms carry their declared resultType
- Digit-wise precedence comparison replaces tuple lengths (was: TS2589
  above ~999); precedence validated as non-negative safe integer
- ValidatedInput accepts trailing whitespace, matching safeParse
- Fixed ResultSchemaOf optional-property matching (same bug class as the
  earlier constraint-extraction fix; every node degraded to "unknown")

Docs & tests:
- DESIGN.md: architecture, the semantics-are-data law, vocabulary/
  constraint/derivation semantics, error ranking, parity rules, the
  recorded arktype decision and roadmap
- README rewritten around the polymorphic API with a working ternary
- Fixture grammar v2 (ternary, overloaded add, same-type eq, polymorphic
  parens); 77 runtime tests + expanded type-level suite

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EzY2ZMd8jG1Pb5mSr7RPZt
A second review pass confirmed all 12 prior fixes hold and both engines
are in exact parity across 60+ probes, but found four defineNode
validation gaps that violated the library's own invariants:

- Binding names 'node'/'outputSchema'/'__proto__' rejected — a binding
  named 'node' made safeParse return ASTs violating the AnyAstNode
  contract (runtime) while the type engine intersected instead (parity
  break)
- Duplicate binding names within a pattern rejected — sameAs resolved
  against the first occurrence while fromBinding/AST used the last,
  and the first child silently vanished
- sameAs/fromBinding targeting const elements rejected — const bindings
  carry their matched text as their type, which escaped the closed
  vocabulary (fromBinding) or made slots unsatisfiable (sameAs)
- Empty constraint lists (lhs([])) rejected — silently dead rules

Also:
- parse() now returns the actual trailing-whitespace rest in its tuple,
  matching what Parse<> computes (was hardcoded "")
- DESIGN.md: corrected the type-level nesting ceiling (measured: ~3
  expr() nesting levels and ~14 right-assoc terms on the 6-level fixture,
  not "a few dozen tokens"); documented unknown==unknown sameAs
  semantics, the wide-schema parse() bypass, and the known
  unclosed-delimiter diagnostics weakness
- Nesting-depth and pow-chain canaries added to types.typetest.ts so
  depth regressions fail loudly; 4 new validation tests (81 total)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EzY2ZMd8jG1Pb5mSr7RPZt
@eralmansouri
eralmansouri merged commit cbac7d0 into main Jul 5, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants