code-standards 7.0.0__py3-none-any.whl

sarj_standards/libs/adoption/packagemanager.py

@@ -0,0 +1,285 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+import json
+import re
+from typing import TYPE_CHECKING, Final
+
+from . import manifest
+
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator, Mapping, Sequence
+    from pathlib import Path
+
+
+class PackageManager(StrEnum):
+    NPM = "npm"
+    PNPM = "pnpm"
+    YARN = "yarn"
+    BUN = "bun"
+
+
+class YarnVariant(StrEnum):
+    CLASSIC = "classic"
+    BERRY = "berry"
+
+
+#: Lockfiles in deterministic package-manager precedence order.
+LOCKFILES: Final[tuple[tuple[str, PackageManager], ...]] = (
+    ("pnpm-lock.yaml", PackageManager.PNPM),
+    ("yarn.lock", PackageManager.YARN),
+    ("bun.lock", PackageManager.BUN),
+    ("bun.lockb", PackageManager.BUN),
+    ("package-lock.json", PackageManager.NPM),
+)
+
+_ESLINT: Final = "eslint"
+_YARN_BERRY_MINIMUM_MAJOR: Final = 2
+_YAML_ENTRY = re.compile(r'^\s*(?P<key>"[^"]+"|\'[^\']+\'|[^:#]+):\s*(?P<value>[^#\n]+?)\s*(?:#.*)?$')
+_EXACT_VERSION = re.compile(
+    r"^(?P<version>(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)"
+    r"(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?)"
+    r"(?:\+sha(?:224|256|384|512)\.[0-9a-f]+)?$"
+)
+
+
+def detect(root: Path) -> PackageManager:
+    declared = _declared_manager(root / "package.json")
+    if declared is not None:
+        return declared
+    detected = {client for name, client in LOCKFILES if (root / name).is_file()}
+    if len(detected) > 1:
+        names = ", ".join(sorted(str(client) for client in detected))
+        msg = f"conflicting package-manager lockfiles in {root}: {names}"
+        raise ValueError(msg)
+    if detected:
+        return next(iter(detected))
+    return PackageManager.NPM
+
+
+def workspace_root(project_root: Path, repository_root: Path) -> Path:
+    repository = repository_root.resolve()
+    project = project_root.resolve()
+    try:
+        project.relative_to(repository)
+    except ValueError as exc:
+        msg = f"TypeScript project {project} is outside repository {repository}"
+        raise ValueError(msg) from exc
+    candidates = (project, *project.parents)
+    bounded = [path for path in candidates if path == repository or repository in path.parents]
+    pnpm = next((path for path in bounded if (path / "pnpm-workspace.yaml").is_file()), None)
+    if pnpm is not None:
+        return pnpm
+    roots = [path for path in bounded if _declared_manager(path / "package.json") is not None or _has_lock(path)]
+    return roots[0] if roots else project
+
+
+def _has_lock(root: Path) -> bool:
+    return any((root / name).is_file() for name, _client in LOCKFILES)
+
+
+def yarn_variant(root: Path) -> YarnVariant:
+    declared = _declared_manager_spec(root / "package.json")
+    if declared is not None and declared.split("@", 1)[0] == PackageManager.YARN:
+        major = declared.partition("@")[2].partition(".")[0]
+        if major.isdigit():
+            return YarnVariant.CLASSIC if int(major) < _YARN_BERRY_MINIMUM_MAJOR else YarnVariant.BERRY
+    if (root / ".yarnrc.yml").is_file():
+        return YarnVariant.BERRY
+    return YarnVariant.CLASSIC
+
+
+def declared_version(root: Path, client: PackageManager) -> str | None:
+    declared = _declared_manager_spec(root / "package.json")
+    if declared is None:
+        return None
+    name, separator, raw_version = declared.partition("@")
+    if name != client or not separator:
+        return None
+    match = _EXACT_VERSION.fullmatch(raw_version)
+    if match is None:
+        msg = f"packageManager {declared!r} must pin an exact semantic version"
+        raise ValueError(msg)
+    return match.group("version")
+
+
+def _declared_manager_spec(package_json: Path) -> str | None:
+    if not package_json.is_file():
+        return None
+    try:
+        parsed: object = json.loads(  # pyright: ignore[reportAny] -- json.loads is an untyped stdlib boundary; the shape is narrowed below
+            package_json.read_text(encoding="utf-8")
+        )
+    except OSError, ValueError:
+        return None
+    return manifest.text_field(manifest.as_table(parsed), "packageManager")
+
+
+def _declared_manager(package_json: Path) -> PackageManager | None:
+    declared = _declared_manager_spec(package_json)
+    if declared is None:
+        return None
+    name = declared.split("@", 1)[0]
+    selected = next((client for client in PackageManager if client == name), None)
+    if selected is None:
+        supported = ", ".join(str(client) for client in PackageManager)
+        msg = f"unsupported packageManager {declared!r} in {package_json}; supported managers: {supported}"
+        raise ValueError(msg)
+    return selected
+
+
+@dataclass(frozen=True)
+class Overrides:
+    #: The package-manager policy document key path, outermost first.
+    key_path: tuple[str, ...]
+    entries: dict[str, object]
+
+    def as_document(self) -> dict[str, object]:
+        document: dict[str, object] = dict(self.entries)
+        for key in reversed(self.key_path):
+            document = {key: document}
+        return document
+
+
+def overrides_for(client: PackageManager) -> Overrides:
+    npm_entries = manifest.eslint_overrides()
+    match client:
+        case PackageManager.NPM:
+            return Overrides(("overrides",), {name: _resolved_tree(value) for name, value in npm_entries.items()})
+        case PackageManager.PNPM:
+            return Overrides(("overrides",), dict(_flatten(npm_entries, ">")))
+        case PackageManager.YARN:
+            return Overrides(("resolutions",), dict(_flatten(npm_entries, "/")))
+        case PackageManager.BUN:
+            # Bun ignores nested npm overrides, so pin ESLint at the root.
+            return Overrides(("overrides",), {_ESLINT: manifest.eslint_peers()[_ESLINT]})
+
+
+def pnpm_workspace_values(text: str) -> dict[str, str]:
+    values: dict[str, str] = {}
+    in_overrides = False
+    for line in text.splitlines():
+        if re.match(r"^overrides:\s*(?:#.*)?$", line):
+            in_overrides = True
+            continue
+        if in_overrides and line and not line[0].isspace():
+            break
+        if not in_overrides or (match := _YAML_ENTRY.match(line)) is None:
+            continue
+        key = match.group("key").strip().strip("\"'")
+        value = match.group("value").strip().strip("\"'")
+        values[key] = value
+    return values
+
+
+def _flatten(entries: Mapping[str, object], separator: str) -> Iterator[tuple[str, str]]:
+    peers = manifest.eslint_peers()
+    for parent, value in entries.items():
+        nested = manifest.as_table(value)
+        if not nested:
+            yield parent, _resolved(value, peers)
+            continue
+        for child, pin in nested.items():
+            yield f"{parent}{separator}{child}", _resolved(pin, peers)
+
+
+def _resolved(value: object, peers: Mapping[str, str]) -> str:
+    if not isinstance(value, str):
+        return str(value)
+    if not value.startswith("$"):
+        return value
+    return peers.get(value.removeprefix("$"), value)
+
+
+def _resolved_tree(value: object) -> object:
+    nested = manifest.as_table(value)
+    if nested:
+        return {name: _resolved_tree(pin) for name, pin in nested.items()}
+    return _resolved(value, manifest.eslint_peers())
+
+
+def install_command(
+    client: PackageManager,
+    *,
+    workspace: bool = False,
+    yarn: YarnVariant = YarnVariant.CLASSIC,
+) -> str:
+    match client:
+        case PackageManager.NPM:
+            return "npm install --ignore-scripts --no-audit --no-fund"
+        case PackageManager.PNPM:
+            suffix = "" if workspace else " --ignore-workspace"
+            return f"pnpm install --no-frozen-lockfile --ignore-scripts{suffix}"
+        case PackageManager.YARN:
+            if yarn is YarnVariant.BERRY:
+                return "yarn install --no-immutable --mode=skip-build"
+            return "yarn install --ignore-scripts"
+        case PackageManager.BUN:
+            return "bun install --ignore-scripts"
+
+
+def install_argv(
+    client: PackageManager,
+    *,
+    workspace: bool = False,
+    yarn: YarnVariant = YarnVariant.CLASSIC,
+) -> Sequence[str]:
+    return tuple(install_command(client, workspace=workspace, yarn=yarn).split())
+
+
+def frozen_install_argv(
+    client: PackageManager,
+    *,
+    yarn: YarnVariant = YarnVariant.CLASSIC,
+) -> Sequence[str]:
+    match client:
+        case PackageManager.NPM:
+            return ("npm", "ci", "--ignore-scripts", "--no-audit", "--no-fund")
+        case PackageManager.PNPM:
+            return ("pnpm", "install", "--frozen-lockfile", "--ignore-scripts")
+        case PackageManager.YARN:
+            if yarn is YarnVariant.BERRY:
+                return ("yarn", "install", "--immutable", "--mode=skip-build")
+            return ("yarn", "install", "--frozen-lockfile", "--ignore-scripts")
+        case PackageManager.BUN:
+            return ("bun", "install", "--frozen-lockfile", "--ignore-scripts")
+
+
+def exec_argv(client: PackageManager, *command: str) -> Sequence[str]:
+    match client:
+        case PackageManager.NPM:
+            return ("npm", "exec", "--offline", "--", *command)
+        case PackageManager.PNPM:
+            # `pnpm exec` only resolves binaries from the installed dependency
+            # tree. Unlike `pnpm dlx`, it never downloads a missing package, so
+            # an `--offline` flag is both unnecessary and invalid on pnpm 11.
+            return ("pnpm", "exec", *command)
+        case PackageManager.YARN:
+            return ("yarn", "exec", *command)
+        case PackageManager.BUN:
+            return ("bunx", "--bun", "--no-install", *command)
+
+
+def install_note(client: PackageManager, *, yarn: YarnVariant = YarnVariant.CLASSIC) -> str | None:
+    if client is PackageManager.YARN:
+        note = (
+            "Yarn resolves `resolutions` at install time, so re-run `yarn install`"
+            f" after the block is written -- and note Yarn pins {_ESLINT} for"
+            " eslint-plugin-react to an exact version rather than tracking your own."
+        )
+        if yarn is YarnVariant.BERRY:
+            note += (
+                " Yarn 4.15+ also refuses a package published within its minimum release"
+                " age (`All versions satisfying ... are quarantined`); if a fresh"
+                " @sarj/eslint-plugin trips that, set `npmMinimalAgeGate: 0` in"
+                " .yarnrc.yml or wait it out."
+            )
+        return note
+    if client is PackageManager.PNPM:
+        return (
+            "Keep pnpm overrides in pnpm-workspace.yaml at the detected install root;"
+            " pnpm 11 ignores package.json#pnpm.overrides even for standalone packages."
+        )
+    return None

