Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 61 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
# Repository guide for AI coding agents

## Project identity and scope

This is VitaliyBoyko's PCOV fork: a native PHP line-coverage extension with synchronous coverage export, immutable executable-line manifests, and optional native Magento GET coverage caching. It is not the upstream `krakjoe/pcov` release. Start with [README.md](README.md) for usage and [docs/manifest-and-records.md](docs/manifest-and-records.md) for the record contract.

The supported release target is Linux, non-thread-safe PHP 8.3, 8.4 and 8.5, as declared by `composer.json`, `config.m4` and CI. Legacy `cfg/701/` through `cfg/704/` and `config.w32` are retained source, not evidence of current PHP 7, Windows or ZTS support.

## Architecture and navigation

| Path | Responsibility |
| --- | --- |
| `pcov.c` | Zend execution/compile hooks, hit recording, CFG discovery, request/module lifecycle and public API registration |
| `php_pcov.h` | Extension version, shared declarations and module globals |
| `pcov_dump.c` | Native record validation, manifest-aware export, serialization and atomic publication |
| `pcov_fingerprint.c`, `pcov_fingerprint.h` | Source fingerprints and file identity checks |
| `pcov_request_cache.h` | Worker-local serialized-record cache, included by `pcov_dump.c` |
| `tools/` | PHP record reader, immutable manifest creation/merge/update CLI, legacy Magento sampling helper; read [tools/AGENTS.md](tools/AGENTS.md) before editing |
| `tests/` | PHPT regression suite and HTTP/cache test helpers |
| `benchmark/large-codebase/` | Synthetic upstream-versus-fork benchmark |
| `benchmark/magento/run.py`, `benchmark/measurements/` | Magento benchmark runner and recorded measurements |
| `.github/workflows/ci.yml`, `.github/workflows/release.yml` | PHP matrix checks and tag-driven release |

Data flow: execution records positive hits and retains selected op-arrays; export validates a manifest and source identity to emit hit-only records, or performs complete CFG discovery and emits full/full-fallback records. PHP tooling merges compatible records with a manifest to reconstruct executable lines, including uncovered lines.

## Build and validation

Run from the repository root with matching PHP CLI/development headers, `phpize`, compiler, autoconf, make and the other build dependencies listed in CI. Use an isolated PHP environment without conflicting coverage extensions.

CI's build and test commands are:

```sh
phpize
CFLAGS="-O2 -Wall -Wextra -Werror" ./configure --enable-pcov
make -j"$(nproc)"
NO_INTERACTION=1 REPORT_EXIT_STATUS=1 make test
```

CI runs these on PHP 8.3, 8.4 and 8.5 NTS. A pass on one runtime does not establish the whole matrix. Inspect skips as well as failures, especially tests requiring native export or HTTP request helpers. There is no PHPUnit or Composer test script; Composer metadata describes a PHP extension.

For changed PHP helpers use `php -l path/to/file.php`; for benchmark shell changes use `bash -n path/to/script.sh`. CI also rejects trailing whitespace. These syntax checks do not replace PHPT behavior checks.

The optional benchmark entry point is `sh benchmark/large-codebase/run.sh` (see its README for arguments). It requires Docker, Git and network access, builds upstream and fork extensions, and writes benchmark results. Do not treat old measurements as validation of a new change. Building/testing does not require `sudo make install` or changing the host's PHP configuration.

## Correctness and safety constraints

