Repository navigation
Evaluate an optional coherent Twig quality profile #9
Description
Migrated from php-fast-forward/dev-tools#269. This is a backlog transfer, not completed implementation. Optional evaluation; not a prerequisite for initial 0.1.0. Related epic: #1.
Problem
Template and view-layer quality is currently not covered by a dedicated Twig-focused toolchain.
Twig-CS-Fixer, twigcs, and twig-linter each cover different areas (format, lint, and language-specific validation) that can prevent template regressions.
Proposal
Group these tools into one evaluation issue for a shared Twig template quality command profile.
Adoption plan:
- Evaluate all three tools and define minimum viable command set.
- Add one or more optional commands/subcommands (
twig:fix,twig:lint, or generic analysis profile). - Keep execution opt-in and non-blocking by default.
- Add docs showing how to configure template paths and severity thresholds.
Goals
- Improve template-level quality gates for repositories with Twig usage.
- Avoid duplicated or contradictory formatting/linting behavior.
- Keep template checks reproducible in CI.
Expected Benefits
- Reduced merge risk in Twig-heavy repositories.
- Clearer conventions around template coding standards and validation.
Why Not (if skipped)
- Additional install/dependency footprint.
- Configuration drift across repositories with different coding styles.
Non-goals
- Replacing front-end tooling for framework-specific template preprocessors.
- Enforcing hard-failure in all repos immediately.
Acceptance Criteria
- A clear single strategy for all three tools is documented and accepted.
- At least one command path is implemented as an evaluation spike.
- Rules/paths are configurable and local overrides take precedence.
Architectural / Isolation Criteria
- MUST: Template checks are isolated into a dedicated tool adapter layer.
- MUST: Report generation is deterministic and idempotent.
Domain constraints and delivery
Keep this opt-in, preserve consumer overrides and deterministic exits, separate check from writes, and avoid the DevTools monolith. No global rollout or dependency/plugin installation as a check side effect. Tests, current-head Codex AND CodeRabbit reviews and successful checks are required before merge. Version publication remains 0.x through the approved Changelog lifecycle only.
Activity
coisa commentedon Oct 21, 2026
Read-only compatibility triage, still optional and outside0.1.0; no packages installed or templates processed.
Current source manifests inspected: Twig-CS-Fixer declares PHP>=8.1/Twig^3.15 and Console through8; twigcs admits PHP8.3/8.4/8.5 and Console8. These are moving-source declarations, not tested release selections. asm89/twig-lint, one possible interpretation of the proposed twig-linter, instead requires Twig^1.16.2 and Console2–4. Do not add it to our runtime or assume the ambiguous name selects that legacy package.
DevTools currently requires Twig for docs/license rendering; that does not prove an existing template-quality profile. Prefer evaluating one style writer, with explicit syntax-validation needs, instead of installing three overlapping tools. Before choosing a release, test target Twig syntax/custom tags, changed-path transport, invalid config/tool exits, check byte preservation, explicit fix/idempotence and override precedence. Twig-CS-Fixer configuration enables a project cache by default; any future check adapter must disable/redirect it rather than silently writing into the consumer. Default PHP-only check remains unchanged.
coisa commentedon Oct 27, 2026
Evaluation update: an isolated fixture exercised Twig-CS-Fixer 4.1.1, twigcs 6.6.1 and Twig's native parser (Twig 3.30.0) on PHP 8.5.12. The proposed coherent strategy is one formatter (Twig-CS-Fixer), with grammar validation through native Twig tokenize()/parse(), without rendering templates. Both style CLIs accepted an unterminated if fixture that the native parser rejected, so formatter success alone is insufficient syntax validation.
Check/source-preservation, explicit fix, a second idempotent pass and a native override were exercised. The adapter still needs to preserve/intersect configured Finder paths with explicit selected files: passing CLI paths to Twig-CS-Fixer replaces its configured Finder. sserbin/twig-linter 3.1.2 cannot be added to the current runtime graph because its Symfony constraints stop at 6.x; twigcs overlaps formatter responsibilities and is not proposed as a second default formatter.
This is a private evaluation spike, not shipped commands or universal template validation. Public configuration/command acceptance, dedicated adapter tests and the actual PHP 8.3/8.4/8.5 runtime matrix remain. Custom extension/runtime semantics and include existence are not proved by tokenize()/parse(). This issue remains open.
coisa commentedon Oct 27, 2026
Evaluation slice integrated by PR #68, merge 195f0bd. Exact-head CI, Codex code/security and CodeRabbit reviews completed without pending findings before merge. Main Quality run40490122133 then passed on PHP 8.3, 8.4 and 8.5, including both isolated dependency provisioning and native Twig-contract evaluation.
The reproducible spike selects Twig-CS-Fixer 4.1.1 plus native Twig 3.30.0 syntax parsing, with 33 checks covering Git/Finder intersection, native overrides, grammar validation before fix, deterministic JSON and idempotence. Twigcs is retained as an overlapping comparator; the evaluated standalone twig-linter has incompatible Symfony constraints. Configuration PHP remains trusted; no consumer autoload is imported automatically and no template is rendered.
This issue remains open for acceptance of the complete shared consumer-profile strategy and its documented integration/compatibility limits. This merge does not expose a supported Code Standards Twig command, migrate consumers or publish a version. The implementation and limits are recorded in docs/twig-evaluation.rst; this comment is delivery evidence, not a claim that every proposal item is complete.