Repository navigation
Refactor: dual-engine parser with runtime evaluation and diagnostics - #1
Merged
Merged
Conversation
…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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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
src/types.test.ts(649 lines of type assertions) andsrc/parse/index.test.ts(141 lines)src/types.typetest.ts(279 lines) — compile-time type assertions excluded from build, checked bytsc --noEmitsrc/parser.test.ts(230 lines) — runtime AST shape and precedence tests using Vitestsrc/evaluate.test.ts(111 lines) — evaluator tests covering literal/path lookup, associativity, and error casessrc/__fixtures__/grammar.ts— shared fixture grammar covering all pattern elements and both associativities.github/workflows/ci.yml— GitHub Actions CI pipeline for Node 20 & 22Runtime Engine
src/runtime/diagnostics.ts(175 lines) — mutableDiagnosticsobject threaded through parser to track furthest failure point and constraint mismatches; enables rich error reporting without affecting control flowsrc/runtime/evaluate.ts(110 lines) — post-order AST evaluator that dispatches to nodeeval()functions and resolves identifier/path lookups against runtime valuessrc/runtime/parser.ts— now accepts trailingDiagnosticsparameter; addedresolvePath()andresolveIdent()helpers; updated all primitive parsers to callfail()on mismatchsrc/runtime/infer.ts— no longer needed; nodes now carryoutputSchemadirectlyType-Level Engine
src/parse/index.ts— addedResolvePath<TData, TSegs>type for dotted-path resolution; updated comments to note parity requirement with runtime enginesrc/combinators/index.ts(242 lines) — combinators merged into grammar/schema layersrc/static/parser.tsandsrc/static/infer.ts— consolidated into main parse moduleSchema & Primitives
path()factory andPathSchemainterface — matches identifiers and dotted paths (e.g.,values.password)PathNodeAST node type withpath: readonly string[]and resolvedoutputSchemasrc/primitive/index.ts— now documents AST node types only; removed parser combinator logic; addedToNumber<S>type utilitysrc/schema/index.ts— addedAssociativitytype ("left" | "right"),PathSchemainterface, andInferValues<TSchema>type for mapping schemas to runtime value shapessrc/grammar/index.ts— removed Hotscript dependency; added inline numeric comparison for precedence validation; enforces non-negative integer precedencesPublic API
src/createParser.ts— now exportsSafeParseResult<TAst>,InferValues<TSchema>, andAnyAstNodetypes;parse()accepts only validated string literals (compile-time checked);safeParse()accepts dynamic strings and returns structured errors; addedevaluate()andevaluateAst()methodsStringentParseErrorandStringentErrortypes insrc/runtime/diagnostics.tssrc/index.ts— exportspath,PathSchema,Associativity,EvaluationError,EvaluationValues, and new resulthttps://claude.ai/code/session_01EzY2ZMd8jG1Pb5mSr7RPZt