@allansantos-dev/smart-tool 0.9.80 → 0.9.81

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/pr_impact.py CHANGED
@@ -2,27 +2,31 @@
2
2
 
3
3
  It joins what Smart Tool already computes: the functions the diff touches and the tests to run (affected_tests), the
4
4
  callers of each touched function and the tests that reach it (code_impact), the documentation anchors the change leaves
5
- out of date (doc_scope), the files that usually change with the diff's files and are missing from it (code_health), the decision
6
- notes that name a touched function (dossier) and the notes the edit hook would have added to the whole diff (hook_decision).
5
+ out of date (doc_scope), the files that usually change with the diff's files and are missing from it, the import cycles
6
+ through the changed files and the changed files that are hotspots (code_health), the new functions no caller or test reaches (code_health), the callers that still name a function
7
+ the diff removed or renamed and the callers of those whose signature changed (removed_callers), the decision notes that name a touched function (dossier) and the notes the
8
+ edit hook would have added to the whole diff (hook_decision).
7
9
  Nothing is published: the agent pastes the report where it belongs.
8
10
  """
9
11
  import os
10
- import re
11
12
 
12
13
  import affected_tests
13
14
  import code_health
14
15
  import code_impact
15
16
  import config
17
+ import doc_check
16
18
  import doc_scope
17
19
  import dossier
18
20
  import hook_decision
21
+ import removed_callers
19
22
 
20
23
  MAX_FUNCTIONS = 15
21
24
  MAX_CALLERS = 8
22
25
  TEST_DEPTH = 3
23
26
  MAX_CHECKED_FILES = 50
24
27
  MAX_COUPLED = 10
25
- MAX_NOTES_PER_FUNCTION = 2
28
+ MAX_HOTSPOTS = 10
29
+ ALL_ROWS = 100000
26
30
 
27
31
 
28
32
  def _callers(root, label, view_id):
@@ -34,34 +38,119 @@ def _callers(root, label, view_id):
34
38
  return found["callers"], found["counts"]["callers"], found["counts"]["tests"]
35
39
 
36
40
 
37
- def _hook_notes(root, base, changes):
38
- """The edit hook's notes over the changed files of the diff, which commits made without the hook never got.
41
+ def _versions(root, base, changes):
42
+ """The text of each changed file at the base and now.
39
43
 
40
44
  Parameters: root (str) project folder; base (str) git revision; changes (dict) the `affected_tests.affected` answer.
41
- Returns: tuple (str notes, "" when nothing is worth saying; str problem, "" when the checks ran).
45
+ Returns: list of (project-relative path, absolute path, text at the base or None when the file is new, text now or None
46
+ when the file is gone); files that cannot be read as text are left out.
42
47
  """
43
48
  paths = sorted({*changes["changed"]["code"], *changes["changed"]["tests"], *changes["changed"]["other"]})
44
- triples = []
49
+ found = []
45
50
  for rel in paths[:MAX_CHECKED_FILES]:
46
51
  full = os.path.join(root, *rel.split("/"))
47
- if not os.path.isfile(full):
48
- continue
49
- try:
50
- with open(full, encoding="utf-8") as stream:
51
- after = stream.read()
52
- except (OSError, UnicodeDecodeError):
53
- continue
52
+ after = None
53
+ if os.path.isfile(full):
54
+ try:
55
+ with open(full, encoding="utf-8") as stream:
56
+ after = stream.read()
57
+ except (OSError, UnicodeDecodeError):
58
+ continue
54
59
  try:
55
60
  before = affected_tests._git(root, "show", f"{base}:./{rel}")
56
61
  except ValueError:
57
62
  before = None
58
- triples.append((full, before, after))
63
+ found.append((rel, full, before, after))
64
+ return found
65
+
66
+
67
+ def _hook_notes(versions):
68
+ """The edit hook's notes over the changed files of the diff, which commits made without the hook never got.
69
+
70
+ Parameters: versions (list) `_versions` of the diff.
71
+ Returns: tuple (str notes, "" when nothing is worth saying; str problem, "" when the checks ran).
72
+ """
73
+ triples = [(full, before, after) for _rel, full, before, after in versions if after is not None]
59
74
  try:
