prefly 0.1.0__tar.gz

prefly-0.1.0/PKG-INFO

@@ -0,0 +1,55 @@
+Metadata-Version: 2.4
+Name: prefly
+Version: 0.1.0
+Summary: Scan a Frappe site for APIs removed or renamed in the next major version, before upgrading
+Author-email: Kaushal Shriwas <64089478+kaulith@users.noreply.github.com>
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: license.txt
+Requires-Dist: click
+Requires-Dist: packaging
+Requires-Dist: pyyaml
+Requires-Dist: semantic-version
+Requires-Dist: tomli; python_version < "3.11"
+Project-URL: Documentation, https://github.com/kaulith/preflight/blob/main/docs/overview.md
+Project-URL: Issues, https://github.com/kaulith/preflight/issues
+Project-URL: Source, https://github.com/kaulith/preflight
+
+# Preflight
+
+Scans a Frappe site before a major version upgrade and lists what will break: removed and renamed
+APIs in its apps, site scripts and customisations, and what the bench needs for the new version. It
+changes nothing on the site.
+
+## Install and run
+
+From the bench directory, into the bench's own environment:
+
+```bash
+./env/bin/pip install prefly
+./env/bin/preflight --site mysite.local --target v16
+```
+
+For CI, scan an app's checkout with no site or bench:
+
+```bash
+pip install prefly
+preflight --path . --target v16
+```
+
+A clean report means no known problems were found, not that the upgrade is safe.
+
+## Docs
+
+- [Overview](https://github.com/kaulith/preflight/blob/main/docs/overview.md): what it checks, options, exit codes, limits
+- [Getting started](https://github.com/kaulith/preflight/blob/main/docs/getting-started.md): install, the first scan, CI, suppressing a finding
+- [Reading a report](https://github.com/kaulith/preflight/blob/main/docs/reading-a-report.md)
+- [Rules](https://github.com/kaulith/preflight/blob/main/docs/rules.md)
+- [Upgrade checklist](https://github.com/kaulith/preflight/blob/main/docs/upgrade-checklist.md)
+- [Writing a rule](https://github.com/kaulith/preflight/blob/main/docs/writing-a-rule.md)
+- [How it was tested](https://github.com/kaulith/preflight/blob/main/docs/how-it-was-tested.md)
+
+## License
+
+MIT
+

prefly-0.1.0/README.md

@@ -0,0 +1,37 @@
+# Preflight
+
+Scans a Frappe site before a major version upgrade and lists what will break: removed and renamed
+APIs in its apps, site scripts and customisations, and what the bench needs for the new version. It
+changes nothing on the site.
+
+## Install and run
+
+From the bench directory, into the bench's own environment:
+
+```bash
+./env/bin/pip install prefly
+./env/bin/preflight --site mysite.local --target v16
+```
+
+For CI, scan an app's checkout with no site or bench:
+
+```bash
+pip install prefly
+preflight --path . --target v16
+```
+
+A clean report means no known problems were found, not that the upgrade is safe.
+
+## Docs
+
+- [Overview](https://github.com/kaulith/preflight/blob/main/docs/overview.md): what it checks, options, exit codes, limits
+- [Getting started](https://github.com/kaulith/preflight/blob/main/docs/getting-started.md): install, the first scan, CI, suppressing a finding
+- [Reading a report](https://github.com/kaulith/preflight/blob/main/docs/reading-a-report.md)
+- [Rules](https://github.com/kaulith/preflight/blob/main/docs/rules.md)
+- [Upgrade checklist](https://github.com/kaulith/preflight/blob/main/docs/upgrade-checklist.md)
+- [Writing a rule](https://github.com/kaulith/preflight/blob/main/docs/writing-a-rule.md)
+- [How it was tested](https://github.com/kaulith/preflight/blob/main/docs/how-it-was-tested.md)
+
+## License
+
+MIT

prefly-0.1.0/license.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kaushal Shriwas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

prefly-0.1.0/preflight/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

prefly-0.1.0/preflight/__main__.py

@@ -0,0 +1,3 @@
+from preflight.commands import preflight_command
+
+preflight_command()

prefly-0.1.0/preflight/app_scan.py

@@ -0,0 +1,177 @@
+"""The scan of an app's own files, which needs only the files: no site, no bench, and no frappe."""
+
+import re
+from collections.abc import Collection, Mapping
+from dataclasses import replace
+from pathlib import Path
+
+from packaging.requirements import Requirement
+from packaging.utils import canonicalize_name
+
+from preflight.compatibility_scanner import CompatibilityScanner, declared_dependencies
+from preflight.hooks_scanner import HooksScanner, hooked_doctypes
+from preflight.js_scanner import JSScanner
+from preflight.models import Finding, Report, Rule
+from preflight.python_scanner import PythonScanner
+from preflight.schema_scanner import SchemaScanner, app_doctype_fields
+from preflight.sources import frontend_files, is_bundle, read_source, source_files
+
+# Inside a comment: `#` in Python, TOML and patches.txt, `//` or `/*` in JS and SCSS, `<!--` in a Vue
+# template.
+IGNORE_COMMENT = re.compile(r"(?:#|//|/\*|<!--).*?\bpreflight:\s*ignore\[([^\]]*)\]")
+# What --path cannot check, having no bench and no site to read.
+PATH_MODE_NOT_CHECKED = (
+	"required_apps: --path reads no bench to find them on, not checked",
+	"bench Python: --path reads no bench, not checked",
+	(
+		"site: --path reads no site, its scripts, Custom Fields, Property Setters, records and Patch Log"
+		" not checked"
+	),
+)
+
+
+class Scanners:
+	"""The five scanners, compiled once from one rule set."""
+
+	def __init__(self, rules: list[Rule]):
+		self.python = PythonScanner(rules)
+		self.js = JSScanner(rules)
+		self.hooks = HooksScanner(rules)
+		self.schema = SchemaScanner(rules)
+		self.compatibility = CompatibilityScanner(rules)
+
+
+def ignored_rules(line: str) -> set[str]:
+	"""The rule ids a `preflight: ignore[rule-a, rule-b]` comment on the line names."""
+	return {
+		rule_id.strip()
+		for comment in IGNORE_COMMENT.finditer(line)
+		for rule_id in comment.group(1).split(",")
+	}
+
+
+def add_findings(
+	report: Report,
+	findings: list[Finding],
+	text: str,
+	app: str | None = None,
+	source: str = "app",
+	declared: set[str] = frozenset(),
+):
+	"""Count the findings read from `text` into the report, as found in `app` and read from `source`.
+
+	An import of a package the app declares is no finding, whatever frappe stops installing. One that an
+	ignore comment on its own line names is counted as suppressed instead."""
+	lines = text.split("\n")
+	for finding in findings:
+		if finding.rule.match.type == "undeclared_import" and not declared.isdisjoint(
+			canonicalize_name(Requirement(dependency).name) for dependency in finding.rule.match.dependencies
+		):
+			continue
+		if finding.line and finding.rule.id in ignored_rules(lines[finding.line - 1]):
+			report.suppressed += 1
+			continue
+		report.findings.append(replace(finding, app=app, source=source))
+
+
+def build_path_report(
+	rules: list[Rule], target: str, app_paths: list[Path], skip_tests: bool = False, online: bool = False
+) -> Report:
+	"""Scan each app's files, `app_paths` naming the directory that holds its hooks.py. There is no frappe
+	version to compare branches with, so each pyproject.toml is read whatever branch the app is on."""
+	scanners = Scanners(rules)
+	report = Report(site=None, target=target, apps=[app_path.name for app_path in app_paths])
+	for app_path in app_paths:
+		scan_app(report, scanners, app_path.name, app_path, skip_tests)
+		scan_pyproject(report, scanners.compatibility, app_path.name, app_path.parent)
+	report.not_checked += PATH_MODE_NOT_CHECKED
+	if online:
+		from preflight.online_scanner import OnlineScanner, scan_online
+
+		app_roots = {app_path.name: app_path.parent for app_path in app_paths}
+		scan_online(report, OnlineScanner(rules), app_roots, None)
+	return report
+
+
+def scan_app(report: Report, scanners: Scanners, app: str, app_path: Path, skip_tests: bool = False):
+	"""The app's Python with its hooks.py, its front-end files anywhere in the repository, the `execute:`
+	lines of its patches.txt, and the link fields of its doctypes. Each file is named from the repository
+	root, the parent of `app_path`; the report's lists name it under the app as well."""
+	app_root = app_path.parent
+	declared = declared_dependencies(app_root)
+	hooked = hooked_doctypes(app_path)
+	for path in source_files(app_path, ".py", skip_tests):
+		file = str(path.relative_to(app_root))
+		source = read_source(path, f"{app}/{file}", report.unreadable_files)
+		if source is None:
+			continue
+		module = ".".join(path.relative_to(app_root).with_suffix("").parts).removesuffix(".__init__")
+		findings = scan_python(report, scanners.python, file, source, app, hooked.get(module, {}))
+		if findings is None:
+			continue
+		if path == app_path / "hooks.py":
+			findings += scanners.hooks.scan(source, file, app_path) + scanners.hooks.missing_hooks(
+				source, file, app_path
+			)
+		add_findings(report, findings, source, app, declared=declared)
+	for path in frontend_files(app_root, skip_tests):
+		file = str(path.relative_to(app_root))
+		source = read_source(path, f"{app}/{file}", report.unreadable_files)
+		if source is not None and not is_bundle(source):
+			add_findings(report, scanners.js.scan(source, file), source, app)
+	scan_patches(report, scanners.python, app, app_path, declared)
+	report.findings += [
+		replace(finding, app=app) for finding in scanners.schema.scan(app_doctype_fields(app_path))
+	]
+
+
+def scan_patches(report: Report, scanner: PythonScanner, app: str, app_path: Path, declared: set[str]):
+	"""The `execute:` lines of the app's patches.txt, which are Python that `bench migrate` runs. They are
+	scanned as one file with every other line blanked, so each finding keeps its patches.txt line."""
+	path = app_path / "patches.txt"
+	if not path.is_file():
+		return
+	file = str(path.relative_to(app_path.parent))
+	source = read_source(path, f"{app}/{file}", report.unreadable_files)
+	if source is None:
+		return
+	code = "\n".join(
+		line.removeprefix("execute:") if line.startswith("execute:") else "" for line in source.splitlines()
+	)
+	add_findings(report, scan_python(report, scanner, file, code, app) or [], code, app, declared=declared)
+
+
+def scan_pyproject(report: Report, scanner: CompatibilityScanner, app: str, app_root: Path):
+	path = app_root / "pyproject.toml"
+	if not path.is_file():
+		return
+	source = read_source(path, f"{app}/pyproject.toml", report.unreadable_files)
+	if source is None:
+		return
+	try:
+		findings = scanner.scan_pyproject(source, "pyproject.toml")
+	except ValueError:
+		report.unparsable_files.append(f"{app}/pyproject.toml")
+		return
+	add_findings(report, findings, source, app)
+
+
+def scan_python(
+	report: Report,
+	scanner: PythonScanner,
+	file: str,
+	source: str,
+	app: str | None = None,
+	hooked: Mapping[str, Collection[str]] = {},
+	docs: Mapping[str, Collection[str]] = {},
+) -> list[Finding] | None:
+	"""The file's findings, or None when it does not parse, with the file named in the report's lists,
+	under `app` when it is one of an app's. `hooked` and `docs` are PythonScanner.scan's."""
+	listed = f"{app}/{file}" if app else file
+	try:
+		return scanner.scan(source, file, hooked, docs)
+	except SyntaxError:
+		report.unparsable_files.append(listed)
+	except (ValueError, RecursionError) as error:
+		report.unreadable_files.append(f"{listed}: {error}")
+	return None

prefly-0.1.0/preflight/commands.py

@@ -0,0 +1,176 @@
+import json
+import os
+import sys
+import tempfile
+import traceback
+from collections import Counter
+from pathlib import Path
+
+import click
+
+from preflight import __version__
+from preflight.app_scan import build_path_report
+from preflight.formatter import format_html, format_json, format_report, format_sarif
+from preflight.models import SEVERITIES, Report, Rule
+from preflight.rule_loader import RuleError, load_rules, load_ruleset, released_targets
+
+FORMATTERS = {"text": format_report, "json": format_json, "html": format_html, "sarif": format_sarif}
+# What a baseline finding is matched on: everything but its line, which moves as the file changes.
+BASELINE_KEYS = ("rule", "app", "file", "snippet")
+
+
+def app_package_dir(path: Path) -> Path:
+	"""The app's package directory, the one holding hooks.py: `path` itself, or the one directory in it
+	that holds one, so an app is named by its repository root or by its package."""
+	path = path.resolve()
+	if (path / "hooks.py").is_file():
+		return path
+	packages = sorted(child for child in path.iterdir() if (child / "hooks.py").is_file())
+	if len(packages) != 1:
+		raise click.UsageError(f"--path {path}: no app, neither it nor one directory in it holds a hooks.py")
+	return packages[0]
+
+
+def read_baseline(path: Path) -> Counter:
+	"""The findings of a report written earlier with --format json, each as often as it appears."""
+	try:
+		data = json.loads(path.read_text(encoding="utf-8"))
+	except (OSError, ValueError) as e:
+		raise click.UsageError(f"--baseline {path}: {e}") from e
+	findings = data.get("findings") if isinstance(data, dict) else None
+	if not isinstance(findings, list) or not all(
+		isinstance(entry, dict) and all(key in entry for key in BASELINE_KEYS) for entry in findings
+	):
+		raise click.UsageError(f"--baseline {path}: not a report written with --format json")
+	return Counter(tuple(entry[key] for key in BASELINE_KEYS) for entry in findings)
+
+
+def scan_site(
+	rules: list[Rule], site: str, target: str, apps: tuple[str, ...], skip_tests: bool, online: bool
+) -> Report:
+	"""Connect to the site from the bench this python's env belongs to (`<bench>/env`), working in its
+	sites directory the way bench does. frappe is imported here only, so --path runs without it."""
+	sites_path = Path(sys.prefix).parent / "sites"
+	if not sites_path.is_dir():
+		raise click.UsageError(
+			f"--site needs the python of a bench's env; {sites_path} is not a bench's sites"
+		)
+	import frappe
+
+	from preflight.scan import build_report
+
+	if int(frappe.__version__.split(".")[0]) >= int(target.removeprefix("v")):
+		raise click.UsageError(
+			f"this bench already runs frappe {frappe.__version__}; --target is the version to upgrade to"
+		)
+	os.chdir(sites_path)
+	try:
+		frappe.init(site=site, sites_path=str(sites_path))
+		frappe.connect()
+		installed = frappe.get_installed_apps()
+		if unknown := [app for app in apps if app not in installed]:
+			raise click.UsageError(f"not installed on {site}: {', '.join(unknown)}")
+		return build_report(rules, site, target, apps, skip_tests, online)
+	except frappe.exceptions.IncorrectSitePath as e:
+		raise click.UsageError(str(e)) from e
+	finally:
+		frappe.destroy()
+
+
+@click.command("preflight")
+@click.version_option(version=__version__, prog_name="preflight")
+@click.option("--site", help="Site to scan, on the bench whose env runs preflight")
+@click.option(
+	"--path",
+	"paths",
+	multiple=True,
+	type=click.Path(exists=True, file_okay=False, path_type=Path),
+	help="Scan the app in this directory, its repository or its package, with no site or bench; repeatable",
+)
+@click.option("--target", required=True, help="Version to check against, selects the rule set (e.g. v16)")
+@click.option("--unreleased", is_flag=True, hidden=True, help="Allow a target that is not released yet")
+@click.option("--app", "apps", multiple=True, help="Scan only this app of the site; repeatable")
+@click.option(
+	"--severity",
+	type=click.Choice(SEVERITIES),
+	default="info",
+	help="Lowest severity to report",
+)
+@click.option(
+	"--fail-on",
+	type=click.Choice((*SEVERITIES, "never")),
+	default="error",
+	help="Lowest severity that exits 1",
+)
+@click.option(
+	"--format", "output_format", type=click.Choice(tuple(FORMATTERS)), default="text", help="Report format"
+)
+@click.option("--open", "open_report", is_flag=True, help="Also open the HTML report in a browser")
+@click.option(
+	"--baseline",
+	type=click.Path(dir_okay=False, path_type=Path),
+	help="Leave out the findings of this earlier --format json report",
+)
+@click.option("--online", is_flag=True, help="Also run the checks that ask git remotes, node and PyPI")
+@click.option("--skip-tests", is_flag=True, help="Skip test files and tests directories")
+def preflight_command(
+	site: str | None,
+	paths: tuple[Path, ...],
+	target: str,
+	unreleased: bool,
+	apps: tuple[str, ...],
+	severity: str,
+	fail_on: str,
+	output_format: str,
+	open_report: bool,
+	baseline: Path | None,
+	online: bool,
+	skip_tests: bool,
+):
+	"""Report APIs removed, renamed or deprecated in the target version"""
+	if bool(site) == bool(paths):
+		raise click.UsageError("Pass --site to scan a site, or --path to scan an app's files: one of the two")
+	if paths and apps:
+		raise click.UsageError("--app picks apps of a site; with --path, pass each app's directory")
+	try:
+		rules = load_rules(target)
+		ruleset = load_ruleset(target)
+	except RuleError as e:
+		raise click.UsageError(str(e)) from e
+	if not ruleset.released and not unreleased:
+		raise click.UsageError(
+			f"{target} is not released yet. Available targets: {', '.join(released_targets())}"
+		)
+	baselined = read_baseline(baseline) if baseline else Counter()
+	app_paths = [app_package_dir(path) for path in paths]
+
+	try:
+		if site:
+			report = scan_site(rules, site, target, apps, skip_tests, online)
+		else:
+			report = build_path_report(rules, target, app_paths, skip_tests, online)
+		report.ruleset = ruleset
+		counted = []
+		for finding in report.findings:
+			key = (finding.rule.id, finding.app, finding.file, finding.snippet)
+			if baselined[key]:
+				baselined[key] -= 1
+				report.baselined += 1
+			else:
+				counted.append(finding)
+		report.findings = counted
+		click.echo(FORMATTERS[output_format](report, severity, fail_on))
+		if open_report:
+			with tempfile.NamedTemporaryFile(
+				"w", encoding="utf-8", prefix="preflight-", suffix=".html", delete=False
+			) as page:
+				page.write(format_html(report, severity, fail_on))
+			click.echo(f"HTML report: {page.name}", err=True)
+			click.launch(page.name)
+	except click.ClickException:
+		raise
+	except Exception:  # noqa: BLE001
+		traceback.print_exc()
+		sys.exit(3)
+	if report.fails(fail_on):
+		sys.exit(1)

prefly-0.1.0/preflight/compatibility_scanner.py

@@ -0,0 +1,207 @@
+import ast
+import re
+from pathlib import Path
+
+import semantic_version
+from packaging.requirements import InvalidRequirement, Requirement
+from packaging.specifiers import SpecifierSet
+from packaging.utils import canonicalize_name
+from packaging.version import InvalidVersion, Version
+
+try:
+	import tomllib
+except ModuleNotFoundError:  # python 3.10, which frappe v15 still runs on
+	import tomli as tomllib
+
+from preflight.hooks_scanner import assigned_names
+from preflight.models import Finding, Rule
+
+PYTHON_RELEASES = tuple(Version(f"3.{minor}.{patch}") for minor in range(8, 30) for patch in (0, 99))
+
+
+def parse_required_app_name(requirement: str) -> str:
+	"""Mirrors frappe.installer.parse_required_app_name from v16, which v15 does not have."""
+	name = requirement.rstrip("/").split("#")[0]
+	name = name.rsplit("/", 1)[-1].rsplit(":", 1)[-1]
+	return name.split("@")[0].removesuffix(".git")
+
+
+def checked_out_branch(app_root: Path) -> str | None:
+	"""The branch the app's checkout is on, or None when HEAD is detached or there is no checkout. A
+	worktree's `.git` is a file naming the git dir that holds its HEAD."""
+	git_dir = app_root / ".git"
+	try:
+		if git_dir.is_file():
+			git_dir = app_root / git_dir.read_text(encoding="utf-8").removeprefix("gitdir:").strip()
+		head = (git_dir / "HEAD").read_text(encoding="utf-8").strip()
+	except OSError:
+		return None
+	return head.removeprefix("ref: refs/heads/") if head.startswith("ref: refs/heads/") else None
+
+
+def is_frappe_branch(branch: str, frappe_major: int) -> bool:
+	"""True on the version branch of the frappe the bench runs (version-15-hotfix on v15), or on a branch
+	cut from it (mergify/bp/version-15-hotfix/pr-1), which the upgrade switches to the target's. An
+	app's own release branch, like Insights' version-3, stays."""
+	return bool(re.search(rf"(^|/)version-{frappe_major}(-hotfix|-beta)?(/|$)", branch))
+
+
+def declared_dependencies(app_root: Path) -> set[str]:
+	"""The canonical names of the packages the app asks pip for: its pyproject's `[project].dependencies`,
+	and a requirements.txt, which older apps still install from. A file that cannot be read declares
+	nothing."""
+	requirements = []
+	try:
+		data = tomllib.loads((app_root / "pyproject.toml").read_text(encoding="utf-8"))
+		requirements += data.get("project", {}).get("dependencies", [])
+	except (OSError, ValueError):
+		pass
+	try:
+		lines = (app_root / "requirements.txt").read_text(encoding="utf-8").splitlines()
+		requirements += [line.partition("#")[0].strip() for line in lines]
+	except (OSError, ValueError):
+		pass
+	names = set()
+	for requirement in requirements:
+		try:
+			names.add(canonicalize_name(Requirement(requirement).name))
+		except InvalidRequirement:
+			continue
+	return names
+
+
+def shares_a_python(first: SpecifierSet, second: SpecifierSet) -> bool:
+	"""Whether any Python release satisfies both. Each minor is tried at .0 and .99, so a bound on a
+	patch release (">=3.14.2") still counts its minor."""
+	return any(first.contains(release) and second.contains(release) for release in PYTHON_RELEASES)
+
+
+def named_versions(specifiers: SpecifierSet) -> set[Version]:
+	"""Each version `specifiers` names, and one just above it, which `>` and `!=` let through."""
+	versions = set()
+	for specifier in specifiers:
+		try:
+			version = Version(specifier.version.removesuffix(".*"))
+		except InvalidVersion:
+			continue
+		versions |= {version, Version(f"{version.base_version}.1")}
+	return versions
+
+
+def can_coexist(first: SpecifierSet, second: SpecifierSet) -> bool:
+	"""Whether a version satisfies both. Only 0 and the `named_versions` of either are tried, which is
+	exact for the pins frappe writes (`==`, `~=`, `>=` with `<`); a pair whose shared versions all lie
+	past a `!=` wildcard (`!=1.*`) reads as a clash."""
+	both = first & second
+	return any(
+		both.contains(version, prereleases=True)
+		for version in {Version("0"), *named_versions(first), *named_versions(second)}
+	)
+
+
+def quoted_line(lines: list[str], start: int, text: str) -> int | None:
+	"""The first line from `start` on that quotes `text`, or None when none does."""
+	return next(
+		(
+			number
+			for number, line in enumerate(lines, 1)
+			if number >= start and (f'"{text}"' in line or f"'{text}'" in line)
+		),
+		None,
+	)
+
+
+def toml_line(lines: list[str], table: str, key: str) -> int | None:
+	"""The line `key` is set on inside `[table]`, or None when it is not found; tomllib keeps no
+	positions."""
+	current = ""
+	for number, line in enumerate(lines, 1):
+		stripped = line.strip()
+		if stripped.startswith("["):
+			current = stripped.strip("[]").strip()
+		elif current == table and stripped.partition("=")[0].strip().strip("\"'") == key:
+			return number
+	return None
+
+
+def finding_on(rule: Rule, file: str, lines: list[str], line: int | None) -> Finding:
+	return Finding(rule=rule, file=file, line=line, snippet=lines[line - 1].strip() if line else "")
+
+
+class CompatibilityScanner:
+	"""Rules on whether the bench can install the target: its Python, and each app's pyproject.toml
+	and required_apps."""
+
+	def __init__(self, rules: list[Rule]):
+		self.rules_by_type: dict[str, list[Rule]] = {}
+		for rule in rules:
+			self.rules_by_type.setdefault(rule.match.type, []).append(rule)
+
+	def scan_environment(self, python_version: str) -> list[Finding]:
+		return [
+			Finding(rule=rule, file="env/bin/python", line=None, snippet=f"Python {python_version}")
+			for rule in self.rules_by_type.get("bench_python", ())
+			if not SpecifierSet(rule.match.python).contains(python_version)
+		]
+
+	def scan_pyproject(self, source: str, file: str) -> list[Finding]:
+		"""Raises ValueError when the file, or a bound or dependency in it, does not parse."""
+		data = tomllib.loads(source)
+		lines = source.splitlines()
+		findings = []
+
+		if requires_python := data.get("project", {}).get("requires-python"):
+			line = toml_line(lines, "project", "requires-python")
+			findings += [
+				finding_on(rule, file, lines, line)
+				for rule in self.rules_by_type.get("requires_python", ())
+				if not shares_a_python(SpecifierSet(requires_python), SpecifierSet(rule.match.python))
+			]
+
+		bench = data.get("tool", {}).get("bench", {})
+		if frappe_bound := bench.get("frappe-dependencies", {}).get("frappe"):
+			line = toml_line(lines, "tool.bench.frappe-dependencies", "frappe")
+			bound = semantic_version.SimpleSpec(frappe_bound)
+			findings += [
+				finding_on(rule, file, lines, line)
+				for rule in self.rules_by_type.get("frappe_bound", ())
+				if semantic_version.Version(rule.match.frappe) not in bound
+			]
+
+		dependencies_line = toml_line(lines, "project", "dependencies")
+		for rule in self.rules_by_type.get("dependency_pins", ()):
+			pins = {canonicalize_name(pin.name): pin for pin in map(Requirement, rule.match.dependencies)}
+			for dependency in data.get("project", {}).get("dependencies", ()):
+				requirement = Requirement(dependency)
+				pin = pins.get(canonicalize_name(requirement.name))
+				if pin and not can_coexist(requirement.specifier, pin.specifier):
+					findings.append(
+						Finding(
+							rule=rule,
+							file=file,
+							line=quoted_line(lines, dependencies_line or 1, dependency),
+							snippet=f"{dependency} (frappe pins {pin})",
+						)
+					)
+		return findings
+
+	def scan_required_apps(self, source: str, file: str, apps_on_bench: set[str]) -> list[Finding]:
+		"""Raises SyntaxError if `source` is not valid Python."""
+		lines = source.splitlines()
+		findings = []
+		for node in ast.parse(source, filename=file).body:
+			if not any(name.id == "required_apps" for name in assigned_names(node)):
+				continue
+			if not isinstance(node.value, ast.List | ast.Tuple):
+				continue
+			for entry in node.value.elts:
+				if (
+					isinstance(entry, ast.Constant)
+					and isinstance(entry.value, str)
+					and parse_required_app_name(entry.value) not in apps_on_bench
+				):
+					findings += [
+						finding_on(rule, file, lines, entry.lineno)
+						for rule in self.rules_by_type.get("required_apps", ())
+					]
+		return findings