- Preserve upstream-compatible collection semantics and `-1` uncovered / positive covered line values. Recording must not acquire expensive CFG discovery work accidentally.
- Manifest uncertainty must fail closed to complete synchronous discovery: changed, new, unreadable or raced sources, incompatible identities, corrupt records and missing executable lines must not produce false hit-only success.
- Validate retained sources even when they have no positive hits. A request-local fallback cannot prove the complete application's file inventory.
- Keep manifests immutable. Publish replacements at new paths; never reinterpret old hit records against a new manifest.
- Maintain binary reader/writer parity, bounded lengths/counts, overflow checks, checksums and deterministic fallback reasons. Coordinate native changes with `tools/` and PHPT tests.
- Preserve exclusive temporary creation and atomic rename. Failed publication must retain retryable in-memory coverage.
- Keep request-allocated Zend data separate from worker-owned cache bytes. Cache reuse must compare actual current coverage and must never skip execution or become an HTTP response cache.
- Do not conflate native request caching with the older PHP sampling helper. Their semantics differ.
- Preserve C ownership and lifecycle cleanup, existing formatting and PHP compatibility. Do not modernize legacy CFG sources or broaden platform claims as part of an unrelated fix.

## Change workflow

Trace the affected API through native implementation, PHP decoder/merger and tests before editing. Extend nearby PHPT cases for changed behavior; `tests/049.phpt` covers fingerprint/checksum boundaries and `tests/050.phpt` malformed record decoding and merge deduplication.

Keep generated build products, coverage records and benchmark output out of the change. Do not change versions, create release tags or publish releases unless requested. PRs should explain the behavioral contract, tests actually run and missing runtime/platform checks. Documentation-only changes need path/command and diff review, not a fabricated runtime-test claim.
4 changes: 4 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -291,3 +291,7 @@ No. Export is synchronous and process-local. Manifest validation can reduce repe
[MageLens](https://github.com/VitaliyBoyko/MageLens) uses this fork for PHP coverage from Cypress or Playwright HTTP requests and combines it with JavaScript and [template coverage](https://github.com/VitaliyBoyko/magento-template-coverage). The [benchmark data](benchmark/measurements/) records specific test environments; it is not a performance guarantee for other workloads.

Report fork-specific problems in [this repository's issues](https://github.com/VitaliyBoyko/pcov/issues), including PHP version, SAPI, extension settings and export mode. Published versions are listed under [releases](https://github.com/VitaliyBoyko/pcov/releases).

## Repository navigation for AI agents

See [AGENTS.md](AGENTS.md) for the architecture map, source entry points, validation commands and contribution constraints.
24 changes: 24 additions & 0 deletions tools/AGENTS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
# PHP record and manifest tools

This guidance supplements the root [AGENTS.md](../AGENTS.md) for `tools/`.

## Navigation

- `pcov_record_loader.php`: strict binary decoder and record constants.
- `pcov_manifest_tools.php`: manifest encoding, bootstrap, merge, source inventory and atomic publication.
- `pcov_manifest.php`: CLI dispatch for `create`, `merge`, `update` and `inspect`; argument signatures are printed by the script.
- `pcov_request_magento_cache.php`: legacy PHP sampling helper. It is distinct from the native cache in `../pcov_request_cache.h`.

## Contracts to preserve

Read [manifest-and-records.md](../docs/manifest-and-records.md) and the corresponding native code in `../pcov_dump.c` before changing framing. The current format uses a 48-byte header, big-endian fields, SHA-256 identities and CRC-32. Never encode platform-dependent pointers or native structures.

Validate sizes before slicing/iterating; reject unsupported framing, duplicate or unsorted entries, invalid line values, overflow, truncation and trailing bytes. Keep PHP integer-width assumptions explicit. Treat record contents as input data, not executable PHP.

Merging requires matching environment and manifest identities. Duplicate hit records must remain idempotent. Full fallback makes the candidate incomplete until an authoritative inventory/full discovery resolves it; do not remove the CLI's incomplete-coverage refusal.

The `merge` CLI writes a PHP coverage array, while CLI status is JSON on stdout and errors go to stderr. Preserve these interfaces and exit behavior. Use temporary fixtures and new output paths; never overwrite an input manifest.

## Validation

Run `php -l` on changed helpers, then the root PHPT suite with the freshly built extension. Add behavioral cases in `../tests/`, especially malformed records, mixed full/hit merges, source changes and atomic-write failures. Lint alone does not validate binary compatibility. Avoid adding a separate PHPUnit/Composer workflow.
Loading