60
75
  return hook_decision.review_diff(triples, config.load_config()), ""
61
76
  except (OSError, ValueError, RuntimeError) as exc:
62
77
  return "", f"the edit checks could not run: {exc}"
63
78
 
64
79
 
80
+ def _reviewed(root, versions, changed_code, review, key, what):
81
+ """The answers of `review` over the changed code files that have something under `key`, or the reason it could not run.
82
+
83
+ Returns: tuple (list of answers; str problem, "" when the check ran).
84
+ """
85
+ answers = []
86
+ try:
87
+ for rel, _full, before, after in versions:
88
+ if rel in changed_code:
89
+ answer = review(root, rel, before, after or "")
90
+ if answer[key]:
91
+ answers.append(answer)
92
+ except (OSError, ValueError, RuntimeError) as exc:
93
+ return answers, f"the callers of {what} could not be read: {exc}"
94
+ return answers, ""
95
+
96
+
97
+ def _removed_callers(root, versions, changed_code):
98
+ """The callers that still name a function the diff removed or renamed, in the changed code files.
99
+
100
+ Returns: tuple (list of answers of `removed_callers.review`, one per file that lost a function; str problem, "" when the
101
+ check ran).
102
+ """
103
+ return _reviewed(root, versions, changed_code, removed_callers.review, "removed", "removed functions")
104
+
105
+
106
+ def _signature_callers(root, versions, changed_code):
107
+ """The callers outside the file of the functions whose signature the diff changed, in the changed code files.
108
+
109
+ Returns: tuple (list of answers of `removed_callers.signature_review`, one per file with a changed signature; str problem,
110
+ "" when the check ran).
111
+ """
112
+ return _reviewed(root, versions, changed_code, removed_callers.signature_review, "changed", "functions with a changed signature")
113
+
114
+
115
+ def _also_defined(item):
116
+ return f" A function named {item['name'].rpartition('.')[2]} also exists in {', '.join(item['also_defined_in'])}." \
117
+ if item["also_defined_in"] else ""
118
+
119
+
120
+ def _callers_section(answers, problem, title, key, finding, quiet_text):
121
+ """The Markdown lines of one caller section, none when there is nothing to say.
122
+
123
+ Parameters: answers (list) of `removed_callers` answers; problem (str) why the check could not run, "" when it ran;
124
+ title (str) the `###` heading; key (str) the answer key holding the names of the functions concerned; finding (str)
125
+ format of a caller line over `item` and `sites`; quiet_text (str) format of the line for names with no caller.
126
+ """
127
+ if not answers and not problem:
128
+ return []
129
+ lines = [f"### {title}", ""]
130
+ for answer in answers:
131
+ for item in answer["findings"]:
132
+ lines.append(finding.format(item=item, sites=removed_callers.sites_text(item), also=_also_defined(item)))
133
+ quiet = [name for name in answer[key] if name not in {item["name"] for item in answer["findings"]}]
134
+ if quiet:
135
+ lines.append(quiet_text.format(names=", ".join(f"`{name}`" for name in quiet)))
136
+ lines += list(dict.fromkeys(answer["note"] for answer in answers if answer["note"]))
137
+ return lines + ([problem] if problem else []) + [""]
138
+
139
+
140
+ def _removed_lines(answers, problem):
141
+ """The Markdown lines of the section on removed or renamed functions, none when the diff removes no function."""
142
+ return _callers_section(answers, problem, "Callers of removed or renamed functions", "removed",
143
+ "- `{item[name]}` ({item[path]}) is gone and is still called from {sites}.{also}",
144
+ "No caller was found for the removed {names}.")
145
+
146
+
147
+ def _signature_lines(answers, problem):
148
+ """The Markdown lines of the section on functions whose signature changed, none when the diff changes no signature."""
149
+ return _callers_section(answers, problem, "Callers of functions whose signature changed", "changed",
150
+ "- `{item[name]}` ({item[path]}) has a new signature and is called from {sites} outside the file.{also}",
151
+ "No caller outside the file was found for {names}, whose signature changed.")
152
+
153
+
65
154
  def _coupled(root, view_id, changes):
