Wire the diff-scoped strict typecheck gate into CI — merged on main but never executes

[nicobytes]

Description

The diff-scoped strict typecheck gate exists on main and has never executed once.

PR #37403 (spike #37401) merged on 2026-09-08. It added 37 files: 31 under core-web/tools/scripts/strict-gate/ and 6 under specs/37401-diff-scoped-strict-typecheck-gate/. It touched zero files under .github/ and zero lines of core-web/pom.xml. The harness README says so plainly: "The spike wires the harness into nothing."

Verified on origin/main @ de342798f4

Check	Result
git grep -l "strict-gate" outside its own directory and spec dir	no matches
<execution> ids in core-web/pom.xml	validate-dist-paths, pnpm-install, lint-test, format-test, build-test, build-analytics, unit-test, nx-reset, prod, do-nx-reset, validate, format, auto-format, auto-lint — no strict-gate
core-web/lint-staged.config.mjs	only nx affected -t lint / nx format:write — no strict-gate
Any workflow in .github/workflows/ mentioning strict	none

Consequence: since 2026-09-08 no pull request has been annotated, reported on, or blocked by the gate. It is dead code on main, and main has kept accumulating strict debt exactly as before the spike.

Why this is worth finishing rather than deleting

The obvious objection is "#37198 turns the whole workspace strict, so drop it." DECOMMISSION.md §2 documents why that does not close the hole:

Declaring strict: true does not mean anything compiles it.

Fact	Value
Nx projects in core-web	57
…with a build target	18 — the other 39 have nothing that compiles them
…with a typecheck target	5, all inferred by @nx/vite/plugin, 0 declared in a project.json
Does the build see .spec.ts?	No — tsconfig.lib.json carries exclude: ["src/**/*.spec.ts", …]
Where the spike's findings lived	8 of 11 in .spec.ts (73 %)

#37198 changes tsconfigs, .ts and .html files — no project.json, no nx.json, no pom.xml, no workflow. It makes the baseline strict and fixes existing violations, but adds no mechanism that runs a type-check over the 39 projects with no build plus every .spec.ts. Lint does not type-check.

So either this gate ships as the interim mechanism, or #37198 grows a typecheck target. Doing neither leaves the gap open in both directions.

Scope decision

Non-blocking (reporting only) in this issue. The blocking flip stays out of scope: measured runtime is 8.4–9.4 s average with a 12 s tail against the 10 s budget SC-005 set to protect what ADR-0013 bought (frontend merge time ~45 min → ~15 min). Templates are a separate no-go (2.2× compiler time on the largest app) and are excluded entirely.

This issue supersedes #37448, which carries the same scope but was never picked up (opened 2026-09-07, no assignee, no milestone, 0 comments).

Acceptance Criteria

