Stepami/hydrascript

HydraScript is a programming language interpreter that processes source code through a lexer, parser, and static analyzer to generate and execute intermediate representation instructions. It supports features such as function overloading, explicit type casting, complex data structures like arrays and objects, and environment variable access. The system utilizes a frame-based virtual machine for runtime execution and provides debugging capabilities via dump files for tokens, AST, and bytecode.

35 changes.

The project underwent a comprehensive rewrite of the HydraScript interpreter, replacing legacy components with a new clean architecture based on .NET 10. This involved rebuilding the lexer, parser, static analysis, and virtual machine from scratch to support modern language features like function overloading and complex data types. The effort also included migrating to xUnit 3, implementing automated regex generation, and adding integration tests to validate the new system.

11 changes.

This period focused on establishing comprehensive test infrastructure across the lexer, parser, and virtual machine layers while introducing explicit type casting capabilities for assignments. The work also included adding a benchmark suite for performance tracking and expanding integration tests to cover new language features like the 'with' expression and nullable types.

A new benchmark project has been introduced to measure the performance of the HydraScript executor. The suite uses BenchmarkDotNet to run benchmarks on .NET 10 and Native AOT 10, specifically focusing on the \Invoke\ method which processes script files from the Samples directory. This allows users to track execution speed and memory usage changes over time.

benchmarks/HydraScript.Benchmarks · high confidence

The application now includes a new dumping subsystem that automatically exports intermediate compiler outputs (tokens, AST, and virtual machine instructions) to files. This is implemented via new \DumpingLexer\, \DumpingParser\, and \DumpingVirtualMachine\ decorators that wrap the core components, using a keyed service registration to inject the dumping behavior. The \DumpingService\ writes these artifacts to the same directory as the input file, using the input filename with specific extensions (\.tokens\, \.dot\, \.tac\) to distinguish the output types.

src/Infrastructure/HydraScript.Infrastructure/Dumping · high confidence

This change adds the core infrastructure components for the HydraScript language, including an Executor that orchestrates parsing, static analysis, and code generation, and a CodeGenerator that utilizes a visitor pattern to produce instructions. It introduces a new StaticAnalyzer that supports extensible pre-analyzers, a SourceCodeProvider for file input, and a HydraScriptConsole for logging via ZLogger. Dependency injection is configured via ServiceCollectionExtensions, registering core services like the Lexer, Parser, and VirtualMachine, with optional dumping decorators for debugging. A GeneratedRegexContainer provides compiled regex patterns for the lexer.

src/Infrastructure/HydraScript.Infrastructure · high confidence

The HydraScript Intermediate Representation (IR) domain now includes a new symbol table system to manage variable scopes and symbol lookups. This change introduces the \ISymbolTable\ interface and its \SymbolTable\ implementation, which support adding symbols, managing open scopes, and performing generic lookups via \ISymbolId\. This infrastructure enables the compiler to correctly resolve identifiers within nested scopes, a prerequisite for features like default function parameters and variable initialization checks.

src/Domain/HydraScript.Domain.IR · high confidence

The Domain layer now includes new foundational classes: Call and FunctionInfo in the BackEnd for representing function calls; Token, Segment, Coordinates, and TokenType in the FrontEnd Lexer for lexical analysis; IFunctionArgument, DefaultValueArgument, TypeValue, and related types in the FrontEnd Parser for AST representation; Scope for managing variable scopes; and various SymbolId classes (FunctionSymbolId, TypeSymbolId, VariableSymbolId) and ObjectType in the IR for intermediate representation. These changes establish the core data structures for the language's frontend and backend processing.

Domain · high confidence

The backend now includes \CallFunction\ and \Simple\ instruction classes within the \WithAssignment\ namespace. \CallFunction\ handles function invocations, managing the call stack and frame context, while \Simple\ executes assignment and arithmetic/logical operations (including string concatenation via ZString and list/dictionary access). This introduces the core execution logic for these language constructs.

src/Domain/HydraScript.Domain.BackEnd/Impl/Instructions/WithAssignment · high confidence

The static analysis engine in HydraScript now allows defining multiple functions with the same name provided they have different parameter signatures. The \DeclarationVisitor\ implements logic to register these overloads in the symbol table, handling cases where parameters have default values by generating additional overload entries for each prefix of arguments. It also detects and reports ambiguous invocations when a function call could match multiple overloads. Additionally, the new \ReturnAnalyzer\ visitor checks that all code paths in a function end with a return statement, ensuring type safety for functions with defined return types.

