Fix IntervalValue equality/bitshift stubs, expose CopyKind, preserve AbstractState subclass identity

[yuleisui]

Summary

Fixes several mismatches between the Python bindings/stubs and the actual C++ implementation/behavior in pysvf:

1. IntervalValue.__eq__/__ne__ returned bool, not IntervalValue. The binding called equals() (bool), while the stub already documented (and C++'s operator==/operator!= actually implement) an abstract-domain result ([1,1]/[0,0]/[0,1]). Rewired the bindings to call operator==/operator!=, and added __bool__ (true only for a definite [1,1]) so common if a == b: patterns keep behaving correctly. Also fixed equals()'s stub, which was mistakenly typed as returning IntervalValue instead of bool.

2. CopyKind enum was missing from the bindings, so callers had to guess raw integer values to detect zext/trunc/etc. copy kinds. Added a CopyKind(IntEnum) to pysvf/enums.py mirroring CopyStmt::CopyKind, following the same convention already used for Predicate/OpCode.

3. AbstractState.clone()/widening()/narrowing() always constructed a plain AbstractState in C++, silently discarding any Python subclass (e.g. a class AEState(AbstractState): ... pattern, as used in the SVF course material). Reconstruct an instance of the caller's actual runtime type instead.

4. isCmpBranchFeasible/isSwitchBranchFeasible don't exist in the C++ library (the real AbstractInterpretation methods are private) and the stub had an incorrect argument count (missing the leading SVFIR/pag argument) and wasn't marked @staticmethod, despite the binding being a def_static. Documented these as pysvf-only helpers in the stub and fixed the signatures to match the real 4-arg binding.

5. IntervalValue.__lshift__/__rshift__ stubs were typed as taking int for the RHS, but the binding accepts another IntervalValue (py::self << py::self).

Validation

• Rebuilt the extension (against a matching svf-lib/LLVM 21 toolchain) and ran the SVF course's Assignment-3 material (Software-Security-Analysis / Software-Security-Analysis-Sol) against it.
• Full 120-case .ll regression corpus passes identically before/after these changes (120/120, 69/69 assertions verified, 0 regressions vs. a pre-fix build using the same SVF/LLVM version).
• Directly exercised the new equality/__bool__, CopyKind, and subclass-preservation behavior against real compiled IR and confirmed correctness.
• stubtest passes with the existing stubtest_allowlist.txt.

No behavioral changes were made to isCmpBranchFeasible/isSwitchBranchFeasible's underlying logic — only their stub signatures were corrected.

[Copilot]

Pull request overview

This PR aligns pysvf’s Python bindings and type stubs with SVF’s intended abstract-domain semantics and the actual pybind-exposed APIs, especially around IntervalValue equality/bitshifts, AbstractState subclass preservation, and feasibility helper signatures. It also exposes CopyStmt copy kinds to Python callers via a new enum.

Changes:

• Rewire IntervalValue equality to return an abstract-domain IntervalValue result and add __bool__ to make common if a == b: patterns work sensibly.
• Add CopyKind(IntEnum) mirroring SVF::CopyStmt::CopyKind and export it from pysvf.__init__.
• Preserve Python subclass identity for AbstractState.clone()/widening()/narrowing() and correct stub signatures for feasibility helpers and shift operators.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
pysvf/pysvf.pyi	Updates stubs for IntervalValue shifts/equality helpers and corrects AbstractState static helper signatures + documentation.
pysvf/enums.py	Adds CopyKind enum for CopyStmt copy-kind inspection.
pysvf/init.py	Re-exports CopyKind from the package top-level.
pybind/AE.cpp	Adjusts IntervalValue equality/truthiness semantics and preserves AbstractState Python subclass identity in clone/widen/narrow.

Suppressed comments (1)

pybind/AE.cpp:135

• __bool__ currently gates on is_numeral() but then calls getIntNumeral(). If is_numeral() can also be true for real numerals (suggested by the presence of is_real()/getRealNumeral()), this can throw or assert for non-integer numerals.

Using is_int() avoids calling getIntNumeral() on non-integer values while preserving the intended [1,1] truthiness semantics.

        .def("__bool__", [](const IntervalValue &self) {
            return self.is_numeral() && self.getIntNumeral() == 1;
        })

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.