66
155
  """Files that usually change with the diff's files but are not in it, or the reason none could be computed."""
67
156
  paths = sorted({*changes["changed"]["code"], *changes["changed"]["tests"], *changes["changed"]["other"]})
@@ -72,33 +161,113 @@ def _coupled(root, view_id, changes):
72
161
  return found["files"], f"The change coupling was not read: {found['note']}" if found["note"] else None
73
162
 
74
163
 
75
- def _name_pattern(name):
76
- """How a note must mention a function to count. A compound name (snake_case or camelCase) is distinctive, so the bare
77
- word counts; a single word such as `load` or `report` is also ordinary prose, so only a code reference counts:
78
- backticks, or a call with parentheses."""
79
- escaped = re.escape(name)
80
- if "_" in name or re.search(r"[a-z][A-Z]", name):
81
- return re.compile(rf"\b(?:{escaped}|{re.escape(name.replace('_', ' '))})\b", re.I)
82
- return re.compile(rf"`[\w.]*\b{escaped}\b[\w.()]*`|\b{escaped}\(")
164
+ def _cycles(root, view_id, changed_code):
165
+ """Import cycles that contain a changed code file, or the reason none could be computed.
166
+
167
+ Returns: tuple (list of `code_health.import_cycles` entries; str note, what the graph cut; str problem, "" when the
168
+ cycles were read).
169
+ """
170
+ try:
171
+ found = code_health.import_cycles(root, view_id, limit=ALL_ROWS)
172
+ except (ValueError, RuntimeError) as exc:
173
+ return [], "", f"The import cycles were not read: {exc}"
174
+ return [c for c in found["cycles"] if changed_code.intersection(c["files"])], found["note"], ""
175
+
176
+
177
+ def _hotspots(root, view_id, changed_code):
178
+ """Changed code files among the hotspots of the project, or the reason none could be computed.
179
+
180
+ Returns: tuple (list of `code_health.hotspots` rows, riskiest first; str problem, "" when the history was read).
181
+ """
182
+ try:
183
+ found = code_health.hotspots(root, view_id, limit=ALL_ROWS)
184
+ except (ValueError, RuntimeError) as exc:
185
+ return [], f"The hotspots were not read: {exc}"
186
+ if found["note"]:
187
+ return [], f"The hotspots were not read: {found['note']}"
188
+ return [f for f in found["files"] if f["path"] in changed_code][:MAX_HOTSPOTS], ""
189
+
190
+
191
+ def _added_functions(versions, changed_code):
192
+ """The (path, qualified name) pairs of the functions the diff adds: those a changed code file defines now and did not at
193
+ the base, every function of a new file included."""
194
+ added = set()
195
+ for rel, _full, before, after in versions:
196
+ if rel in changed_code and after is not None and doc_check.supported(rel):
197
+ known = {f["name"] for f in doc_check.functions(rel, before)} if before is not None else set()
198
+ added.update((rel, f["name"]) for f in doc_check.functions(rel, after) if f["name"] not in known)
199
+ return added
200
+
201
+
202
+ def _new_dead(root, view_id, versions, changed_code):
203
+ """The functions the diff adds that no function and no test calls, from `code_health.dead_code`.
204
+
205
+ Returns: tuple (list of `dead_code` entries; str note, what the graph cut; str problem, "" when the check ran). Nothing is
206
+ asked of the graph when the diff adds no function.
207
+ """
208
+ added = _added_functions(versions, changed_code)
209
+ if not added:
210
+ return [], "", ""
211
+ try:
212
+ found = code_health.dead_code(root, view_id, limit=ALL_ROWS)
213
+ except (ValueError, RuntimeError) as exc:
214
+ return [], "", f"The new functions without a caller were not read: {exc}"
215
+ return [f for f in found["no_caller"] if (f["path"], f["name"]) in added], found["graph_note"], ""
216
+
217
+
218
+ def _new_dead_lines(dead, note, problem):
219
+ """The Markdown section on new functions nothing calls; left out when the diff adds none or all have a caller, unless
220
+ the graph was cut or the check could not run, which are said."""
221
+ if not (dead or note or problem):
222
+ return []
223
+ lines = ["### New functions nothing calls", ""]
224
+ lines += [f"- `{f['name']}` ({f['path']}:{f['line']})" + ("" if f["public"] else " - private") for f in dead]
225
+ if dead:
226
+ lines.append("Candidates from the static call graph (Python and Go only): a call through a framework, a decorator or a "
227
+ "name built at run time is not seen.")
228
+ elif not problem:
229
+ lines.append(f"No new function without a caller was found. {note}".rstrip())
230
+ note = ""
231
+ lines += [note] if note else []
232
+ return lines + ([problem] if problem else []) + [""]
233
+
234
+
235
+ def _shape_lines(cycles, cycles_note, cycles_problem, hotspots, hotspots_problem, changed_code):
236
+ """The Markdown sections on import cycles and hotspots of the changed files; a section with nothing to say is left out
237
+ unless the graph was cut or the check could not run, which are said."""
238
+ lines = []
239
+ if cycles or cycles_note or cycles_problem:
240
+ lines += ["### Import cycles through the changed files", ""]
241
+ lines += [f"- {c['size']} files import each other, directly or through a chain: "
242
+ + ", ".join(f"`{f}`" for f in c["files"]) + "; changed: "
243
+ + ", ".join(f"`{f}`" for f in c["files"] if f in changed_code) for c in cycles]
244
+ if not cycles and not cycles_problem:
245
+ lines.append(f"No cycle through the changed files was found. {cycles_note}")
246
+ lines += [cycles_problem] if cycles_problem else []
247
+ lines.append("")
248
+ if hotspots or hotspots_problem:
249
+ lines += ["### Changed files that are hotspots", ""]
250
+ lines += [f"- `{f['path']}`: {f['commits']} commits, {f['lines']} lines, last changed {f['last_change']}" for f in hotspots]
251
+ lines += [hotspots_problem] if hotspots_problem else []
252
+ lines.append("")
253
+ return lines
83
254
 
