149 lines
6.8 KiB
Python
149 lines
6.8 KiB
Python
"""An item's prediction of the files and parts it will touch, as its detail spells it, and where two predictions overlap.
|
|
|
|
It sits in plan so that plan_store's `FilePlan.check` and todo-item can call `predicted`: touch_predictions imports plan_store, and importing touch_predictions from plan_store would make the two packages import each other.
|
|
|
|
The spelling, which the decision `todo.md: an item of the next release predicts the files and parts it will touch …` gives the reasons for:
|
|
|
|
Touches:
|
|
|
|
- `bin/a.py`: `main`, `Plan.branch` (small)
|
|
- `bin/run.sh`: lines 10-20
|
|
- `docs/new.md`
|
|
|
|
A path alone is the whole file, and (small) marks a part the item changes only a little. file_parts says how a part is named.
|
|
|
|
A path or a name that holds a backtick is spelt as a Markdown code span that holds one: in a longer run of backticks than any it holds, with a space inside each end, as in `` ## The `foo` tool ``. So every path and name on one line has a spelling. A description kept in Jira reaches here through adf_codec, which pads a span only where its text opens or ends in a backtick, or opens and ends in a space. So it spells a`b.md as ``a`b.md``; code_span reads that as the name too."""
|
|
import dataclasses
|
|
import re
|
|
|
|
from failure import Failure
|
|
|
|
LABEL = "Touches:"
|
|
SMALL = " (small)"
|
|
RANGE = re.compile(r"lines (\d+)-(\d+)")
|
|
BACKTICKS = re.compile(r"`+")
|
|
|
|
|
|
@dataclasses.dataclass(frozen=True)
|
|
class Part:
|
|
"""A part of a file, by the name file_parts gives it or as `lines <first>-<last>`; small where the item changes it only a little."""
|
|
name: str
|
|
small: bool = False
|
|
|
|
|
|
# Each file's parts by its path; no parts where the whole file is touched.
|
|
Touches = dict[str, tuple[Part, ...]]
|
|
|
|
|
|
def predicted(detail: str) -> Touches | None | Failure:
|
|
"""The prediction in an item's detail: the bullets under its `Touches:` line, up to the first other text. None where the detail has no such line."""
|
|
lines = detail.splitlines()
|
|
if LABEL not in lines:
|
|
return None
|
|
touches: Touches = {}
|
|
for line in lines[lines.index(LABEL) + 1:]:
|
|
if not line.strip():
|
|
continue
|
|
if not line.startswith("- "):
|
|
break
|
|
read = bullet(line)
|
|
if read is None:
|
|
return Failure(f"the bullet {line!r} under `{LABEL}` is not a path in backticks, then optionally a colon and its parts, each a name in backticks or `lines <first>-<last>` that `{SMALL.strip()}` may follow; `{SMALL.strip()}` follows a part, never a bare path")
|
|
if any(span and span[0] > span[1] for span in map(line_range, read[1])):
|
|
return Failure(f"the bullet {line!r} under `{LABEL}` holds a line range whose first line comes after its last")
|
|
touches = together([touches, {read[0]: read[1]}])
|
|
return touches or Failure(f"no bullet follows `{LABEL}`")
|
|
|
|
|
|
def bullet(line: str) -> tuple[str, tuple[Part, ...]] | None:
|
|
"""The path and the parts a bullet names; None where it is not spelt as one."""
|
|
path = code_span(line, len("- "))
|
|
if path is None:
|
|
return None
|
|
parts = []
|
|
at, separator = path[1], ": "
|
|
while at < len(line):
|
|
if not line.startswith(separator, at):
|
|
return None
|
|
found = RANGE.match(line, at + len(separator))
|
|
part = (found.group(), found.end()) if found else code_span(line, at + len(separator))
|
|
if part is None:
|
|
return None
|
|
small = line.startswith(SMALL, part[1])
|
|
parts.append(Part(part[0], small))
|
|
at, separator = part[1] + len(SMALL) * small, ", "
|
|
return path[0], tuple(parts)
|
|
|
|
|
|
def code_span(line: str, at: int) -> tuple[str, int] | None:
|
|
"""The text of the code span that opens at index at of line, and the index after it; None where none does. The span ends at the next run of as many backticks as open it."""
|
|
opened = BACKTICKS.match(line, at)
|
|
run = opened.group() if opened else ""
|
|
closed = re.search(rf"(?<!`){run}(?!`)", line[opened.end():]) if opened else None
|
|
if opened is None or closed is None:
|
|
return None
|
|
text = line[opened.end():opened.end() + closed.start()]
|
|
# In a longer run, a space at both ends is padding, which keeps a backtick at either end of the text apart from the run. Without one at both ends, the span is its text. A one-backtick span is always its text, so a name that opens and ends in a space isn't read back from Jira, whose codec pads it; no path or heading is spelt so.
|
|
if len(run) > 1 and text.startswith(" ") and text.endswith(" "):
|
|
text = text[1:-1]
|
|
return (text, opened.end() + closed.end()) if text else None
|
|
|
|
|
|
def rendered(touches: Touches) -> str:
|
|
"""touches as the bullets predicted reads."""
|
|
return "\n".join(f"- {code(path)}" + (": " + ", ".join(shown(part) + SMALL * part.small for part in parts) if parts else "") for path, parts in touches.items())
|
|
|
|
|
|
def shown(part: Part) -> str:
|
|
return part.name if line_range(part) else code(part.name)
|
|
|
|
|
|
def code(text: str) -> str:
|
|
"""text as the code span code_span reads."""
|
|
if "`" not in text:
|
|
return f"`{text}`"
|
|
run = "`" * (1 + max(map(len, BACKTICKS.findall(text))))
|
|
return f"{run} {text} {run}"
|
|
|
|
|
|
def line_range(part: Part) -> tuple[int, int] | None:
|
|
found = RANGE.fullmatch(part.name)
|
|
return (int(found.group(1)), int(found.group(2))) if found else None
|
|
|
|
|
|
def together(several: list[Touches]) -> Touches:
|
|
"""What several predictions touch between them. A file one of them touches whole is touched whole, and a part is small only where each that names it says so."""
|
|
joined: dict[str, dict[str, bool] | None] = {}
|
|
for touches in several:
|
|
for path, parts in touches.items():
|
|
held = joined.setdefault(path, {})
|
|
if held is None or not parts:
|
|
joined[path] = None
|
|
continue
|
|
for part in parts:
|
|
held[part.name] = held.get(part.name, True) and part.small
|
|
return {path: tuple(Part(name, small) for name, small in held.items()) if held else () for path, held in joined.items()}
|
|
|
|
|
|
def overlaps(ours: Touches, theirs: Touches) -> list[str]:
|
|
"""Each place both touch: a file either touches whole, by its path alone, and else each part as ours names it. A part either side marks small is left out: a conflict there is cheap to settle, and a chunk that waits costs hours."""
|
|
found = []
|
|
for path, parts in ours.items():
|
|
if path not in theirs:
|
|
continue
|
|
if not parts or not theirs[path]:
|
|
found.append(f"`{path}`")
|
|
continue
|
|
found.extend(f"`{path}` {shown(part)}" for part in parts if any(same_part(part, other) and not (part.small or other.small) for other in theirs[path]))
|
|
return found
|
|
|
|
|
|
def same_part(one: Part, other: Part) -> bool:
|
|
"""Whether two parts of one file share lines, as far as their names tell: line ranges that share a line, a line range and a name, since the name doesn't say which lines it holds, equal names, or a class and what it holds."""
|
|
spans = line_range(one), line_range(other)
|
|
if spans[0] and spans[1]:
|
|
return spans[0][0] <= spans[1][1] and spans[1][0] <= spans[0][1]
|
|
if spans[0] or spans[1]:
|
|
return True
|
|
return one.name == other.name or one.name.startswith(f"{other.name}.") or other.name.startswith(f"{one.name}.")
|