src/Application/HydraScript.Application.StaticAnalysis/Visitors · high confidence

The static analysis layer for HydraScript has been initialized with a new set of interfaces and dependency registrations. This includes core services for managing symbol tables, type declarations, and standard library access, alongside specific storage mechanisms for handling ambiguous function invocations and functions with undefined returns. The system also registers visitors for building types, analyzing return statements, initializing symbol tables, loading the type system, resolving declarations, and performing semantic checks, establishing the foundation for compile-time validation.

src/Application/HydraScript.Application.StaticAnalysis · high confidence

The backend now supports complex data types, allowing users to create arrays and objects within \with\ assignments. Arrays are initialized with a specified size and filled with null values, while objects are created as empty dictionaries. Users can read from and write to these structures using dot notation for object properties (e.g., \obj.field\) and index notation for array elements (e.g., \arr\[index\]\).

src/Domain/HydraScript.Domain.BackEnd/Impl/Instructions/WithAssignment/ComplexData · high confidence

Users can now explicitly cast values to boolean, number, string, or other types within assignment instructions. This change introduces a new instruction hierarchy (AsInstruction) that handles the conversion logic, allowing expressions like assigning a value as a specific type (e.g., \x = y as bool\). The implementation supports casting to bool, double, and string, with string conversion utilizing JSON serialization for complex objects.

src/Domain/HydraScript.Domain.BackEnd/Impl/Instructions/WithAssignment/ExplicitCast · high confidence

The BasicBlock, BasicBlockBuilder, and ControlFlowGraph classes have been removed from the IR module. This eliminates the previous implementation of basic block construction and control-flow graph representation, indicating a shift in how the interpreter structures and analyzes its intermediate representation.

Interpreter.Lib/IR · high confidence

The \Interpreter.Lib/VM\ directory has been completely removed, deleting the legacy virtual machine implementation and its associated core components. This includes the \VirtualMachine\ class responsible for the instruction execution loop, as well as the supporting domain model classes \Call\, \Constant\, \Frame\, \FunctionInfo\, and \Name\. Users relying on this specific VM implementation will need to migrate to the new system referenced in the commit messages.

Interpreter.Lib/VM · high confidence

The \Interpreter.Lib/RBNF\ directory has removed the legacy lexical analysis infrastructure, including the \Lexer\, \Domain\, \Token\, \Segment\, and \Coordinates\ classes, as well as the \LexerException\ and \ParserException\ types. This cleanup eliminates the old token-based parsing foundation, indicating a shift toward a new internal representation or parsing strategy within the interpreter.

Interpreter.Lib/RBNF · high confidence

The \Interpreter.Lib/Semantic\ directory has been completely removed, deleting the legacy Abstract Syntax Tree (AST) implementation, the \SemanticAnalyzer\, and all associated semantic exception classes (such as \IncompatibleTypesOfOperands\, \WrongReturnType\, and \AssignmentToConst\). This change eliminates the previous code-generation and type-checking pipeline from this location, indicating a migration to a new semantic or compilation architecture.

Interpreter.Lib/Semantic · high confidence

The \LexerCreatorService\ and \ParserCreatorService\ interfaces and their implementations have been removed from the interpreter's service layer. This eliminates the dedicated factory components that previously instantiated the lexer and parser objects, indicating a shift in how lexical and syntactic analysis components are initialized or managed within the system.

Interpreter/Services · high confidence

The code generation layer has been restructured to separate general script instructions from expression-specific logic. A new \CodeGeneratorType\ enum distinguishes between \General\ and \Expression\ generators, with \InstructionProvider\ handling top-level statements (like loops, functions, and declarations) and delegating expression evaluation to \ExpressionInstructionProvider\. This separation allows for specialized handling of complex expressions, including array/object literals, binary/unary operations, explicit casts, and \with\ expressions, while \ValueFactory\ centralizes the creation of runtime values from AST nodes.

src/Application/HydraScript.Application.CodeGeneration · high confidence

The lexer infrastructure now uses a Roslyn incremental source generator (PatternGenerator) to automatically construct the regular expression pattern at compile time. This generator reads token definitions from a stream provider, orders them by priority, and emits a compiled PatternContainer class containing the combined regex pattern, replacing any previous manual or static configuration approaches.