84
255
 
85
256
  def _decisions(root, labels):
86
- """Decision notes and commit messages that name each touched function: the dossier search over the project's notes and
87
- commit history, keeping only hits that contain the function's own name, as a term match alone is too loose.
257
+ """Decision notes and commit messages that name each touched function (`dossier.notes_about`, whose rule keeps a
258
+ single word out of ordinary prose).
88
259
 
89
260
  Returns: tuple (dict label -> list of hits, str problem, "" when the search ran whole).
90
261
  """
91
262
  found, reasons = {}, []
92
263
  for label in labels:
93
- name = label.partition("::")[2].rpartition(".")[2]
94
- if not name:
264
+ rel, _, qualified = label.partition("::")
265
+ if not qualified:
95
266
  continue
96
- answer = dossier.query(root, name.replace("_", " "), max_hits=MAX_NOTES_PER_FUNCTION * 3, history=True)
267
+ answer = dossier.notes_about(root, rel, qualified)
97
268
  reasons += [reason for reason in answer["reasons"] if reason not in reasons]
98
- named = _name_pattern(name)
99
- hits = [hit for hit in answer["hits"] if named.search(f"{hit['title']} {hit['snippet']}")]
100
- if hits:
101
- found[label] = hits[:MAX_NOTES_PER_FUNCTION]
269
+ if answer["hits"]:
270
+ found[label] = answer["hits"]
102
271
  return found, f"The notes search was cut: {'; '.join(reasons)}" if reasons else ""
103
272
 
104
273
 
@@ -122,9 +291,15 @@ def report(root, base="HEAD", limit=30, view_id=None):
122
291
  callers = {label: _callers(root, label, view_id) for label in touched}
123
292
  stale, stale_note = _stale(root, view_id, changed_code)
124
293
  untested = [label for label in touched if callers[label] is None or callers[label][2] == 0]
125
- notes, notes_problem = _hook_notes(root, base, changes)
294
+ versions = _versions(root, base, changes)
295
+ notes, notes_problem = _hook_notes(versions)
296
+ removed, removed_problem = _removed_callers(root, versions, changed_code)
297
+ resigned, resigned_problem = _signature_callers(root, versions, changed_code)
126
298
  coupled, coupled_note = _coupled(root, view_id, changes)
127
299
  decisions, decisions_note = _decisions(root, touched)
300
+ cycles, cycles_note, cycles_problem = _cycles(root, view_id, changed_code) if changed_code else ([], "", "")
301
+ hotspots, hotspots_problem = _hotspots(root, view_id, changed_code) if changed_code else ([], "")
302
+ new_dead, new_dead_note, new_dead_problem = _new_dead(root, view_id, versions, changed_code)
128
303
  lines = [f"## Impact of the change against `{base}`", "",
129
304
  f"{changes['counts']['changed_files']} changed file(s), {len(changes['touched_functions'])} touched "
130
305
  f"function(s), {changes['counts']['tests']} test file(s) to run.", ""]
@@ -146,6 +321,8 @@ def report(root, base="HEAD", limit=30, view_id=None):
146
321
  lines += ["### Touched functions no test reaches", ""]
147
322
  lines += [f"- `{label}`" for label in untested] if untested else ["Every touched function is reached by a test."]
148
323
  lines.append("")
324
+ lines += _removed_lines(removed, removed_problem)
325
+ lines += _signature_lines(resigned, resigned_problem)
149
326
  lines += ["### Documentation left out of date", ""]
150
327
  if stale_note:
151
328
  lines += [stale_note, ""]
@@ -169,6 +346,8 @@ def report(root, base="HEAD", limit=30, view_id=None):
169
346
  for f in coupled] + [""]
170
347
  else:
171
348
  lines += ["No file that usually changes with these is missing from the diff.", ""]
349
+ lines += _shape_lines(cycles, cycles_note, cycles_problem, hotspots, hotspots_problem, changed_code)
350
+ lines += _new_dead_lines(new_dead, new_dead_note, new_dead_problem)
172
351
  lines += ["### Tests to run", ""]
173
352
  if changes["tests"]:
174
353
  lines += [f"- `{t['path']}`: {t['why']}" for t in changes["tests"]]
@@ -184,6 +363,8 @@ def report(root, base="HEAD", limit=30, view_id=None):
184
363
  lines += ["", changes["note"]]
185
364
  return {"base": base, "markdown": "\n".join(lines).rstrip("\n") + "\n", "touched": touched,
186
365
  "callers": {label: (reached[1] if reached else 0) for label, reached in callers.items()},
187
- "untested": untested, "coupled": coupled, "decisions": decisions, "edit_checks": notes or notes_problem,
366
+ "untested": untested, "coupled": coupled, "cycles": cycles, "hotspots": hotspots, "new_without_caller": new_dead, "decisions": decisions, "edit_checks": notes or notes_problem,
367
+ "removed_callers": [item for answer in removed for item in answer["findings"]],
368
+ "signature_callers": [item for answer in resigned for item in answer["findings"]],
188
369
  "stale_anchors": stale, "stale_note": stale_note, "tests": changes["tests"],
189
370
  "commands": changes["commands"], "run_all": changes["run_all"], "counts": changes["counts"]}
@@ -8,6 +8,7 @@ longer exist, are junk (`junk_reason`)."""
8
8
  import os
