feat(ir): Add BreakStmt and ContinueStmt IR nodes

[Hzfengsy]

Summary

Add BreakStmt and ContinueStmt IR nodes for loop control flow (break and continue). Both are minimal leaf statements with no fields (only inherited Span), used inside ForStmt/WhileStmt loop bodies.

Changes across all three layers (18 files):

• C++ core: ObjectKind enum entries, class definitions in stmt.h, KindTrait entries
• Visitor/mutator framework: functor dispatch, visitor (empty leaf), mutator (identity return)
• IR infrastructure: python printer ("break"/"continue"), structural hash, structural equality, serialization, deserialization
• Python bindings: nanobind class bindings with BindFields
• Type stubs: .pyi entries with docstrings
• Documentation: BNF grammar and statement tables in 01-hierarchy.md

Testing

• 48 new tests across test_break_stmt.py and test_continue_stmt.py covering:
  • Creation, type hierarchy, span, immutability
  • python_print, structural hash, structural equality
  • Serialization/deserialization roundtrip
  • Cross-type inequality (break != continue != other stmts)
  • Composition inside ForStmt and WhileStmt bodies
  • Conditional break/continue inside IfStmt within loops
  • Nested loop structures with break/continue
• Full test suite passes (1339 tests, 0 failures)

Related Issues

Closes #166
Closes #167

[gemini-code-assist]

Summary of Changes

Hello @Hzfengsy, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request enhances the Intermediate Representation (IR) system by adding dedicated nodes for break and continue statements. This allows for a more accurate and complete representation of loop control flow within the IR, which is crucial for subsequent analysis and optimization passes. The changes ensure that these new statements are fully supported throughout the IR's lifecycle, from definition to serialization and transformation.

Highlights

• New IR Nodes: Introduced BreakStmt and ContinueStmt as new Intermediate Representation (IR) nodes to represent loop control flow statements.
• Comprehensive Integration: The new IR nodes are integrated across all layers of the system, including C++ core definitions, visitor/mutator framework, IR infrastructure (Python printer, structural hash/equality, serialization/deserialization), Python bindings, type stubs, and documentation.
• Extensive Testing: Added 48 new unit tests specifically for BreakStmt and ContinueStmt, covering creation, type hierarchy, span, immutability, python_print output, structural hashing and equality, serialization/deserialization roundtrips, and composition within ForStmt and WhileStmt bodies, including conditional and nested scenarios.

Changelog

• docs/dev/ir/01-hierarchy.md
  • Updated the BNF grammar to include break_stmt and continue_stmt.
  • Expanded the statement tables to list BreakStmt and ContinueStmt with their descriptions.
• include/pypto/ir/core.h
  • Added BreakStmt and ContinueStmt entries to the ObjectKind enum.
• include/pypto/ir/kind_traits.h
  • Defined KindTrait for BreakStmt and ContinueStmt.
  • Updated the Stmt base class KindTrait to include BreakStmt and ContinueStmt.
• include/pypto/ir/stmt.h
  • Defined the BreakStmt class, inheriting from Stmt.
  • Defined the ContinueStmt class, inheriting from Stmt.
• include/pypto/ir/transforms/base/functor.h
  • Added virtual VisitStmt_ methods for BreakStmt and ContinueStmt to StmtFunctor.
  • Updated the STMT_FUNCTOR_DISPATCH macro to include BreakStmt and ContinueStmt.
• include/pypto/ir/transforms/base/mutator.h
  • Added VisitStmt_ method declarations for BreakStmt and ContinueStmt to IRMutator.
• include/pypto/ir/transforms/base/visitor.h
  • Added VisitStmt_ method declarations for BreakStmt and ContinueStmt to IRVisitor.
• python/bindings/modules/ir.cpp
  • Added nanobind class bindings for BreakStmt and ContinueStmt, including their constructors and field descriptors.
• python/pypto/pypto_core/ir.pyi
  • Added type stub definitions for BreakStmt with docstrings.
  • Added type stub definitions for ContinueStmt with docstrings.
• src/ir/serialization/serializer.cpp
  • Updated the IRSerializer implementation to serialize BreakStmt and ContinueStmt fields.
• src/ir/serialization/type_deserializers.cpp
  • Added DeserializeBreakStmt function for deserializing BreakStmt.
  • Added DeserializeContinueStmt function for deserializing ContinueStmt.
  • Registered BreakStmt and ContinueStmt with the type deserializer system.
• src/ir/transforms/mutator.cpp
  • Implemented VisitStmt_ for BreakStmt in IRMutator to return the original leaf node.
  • Implemented VisitStmt_ for ContinueStmt in IRMutator to return the original leaf node.