src/Infrastructure/HydraScript.Infrastructure.LexerRegexGenerator · high confidence

The HydraScript back-end has been restructured to implement a clean architecture, introducing a new virtual machine that executes a linked list of addressed instructions. This change replaces the previous interpreter logic with a frame-based execution model, where \FrameContext\ manages a stack of execution frames (including environment variable frames) to handle variable scoping and state. The diff introduces core interfaces for the virtual machine, execution parameters, and executable instructions, along with specific jump instructions (Goto, IfNotGoto) to control flow, fundamentally changing how the language is interpreted at runtime.

src/Domain/HydraScript.Domain.BackEnd · high confidence

The HydraScript CLI has been updated to require a path to an input file as a positional argument and includes a new --dump (aliases -d, /d) option to display interpreter dump data. This change replaces the previous command-line interface structure, utilizing System.CommandLine for argument parsing and integrating ZLogger for console logging within the application's dependency injection setup.

src/HydraScript · high confidence

The parser's Abstract Syntax Tree (AST) has been completely restructured to support new language capabilities, including environment variable references (EnvVarReference), explicit type casting (CastAsExpression), and object spread syntax (WithExpression). The new node hierarchy introduces dedicated classes for complex literals like ObjectLiteral and ArrayLiteral, and updates function declarations to handle default argument values. This refactoring also integrates ZString for efficient AST stringification and ZLinq for optimized tree traversal, ensuring the parser can correctly model these expanded syntax elements.

src/Domain/HydraScript.Domain.FrontEnd/Parser · high confidence

The backend implementation now includes specific value types to handle constants and environment variables. A new \Constant\ class represents immutable literal values, while \EnvName\ and \Name\ classes manage variable references within execution frames. \EnvName\ specifically handles environment variable lookups (displayed with a \$\ prefix) and prevents frame switching, whereas the base \Name\ class supports standard variable get/set operations and frame updates.

src/Domain/HydraScript.Domain.BackEnd/Impl/Values · high confidence

The interpreter no longer requires an external \tokenTypes.json\ file to define lexical rules. The previous implementation, which relied on \QueryCreator\ to read and map this JSON file via AutoMapper, has been removed. This change simplifies the command-line interface by eliminating the need to specify a lexer configuration path, as token types are now handled directly in memory.

Interpreter · high confidence

The lexer in src/Domain/HydraScript.Domain.FrontEnd/Lexer/Impl has been replaced with a new regex-driven approach. RegexLexer now uses a generated regex pattern and a Structure class to iterate through matches, replacing the previous manual scanning logic. Token type resolution is handled by TokenTypesProvider, which orders types by priority and filters ignorable tokens. Text coordinate calculation (line/column) is now performed by TextCoordinateSystemComputer, which uses SearchValues for efficient newline detection to map absolute indices to user-friendly coordinates.

src/Domain/HydraScript.Domain.FrontEnd/Lexer/Impl · high confidence

The lexer module now exposes a set of core interfaces to define its contract: \ILexer\ for token generation, \IStructure\ for managing token types and regex patterns, \IGeneratedRegexContainer\ for regex access, \ITokenTypesProvider\ for retrieving token type mappings, and \ITextCoordinateSystemComputer\ for calculating line and column positions in source text. Additionally, a new \LexerException\ class has been added to handle lexer-specific errors, such as encountering unknown tokens.

src/Domain/HydraScript.Domain.FrontEnd/Lexer · high confidence

