Method check_needs_update

ci/fingerprint/core.py:566–623

Check if files need to be processed. Delegates to ``zccache-fingerprint --cache-type hash check``. Exit 0 = run needed. Exit 1 = skip (cache hit). Use ``ext`` + ``root`` for fastest scanning (simple suffix match, scoped directory walk). Use ``include`` fo

(
        self,
        include: list[str] | None = None,
        exclude: list[str] | None = None,
        *,
        root: str = ".",
        ext: list[str] | None = None,
    )

        self.cache_file = self.fingerprint_dir / f"{subpath}.json"

    def check_needs_update(
        self,
        include: list[str] | None = None,
        exclude: list[str] | None = None,
        *,
        root: str = ".",
        ext: list[str] | None = None,
    ) -> bool:
        """
        Check if files need to be processed.

        Delegates to ``zccache-fingerprint --cache-type hash check``.
        Exit 0 = run needed.  Exit 1 = skip (cache hit).

        Use ``ext`` + ``root`` for fastest scanning (simple suffix match,
        scoped directory walk).  Use ``include`` for glob-pattern matching.

        Args:
            include: Glob patterns for files to monitor.
                     Cannot be combined with ``ext``.
            exclude: Optional patterns to exclude.
            root: Root directory for scanning (default: ".").
            ext: File extensions without dot (e.g., ["h", "cpp"]).
                 Faster than ``include`` — uses simple suffix match.
                 Cannot be combined with ``include``.

        Returns:
            True if processing is needed, False if cache is valid.
        """
        abs_root = str(Path(root).resolve())
        args = [
            "--cache-file",
            str(self.cache_file),
            "--cache-type",
            "hash",
            "check",
            "--root",
            abs_root,
        ]
        if ext:
            for e in ext:
                args.extend(["--ext", e])
        elif include:
            for pattern in include:
                args.extend(["--include", pattern])
        if exclude:
            for pattern in exclude:
                args.extend(["--exclude", pattern])

        result = _run_zccache(args)

        needs_update = result.returncode != 1

        # Write timestamp file on change (preserves existing feature)
        if needs_update and self.timestamp_file is not None:
            self._write_timestamp_file()

        return needs_update