9
9
  import tempfile
10
10
 
11
+ import i18n
11
12
  import project_identity
12
13
  import project_store
13
14
  import redirect_rule
@@ -81,25 +82,25 @@ def refusal(root):
81
82
  norm = _norm(real)
82
83
  scratch = _scratch_roots()
83
84
  if os.path.dirname(real) == real:
84
- return "a drive or filesystem root"
85
+ return i18n.N_("a drive or filesystem root")
85
86
  if norm in _personal_folders():
86
- return "a personal folder, not a project"
87
+ return i18n.N_("a personal folder, not a project")
87
88
  if norm == scratch[0]:
88
- return "the temporary folder"
89
+ return i18n.N_("the temporary folder")
89
90
  home = _norm(os.path.expanduser("~"))
90
91
  if _inside(norm, home) and norm != home and os.path.relpath(norm, home).split(os.sep)[0].startswith("."):
91
- return "inside a tool's hidden folder in the home folder"
92
+ return i18n.N_("inside a tool's hidden folder in the home folder")
92
93
  if any(_inside(norm, base) for base in _system_roots()):
93
- return "a system or application folder"
94
+ return i18n.N_("a system or application folder")
94
95
  if (any(_inside(norm, base) for base in _env_folders("APPDATA", "LOCALAPPDATA", "LOCALAPPDATA_LOW"))
95
96
  and not any(_inside(norm, base) for base in scratch)):