• src/ir/transforms/python_printer.cpp
  • Added VisitStmt_ method declarations for BreakStmt and ContinueStmt to IRPythonPrinter.
  • Implemented VisitStmt_ for BreakStmt to print the string 'break'.
  • Implemented VisitStmt_ for ContinueStmt to print the string 'continue'.
• src/ir/transforms/structural_equal.cpp
  • Updated StructuralEqualImpl to include dispatch for BreakStmt and ContinueStmt.
• src/ir/transforms/structural_hash.cpp
  • Updated StructuralHasher to include dispatch for BreakStmt and ContinueStmt.
• src/ir/transforms/visitor.cpp
  • Implemented VisitStmt_ for BreakStmt in IRVisitor as a leaf node.
  • Implemented VisitStmt_ for ContinueStmt in IRVisitor as a leaf node.
• tests/ut/ir/statements/test_break_stmt.py
  • Added a new file containing comprehensive unit tests for BreakStmt.
• tests/ut/ir/statements/test_continue_stmt.py
  • Added a new file containing comprehensive unit tests for ContinueStmt.

Activity

• The pull request introduces two new Intermediate Representation (IR) nodes: BreakStmt and ContinueStmt.
• The C++ core, including ObjectKind enum and KindTrait definitions, has been updated to recognize these new statement types.
• The visitor and mutator frameworks have been extended to properly handle BreakStmt and ContinueStmt.
• IR infrastructure components like the Python printer, structural hash, structural equality, and serialization/deserialization mechanisms have been adapted.
• Python bindings and type stubs (.pyi files) have been added to expose the new IR nodes to Python.
• Documentation, specifically the BNF grammar and statement tables, has been updated to reflect the new IR nodes.
• A total of 48 new tests were added across test_break_stmt.py and test_continue_stmt.py to validate the functionality and integration of the new nodes.
• The full test suite passed, confirming that the changes do not introduce regressions.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces BreakStmt and ContinueStmt IR nodes, which is a great addition for loop control flow. The changes are very thorough, touching all necessary layers of the IR framework from the C++ core and visitor patterns to serialization, Python bindings, and documentation. The new tests are comprehensive and cover many important cases.

I have one suggestion regarding the new test files to improve maintainability by reducing code duplication. Overall, this is an excellent and well-executed feature addition.

[Copilot]

Pull request overview

This PR adds BreakStmt and ContinueStmt IR nodes to support loop control flow statements (break and continue). These are minimal leaf statement nodes with only an inherited Span field, designed for use inside ForStmt and WhileStmt loop bodies. The implementation is comprehensive and consistent, spanning all three layers of the codebase: C++ core, Python bindings, and type stubs, along with documentation and extensive test coverage.

Changes:

• Added two new IR statement node types (BreakStmt and ContinueStmt) following the established pattern for leaf statements
• Updated all visitor/mutator infrastructure, serialization/deserialization, structural comparison, and printing facilities
• Provided comprehensive test coverage with 48 new tests covering basic functionality, composition, and edge cases
• Updated documentation with BNF grammar and node hierarchy tables

Reviewed changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
include/pypto/ir/core.h	Added BreakStmt and ContinueStmt to ObjectKind enum
include/pypto/ir/stmt.h	Added BreakStmt and ContinueStmt class definitions with proper field descriptors
include/pypto/ir/kind_traits.h	Added KindTrait entries and updated Stmt base class trait count from 10 to 12
include/pypto/ir/transforms/base/functor.h	Added functor dispatch entries for both statement types
include/pypto/ir/transforms/base/visitor.h	Added visitor method declarations
include/pypto/ir/transforms/base/mutator.h	Added mutator method declarations
src/ir/transforms/visitor.cpp	Added empty visitor implementations for leaf nodes
src/ir/transforms/mutator.cpp	Added identity mutator implementations for leaf nodes
src/ir/transforms/python_printer.cpp	Added printer implementations outputting "break" and "continue"
src/ir/transforms/structural_hash.cpp	Added hash dispatch entries
src/ir/transforms/structural_equal.cpp	Added equality dispatch entries
src/ir/serialization/serializer.cpp	Added serialization dispatch
src/ir/serialization/type_deserializers.cpp	Added deserialization functions and registrars
python/bindings/modules/ir.cpp	Added nanobind class bindings with docstrings
python/pypto/pypto_core/ir.pyi	Added type stub entries with complete docstrings
docs/dev/ir/01-hierarchy.md	Updated BNF grammar, statement table, and node count summary
tests/ut/ir/statements/test_break_stmt.py	Added 24 comprehensive tests (445 lines)
tests/ut/ir/statements/test_continue_stmt.py	Added 24 comprehensive tests (445 lines)