• core-web/pom.xml gains a strict-gate <execution> in the generate-resources phase, beside lint-test / format-test, gated by <skip>${skip.validate}</skip> so it runs only under -Pvalidate
• The execution runs node tools/scripts/strict-gate/run.mjs --base=${git.origin.branch} --flags=strict --granularity=line --scope=core-web --format=github
• Non-blocking semantics are explicit, not accidental: <successCodes> accepts 0 and 1 (findings do not fail the build) but not 2 — a harness that could not run must still fail loudly. Exit-code contract: contracts/cli.md
• A pull request touching core-web TypeScript shows inline annotations on the diff and a job summary on the run page (--format github writes to $GITHUB_STEP_SUMMARY)
• A pull request touching only backend code is a no-op pass — verified, not assumed (the frontend filter in .github/filters.yaml already gates the job on core-web/**)
• core-web/lint-staged.config.mjs runs the gate on staged TS files, in a non-overlapping glob key so it does not race the existing nx affected -t lint on git's index.lock
• The harness test suite (31 files) still passes and is documented as needing --test-concurrency=1
• Observed runtime is recorded on this issue from at least 5 real pull requests, so the blocking decision has a measured tail instead of the spike's corpus number
• core-web/tools/scripts/strict-gate/README.md no longer says the gate is wired into nothing; it states where the hook lives and that it is non-blocking
• strict mode: ship the diff-scoped strict typecheck gate (non-blocking first) #37448 is closed as superseded by this issue
• Out of scope, stated in the PR description: flipping to blocking, the template arm, and the three untried closure optimisations

Priority

Medium

Additional Context

No workflow change is required

cicd_comp_test-phase.yml already fetches origin/main (the Frontend Unit Tests job needs it for nx affected), and .github/filters.yaml already carries the frontend filter (core-web/**). The hook belongs in core-web/pom.xml like every other frontend gate — this is why grepping the workflows for "strict" finds nothing and always would.

Shape of the pom.xml execution

Model it on lint-test. The exec plugin's executable is ${node.install.dir}/pnpm, so the arguments start with exec:

<execution>
    <id>strict-gate</id>
    <goals><goal>exec</goal></goals>
    <phase>generate-resources</phase>
    <configuration>
        <skip>${skip.validate}</skip>
        <!-- 0 = clean, 1 = findings (non-blocking for now), 2 = harness failure (must fail) -->
        <successCodes>
            <successCode>0</successCode>
            <successCode>1</successCode>
        </successCodes>
        <arguments>
            <argument>exec</argument>
            <argument>node</argument>
            <argument>tools/scripts/strict-gate/run.mjs</argument>
            <argument>--base=${git.origin.branch}</argument>
            <argument>--flags=strict</argument>
            <argument>--granularity=line</argument>
            <argument>--scope=core-web</argument>
            <argument>--format=github</argument>
        </arguments>
    </configuration>
</execution>

parseArgs in run.mjs splits on =, so the inline --flag=value form used by lint-test works as-is. Unknown options are rejected by name.

Why --flags=strict --granularity=line

• strict is the repo convention (strict + noPropertyAccessFromIndexSignature, noImplicitOverride, noImplicitReturns, noFallthroughCasesInSwitch) — the same yardstick as tsconfig.base.json on the strict-mode branch. At line granularity it costs one extra finding over the narrow set across the whole corpus.
• line because whole-file makes an author inherit 83 % of what it reports from lines they did not write. New files are unaffected — every line of an added file is a changed line.

Measured evidence from the spike

• 11 findings across a 5-PR corpus, all 11 real, 0 false positives
• 99.1 % of diagnostics discarded on a representative portlet (217 of 219)
• Zero changes to any version-controlled file — strictness is forced in memory, never through a temporary config
• No new dependency; not an Nx project (registering one would put the harness into the graph it measures)

Local repro

cd core-web
nvm use
node tools/scripts/strict-gate/run.mjs --base origin/main --head HEAD
node --test --test-concurrency=1 'tools/scripts/strict-gate/*.test.mjs'

Verification for the reviewer

# Before the PR both come back empty. After it, both must match.
git grep -n "strict-gate" -- core-web/pom.xml core-web/lint-staged.config.mjs

References

• Spike: strict mode: validate a diff-scoped strict typecheck gate to stop new non-strict code landing on main #37401 · Spike PR: 37401 strict mode validate a diff scoped strict typecheck gate to stop new non strict code landing on main #37403 · Superseded follow-up: strict mode: ship the diff-scoped strict typecheck gate (non-blocking first) #37448
• Strict-mode migration this gate is scaffolding for: refactor(core-web): TS strict mode across all 44 projects — completes epic #35932 #37198
• core-web/tools/scripts/strict-gate/README.md
• specs/37401-diff-scoped-strict-typecheck-gate/findings.md (§5 runtime, §6 decisions, §7 templates, §10 go/no-go, §12 follow-up)
• specs/37401-diff-scoped-strict-typecheck-gate/DECOMMISSION.md (§2 precondition, §3.3 what to remove if promoted)
• specs/37401-diff-scoped-strict-typecheck-gate/contracts/cli.md (options, exit codes, output formats)

[github-actions]

PRs linked to this issue

• [DO NOT MERGE] probe: prove the strict gate blocks (#37536) by @nicobytes
• ci(core-web): run the diff-scoped strict typecheck gate on pull requests (#37536) by @nicobytes

[nicobytes]

Scope change: the gate ships blocking, not reporting-only

Recording this here because the issue body says the opposite and, as raised in review on #37545, the issue is the reviewer-facing contract — a decision that lives only in a pull request description is one the next reader will not find.

What this issue says (Scope decision, verbatim): "Non-blocking (reporting only) in this issue. The blocking flip stays out of scope", with <successCode>0</successCode><successCode>1</successCode> in the acceptance list and "flipping to blocking" named under Out of scope.

What #37545 ships: successCodes lists 0 and nothing else. Findings fail the check, and the change does not merge until they are fixed.

Why it moved

A reporting-only gate has no enforcement point anywhere in the delivery. The local pre-push hook that would have provided one was cut earlier in the same pull request (CI-only scope), so what remained was a gate that annotates a diff and lets the violation merge anyway. The decision was to make it actually gate.

Worth stating plainly: this was not re-approved against the issue's stated scope. It was a direct decision during implementation, which is why it is being written down here rather than left in a description.

The runtime argument this issue used has weakened, and a new one replaced it

The original reason to defer blocking was runtime: 8.4–9.4 s average, 12 s tail, against a 10 s budget. In context that is under 2% of the ~15 min a frontend-only change spends in the merge queue (ADR-0013), so it is not the obstacle this issue treated it as.

But review surfaced something that matters more, and it cuts the other way:

The gate had no merge base in CI, and was comparing against the tip of origin/main.

Confirmed in #37545's own run (job 104166954128):

strict-gate: warning — no merge base between 'origin/main' and head;
comparing against the tip of 'origin/main' instead.

cicd_comp_test-phase.yml checks out at fetch-depth: 1 and compensates with a depth-1 fetch, so both sides are truncated and git merge-base cannot traverse. That is survivable for nx affected — over-including projects for lint is harmless on a lint-clean main — which is why it went unnoticed while that was the only consumer. It is not survivable for a blocking strict check, because main is deliberately not strict-clean while #37198 is in flight: every commit main moved ahead gets attributed to the pull request and strict-checked. The harness's own comment on that code path records it producing 50 findings, essentially none of them the branch's own.

Consequence for this issue's evidence: the "11 findings, all 11 real, 0 false positives" figure was measured with a correct merge base. It does not transfer to the configuration the gate was about to ship in. Fixed in 61f3fde by resolving the base from the event payload (pull_request.base.sha / merge_group.base_sha), which also makes the hardcoded-origin/main-vs-master concern moot.

Other deviations from the acceptance list

Acceptance criterion	What ships	Why
<successCodes> accepts 0 and 1	0 only	Above
lint-staged.config.mjs runs the gate on staged files	not modified	The harness compares two committed points, so a commit-time hook would examine the previous commit and report "clean" on the violation being committed — verified, not theorised. A local hook has to sit at push time; one was built and then cut when the scope was narrowed to CI.
<skip>${skip.validate}</skip>	its own skip.strict.gate	A blocking gate that the documented way to silence lint and prettier also silences is not much of a gate
Gate runs on pull requests	pull requests and merge queue	main declares no required status checks, so a red check on a pull request does not stop a merge. A job failing in the merge queue ejects the pull request. Without the second context the gate would go red and merge anyway.

Still owed on this issue

• Evidence from [DO NOT MERGE] probe: prove the strict gate blocks (#37536) #37564 (throwaway probe): merge-base warning gone, annotation rendering inline, exit 1 failing the check
• Observed duration and diff size from at least five real pull requests, worst stated against the 10 s budget — still wanted, and now for a sharper reason: the gate is on the critical path of every frontend merge
• Follow-up issue for three things review raised that cross the harness's decision logic and were deliberately left out of ci(core-web): block merges that add strict-mode violations (#37536) #37545: exiting 2 when base resolution falls back to base-tip, a ::warning for changed files no project claims, and an internal deadline in run.mjs (the Maven watchdog kills pnpm, not the node grandchild)

Full review and per-thread responses: #37545.

[nicobytes]

Acceptance evidence: the gate blocks, and annotates the right line

From the throwaway probe #37564 (now closed), which carried #37545 plus one deliberate TS7006. Job 104606541845, run 35035425840.

1. The base comes from the event payload

strict-gate base: 6fe9551d4bcbd8481a841cb137382d90aaa8c279

2. The annotation is anchored to the file and line

From the check-run annotations API — this is what renders inline on the diff, and it is the one link in the chain that cannot be tested anywhere but GitHub:

path:    core-web/libs/utils/src/lib/dot-utils.ts
lines:   270-270
level:   failure
title:   strict-gate TS7006
message: TS7006: Parameter 'value' implicitly has an 'any' type.
         — Parameter is implicitly `any`. Add an explicit type annotation.

3. Findings fail the build

[INFO] --- exec:3.0.0:exec (strict-gate) @ dotcms-core-web ---
##[error]TS7006: Parameter 'value' implicitly has an 'any' type. …
[ERROR] Failed to execute goal …:exec (strict-gate) on project dotcms-core-web:
        Command execution failed. Process exited with an error: 1 (Exit value: 1)
[INFO] BUILD FAILURE

PR Test / Frontend Unit Tests concluded failure. In the merge queue that ejects the pull request, which is the mechanism this whole change rests on.

This closes the acceptance criterion "a pull request touching core-web TypeScript shows inline annotations on the diff and a job summary", and the request from review on #37545 to prove exit 1, rendering, and the blocking path before merging.

---

One thing the probe surfaced that is worth a follow-up

The base-tip warning still fires, and its wording is now wrong:

strict-gate: warning — no merge base between '6fe9551d…' and head;
comparing against the tip of '6fe9551d…' instead.
Findings may include changes the base introduced.

The behaviour is correct — the base is the divergence point, so comparing against its tip is exactly right, which is the whole point of the fix. But two consequences:

• Because both sides are still shallow, git merge-base can never traverse, so this warning now fires on every run rather than signalling anything.
• "Findings may include changes the base introduced" is no longer true, and a warning that is always present and says something false is one people learn to skip past — the same failure this issue is about, in miniature.

The harness cannot currently tell "no merge base, base is arbitrary" (genuinely degraded) from "no merge base, base is the divergence point" (correct). Folding this into the follow-up alongside exiting 2 on a genuinely degraded fallback, since they are the same distinction viewed from either side.