96
- return "application data"
97
+ return i18n.N_("application data")
97
98
  folder = next((part for part in real.replace("\\", "/").split("/") if part.lower() in TOOL_FOLDERS), None)
98
99
  if folder:
99
- return f"a build or dependency folder ({folder})"
100
+ return i18n.N_("a build or dependency folder ({folder})").format(folder=folder)
100
101
  java = _env_folders("JAVA_HOME")
101
102
  if any(_inside(norm, base) for base in java) or any(_is_java_home(path) for path in _ancestors(real)):
102
- return "a Java home"
103
+ return i18n.N_("a Java home")
103
104
  return None
104
105
 
105
106
 
@@ -110,7 +111,7 @@ def temporary_refusal(root):
110
111
  norm = _norm(project_identity.display_root(root))
111
112
  if _inside(norm, _norm(project_identity.display_root(redirect_rule.system_temp()))) and not any(
112
113
  _inside(norm, base) for base in _env_folders("SMART_TOOL_SCRATCH")):
113
- return "inside the system temporary folder"
114
+ return i18n.N_("inside the system temporary folder")
114
115
  return None
115
116
 
116
117
 
@@ -150,18 +151,19 @@ def admit(path, origin=None):
150
151
  return root
151
152
  reason = refusal(root) or temporary_refusal(root)
152
153
  if reason:
153
- raise ValueError(f"Not indexing {root}: it is {reason}. A project is the folder where the session started; "
154
- "pass that folder as project_root.")
154
+ raise ValueError(i18n.t("Not indexing {root}: it is {reason}. A project is the folder where the session started; "
155
+ "pass that folder as project_root.", root=root, reason=i18n.t(reason)))
155
156
  if origin:
156
157
  home, _held = resolve(origin)
157
158
  home_reason = refusal(home)
158
159
  if home_reason:
159
- raise ValueError(f"Not indexing {root}: the session started in {home}, which is {home_reason}, not a "
160
- "project. Start the session inside the project folder.")
160
+ raise ValueError(i18n.t("Not indexing {root}: the session started in {home}, which is {home_reason}, not a "
161
+ "project. Start the session inside the project folder.",
162
+ root=root, home=home, home_reason=i18n.t(home_reason)))
161
163
  if _inside(_norm(root), _norm(home)):
162
164
  return home
163
- raise ValueError(f"Not indexing {root}: the session started in the project {home}, and a new project is "
164
- "indexed only from the session that started in it.")
165
+ raise ValueError(i18n.t("Not indexing {root}: the session started in the project {home}, and a new project is "
166
+ "indexed only from the session that started in it.", root=root, home=home))
165
167
  return root
166
168
 
167
169
 