sarj_standards/libs/adoption/retired_suppressions.py

@@ -0,0 +1,371 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum, auto
+import io
+import json
+from pathlib import Path
+import re
+import tokenize
+from typing import TYPE_CHECKING, Final
+
+from sarj_standards.libs.repository import ledger
+
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Iterable
+
+
+_SOURCE_SUFFIXES: Final = frozenset({".cjs", ".cts", ".js", ".jsx", ".mjs", ".mts", ".py", ".pyi", ".ts", ".tsx"})
+_ESLINT_DIRECTIVE: Final = re.compile(
+    r"(?P<intro>(?://|/\*)\s*eslint-(?:disable(?:-next-line|-line)?|enable)\s+)"
+    r"(?P<body>.*?)(?P<close>\s*\*/)?$"
+)
+_PYTHON_DIRECTIVE: Final = re.compile(r"(?P<intro>#\s*sarj-noqa:\s*)(?P<body>.*?)$")
+_REASON: Final = re.compile(r"(?P<rules>.*?)(?P<reason>\s+(?:--|[–—])\s+.*)?$")
+_ESLINT_SEGMENT = r"[A-Za-z0-9][A-Za-z0-9_-]*"
+_ESLINT_ID: Final = re.compile(rf"^(?:{_ESLINT_SEGMENT}|@?{_ESLINT_SEGMENT}(?:/{_ESLINT_SEGMENT})+)$")
+_SARJ_CODE: Final = re.compile(r"^SARJ\d+$")
+_ESLINT_SUPPRESSIONS: Final = "eslint-suppressions.json"
+
+
+@dataclass(frozen=True, slots=True)
+class Rewrite:
+    path: Path
+    contents: str
+
+
+class _DirectiveState(Enum):
+    NONE = auto()
+    VALID = auto()
+    AMBIGUOUS = auto()
+
+
+@dataclass(frozen=True, slots=True)
+class _CommentSpan:
+    start: int
+    end: int
+
+
+@dataclass(frozen=True, slots=True)
+class _Directive:
+    state: _DirectiveState
+    tokens: tuple[str, ...] = ()
+    match: re.Match[str] | None = None
+    reason: str = ""
+
+
+def supports(path: Path) -> bool:
+    return path.suffix.lower() in _SOURCE_SUFFIXES
+
+
+def plan(files: Iterable[Path]) -> tuple[Rewrite, ...]:
+    shipped = ledger.load()
+    retired = shipped.retired
+    active = shipped.active_ids()
+    eslint = {entry.id: _replacement(entry, active) for entry in retired if entry.kind == ledger.ESLINT}
+    codes = {entry.id: _replacement(entry, active) for entry in retired if entry.kind == ledger.CODE}
+    rewrites: list[Rewrite] = []
+    for path in files:
+        if not supports(path) and path.name != _ESLINT_SUPPRESSIONS:
+            continue
+        try:
+            original = path.read_bytes().decode("utf-8")
+        except OSError, UnicodeDecodeError:
+            continue
+        if "sarj-doctor-ignore-retired-rules" in original:
+            continue
+        migrated = (
+            _rewrite_eslint_suppressions(original, eslint)
+            if path.name == _ESLINT_SUPPRESSIONS
+            else _rewrite(path, original, eslint, codes)
+        )
+        if migrated != original:
+            rewrites.append(Rewrite(path, migrated))
+    return tuple(rewrites)
+
+
+def reference_counts(path: Path, text: str) -> dict[str, int]:
+    if "sarj-doctor-ignore-retired-rules" in text:
+        return {}
+    retired = ledger.load().retired
+    entries = {entry.id: entry for entry in retired}
+    counts: dict[str, int] = {}
+    spans = _comment_spans(path, text)
+    for span in spans:
+        comment = text[span.start : span.end]
+        directive = _classify_directive(path, comment)
+        if directive.state is _DirectiveState.VALID:
+            for token in directive.tokens:
+                if token in entries:
+                    counts[token] = counts.get(token, 0) + 1
+        elif directive.state is _DirectiveState.AMBIGUOUS:
+            _add_pattern_hits(counts, retired, comment)
+
+    # Config objects and fixture strings can be reference sites too. Mask real
+    # comments first so ordinary prose and already-classified directives are not
+    # counted a second time.
+    uncomments = _mask_spans(text, spans)
+    for line in uncomments.splitlines():
+        if not _looks_like_ambiguous_reference(line, path):
+            continue
+        _add_pattern_hits(counts, retired, line)
+    return counts
+
+
+def _add_pattern_hits(counts: dict[str, int], retired: tuple[ledger.Retired, ...], text: str) -> None:
+    for entry in retired:
+        hits = len(entry.pattern.findall(text))
+        if hits:
+            counts[entry.id] = counts.get(entry.id, 0) + hits
+
+
+def _replacement(entry: ledger.Retired, active: frozenset[str]) -> str | None:
+    if entry.status is ledger.Status.REMOVED:
+        return None
+    replacement = entry.replacement
+    if replacement is None or replacement not in active:
+        return entry.id
+    if entry.kind == ledger.ESLINT and not replacement.startswith("@sarj/"):
+        return entry.id
+    if entry.kind == ledger.CODE and _SARJ_CODE.fullmatch(replacement) is None:
+        return entry.id
+    return replacement
+
+
+def _rewrite_eslint_suppressions(text: str, retired: dict[str, str | None]) -> str:
+    bom = "\ufeff" if text.startswith("\ufeff") else ""
+    payload = text.removeprefix("\ufeff")
+    try:
+        parsed: object = json.loads(  # pyright: ignore[reportAny] -- untyped stdlib boundary
+            payload,
+            object_pairs_hook=_unique_object,
+        )
+    except _DuplicateKeyError, json.JSONDecodeError:
+        return text
+    if not isinstance(parsed, _JsonObject):
+        return text
+    document: dict[str, dict[str, dict[str, int]]] = {}
+    changed = False
+    for file_name, raw_rules in parsed.values.items():
+        if not isinstance(raw_rules, _JsonObject):
+            return text
+        rules: dict[str, dict[str, int]] = {}
+        for rule_id, raw_budget in raw_rules.values.items():
+            if (count := _suppression_count(raw_budget)) is None:
+                return text
+            target = retired.get(rule_id, rule_id)
+            changed |= target != rule_id
+            if target is None:
+                continue
+            existing = rules.get(target)
+            rules[target] = {"count": count if existing is None else max(count, existing["count"])}
+        document[file_name] = rules
+    if not changed:
+        return text
+    line_ending = "\r\n" if "\r\n" in payload else "\n"
+    trailing = line_ending if payload.endswith(("\n", "\r")) else ""
+    rendered = json.dumps(document, ensure_ascii=False, indent=2).replace("\n", line_ending)
+    return f"{bom}{rendered}{trailing}"
+
+
+class _DuplicateKeyError(ValueError):
+    """A JSON object repeated a key and therefore has no lossless object model."""
+
+
+@dataclass(frozen=True, slots=True)
+class _JsonObject:
+    values: dict[str, object]
+
+
+def _unique_object(pairs: list[tuple[str, object]]) -> _JsonObject:
+    result: dict[str, object] = {}
+    for key, value in pairs:
+        if key in result:
+            raise _DuplicateKeyError(key)
+        result[key] = value
+    return _JsonObject(result)
+
+
+def _suppression_count(value: object) -> int | None:
+    if not isinstance(value, _JsonObject) or set(value.values) != {"count"}:
+        return None
+    count = value.values.get("count")
+    return count if isinstance(count, int) and not isinstance(count, bool) and count >= 0 else None
+
+
+def _rewrite(path: Path, text: str, eslint: dict[str, str | None], codes: dict[str, str | None]) -> str:
+    rewritten = text
+    for span in reversed(_comment_spans(path, text)):
+        comment = text[span.start : span.end]
+        if _is_jsx_comment_wrapper(path, text, span, comment):
+            continue
+        directive = _classify_directive(path, comment)
+        if directive.state is not _DirectiveState.VALID:
+            continue
+        retired = codes if path.suffix.lower() in {".py", ".pyi"} else eslint
+        if not any(token in retired for token in directive.tokens):
+            continue
+        replacement = _rewrite_valid_directive(directive, retired)
+        start = span.start
+        if not replacement:
+            line_start = rewritten.rfind("\n", 0, start) + 1
+            prefix = rewritten[line_start:start]
+            trimmed = prefix.rstrip(" \t")
+            end = span.end
+            if not trimmed:
+                if rewritten.startswith("\r\n", end):
+                    end += 2
+                elif rewritten.startswith("\n", end):
+                    end += 1
+            rewritten = f"{rewritten[:line_start]}{trimmed}{rewritten[end:]}"
+        else:
+            rewritten = f"{rewritten[:start]}{replacement}{rewritten[span.end :]}"
+    return rewritten
+
+
+def _is_jsx_comment_wrapper(path: Path, text: str, span: _CommentSpan, comment: str) -> bool:
+    if path.suffix.lower() not in {".jsx", ".tsx"} or not comment.startswith("/*"):
+        return False
+    line_start = text.rfind("\n", 0, span.start) + 1
+    line_end = text.find("\n", span.end)
+    if line_end < 0:
+        line_end = len(text)
+    return text[line_start : span.start].rstrip().endswith("{") and text[span.end : line_end].lstrip().startswith("}")
+
+
+def _classify_directive(path: Path, comment: str) -> _Directive:
+    python = path.suffix.lower() in {".py", ".pyi"}
+    pattern = _PYTHON_DIRECTIVE if python else _ESLINT_DIRECTIVE
+    marker = "sarj-noqa" if python else "eslint-"
+    valid = _SARJ_CODE.fullmatch if python else _ESLINT_ID.fullmatch
+    match = pattern.fullmatch(comment)
+    if match is None:
+        state = _DirectiveState.AMBIGUOUS if marker in comment.lower() else _DirectiveState.NONE
+        return _Directive(state)
+    reason_match = _REASON.fullmatch(match.group("body"))
+    if reason_match is None:
+        return _Directive(_DirectiveState.AMBIGUOUS)
+    tokens = _comma_delimited_tokens(reason_match.group("rules"), valid)
+    if not tokens:
+        return _Directive(_DirectiveState.AMBIGUOUS)
+    return _Directive(_DirectiveState.VALID, tokens, match, reason_match.group("reason") or "")
+
+
+def _comma_delimited_tokens(body: str, valid: Callable[[str], object | None]) -> tuple[str, ...]:
+    raw = tuple(part.strip() for part in body.strip().split(","))
+    if not raw or any(not token or valid(token) is None for token in raw):
+        return ()
+    return raw
+
+
+def _comment_spans(path: Path, text: str) -> tuple[_CommentSpan, ...]:
+    return _python_comment_spans(text) if path.suffix.lower() in {".py", ".pyi"} else _javascript_comment_spans(text)
+
+
+def _python_comment_spans(text: str) -> tuple[_CommentSpan, ...]:
+    try:
+        tokens = tokenize.generate_tokens(io.StringIO(text).readline)
+        offsets = _line_offsets(text)
+        return tuple(
+            _CommentSpan(offsets[token.start[0] - 1] + token.start[1], offsets[token.end[0] - 1] + token.end[1])
+            for token in tokens
+            if token.type == tokenize.COMMENT
+        )
+    except IndentationError, SyntaxError, tokenize.TokenError:
+        return ()
+
+
+def _javascript_comment_spans(text: str) -> tuple[_CommentSpan, ...]:
+    spans: list[_CommentSpan] = []
+    index = 0
+    quote: str | None = None
+    while index < len(text):
+        char = text[index]
+        if char == "\n":
+            if quote in {"'", '"'}:
+                quote = None
+            index += 1
+            continue
+        if quote is not None:
+            if char == quote and not _escaped(text, index):
+                quote = None
+            index += 1
+            continue
+        if char in {"'", '"', "`"}:
+            quote = char
+            index += 1
+            continue
+        if char == "/" and index + 1 < len(text) and not _escaped(text, index):
+            following = text[index + 1]
+            if following == "/":
+                newline = text.find("\n", index + 2)
+                end = len(text) if newline < 0 else newline - int(newline > 0 and text[newline - 1] == "\r")
+                spans.append(_CommentSpan(index, end))
+                index = len(text) if newline < 0 else newline
+                continue
+            if following == "*":
+                closing = text.find("*/", index + 2)
+                if closing < 0:
+                    spans.append(_CommentSpan(index, len(text)))
+                    return tuple(spans)
+                spans.append(_CommentSpan(index, closing + 2))
+                index = closing + 2
+                continue
+        index += 1
+    return tuple(spans)
+
+
+def _line_offsets(text: str) -> tuple[int, ...]:
+    offsets = [0]
+    offsets.extend(index + 1 for index, char in enumerate(text) if char == "\n")
+    return tuple(offsets)
+
+
+def _mask_spans(text: str, spans: tuple[_CommentSpan, ...]) -> str:
+    masked = list(text)
+    for span in spans:
+        for index in range(span.start, span.end):
+            if masked[index] not in {"\r", "\n"}:
+                masked[index] = " "
+    return "".join(masked)
+
+
+def _escaped(text: str, index: int) -> bool:
+    backslashes = 0
+    cursor = index - 1
+    while cursor >= 0 and text[cursor] == "\\":
+        backslashes += 1
+        cursor -= 1
+    return backslashes % 2 == 1
+
+
+def _looks_like_ambiguous_reference(line: str, path: Path) -> bool:
+    normalized = line.lower()
+    if "sarj" not in normalized:
+        return False
+    if "baseline" in path.name.lower():
+        return True
+    return (
+        "eslint-disable" in normalized
+        or "eslint-enable" in normalized
+        or "sarj-noqa" in normalized
+        or "--rule" in normalized
+        or re.search(r"[\"']@sarj/[^\"']+[\"']\s*:", line) is not None
+        or re.search(r"^\s*(?:-\s*)?(?:id|entry)\s*:\s*.*sarj", line, re.IGNORECASE) is not None
+    )
+
+
+def _rewrite_valid_directive(directive: _Directive, retired: dict[str, str | None]) -> str:
+    match = directive.match
+    if match is None:
+        return ""
+    migrated = tuple(
+        dict.fromkeys(
+            replacement for token in directive.tokens if (replacement := retired.get(token, token)) is not None
+        )
+    )
+    if migrated:
+        close = match.groupdict().get("close") or ""
+        return f"{match.group('intro')}{', '.join(migrated)}{directive.reason}{close}"
+    return ""