Fix incomplete and repetitive Composer scripts across monorepo

[coderabbitai]

Overview

Several composer.json files across the monorepo contain Composer script definitions that are either unsupported syntax or produce incomplete results. These are non-blocking today but should be fixed for developer ergonomics and accurate coverage reporting.

Reported via PR #45 comment: #45 (comment)

Requested by: @juliolmuller

---

Problem 1 — @script extra-args is not supported by Composer

Composer does not support passing additional CLI arguments to a @script-name reference (e.g. "test:cov": "@test --coverage-html coverage"). The extra flags are silently ignored or cause unexpected behaviour.

Affected files:

• packages/cpf-dv/composer.json: "test:watch": "@test --watch" and "test:cov": "@test --coverage-html coverage"
• packages/cnpj-dv/composer.json: "test:watch": "@test --watch" and "test:cov": "@test --coverage-html coverage"
• packages/cnpj-fmt/composer.json: "test:watch": "@test --watch" and "test:cov": "@test --coverage-html coverage"

Each of these should be rewritten as self-contained commands (e.g. pest --configuration=.pest.config.xml --coverage-html coverage).

---

Problem 2 — test:cov missing coverage flag on isolated-process run

For packages whose test script is split into two Pest invocations (one for --group isolated-process-tests and one for the rest), only the second invocation in test:cov includes --coverage-html coverage. The isolated-process run is excluded, underreporting package coverage.

Affected files:

• packages/cnpj-utils/composer.json
• packages/cnpj-gen/composer.json
• packages/cnpj-val/composer.json

The first Pest call in each test:cov array should also include the coverage flag.

---

Problem 3 — Legacy PHPUnit-style scripts still in use

Several packages have not yet migrated to Pest and still reference phpunit-watcher which is no longer a dependency in most packages:

• packages/cpf-utils/composer.json
• packages/cpf-gen/composer.json
• packages/cpf-val/composer.json
• packages/cpf-fmt/composer.json
• packages/utils/composer.json
• packages/br-utils/composer.json

These packages should be evaluated for Pest migration or at minimum have their test:watch / test-coverage scripts corrected.

---

Acceptance Criteria

• All @script extra-args patterns replaced with self-contained commands
• All test:cov scripts produce coverage for both isolated-process and regular test runs
• Legacy phpunit-watcher references removed or replaced
• All affected composer test and composer test:cov scripts verified to run successfully

[coderabbitai]

🔗 Related PRs

#35 - Create new package for reusable utilities [merged]
#42 - Refactor CNPJ validation: optimize storage and remove Reflection [merged]
#43 - [v2][cnpj-val] Upgrade to latest API and add support to alphanumeric CNPJ format [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[juliolmuller]

@coderabbitai, search for information about the Problem 1 of this issue. It seems Composer does support extra args after the @some-script notation. If it's not an issue, mark the respective text with strike-through (like this), so we don't lose history of the considerations along the way.

[coderabbitai]

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
gh issue view 46 --repo LacusSolutions/br-utils-php

Length of output: 3028

---

🌐 Web query:

Composer scripts @some-script notation extra arguments pass through documentation

Length of output: 15235

---

🏁 Script executed:

#!/bin/bash
# Fetch the raw issue body as JSON
gh api repos/LacusSolutions/br-utils-php/issues/46 --jq '.body' > /tmp/issue_body.txt
cat /tmp/issue_body.txt

Length of output: 2886

---

🏁 Script executed:

#!/bin/bash
python3 << 'EOF'
import json, re

with open('/tmp/issue_body.txt', 'r') as f:
    body = f.read()

# Strike-through the Problem 1 section (between its ## heading and the next ---)
p1_pattern = r'(## Problem 1 — `@script extra-args` is not supported by Composer\n\nComposer does \*\*not\*\* support passing additional CLI arguments to a `@script-name` reference \(e\.g\. `"test:cov": "`@test` --coverage-html coverage"`\)\. The extra flags are silently ignored or cause unexpected behaviour\.\n\nAffected files:\n- `packages/cpf-dv/composer\.json`: `"test:watch": "`@test` --watch"` and `"test:cov": "`@test` --coverage-html coverage"`\n- `packages/cnpj-dv/composer\.json`: `"test:watch": "`@test` --watch"` and `"test:cov": "`@test` --coverage-html coverage"`\n- `packages/cnpj-fmt/composer\.json`: `"test:watch": "`@test` --watch"` and `"test:cov": "`@test` --coverage-html coverage"`\n\nEach of these should be rewritten as self-contained commands \(e\.g\. `pest --configuration=\.pest\.config\.xml --coverage-html coverage`\)\.)'