@@ -0,0 +1,146 @@
1
+ """Callers that still name a function an edit removed or renamed, or whose signature it changed.
2
+
3
+ The functions the text before the edit defines and the text after lacks (`doc_check.functions`) are looked up in the code
4
+ graph: calls the graph resolved to them (a graph of the text before the edit, as in the edit hook), calls it left
5
+ unresolved under that name (a graph of the text after the edit, as in a diff already on disk), imports of the name, and
6
+ the calls still in the edited file. Names are compared by their last segment, so a name the file still defines
7
+ elsewhere (a method of another class) is not reported. For a function that stays with another signature the callers are
8
+ the calls from other files, resolved or unresolved by name; imports and calls in the edited file are left out.
9
+ """
10
+ import posixpath
11
+ import re
12
+
13
+ import code_graph
14
+ import code_impact
15
+ import doc_check
16
+ import doc_scope
17
+
18
+ MAX_CALLERS = 5
19
+ MAX_SITES = 200
20
+ UNRESOLVED_CAP = 1000
21
+ _IDENTIFIER = re.compile(r"[A-Za-z_$][\w$]*")
22
+ _COMMENT = re.compile(r"^\s*(#|//|\*|/\*)")
23
+
24
+
25
+ def _short(name):
26
+ return name.rpartition(".")[2]
27
+
28
+
29
+ def _gone(rel, before, after):
30
+ """Functions of `before` whose last name segment the functions of `after` no longer carry: {short name: qualified name}."""
31
+ kept = {_short(function["name"]) for function in doc_check.functions(rel, after)}
32
+ old = {}
33
+ for function in doc_check.functions(rel, before):
34
+ short = _short(function["name"])
35
+ if short not in kept and not (short.startswith("__") and short.endswith("__")):
36
+ old.setdefault(short, function["name"])
37
+ return old
38
+
39
+
40
+ def _resigned(rel, before, after):
41
+ """Qualified names of the functions both texts define once whose signature differs; a name a text defines more than once
42
+ (overloads) is not compared."""
43
+ def hashes(text):
44
+ found = {}
45
+ for function in doc_check.functions(rel, text):
46
+ found.setdefault(function["name"], []).append(doc_scope.signature_hash(function["signature"]))
47
+ return found
48
+ old, new = hashes(before), hashes(after)
49
+ return [name for name, signed in old.items()
50
+ if len(signed) == 1 and len(new.get(name, ())) == 1 and new[name] != signed
51
+ and not (_short(name).startswith("__") and _short(name).endswith("__"))]
52
+
53
+
54
+ def _names(expression, short, stem, method):
55
+ """Whether a call expression can mean the removed function: its last name is the function's, and for a plain function
56
+ it is bare or reached through the module (`stem.name`); a method is reached through any receiver."""
57
+ parts = _IDENTIFIER.findall(expression)
58
+ return bool(parts) and parts[-1] == short and (len(parts) == 1 or method or parts[-2] == stem)
59
+
60
+
61
+ def _sites(root, data, rel, name, short, after, removed=True):
62
+ """The (path, line) pairs that reference one function, from the graph; for a removed function also the imports of its
63
+ name and the calls left in the edited file (`after`)."""
64
+ method, stem = "." in name, posixpath.splitext(posixpath.basename(rel))[0]
65
+ sites = set()
66
+ try:
67
+ found = code_impact.impact(root, f"{rel}::{name}", limit=MAX_SITES)
68
+ sites.update((site["path"], site["line"]) for site in found["callers"] if site["path"] != rel)
69
+ except ValueError:
70
+ pass
71
+ sites.update((call["path"], call["line"]) for call in data.get("unresolved") or []
72
+ if call["path"] != rel and _names(call["expression"], short, stem, method))
73
+ if not removed:
74
+ return sorted(sites)
75
+ sites.update((dep["source"], dep["line"]) for dep in data.get("dependencies") or []
76
+ if dep.get("target") == rel and dep["source"] != rel and _names(dep.get("specifier") or "", short, stem, False))
77
+ called = re.compile(rf"\b{re.escape(short)}\s*\(")
78
+ sites.update((rel, number) for number, line in enumerate(after.splitlines(), 1)
79
+ if called.search(line) and not _COMMENT.match(line))
80
+ return sorted(sites)
81
+
82
+
83
+ def _note(data):
84
+ parts = []
85
+ cut = code_graph.left_out_sentence(data)
86
+ if cut:
87
+ parts.append(f"{cut} Callers beyond the cut are not listed.")
88
+ if len(data.get("unresolved") or []) >= UNRESOLVED_CAP:
89
+ parts.append(f"The graph keeps at most {UNRESOLVED_CAP} unresolved calls and this one reached it, so calls by name "
90
+ "beyond them may be missing.")
91
+ if not data.get("symbols") and not data.get("dependencies"):
92
+ parts.append("The code graph is empty: index the project (project_manage action=index) to find the callers.")
93
+ return " ".join(parts)
94
+
95
+
96
+ def review(root, rel, before, after):
97
+ """The callers that still reference the functions an edit removed or renamed in one file.
98
+
99
+ Parameters: root (str) project folder; rel (str) project-relative path of the edited file; before (str or None) text
100
+ before the edit; after (str) text after it.
101
+ Returns: dict {"removed": [qualified names], "findings": [{"name", "path", "callers": [{"path", "line"}] (up to
102
+ MAX_CALLERS), "total", "also_defined_in": [paths]}], "note": str}; `note` says what the graph cut, "" when it cut
103
+ nothing. The graph is read only when a function is gone; findings hold the removed functions something still calls.
104
+ Raises: RuntimeError when the graph cannot be built, ValueError when the project has no index.
105
+ """
106
+ gone = _gone(rel, before, after) if before and doc_check.supported(rel) else {}
107
+ if not gone:
108
+ return {"removed": [], "findings": [], "note": ""}
109
+ return {"removed": list(gone.values()), **_findings(root, rel, list(gone.items()), after, True)}
110
+
111
+
112
+ def _findings(root, rel, functions, after, removed):
113
+ """The callers of each (short name, qualified name) pair, as `review` and `signature_review` return them."""
114
+ data = code_graph.build_current(root, None, shared=True)
115
+ defined = {}
116
+ for symbol in data.get("symbols") or []:
117
+ defined.setdefault(_short(symbol["name"]), set()).add(symbol["path"])
118
+ findings = []
119
+ for short, name in functions:
120
+ sites = _sites(root, data, rel, name, short, after, removed)
121
+ if sites:
122
+ findings.append({"name": name, "path": rel, "callers": [{"path": p, "line": n} for p, n in sites[:MAX_CALLERS]],
123
+ "total": len(sites), "also_defined_in": sorted(defined.get(short, set()) - {rel})})
124
+ return {"findings": findings, "note": _note(data)}
125
+
126
+
127
+ def signature_review(root, rel, before, after):
128
+ """The callers in other files of the functions an edit left with another signature (parameters, order, defaults, return
129
+ annotation) in one file.
130
+
131
+ Parameters: as `review`.
132
+ Returns: dict {"changed": [qualified names], "findings": as `review`, "note": str}; the callers are those outside
133
+ `rel`. The graph is read only when a signature changed.
134
+ Raises: RuntimeError when the graph cannot be built, ValueError when the project has no index.
135
+ """
136
+ changed = _resigned(rel, before, after) if before and doc_check.supported(rel) else []
137
+ if not changed:
138
+ return {"changed": [], "findings": [], "note": ""}
139
+ return {"changed": changed, **_findings(root, rel, [(_short(name), name) for name in changed], after, False)}
140
+
141
+
142
+ def sites_text(finding):
143
+ """`app/api.py:6, app/cli.py:3 (+2 more)` for one finding."""
144
+ shown = ", ".join(f"{site['path']}:{site['line']}" for site in finding["callers"])
145
+ more = f" (+{finding['total'] - len(finding['callers'])} more)" if finding["total"] > len(finding["callers"]) else ""
146
+ return shown + more