The domain constants module now provides the foundational lexical definitions for the HydraScript language. TokenTypes defines the regular expression patterns, tags, and priorities for all supported tokens, including identifiers, literals (integer, float, string, boolean, null), operators (including compound assignments like += and -=), keywords (such as let, const, function, if, else, while, break, continue, return, as, type, with), and punctuation. It also introduces support for shebang comments (\#!) and double-slash comments (//). Additionally, the module introduces constants for the End of Program (EOP) marker, jump keywords (break, continue), and a shim for IsExternalInit to support record structs.

src/Domain/HydraScript.Domain.Constants · high confidence

The backend now introduces two new address types: HashAddress, which generates unique names using a seed and random characters, and Label, which represents named addresses. These classes implement the IAddress interface and replace previous address handling logic in the backend.

src/Domain/HydraScript.Domain.BackEnd/Impl/Addresses · high confidence

The backend instruction implementation has been restructured to support a cleaner architecture. This change introduces new instruction types including BlockLabel (for managing function, loop, and condition scopes), Input (for reading console input), and Halt (for explicit execution termination). It also refactors existing logic, such as PopParameter now supporting default values and Return handling stack unwinding more explicitly, to align with the new System.CommandLine-driven design.

src/Domain/HydraScript.Domain.BackEnd/Impl/Instructions · high confidence

The symbol representation in the Intermediate Representation has been restructured to support function overloading and improved type resolution. A new \FunctionSymbol\ class now distinguishes functions by their parameter list, enabling the compiler to identify and handle overloaded functions. The symbol base class and specific types (Variable, Object, Type) have been refactored to use a generic \SymbolId\ system, improving type safety and equality checks. Additionally, \VariableSymbol\ now tracks initialization state to enforce variable initialization checks, and \TypeSymbol\ includes logic to resolve type references.

src/Domain/HydraScript.Domain.IR/Impl/Symbols · high confidence

The lexer's token type definitions have been restructured into specific record classes (EndOfProgramType, ErrorType, IgnorableType) within the TokenTypes directory. This change introduces explicit behavior for error handling and ignorable tokens, such as overriding the Error() and CanIgnore() methods, which likely improves how the lexer categorizes and processes these specific token kinds during compilation.

src/Domain/HydraScript.Domain.FrontEnd/Lexer/TokenTypes · medium confidence

The static analysis error handling has been reorganized to support a cleaner architecture. The base exception class, previously named EndOfProgramType, has been renamed to SemanticException and moved to the HydraScript.Application.StaticAnalysis.Exceptions namespace. A comprehensive set of specific semantic error classes has been introduced to provide detailed feedback for various language violations, including access before initialization, ambiguous function invocations, invalid array or object access, assignment restrictions (const, void, null), type mismatches, and function overload issues.

src/Application/HydraScript.Application.StaticAnalysis/Exceptions · high confidence

The internal type system in the HydraScript IR has been restructured to define types (such as \Any\, \ArrayType\, \BooleanType\, \NumberType\, \NullType\, \NullableType\, and \StringType\) as distinct classes that explicitly declare their supported operators (e.g., arithmetic, comparison, concatenation, indexing). This change introduces a new \IOperator\ interface and specific operator structs to manage type-checking logic for operations like array concatenation (\++\), removal (\::\), and length (\\~\), replacing the previous implicit or monolithic type handling with a more modular, operator-driven approach.

src/Domain/HydraScript.Domain.IR/Types · high confidence

The \Interpreter.Lib/IR/Instructions\ directory has been cleared of its previous instruction set, including \AsStringInstruction\, \CallInstruction\, \EndInstruction\, \GotoInstruction\, \IfNotGotoInstruction\, \Instruction\, \PopParametersInstruction\, \PrintInstruction\, \PushParameterInstruction\, \ReturnInstruction\, and \ThreeAddressCodeInstruction\. This deletion removes the existing virtual machine execution logic for operations such as function calls, control flow jumps, arithmetic, and printing, indicating a foundational refactor of the interpreter's intermediate representation.

Interpreter.Lib/IR/Instructions · high confidence

The project has been reorganized with a new solution file (ExtendedJavaScriptSubset.slnx) replacing the legacy CompilersCourseWork.sln, and the build target has been updated to .NET 10.0 via Directory.Build.props. This change includes enabling implicit usings and nullable reference types, configuring AOT compatibility, and setting up a new .editorconfig for consistent code formatting across the repository.

(repo-wide) · high confidence

The static analysis subsystem has been restructured to support more robust type checking and symbol resolution. This change introduces dedicated storage classes for managing ambiguous function invocations, functions with undefined returns, method bindings, and symbol tables, alongside a new service for handling HydraScript types and a provider for the standard library. Additionally, the type declaration resolver has been updated to utilize ZLinq for improved performance and to support generic symbol searching, enabling better handling of type conversions and default values during the analysis phase.

src/Application/HydraScript.Application.StaticAnalysis/Impl · high confidence

Added integration test infrastructure with xUnit 3 and Serilog logging; Added integration tests for HydraScript core features; Added integration tests for language error handling; Added test infrastructure for HydraScript unit tests; Added unit tests for BackEnd instructions and virtual machine; Added unit tests for HydraScript Application layer components; Added unit tests for IR type system operations; Added unit tests for the HydraScript lexer, parser, and AST nodes; Added unit tests for the Lexer Regex Generator's PatternContainer output; Expanded integration test coverage for HydraScript language features; Removed obsolete unit tests for AST, parser, and symbol table.

The project now uses a centralized \Directory.Packages.props\ file to manage dependency versions, ensuring consistency across all projects. This change introduces several library updates, including migrating the testing framework from xUnit v2 to xunit.v3, replacing FluentAssertions with AwesomeAssertions, and upgrading Microsoft.Extensions packages to version 10.0.11. Additionally, new dependencies such as System.IO.Abstractions, ZLogger, ZString, and ZLinq have been added, while older packages like AutoMapper, CliWrap, and Newtonsoft.Json have been removed.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 57 → 66 (+8.9)
• Rubric changed (rubric-2026.08.18 → rubric-2026.09.15) — scores are not directly comparable.

• Code Health 95 → 82 (-13.1)
• Architecture 84 → 84 (+0.2)
• Maturity 52 → 77 (+25.6)
• Readiness 52 → 52 (+0.0)
• Security 60 → 76 (+16.2)
• Domain Modelling 100 (new)
• Performance 80 → 80 (+0.0)

• Bounded contexts not declared
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• …and 11 more

• CoverageExclusion (benchmarks/HydraScript.Benchmarks/Program.cs)
• CoverageExclusion (src/Application/HydraScript.Application.StaticAnalysis/Exceptions/AccessBeforeInitialization.cs)
• CoverageExclusion (src/Application/HydraScript.Application.StaticAnalysis/Exceptions/AmbiguousInvocation.cs)
• CoverageExclusion (src/Application/HydraScript.Application.StaticAnalysis/Exceptions/ArrayAccessException.cs)
• CoverageExclusion (src/Application/HydraScript.Application.StaticAnalysis/Exceptions/AssignmentToConst.cs)
• CoverageExclusion (src/Application/HydraScript.Application.StaticAnalysis/Exceptions/CannotAssignNullWhenUndefined.cs)
• CoverageExclusion (src/Application/HydraScript.Application.StaticAnalysis/Exceptions/CannotAssignVoid.cs)
• CoverageExclusion (src/Application/HydraScript.Application.StaticAnalysis/Exceptions/CannotDefineType.cs)
• CoverageExclusion (src/Application/HydraScript.Application.StaticAnalysis/Exceptions/ConstWithoutInitializer.cs)
• CoverageExclusion (src/Application/HydraScript.Application.StaticAnalysis/Exceptions/DeclarationAlreadyExists.cs)
• CoverageExclusion (src/Application/HydraScript.Application.StaticAnalysis/Exceptions/ExplicitCastNotSupported.cs)
• CoverageExclusion (src/Application/HydraScript.Application.StaticAnalysis/Exceptions/FunctionWithoutReturnStatement.cs)
• CoverageExclusion (src/Application/HydraScript.Application.StaticAnalysis/Exceptions/IncompatibleTypesOfOperands.cs)
• CoverageExclusion (src/Application/HydraScript.Application.StaticAnalysis/Exceptions/NamedArgumentAfterDefaultValueArgument.cs)
• CoverageExclusion (src/Application/HydraScript.Application.StaticAnalysis/Exceptions/NonAccessibleType.cs)
• CoverageExclusion (src/Application/HydraScript.Application.StaticAnalysis/Exceptions/NotBooleanTestExpression.cs)
• CoverageExclusion (src/Application/HydraScript.Application.StaticAnalysis/Exceptions/ObjectAccessException.cs)
• CoverageExclusion (src/Application/HydraScript.Application.StaticAnalysis/Exceptions/OutsideOfStatement.cs)
• CoverageExclusion (src/Application/HydraScript.Application.StaticAnalysis/Exceptions/OverloadAlreadyExists.cs)
• CoverageExclusion (src/Application/HydraScript.Application.StaticAnalysis/Exceptions/ReturnOutsideFunction.cs)
• …and 64 more

• 5 commits — 5 feature/other, 0 fixes

• .github/workflows — 2 commits
• (root) — 1 commit
• docs/adr — 1 commit
• tests/HydraScript.UnitTests — 1 commit

• change: chore(deps): bump packages (#250)
• change: chore: bump packages (#249)
• change: chore: editorcondig (#252)
• change: docs(ai): agents (#253)
• change: test(naming): roy osherove (#251)

• Unchanged — 1 containers · 1 contexts · 0 edges

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

Stepami/hydrascript was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.