replacement = '<del>\n\n## Problem 1 — `@script extra-args` is not supported by Composer\n\nComposer does **not** support passing additional CLI arguments to a `@script-name` reference (e.g. `"test:cov": "`@test` --coverage-html coverage"`). The extra flags are silently ignored or cause unexpected behaviour.\n\nAffected files:\n- `packages/cpf-dv/composer.json`: `"test:watch": "`@test` --watch"` and `"test:cov": "`@test` --coverage-html coverage"`\n- `packages/cnpj-dv/composer.json`: `"test:watch": "`@test` --watch"` and `"test:cov": "`@test` --coverage-html coverage"`\n- `packages/cnpj-fmt/composer.json`: `"test:watch": "`@test` --watch"` and `"test:cov": "`@test` --coverage-html coverage"`\n\nEach of these should be rewritten as self-contained commands (e.g. `pest --configuration=.pest.config.xml --coverage-html coverage`).\n\n</del>'

new_body = re.sub(p1_pattern, replacement, body, flags=re.DOTALL)

# Strike-through the first acceptance criteria item
new_body = new_body.replace(
    '- [ ] All `@script extra-args` patterns replaced with self-contained commands',
    '- ~~[ ] All `@script extra-args` patterns replaced with self-contained commands~~'
)

print(repr(new_body))
EOF

Length of output: 5031

---

🏁 Script executed:

#!/bin/bash
python3 << 'EOF'
import subprocess, json

new_body = '## Overview\n\nSeveral `composer.json` files across the monorepo contain Composer script definitions that are either unsupported syntax or produce incomplete results. These are non-blocking today but should be fixed for developer ergonomics and accurate coverage reporting.\n\nReported via PR `#45` comment: https://github.com/LacusSolutions/br-utils-php/pull/45#discussion_r3326366307\n\nRequested by: `@juliolmuller`\n\n---\n\n<del>\n\n## Problem 1 — `@script extra-args` is not supported by Composer\n\nComposer does **not** support passing additional CLI arguments to a `@script-name` reference (e.g. `"test:cov": "`@test` --coverage-html coverage"`). The extra flags are silently ignored or cause unexpected behaviour.\n\nAffected files:\n- `packages/cpf-dv/composer.json`: `"test:watch": "`@test` --watch"` and `"test:cov": "`@test` --coverage-html coverage"`\n- `packages/cnpj-dv/composer.json`: `"test:watch": "`@test` --watch"` and `"test:cov": "`@test` --coverage-html coverage"`\n- `packages/cnpj-fmt/composer.json`: `"test:watch": "`@test` --watch"` and `"test:cov": "`@test` --coverage-html coverage"`\n\nEach of these should be rewritten as self-contained commands (e.g. `pest --configuration=.pest.config.xml --coverage-html coverage`).\n\n</del>\n\n---\n\n## Problem 2 — `test:cov` missing coverage flag on isolated-process run\n\nFor packages whose `test` script is split into two Pest invocations (one for `--group isolated-process-tests` and one for the rest), only the second invocation in `test:cov` includes `--coverage-html coverage`. The isolated-process run is excluded, underreporting package coverage.\n\nAffected files:\n- `packages/cnpj-utils/composer.json`\n- `packages/cnpj-gen/composer.json`\n- `packages/cnpj-val/composer.json`\n\nThe first Pest call in each `test:cov` array should also include the coverage flag.\n\n---\n\n## Problem 3 — Legacy PHPUnit-style scripts still in use\n\nSeveral packages have not yet migrated to Pest and still reference `phpunit-watcher` which is no longer a dependency in most packages:\n\n- `packages/cpf-utils/composer.json`\n- `packages/cpf-gen/composer.json`\n- `packages/cpf-val/composer.json`\n- `packages/cpf-fmt/composer.json`\n- `packages/utils/composer.json`\n- `packages/br-utils/composer.json`\n\nThese packages should be evaluated for Pest migration or at minimum have their `test:watch` / `test-coverage` scripts corrected.\n\n---\n\n## Acceptance Criteria\n\n- ~~[ ] All `@script extra-args` patterns replaced with self-contained commands~~\n- [ ] All `test:cov` scripts produce coverage for **both** isolated-process and regular test runs\n- [ ] Legacy `phpunit-watcher` references removed or replaced\n- [ ] All affected `composer test` and `composer test:cov` scripts verified to run successfully\n'

payload = json.dumps({"body": new_body})
with open('/tmp/payload.json', 'w') as f:
    f.write(payload)

result = subprocess.run(
    ['gh', 'api', '--method', 'PATCH', 'repos/LacusSolutions/br-utils-php/issues/46',
     '--input', '/tmp/payload.json', '--jq', '.number'],
    capture_output=True, text=True
)
print("stdout:", result.stdout)
print("stderr:", result.stderr)
print("returncode:", result.returncode)
EOF

Length of output: 3330

---

---

@juliolmuller, you're right! Composer has supported passing extra arguments after @script-name since Composer 1.8 (via PR #7720, merged November 2018). The official docs explicitly show this pattern as valid:

{
  "scripts": {
    "tests": "phpunit",
    "testsVerbose": "`@tests` -vvv"
  }
}

So patterns like "test:cov": "@test --coverage-html coverage" in the affected packages are perfectly valid and do not need to be rewritten as self-contained commands.

I've updated issue #46 accordingly:

• The entire Problem 1 section is now struck through using <del> tags.
• The first Acceptance Criteria item (All @script extra-args patterns replaced with self-contained commands) is struck through as well.