fixpm 0.1.0__py3-none-any.whl

fixpm/__init__.py

@@ -0,0 +1,3 @@
+"""fixpm — interactive command fixer for npm / npx / pnpm / yarn."""
+
+__version__ = "0.1.0"

fixpm/__main__.py

@@ -0,0 +1,3 @@
+from fixpm.cli import app
+
+app()

fixpm/cli.py

@@ -0,0 +1,132 @@
+"""CLI entry point.
+
+Modes:
+  fixpm                       fix $FIXPM_LAST_COMMAND (set by shell hook)
+  fixpm <command words...>    fix an explicit command line
+  fixpm --dry-run <cmd>       print fixes without prompting/executing
+  fixpm --init zsh|bash       emit the hook script for eval "$(...)"
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from importlib import resources
+
+import typer
+
+from . import __version__
+from .corrector import get_corrections
+from .interactive import choose
+from .rules import all_specs, spec_for_binary
+from .rules.base import KIND_LABEL
+
+app = typer.Typer(
+    add_completion=False,
+    context_settings={"help_option_names": ["-h", "--help"]},
+    help="Fix broken npm / npx / pnpm / yarn commands.",
+)
+
+ENV_COMMAND = "FIXPM_LAST_COMMAND"
+ENV_EXIT_CODE = "FIXPM_LAST_EXIT_CODE"
+
+_HOOKS = {"bash": "fixpm.bash", "zsh": "fixpm.zsh"}
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"fixpm {__version__}")
+        raise typer.Exit()
+
+
+@app.callback(invoke_without_command=True)
+def main(
+    ctx: typer.Context,
+    command: list[str] | None = typer.Argument(
+        None, help="Failed command to fix. Reads $FIXPM_LAST_COMMAND when omitted."
+    ),
+    manager: str | None = typer.Option(
+        None, "--manager", "-m",
+        help="Force a package manager instead of auto-detecting.",
+    ),
+    dry_run: bool = typer.Option(
+        False, "--dry-run", help="Print fixes without prompting or executing."
+    ),
+    version: bool = typer.Option(
+        False, "--version", "-V", callback=_version_callback, is_eager=True,
+        help="Show version and exit.",
+    ),
+    init_shell: str | None = typer.Option(
+        None, "--init",
+        help='Emit a hook script for the given shell ("bash" or "zsh"). '
+             'Use inside eval: eval "$(fixpm --init zsh)".',
+    ),
+) -> None:
+    if init_shell is not None:
+        _emit_hook(init_shell)
+        return
+    if ctx.invoked_subcommand is not None:
+        return
+
+    text = " ".join(command).strip() if command \
+        else os.environ.get(ENV_COMMAND, "").strip()
+    if not text:
+        typer.secho("No command provided.", fg="red")
+        typer.echo(
+            'Run `fixpm <failed command>` or install a shell hook first: '
+            '`fixpm --init zsh`.'
+        )
+        raise typer.Exit(code=1)
+
+    spec = None
+    if manager:
+        spec = spec_for_binary(manager)
+        if spec is None:
+            names = ", ".join(sorted({s.binaries[0] for s in all_specs()}))
+            raise typer.BadParameter(f"unknown manager {manager!r}; pick one of: {names}")
+
+    corrections = get_corrections(text, spec=spec)
+    if not corrections:
+        typer.secho(f"No fix found for: {text}", fg="yellow")
+        raise typer.Exit(code=1)
+
+    if dry_run:
+        for c in corrections:
+            typer.echo(f"  [{KIND_LABEL[c.kind]}] {c.command}")
+        return
+
+    choice = choose(corrections)
+    if choice is None:
+        typer.echo("Cancelled.")
+        raise typer.Exit(code=1)
+
+    typer.secho(f"-> {choice.command}", fg="cyan", bold=True)
+    if not choice.executable:
+        typer.echo("This fix needs manual arguments — copy it and fill them in.")
+        raise typer.Exit(code=0)
+
+    raise typer.Exit(code=subprocess.run(choice.command, shell=True).returncode)
+
+
+def _emit_hook(shell: str) -> None:
+    filename = _HOOKS.get(shell)
+    if filename is None:
+        supported = ", ".join(sorted(_HOOKS))
+        typer.secho(f"Unsupported shell {shell!r}. Supported: {supported}",
+                    fg="red", err=True)
+        raise typer.Exit(code=1)
+    script = (resources.files("fixpm.shell") / filename).read_text(encoding="utf-8")
+    # Write LF-only bytes directly: Windows pipes translate "\n" to "\r\n",
+    # and a unix shell sourcing CRLF text ends up with broken hook definitions
+    # (functions named "...{\r"). Git Bash/MSYS silently tolerates CRLF, WSL
+    # and native Linux do not — so the raw byte stream must be LF.
+    sys.stdout.buffer.write(script.replace("\r\n", "\n").encode("utf-8"))
+    sys.stdout.buffer.flush()
+    rc_file = "~/.zshrc" if shell == "zsh" else "~/.bashrc"
+    typer.secho(f"# Add this line to your {rc_file}: "
+                f'eval "$(fixpm --init {shell})"', dim=True, err=True)
+
+
+if __name__ == "__main__":
+    app()

fixpm/corrector.py

@@ -0,0 +1,118 @@
+"""Turn analyzer issues into concrete, ranked replacement commands."""
+
+from __future__ import annotations
+
+import shlex
+
+from .detector import analyze, tokenize
+from .distance import similarity
+from .packages import NpmRegistry, base_name, format_downloads
+from .rules.base import Correction, Issue, IssueKind, ManagerSpec
+
+_client: NpmRegistry | None = None
+
+# Placeholder shown when a fix needs manual input (never auto-executed).
+_PLACEHOLDERS = {
+    "run": "<script>",
+    "exec": "<package> [args...]",
+    "dlx": "<package> [args...]",
+    "add": "<package>",
+    "install": "<package>",
+    "remove": "<package>",
+    "uninstall": "<package>",
+    "why": "<package>",
+    "info": "<package>",
+    "create": "<initializer>",
+    "config": "<key> <value>",
+    "cache": "<action>",
+    "pkg": "<action>",
+}
+
+
+def _default_client() -> NpmRegistry:
+    global _client
+    if _client is None:
+        _client = NpmRegistry()
+    return _client
+
+
+def get_corrections(
+    text: str,
+    *,
+    spec: ManagerSpec | None = None,
+    client: NpmRegistry | None = None,
+) -> list[Correction]:
+    """Top fix suggestions (max 3), best first."""
+    tokens, spec, issues = analyze(text, spec)
+    if spec is None or not issues:
+        return []
+    client = client or _default_client()
+    corrections: list[Correction] = []
+    for issue in issues:
+        corrections.extend(_fix_issue(tokens, spec, issue, client))
+    best: dict[str, Correction] = {}
+    for c in corrections:
+        if c.command not in best or c.score > best[c.command].score:
+            best[c.command] = c
+    ranked = sorted(best.values(), key=lambda c: (-c.score, c.command))
+    return ranked[:3]
+
+
+def _ratio_score(ratio: float) -> float:
+    return round(0.5 + 0.45 * ratio, 3)
+
+
+def _replace(tokens: list[str], index: int, new_token: str) -> str:
+    patched = list(tokens)
+    patched[index] = new_token
+    return shlex.join(patched)
+
+
+def _fix_issue(tokens: list[str], spec: ManagerSpec, issue: Issue,
+               client: NpmRegistry) -> list[Correction]:
+    kind = issue.kind
+
+    if kind is IssueKind.SUBCOMMAND_TYPO:
+        out = []
+        hinted = spec.typo_hints.get(issue.token.lower())
+        for cand in issue.candidates[:3]:
+            score = (0.95 if cand == hinted
+                     else _ratio_score(similarity(issue.token.lower(), cand)))
+            out.append(Correction(_replace(tokens, issue.index, cand),
+                                  kind, score, issue.message))
+        return out
+
+    if kind is IssueKind.FLAG_TYPO:
+        return [
+            Correction(_replace(tokens, issue.index, cand), kind,
+                       _ratio_score(similarity(issue.token, cand)),
+                       issue.message)
+            for cand in issue.candidates[:2]
+        ]
+
+    if kind is IssueKind.MISSING_DASHES:
+        return [Correction(_replace(tokens, issue.index, issue.candidates[0]),
+                           kind, 0.9, issue.message)]
+
+    if kind is IssueKind.ARG_REQUIRED:
+        placeholder = _PLACEHOLDERS.get(issue.token, "<arguments>")
+        return [Correction(f"{shlex.join(tokens)} {placeholder}", kind, 0.6,
+                           issue.message, False)]
+
+    if kind is IssueKind.PACKAGE_TYPO:
+        name = base_name(issue.token)
+        out = []
+        for s in client.suggest(name)[:3]:
+            if s.name.lower() == name.lower():
+                continue
+            new_token = issue.token.replace(name, s.name, 1)
+            detail = (f"package '{name}' -> '{s.name}' "
+                      f"({format_downloads(s.weekly_downloads)}/week)")
+            out.append(Correction(_replace(tokens, issue.index, new_token),
+                                  kind, s.score, detail))
+        return out
+
+    return []
+
+
+__all__ = ["get_corrections", "tokenize"]

fixpm/detector.py

@@ -0,0 +1,223 @@
+"""Classify what went wrong in a failed package-manager command line.
+
+One generic engine consumes every ``ManagerSpec``; per-manager knowledge lives
+entirely in the rule tables under ``fixpm.rules``.
+"""
+
+from __future__ import annotations
+
+import re
+import shlex
+
+from .distance import rank
+from .rules import spec_for_binary
+from .rules.base import Issue, IssueKind, ManagerSpec
+
+_PKG_RE = re.compile(
+    r"^(@[a-z0-9-~][a-z0-9-._~]*/)?[a-z0-9-~][a-z0-9-._~]*$", re.IGNORECASE
+)
+
+
+def tokenize(text: str) -> list[str]:
+    try:
+        return shlex.split(text)
+    except ValueError:
+        return text.split()
+
+
+def looks_like_package(token: str) -> bool:
+    """Conservative npm-package-name shape check (paths, globs and files out)."""
+    if not token or any(c in token for c in "*~=\\"):
+        return False
+    if token.startswith((".", "~")):
+        return False
+    if "/" in token and not token.startswith("@"):
+        return False
+    return bool(_PKG_RE.match(token))
+
+
+def _nearest(token: str, pool: tuple[str, ...], top: int = 2,
+             min_score: float = 0.6) -> list[str]:
+    return [c for c, _ in rank(token.lower(), [p.lower() for p in sorted(pool)],
+                               top=top, min_score=min_score)]
+
+
+def _sub_candidates(token: str, spec: ManagerSpec) -> list[str]:
+    hint = spec.typo_hints.get(token.lower())
+    if hint:
+        return [hint]
+    return _nearest(token, tuple(spec.vocabulary), top=3, min_score=0.55)
+
+
+def analyze(
+    text: str, spec: ManagerSpec | None = None
+) -> tuple[list[str], ManagerSpec | None, list[Issue]]:
+    """Return ``(tokens, spec_or_None, issues)`` for a failed command line."""
+    tokens = tokenize(text)
+    located = _locate(tokens, spec)
+    if located is None:
+        return tokens, None, []
+    index, spec = located
+    if spec.package_first:
+        return tokens, spec, _analyze_package_first(spec, tokens, index + 1)
+    return tokens, spec, _analyze_subcommand(spec, tokens, index + 1)
+
+
+def _locate(tokens: list[str],
+            spec: ManagerSpec | None) -> tuple[int, ManagerSpec] | None:
+    if spec is not None:
+        for i, t in enumerate(tokens[:4]):
+            if t in spec.binaries:
+                return i, spec
+        return None
+    for i, t in enumerate(tokens[:4]):
+        found = spec_for_binary(t)
+        if found is not None:
+            return i, found
+    return None
+
+
+def _analyze_subcommand(spec: ManagerSpec, tokens: list[str],
+                        start: int) -> list[Issue]:
+    issues: list[Issue] = []
+    rest = tokens[start:]
+
+    # Leading global flags, e.g. `npm --prefix ./x install`
+    i = 0
+    while i < len(rest) and rest[i].startswith("-"):
+        flag = rest[i]
+        if flag in spec.value_flags and i + 1 < len(rest):
+            i += 2
+            continue
+        if flag not in spec.global_flags:
+            near = _nearest(flag, spec.global_flags)
+            if near:
+                issues.append(Issue(
+                    IssueKind.FLAG_TYPO, flag, start + i,
+                    f"Unknown global flag '{flag}' — did you mean {near[0]}?",
+                    tuple(near),
+                ))
+        i += 1
+
+    if i >= len(rest):
+        return issues
+
+    sub = rest[i]
+    sub_abs = start + i
+    canon = spec.canonical(sub)
+
+    if canon is None:
+        candidates = _sub_candidates(sub, spec)
+        if candidates:
+            issues.append(Issue(
+                IssueKind.SUBCOMMAND_TYPO, sub, sub_abs,
+                f"'{sub}' is not a {spec.name} command",
+                tuple(candidates),
+            ))
+        # One fix at a time: stop validating after an unknown command.
+        return issues
+
+    # Chain commands like `yarn global add <pkg>` — absorb the sub-verb.
+    extra = 0
+    if canon == "global" and spec.sub_verbs and \
+            i + 1 < len(rest) and rest[i + 1] in spec.sub_verbs:
+        extra = 1
+        canon = f"global {rest[i + 1]}"
+    effective = canon.rsplit(" ", 1)[-1]
+    allowed = spec.flags.get(effective, ())
+
+    positional: list[tuple[int, str]] = []
+    j = i + 1 + extra
+    while j < len(rest):
+        token = rest[j]
+        if token == "--":  # passthrough separator: everything after is exempt
+            break
+        if token.startswith("-"):
+            if allowed and token not in allowed and token not in spec.global_flags:
+                near = _nearest(token, allowed)
+                if near:
+                    issues.append(Issue(
+                        IssueKind.FLAG_TYPO, token, start + j,
+                        f"Unknown flag '{token}' for `{spec.name} "
+                        f"{effective}` — did you mean {near[0]}?",
+                        tuple(near),
+                    ))
+            if token in spec.value_flags:
+                j += 1  # skip the consumed value
+        else:
+            positional.append((j, token))
+        j += 1
+
+    # `npm install express save-dev` -> missing dashes on `save-dev`
+    dashless = {f.lstrip("-"): f for f in allowed}
+    flagged: set[int] = set()
+    for jj, token in positional:
+        if len(token) > 1 and token in dashless:
+            issues.append(Issue(
+                IssueKind.MISSING_DASHES, token, start + jj,
+                f"Missing flag prefix — did you mean {dashless[token]}?",
+                (dashless[token],),
+            ))
+            flagged.add(jj)
+    positional = [(jj, t) for jj, t in positional if jj not in flagged]
+
+    if canon in spec.arg_required and not positional and extra == 0:
+        issues.append(Issue(
+            IssueKind.ARG_REQUIRED, sub, sub_abs,
+            f"`{spec.name} {sub}` needs an argument "
+            f"(see `{spec.name} help {effective}`)",
+            (),
+        ))
+
+    if canon in spec.package_commands or canon.startswith("global "):
+        checked = 0
+        for jj, token in positional:
+            if checked >= 2:
+                break
+            if token.lower() in spec.vocabulary or not looks_like_package(token):
+                continue
+            issues.append(Issue(
+                IssueKind.PACKAGE_TYPO, token, start + jj,
+                f"Check package name '{token}'",
+                (),
+            ))
+            checked += 1
+    return issues
+
+
+def _analyze_package_first(spec: ManagerSpec, tokens: list[str],
+                           start: int) -> list[Issue]:
+    issues: list[Issue] = []
+    rest = tokens[start:]
+    i = 0
+    while i < len(rest) and rest[i].startswith("-"):
+        flag = rest[i]
+        if flag in spec.value_flags and i + 1 < len(rest):
+            i += 2
+            continue
+        if flag not in spec.global_flags:
+            near = _nearest(flag, spec.global_flags)
+            if near:
+                issues.append(Issue(
+                    IssueKind.FLAG_TYPO, flag, start + i,
+                    f"Unknown flag '{flag}' — did you mean {near[0]}?",
+                    tuple(near),
+                ))
+        i += 1
+
+    if i >= len(rest):
+        issues.append(Issue(
+            IssueKind.ARG_REQUIRED, spec.name, start - 1,
+            f"`{spec.name}` needs a package or binary to run",
+            (),
+        ))
+        return issues
+
+    pkg = rest[i]
+    if looks_like_package(pkg):
+        issues.append(Issue(
+            IssueKind.PACKAGE_TYPO, pkg, start + i,
+            f"Check package name '{pkg}'",
+            (),
+        ))
+    return issues

fixpm/distance.py

@@ -0,0 +1,63 @@
+"""String-similarity primitives.
+
+We use optimal-string-alignment (a restricted Damerau-Levenshtein) so common
+transpositions ("svae" -> "save") cost 1, not 2. Pure stdlib, zero deps.
+"""
+
+from __future__ import annotations
+
+
+def edit_distance(a: str, b: str) -> int:
+    if a == b:
+        return 0
+    la, lb = len(a), len(b)
+    if la == 0 or lb == 0:
+        return la + lb
+    prev2: list[int] | None = None
+    prev = list(range(lb + 1))
+    for i in range(1, la + 1):
+        cur = [i] + [0] * lb
+        ca = a[i - 1]
+        for j in range(1, lb + 1):
+            cost = 0 if ca == b[j - 1] else 1
+            v = min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + cost)
+            if (
+                prev2 is not None
+                and i > 1
+                and j > 1
+                and ca == b[j - 2]
+                and a[i - 2] == b[j - 1]
+            ):
+                v = min(v, prev2[j - 2] + 1)
+            cur[j] = v
+        prev2, prev = prev, cur
+    return prev[lb]
+
+
+def similarity(a: str, b: str) -> float:
+    """Normalized similarity in [0, 1]; 1 means identical."""
+    m = max(len(a), len(b))
+    if m == 0:
+        return 1.0
+    return 1.0 - edit_distance(a, b) / m
+
+
+def rank(
+    target: str,
+    candidates: list[str],
+    *,
+    top: int = 3,
+    min_score: float = 0.6,
+) -> list[tuple[str, float]]:
+    """Best matches for *target*, sorted by score desc then length/name asc."""
+    seen: set[str] = set()
+    scored: list[tuple[str, float]] = []
+    for c in candidates:
+        if c in seen:
+            continue
+        seen.add(c)
+        s = similarity(target, c)
+        if s >= min_score:
+            scored.append((c, s))
+    scored.sort(key=lambda t: (-t[1], len(t[0]), t[0]))
+    return scored[:top]

fixpm/interactive.py

@@ -0,0 +1,28 @@
+"""Arrow-key interactive selection (questionary / prompt_toolkit)."""
+
+from __future__ import annotations
+
+import questionary
+from questionary import Choice
+
+from .rules.base import KIND_LABEL, Correction
+
+
+def choose(corrections: list[Correction]) -> Correction | None:
+    choices = [
+        Choice(
+            title=f"{c.command}   · {KIND_LABEL[c.kind]} · {int(c.score * 100)}%",
+            value=c,
+        )
+        for c in corrections
+    ]
+    choices.append(Choice(title="Skip — do nothing", value=None))
+    try:
+        return questionary.select(
+            "Apply a fix:",
+            choices=choices,
+            qmark="?",
+            instruction="(↑/↓ move · enter select · ctrl+c cancel)",
+        ).ask()
+    except (KeyboardInterrupt, EOFError):
+        return None