infra: migrate chronos to helper.py (#14313)

```
$ python3 infra/helper.py check-tests --integrity-check json-c
...
23/25 Test #23: test_object_iterator .............   Passed    0.02 sec
      Start 24: test_json_pointer
24/25 Test #24: test_json_pointer ................   Passed    0.02 sec
      Start 25: test_json_patch
25/25 Test #25: test_json_patch ..................   Passed    0.03 sec

100% tests passed, 0 tests failed out of 25

Total Test time (real) =   0.71 sec
Integrity validator run tests for project: json-c
Diff patching for stage after.
Diff patch analysis begin. Stage: after, Current working dir: /src/json-c
Diff patch analysis after stage.
Git repo found: /src/json-c
Diff patch generated at /tmp/chronos-diff.patch
Difference between diffs:
Patch result: success. No patch found that affects source control versioning.
INFO:chronos.manager:succeeded patch: True
INFO:chronos.manager:run_tests.sh result succeeded: does not patch source control
INFO:chronos.manager:json-c test completion succeeded: Duration of run_tests.sh: 2.45 seconds
```

and for a failing project:
```
$ python3 infra/helper.py check-tests --integrity-check cups
...
> -#~ msgstr "Utilização: cups-x509 [OPÇÕES] [COMANDO] [ARGUMENTO]"
> -
> -#, c-format
> -#~ msgid "cups-x509: Bad URI '%s'."
> -#~ msgstr "O URI '%s' não é válido para o cups-x509."
> -
> -#, c-format
> -#~ msgid "cups-x509: Unable to connect to '%s' on port %d: %s"
> -#~ msgstr "Não foi possível conectar '%s' na porta %d de %s para o cups-x509"

Patch result: failed. Patch found that affects source control versioning.
INFO:chronos.manager:succeeded patch: False
INFO:chronos.manager:run_tests.sh result failed: patches source control
INFO:chronos.manager:cups test completion failed: Duration of run_tests.sh: 278.28 seconds
```

Cups is failing because it patches the source control (fix in
#14291).

---------

Signed-off-by: David Korczynski <[email protected]>

Author: DavidKorczynski

infra/chronos/README.md

@@ -0,0 +1,120 @@
+# Chronos: rebuilding OSS-Fuzz harnesses using cached builds
+
+Chronos is a utility tooling to enable fast re-building of OSS-Fuzz projects
+and analysis of projects' testing infrastructure. This is used by projects,
+e.g. [OSS-Fuzz-gen](https://github.com/google/oss-fuzz-gen) to help speed up
+valuation processes during fuzzing harness generation.
+
+At the core, Chronos relies on caching containers after project build, in order
+to enable fast rebuilding of a project following minor patches, and also enable
+running of the tests in a given project. To support this, Chronos creates a snapshot
+of the Docker container given project post build completion. This means that all `.o` files, generated
+configurations etc. persist in the Docker container. These artifacts are then
+leveraged for future "replay builds" where only a minor part of the project has changed,
+e.g. due to some patching on the project. This patching could be e.g. minor adjustments
+to the fuzzing harness source code e.g. by [oss-fuzz-gen](https://github.com/google/oss-fuzz-gen).
+
+As such, at the core of Chronos are cached containers that are generated by taking a
+snapshot of the container of a project post project build.
+
+Chronos is focused on two features, rebuilding projects fast and running the
+tests of a given project.
+
+
+## Chronos features: fast rebuilding and running the tests of a project
+
+### CLI interface for Chronos
+
+The default route to validating Chronos is using the CLI available in `infra/experimental/chronos/manager.py`
+
+### Chronos feature: Fast rebuilding
+
+Chronos enables rebuilding projects efficiently in contexts where only a small patch
+needs to be evaluated in the target. This is achieved by running a replay build script
+in the build container, similarly to how a regular `build_fuzzers` command would run, but
+with the caveat that the replay build script only performs a subset of the operations
+of the original `build.sh`.
+
+The replay build scripts are constructed in two ways: manually or automatically.
+
+#### Option 1: Automated rebuilds
+
+Chronos supports automated rebuilding. This is meant as a generic mechanism to enable Chronos support for projects by default. This is achieved by:
+
+1. Calling into a `replay_build.sh` script during the building inside the container [here](https://github.com/google/oss-fuzz/blob/206656447b213fb04901d15122692d8dd4d45312/infra/base-images/base-builder/compile#L292-L296)
+2. The `replay_build.sh` calls into `make_build_replayable.py`: [here](https://github.com/google/oss-fuzz/blob/master/infra/base-images/base-builder/replay_build.sh)
+3. `make_build_replayable.py` adjusts the build environment to wrap around common commands, to avoid performing a complete run of `build.sh`: [here](https://github.com/google/oss-fuzz/blob/master/infra/base-images/base-builder/make_build_replayable.py).
+
+The automated rebuilding works in combination with [Ccache](https://ccache.dev/), in order to facilitate caching of e.g. `.o` files.
+This means that during rebuild mode as long as we have a cache, we don't need to e.g. run `configure` again and will only have to
+rebuild the changed source code.
+
+#### Option 2: Manually provided replay builds
+
+`replay_build.sh` above, is simply just a wrapper script around `build.sh` that aims to enable
+fast rebuilding of the project. This `replay_build.sh` can, however, be overwritten in the Dockerfile
+of the project's builder image to support a custom approach to fast rebuilding. Two examples of this is [php](https://github.com/google/oss-fuzz/blob/206656447b213fb04901d15122692d8dd4d45312/projects/php/replay_build.sh#L1) and [ffmpeg](https://github.com/google/oss-fuzz/blob/master/projects/ffmpeg/replay_build.sh#L1).
+
+Providing a manual `replay_build.sh` is likely more efficient at build time and can help speed up the process. Automated replay build scripts can also be erroneous.
+
+
+#### Testing the validity of a replay build
+
+The Chronos manager can use the `manager.py` to validate the validity of a
+replay build for a given project:
+
+```sh
+python3 infra/experimental/chronos/manager.py check-replay tinyobjloader
+```
+
+If the above command fails for the relevant project, then the replay build feature
+does not work for the given project.
+
+### Chronos feature:  Running tests of a project
+
+The second part of Chronos is a feature to enable running the tests of a given
+project. This is done by way of a script `run_tests.sh`. Samples of
+this script include [jsonnet](https://github.com/google/oss-fuzz/blob/master/projects/jsonnet/run_tests.sh#L1) and [tinyobjloader](https://github.com/google/oss-fuzz/blob/master/projects/tinyobjloader/run_tests.sh#L1).
+
+
+#### Run tests constraints
+
+1. The `run_tests.sh` main task is to run the tests of a project and return `0` upon success and non-null otherwise.
+2. The `run_tests.sh` script must leave the main repository in the state as it was prior to the execution of `run_tests.sh` relative to `git diff` (or similar diff features of other version control systems).
+
+#### Testing the validity of run_tests.sh
+
+The Chronos manager can use the `manager.py` to validate the validity of a
+`run_tests.sh` script:
+
+```sh
+python3 infra/experimental/chronos/manager.py check-tests json-c
+```
+
+
+### Constraints imposed on replay_build.sh and run_tests.sh
+
+At the core of chronos are the two scripts `replay_build.sh` and `run_tests.sh`. We have a default
+mechanism for `replay_build.sh` so it's not strictly necessary to have a custom one, although it will
+likely improve speed and maybe correctness by providing one.
+
+There are three stages of the Chronos workflow:
+
+1. The cached containers represent the state of a build container after a successful project build.
+2. The `replay_build.sh` is able to rebuild a given project from the state of a cached container.
+3. The `run_tests.sh` script is able to run the tests of a given project. This should be able to succeed following the running of a `replay_build.sh`.
+
+The stages (2) and (3) must both support running without network connectivity.
+Specifically, this means that the `replay_build.sh` must not do tasks e.g. fetch
+dependencies, download corpus, or anything of this nature. Similarly, the `run_tests.sh`
+must be able to operate completely in a closed network environment.
+
+
+## Pre-built images.
+
+Chronos cached images are built daily, and pre-built images are available at:
+
+- `us-central1-docker.pkg.dev/oss-fuzz/oss-fuzz-gen/<PROJECT>-ofg-cached-address`
+- `us-central1-docker.pkg.dev/oss-fuzz/oss-fuzz-gen/<PROJECT>-ofg-cached-coverage`
+
+They can be used as drop-in replacements for the usual `gcr.io/oss-fuzz/<PROJECT>` images.

infra/chronos/__init__.py

@@ -0,0 +1,16 @@
+#!/bin/bash -eux
+# Copyright 2025 Google LLC.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+###############################################################################

infra/chronos/container_cache_build.sh

@@ -0,0 +1,20 @@
+#!/bin/bash -eux
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+echo "Starting prepare cache build script"
+export PATH=/ccache/bin:$PATH
+python3.11 -m pip install -r /chronos/requirements.txt
+rm -rf /out/*
+compile
+cp -n /usr/local/bin/replay_build.sh $SRC/

infra/chronos/container_coverage_collection.sh

@@ -0,0 +1,20 @@
+#!/bin/bash -eux
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+chmod +x /src/run_tests.sh
+find /src/ -name "*.profraw" -exec rm -f {} \;
+/src/run_tests.sh
+python3 /chronos/coverage_test_collection.py
+chmod -R 755 /out/test-html-generation/

infra/chronos/container_patch_replay_test.sh

@@ -0,0 +1,22 @@
+#!/bin/bash -eux
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+echo "Starting container patch replay script: $1"
+
+python3 /chronos/integrity_validator_check_replay.py $1
+
+export PATH=/ccache/bin$PATH
+rm -rf /out/*
+compile

infra/chronos/container_patch_tests_test.sh

@@ -0,0 +1,25 @@
+#!/bin/bash -eux
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+echo "Starting container patch tests script"
+
+# Ensure dependencies are installed
+python3 -m pip install -r /chronos/requirements.txt
+
+# Capture patch, run tests and then diff patches.
+python3 /chronos/integrity_validator_run_tests.py diff-patch before
+chmod +x /src/run_tests.sh
+/src/run_tests.sh        
+python3 /chronos/integrity_validator_run_tests.py diff-patch after