check_workflow_make_targets¶

def check_workflow_make_targets(repo_root: Path) -> list[str]:
    """Report every CI invocation of a make target that nothing defines.

    Args:
        repo_root: Root directory of the repository.

    Returns:
        List of error messages, one per (file, missing target) pair. Empty when
        there is no Makefile — with no targets to compare against, every invocation
        would be reported, which is noise rather than signal.
    """
    return _undefined_targets(collect_targets(repo_root), _ci_invocations(_ci_files(repo_root), repo_root))

def invoked_targets(snippet: str) -> set[str]:
    """Return the resolvable make targets a shell snippet invokes.

    >>> sorted(invoked_targets("make fmt && make test"))
    ['fmt', 'test']

    Flags are dropped, including the value of a flag that takes one, so the
    argument of ``-C`` is never read as a target:

    >>> sorted(invoked_targets("make -C sub build"))
    ['build']

    ``VAR=value`` overrides are not targets either:

    >>> sorted(invoked_targets("make CFLAGS=-O2 release"))
    ['release']

    A word only make or a shell can resolve abandons the whole command, rather
    than contributing invented target names:

    >>> sorted(invoked_targets("make ${{ matrix.task }}"))
    []
    """
    targets: set[str] = set()
    for line in snippet.splitlines():
        words = line.replace(";", " ; ").replace("&&", " && ").split()
        for index, word in enumerate(words):
            if word == "make":
                targets.update(_targets_in_command(words[index + 1 :]))
    return targets

def main(argv: list[str] | None = None) -> int:
    """Run the hook and return a process exit code."""
    parser = argparse.ArgumentParser(description="Check every make target invoked by CI exists")
    parser.add_argument(
        "filenames",
        nargs="*",
        help="Filenames (ignored: a target removal must be caught as well as a workflow edit)",
    )
    parser.add_argument(
        "--require-invocations",
        action="store_true",
        help="Fail when the repo has CI files but none of them invokes make, rather than passing vacuously",
    )
    args = parser.parse_args(argv)  # filenames are consumed for pre-commit's sake and unused

    repo_root = find_repo_root()
    ci_files = _ci_files(repo_root)
    invocations = _ci_invocations(ci_files, repo_root)
    defined = collect_targets(repo_root)
    errors = _undefined_targets(defined, invocations)

    # Always, and before the errors: on a failing run this is the context for them, and
    # on a passing one it is the only thing distinguishing a real check from an empty
    # one. pre-commit hides a passing hook's output unless the hook sets `verbose: true`,
    # which is why --require-invocations exists rather than this line alone.
    print(summarize(len(ci_files), invocations, catch_all=defined.catch_all), file=sys.stderr)

    # A repo with no CI files at all is not claiming to have invocations, so it is not
    # held to the flag; one that ships CI files and yields nothing is what the flag is for.
    if args.require_invocations and ci_files and not invocations:
        errors.append(
            "no CI file invokes `make`, and --require-invocations was given. "
            "A workflow that delegates to a reusable one (`uses:`) keeps its commands in "
            "another repository, which this hook does not read; drop the flag if that is "
            "the intended shape of this repo's CI."
        )

    for error in errors:
        print(f"ERROR: {error}", file=sys.stderr)

    return 1 if errors else 0

def summarize(ci_file_count: int, invocations: dict[str, set[str]], *, catch_all: bool = False) -> str:
    """Return the one-line account of what a run actually inspected.

    A guard that finds no input passes exactly like one that passes on merit, so the
    run says what it read. The count is of distinct (file, target) pairs, which is
    what the check compares — ``make fmt test`` contributes two, and a target named
    twice in one file contributes one:

    >>> summarize(4, {"ci.yml": {"fmt", "test"}, ".gitlab-ci.yml": {"test"}})
    'inspected 4 CI file(s), found 3 resolvable `make` target invocation(s)'

    Zero is the answer worth being able to see. It is what a repo whose CI is
    entirely delegated to reusable workflows gets, and it means the check compared
    nothing:

    >>> summarize(8, {})
    'inspected 8 CI file(s), found 0 resolvable `make` target invocation(s)'

    A catch-all rule is the other way to compare nothing, and the more surprising
    one, because the invocations are right there and every one of them passes:

    >>> line = summarize(2, {"ci.yml": {"test"}}, catch_all=True)
    >>> line.startswith("inspected 2 CI file(s), found 1 resolvable")
    True
    >>> line.endswith("a catch-all rule (`%:`) defines every name, so none was compared")
    True
    """
    found = sum(len(targets) for targets in invocations.values())
    line = f"inspected {ci_file_count} CI file(s), found {found} resolvable `make` target invocation(s)"
    if catch_all:
        line += "; a catch-all rule (`%:`) defines every name, so none was compared"
    return line