Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
"""What a signature change does to a caller, decided from the two indexed signatures.
Signatures are written the way the indexer emits them (``def f(...) -> T``,
``function f(...) -> T``, ``fn f(...)``, ``func (r *T) M(...)``, ``f(int a) -> T``).
"""
from __future__ import annotations
import pytest
from repowise.core.analysis.signature_effect import (
EFFECT_BREAKING,
EFFECT_COMPATIBLE,
EFFECT_NONE,
EFFECT_UNKNOWN,
bound_names,
classify_signature_change,
parameter_names,
)
BREAKS = {EFFECT_BREAKING, EFFECT_UNKNOWN}
def _effect(before: str, after: str, lang: str | None, kind: str | None = "function"):
return classify_signature_change(before, after, lang, kind)
@pytest.mark.parametrize(
("before", "after", "lang"),
[
("def run(self, x, y) -> int", "def run(\n self,\n x,\n y\n) -> int", "python"),
("def run(x, y)", "def run(x, y,)", "python"),
# Comments, including an inline one with an apostrophe.
("def f(a, b=1)", "def f(\n a, # the drawer's row\n b=1,\n)", "python"),
("def f(\n a, # it's\n b=1,\n)", "def f(\n a,\n # b's default\n b=1,\n)", "python"),
# Rust lifetimes are not string quotes.
("fn f(x: &'a str) -> &'a str", "fn f(\n x: &'a str,\n) -> &'a str", "rust"),
# Go's grouped parameters are the same parameters.
("function F(a, b int)", "function F(a int, b int)", "go"),
# Reordering keyword-only parameters moves nothing a caller passes by position.
("def f(a, *, b=1, c=2)", "def f(a, *, c=2, b=1)", "python"),
("void f(String a, Integer b)", "void f(\n String a,\n Integer b\n)", "apex"),
],
)
def test_text_only_changes_have_no_effect(before, after, lang):
assert _effect(before, after, lang).effect == EFFECT_NONE
@pytest.mark.parametrize(
("before", "after", "lang", "reason"),
[
("def run(x)", "def run(x, y=None)", "python", "added optional `y`"),
(
"function run(a: string)",
"function run(a: string, b?: number)",
"typescript",
"added optional `b`",
),
("def run(x, y)", "def run(x, y=1)", "python", "`y` is now optional"),
("def run(x)", "def run(x: int)", "python", "annotated `x`"),
("def run(x) -> int", "def run(x) -> str", "python", "changed its return annotation"),
("def f(a, t=30)", "def f(a, t='30s')", "python", "changed the default of `t`"),
("def f(mode='async')", "def f(mode='sync')", "python", "changed the default of `mode`"),
(
"def f(a, b, /)",
"def f(a, b)",
"python",
"`a` can now be passed by name and `b` can now be passed by name",
),
# Callers of these languages never name an argument.
(
"function f(a)",
"function f(b)",
"javascript",
"renamed `a` to `b`, which callers never name",
),
(
"function F(a int)",
"function F(b int)",
"go",
"renamed `a` to `b`, which callers never name",
),
(
"f(int a) -> void",
"f(int b) -> void",
"java",
"renamed `a` to `b`, which callers never name",
),
(
"void f(String a) -> void",
"void f(String b) -> void",
"apex",
"renamed `a` to `b`, which callers never name",
),
("function F(a int)", "function F(a int, opts ...Opt)", "go", "added `...opts`"),
("f(String[] a) -> void", "f(String... a) -> void", "java", "now takes `a` as varargs"),
(
"function C({a, b}: {a: string; b: number})",
"function C({a, b}: {a: string; b?: number})",
"typescript",
"member `b` is now optional",
),
(
"function C({a}: {a: string})",
"function C({a}: {a: string; b?: number})",
"typescript",
"added optional member `b`",
),
("func (t *T) M(a int)", "func (t T) M(a int)", "go", "moved to a value receiver"),
],
)
def test_changes_every_existing_call_survives_are_compatible(before, after, lang, reason):
effect = _effect(before, after, lang)
assert effect.effect == EFFECT_COMPATIBLE
assert effect.reason == reason
@pytest.mark.parametrize(
("before", "after", "lang", "reason"),
[
("def run(x, y)", "def run(x)", "python", "removed the required `y`"),
("def run(x)", "def run(x, y)", "python", "added the required `y`"),
("def run(x, y=1)", "def run(x, y)", "python", "`y` is now required"),
("def run(x, y)", "def run(y, x)", "python", "reordered its parameters"),
(
"def f(a, timeout=1)",
"def f(a, deadline=1)",
"python",
"renamed `timeout` to `deadline`",
),
("F(int count) -> void", "F(int n) -> void", "csharp", "renamed `count` to `n`"),
(
"def run(x)",
"async def run(x)",
"python",
"became async, so its callers' await changes",
),
# An optional parameter inserted ahead of one callers pass by position.
("def f(a, b=1)", "def f(a, c=None, b=1)", "python", "inserted `c` before `b`"),
(
"function f(a: string, b?: number)",
"function f(a: string, c?: string, b?: number)",
"typescript",
"inserted `c` before `b`",
),
("def f(a, *args)", "def f(a, b=None, *args)", "python", "inserted `b` before `*args`"),
# Variadics are told apart by kind.
("def f(a, *args, **kw)", "def f(a, **kw)", "python", "removed `*args`"),
("def f(a, *args, **kw)", "def f(a, *args)", "python", "removed `**kw`"),
("def f(a, *args)", "def f(a, **kw)", "python", "removed `*args`"),
("def f(a, b=1)", "def f(a, *args, b=1)", "python", "made `b` keyword-only"),
("def f(a, b=1)", "def f(a, *, b=1)", "python", "made `b` keyword-only"),
(
"def f(a, b)",
"def f(a, b, /)",
"python",
"made `a` positional-only and made `b` positional-only",
),
# Shifts in a default value are operators, not generics.
("def f(a=1 << 4, b=2, c=8 >> 1)", "def f(a=1 << 4, c=8 >> 1)", "python", "removed `b`"),
("func (t T) M(a int)", "func (t *T) M(a int)", "go", "moved to a pointer receiver"),
# Typed languages: a retype or a new return type breaks the call.
(
"function f(x: string)",
"function f(x: number)",
"typescript",
"changed the type of `x` from `string` to `number`",
),
(
"function f() -> Promise<void>",
"function f() -> void",
"typescript",
"changed its return type from `Promise<void>` to `void`",
),
(
"fn f(x: &str)",
"fn f(x: &mut str)",
"rust",
"changed the type of `x` from `&str` to `&mut str`",
),
(
"fn f(x: u32) -> u32",
"fn f(x: u32) -> Result<u32, E>",
"rust",
"changed its return type from `u32` to `Result<u32, E>`",
),
(
"function F(a int) -> int",
"function F(a int) -> (int, error)",
"go",
"changed its return type from `int` to `(int, error)`",
),
(
"func (s *S) F(a int) -> int",
"func (s *S) F(a int) -> (int, error)",
"go",
"changed its return type from `int` to `(int, error)`",
),
(
"foo(int a) -> int",
"foo(int a) -> String",
"java",
"changed its return type from `int` to `String`",
),
(
"Foo(int a) -> int",
"Foo(int a) -> string",
"csharp",
"changed its return type from `int` to `string`",
),
(
"foo(String a) -> void",
"foo(String a) -> Integer",
"apex",
"changed its return type from `void` to `Integer`",
),
(
"foo(String[] a) -> void",
"foo(String a) -> void",
"apex",
"changed the type of `a` from `String[]` to `String`",
),
(
"function C({a}: {a: string})",
"function C({a, b}: {a: string; b: number})",
"typescript",
"added the required member `b`",
),
(
"operator()(int a) -> int",
"operator()(int a, int b) -> int",
"cpp",
"added the required `b`",
),
],
)
def test_changes_that_can_break_a_call_are_breaking(before, after, lang, reason):
effect = _effect(before, after, lang)
assert effect.effect == EFFECT_BREAKING
assert effect.reason == reason
def test_a_static_method_gaining_self_breaks_calls_through_the_class():
effect = _effect("def f(a)", "def f(self, a)", "python", kind="method")
assert effect.effect == EFFECT_BREAKING
assert effect.reason == "became an instance method, so calls through the class break"
def test_a_classmethod_becoming_static_is_compatible():
effect = _effect("def f(cls, a)", "def f(a)", "python", kind="method")
assert effect.effect == EFFECT_COMPATIBLE
def test_a_leading_self_is_a_parameter_of_a_module_function():
effect = _effect("def f(self, a)", "def f(a)", "python", kind="function")
assert effect.effect == EFFECT_BREAKING
def test_a_named_type_swapped_for_another_is_unknown_not_safe():
effect = _effect("function C({a}: OldProps)", "function C({a}: NewProps)", "typescript")
assert effect.effect == EFFECT_UNKNOWN
def test_an_unbalanced_parameter_list_is_unknown_not_safe():
effect = _effect("def run(x, y)", "def run(x, y: Dict[str, int)", "python")
assert effect.effect == EFFECT_UNKNOWN
def test_without_a_language_types_and_names_both_count():
assert _effect("f(x: A)", "f(x: B[])", None).effect in BREAKS
assert _effect("f(a)", "f(b)", None).effect in BREAKS
def test_async_is_read_from_the_signature_prefix_only():
effect = _effect("def f(mode='async')", "def f(mode='async', x=1)", "python")
assert effect.effect == EFFECT_COMPATIBLE
def test_an_arrow_type_does_not_unbalance_the_list():
before = "function run(cb: (a: number) => void)"
after = "function run(cb: (a: number) => void, opts?: Options)"
assert _effect(before, after, "typescript").effect == EFFECT_COMPATIBLE
def test_a_lambda_default_does_not_split_the_list():
before = "def f(a, key=lambda x, y: x)"
after = "def f(a, key=lambda x, y: x, b=2)"
assert _effect(before, after, "python").reason == "added optional `b`"
def test_a_block_comment_inside_the_signature_does_not_make_it_unparseable():
before = "function Drawer({\n row,\n}: {\n /** The drawer's row. */\n row: Row;\n})"
after = (
"function Drawer({\n row,\n onClose,\n}: {\n /** The drawer's row. */\n"
" row: Row;\n onClose?: () => void;\n})"
)
assert _effect(before, after, "typescript").effect == EFFECT_COMPATIBLE
def test_a_widened_parameter_or_narrowed_return_type_is_compatible():
widened = _effect("function f(x: string)", "function f(x: string | null)", "typescript")
assert widened.effect == EFFECT_COMPATIBLE
narrowed = _effect("function f() -> string | null", "function f() -> string", "typescript")
assert narrowed.effect == EFFECT_COMPATIBLE
# The reverse promises callers something new to handle.
widened_return = _effect(
"function f() -> string", "function f() -> string | null", "typescript"
)
assert widened_return.effect == EFFECT_BREAKING
def test_apex_parameter_and_bound_names():
sig = "findByName(String name, List<Id> ids) -> List<Account>"
assert parameter_names(sig, "apex") == (None, ["name", "ids"])
assert bound_names(sig, "apex") == {"name", "ids"}