refactor(core-web): enable TS strict mode in utils, dotcms-js and sdk-create-app + document the rollout

[nicobytes]

What

Four steps of the strict-mode rollout (epic #35932):

Issue	Project	Change
#35940	utils	Enable strict + fix the 32 (+17 spec) resulting type errors
#35939	dotcms-js	Enable strict + fix the 38 resulting type errors
#35938	sdk-create-app	Enable strict + fix the 2 resulting type errors
#35935	sdk-types	No code needed — it was already strict. Documents the rollout pattern instead.

All three add the standard six flags to the project's own tsconfig.json, following the pattern established in #36879 (dotcms-models). tsconfig.base.json stays at "strict": false — the rollout never flips it globally.

---

dotcms-js (#35939)

The largest of the three: 38 errors across 11 files, in a layer-1 core library with 20 dependent projects, including the dotcms-ui admin app. Six of those dependents are already strict, so this library's loose types were leaking uncertainty into projects that had opted into rigour.

Most fixes correct types that were simply wrong, rather than silencing the compiler:

Site	Was	Reality
Auth.loginAsUser	User	The code has always passed null when nobody is impersonating, and every consumer already guards with auth.loginAsUser || auth.user. Now User | null.
StringUtils.getLine	string	Its own JSDoc says "null if it does not exists". Now string | null.
HttpRequestUtils.getQueryStringParam	string	Same — JSDoc already documented the null case.
RoutingService.getPortletURL	string	Returns Map.get(). Now string | undefined.
SiteService.switchSiteById	Observable<Site>	Emits of(null) when no site is found. Now Observable<Site | null>; its one consumer already handled null.
ResponseView.bodyJsonObject	DotCMSResponse<T>	Assigned from HttpResponse.body, which is nullable. The surrounding try/catch could never throw and has been removed.

LoginService.urls moved from Record<string, string> to inference-typed, which resolves all 8 TS4111 errors at once and gives each endpoint a named property.

Two definite-assignment assertions were used, each with a TODO: LoginService._auth and SiteService.selectedSite are assigned during init but not in the constructor. Modelling them as | undefined is the truthful type, but their public getters (auth, currentSite) are consumed by already-strict projects, so widening them is a public-API change that belongs in its own issue.

No new any, @ts-ignore, or @ts-expect-error anywhere in this PR.

⚠️ dotcms-js has no build target and is tag-excluded from lint and test, so nothing in CI verifies these flags. They document intent; they do not enforce it. This was an explicit scoping decision — no typecheck target or CI gate was added. The six already-strict consumers provide partial, incidental coverage only. Full reasoning in specs/35939-dotcms-js-strict-mode/spec.md, which is included in this PR.

Blast-radius verification

data-access (a strict consumer) went from 106 type errors to 68, with zero new errors introduced — the honest types upstream remove noise downstream. dotcms-ui typechecks clean apart from a pre-existing missing dotcms-webcomponents/loader dist.

---

utils (#35940)

32 errors across only 3 files, plus 17 more that appeared in the spec files once the flags propagated through tsconfig.spec.json (baseline there was 0). Both are fixed here — leaving the spec errors would have shipped a regression.

The bulk was one constant. EMPTY_FIELD assigned null to 18 members that DotCMSContentTypeField declares non-nullable:

• Replaced with zero values of the declared types. Verified safe: nothing compares those members to null strictly — consumers use falsy checks such as isNewField's !field.id — so '', 0 and false behave identically at runtime.
• clazz has no zero value (DotCMSClazz is a union of concrete Java class names), so EMPTY_FIELD and EMPTY_SYSTEM_FIELD are now Omit<DotCMSContentTypeField, 'clazz'>. They are partial templates, not valid fields, and the type now says so. The derived COLUMN_FIELD / ROW_FIELD / TAB_FIELD already supply their own clazz, so they remain complete.

Other fixes:

Site	Change
getFieldsWithoutLayout	Truthy .filter() did not narrow the optional row.columns. A type predicate clears the TS2532 and both TS2769 without a cast.
ellipsizeText	Accepted null/undefined at runtime — its own guard and its tests say so — but declared string/number. Widened to match, with an explicit limit == null check so later comparisons narrow.
fallbackErrorMessages	Typed { [key: number]: string }, mirroring the identical declaration already in libs/data-access/.../dot-upload.service.ts.
dot-utils.ts	Bracket access for the six DotCMSContentlet index-signature reads in getImageAssetUrl.
dot-asset.service.ts	Explicit types for promises and the two fetchAsset params.

The nine as unknown as casts added are all in spec files, on inputs the tests deliberately pass as invalid, matching the idiom those files already used.

⚠️ Same enforcement gap as dotcms-js: utils has no build target and is tag-excluded from lint and test, so nothing in CI verifies these flags. Accepted trade-off, consistent with #35939.

Blast-radius verification

data-access (strict consumer) went from 68 type errors to 36, zero new. utils-testing (strict) unchanged at its 1 pre-existing error — the Omit did not break its EMPTY_SYSTEM_FIELD spread.

---

sdk-create-app (#35938)

Two errors, both from flags beyond plain strict:

• src/index.ts:393 — process.env.DEBUG needs bracket access under noPropertyAccessFromIndexSignature (TS4111). It is the only process.env.* dot access in the project.
• src/utils/index.ts:41 — fetchWithRetry tripped noImplicitReturns (TS7030). The loop returns on success and throws on the last attempt, but with retries < 1 the loop never runs and the function fell through returning undefined. Its only caller (isDotcmsRunning, src/index.ts:506) already guarded with if (res && …), so nothing broke in practice — but the signature was lying. Throwing after the loop closes the gap and narrows the return type to Promise<AxiosResponse>.

No build or CI wiring was needed here. The @nx/esbuild:esbuild executor type-checks before bundling (skipTypeCheck defaults to false and is not overridden), and CI already builds this project via nx run-many -t build (build-test in core-web/pom.xml). The same build runs in the SDK release pipeline (cicd_release-sdk.yml → nx run-many --projects='sdk-*'), so the flags are enforced on every release.

---

sdk-types (#35935)

libs/sdk/types/tsconfig.json has carried strict: true plus the four extra safety flags since the library was created (#31967), and tsc --noEmit passes with zero errors. It is also already enforced: tsconfig.lib.json sets "declaration": true, so @rollup/plugin-typescript sits in the Rollup chain and fails the build on a strict violation.

So no code change was required. What was missing was documentation, added here to core-web/CLAUDE.md:

• A ## TypeScript Strict Mode section covering the per-project flags, what actually enforces them, and the Vite exception (esbuild skips type checking, which is why the Nx Vite plugin infers a separate typecheck target).
• Fixes a line that forbade "strict": true in project tsconfigs. It sat under the Jest config guidance but read as a blanket ban, contradicted docs/frontend/TYPESCRIPT_STANDARDS.md, and blocked the epic outright. The restriction now points at tsconfig.spec.json, which is what it meant.

---

Test plan

dotcms-js

• pnpm exec tsc -p libs/dotcms-js/tsconfig.lib.json --noEmit — 0 errors (from 38)
• All six already-strict consumers build green: data-access, global-store, portlets-dot-analytics, portlets-dot-analytics-data-access, portlets-dot-locales-portlet, utils-testing
• data-access typecheck: 106 → 68 errors, zero new
• dotcms-ui typecheck clean (one pre-existing unrelated error)
• dotcms-js lint went from 42 to 41 problems (still tag-excluded)

sdk-create-app

• tsc --noEmit clean on lib and spec
• nx run sdk-create-app:build / :lint / :test green
• CLI smoke test: node dist/libs/sdk/create-app/index.js --help works
• Negative test: reverting the DEBUG fix makes nx run sdk-create-app:build fail with TS4111 — confirming the build gate is real

Both

• pnpm exec nx format:check --base=origin/main green
• No new any / @ts-ignore / @ts-expect-error (verified by diff grep)

Note: neither sdk-create-app nor dotcms-js has usable tests. sdk-create-app has zero test files (passWithNoTests: true); dotcms-js has 3 spec files that do not run (skip:test, and tsconfig.spec.json fails on a pre-existing jasmine types error). A green :test means nothing for either — the real verification is compilation.

---

Correction: a verification false negative (review follow-up)

A review comment caught a real regression this PR introduced, and the reason it slipped through matters for how the numbers above should be read.

libs/utils-testing/tsconfig.lib.json declares "types": ["jasmine"], and that package is not installed. tsc therefore emits TS2688: Cannot find type definition file for 'jasmine' and stops before semantic checking. So tsc -p libs/utils-testing/tsconfig.lib.json --noEmit reports exactly one error no matter what the code does.

The utils section originally reported "utils-testing unchanged at 1 pre-existing error" as evidence of no regression. That measurement proved nothing — nothing was being type-checked. Running the same config with --types node reveals 33 errors, including a genuine TS2741 caused by retyping EMPTY_SYSTEM_FIELD to Omit<DotCMSContentTypeField, 'clazz'>: the mock at dot-content-types.mock.ts:71 spreads it and never supplies clazz.

Fixed by giving the mock clazz: DotCMSClazzes.TEXT; that config is now at 32 errors, all pre-existing and unrelated.

Because the mock has ~103 consumers whose tests do run in CI, the runtime-value change was verified rather than assumed — clazz went null (pre-PR) → absent (this PR) → TEXT:

• FieldUtil.isRow / isColumn / isTabDivider compare for equality and return false for all three values.
• There is no !field.clazz or field.clazz === null anywhere in the repo.
• Test runs: default-value-property 7/7; dot-content-types-edit 545 passed across 48 suites; data-access 751 passed across 79 suites.

The data-access figures reported elsewhere in this PR (106 → 68 for dotcms-js, 68 → 36 for utils) are not affected — that project has no unresolved types entry, so those runs were doing real semantic checking.

core-web/CLAUDE.md now documents this masking behaviour so the next person does not repeat it.

Other two comments

• sdk-create-app — the throw said "requires at least 1 retry", but retries is the total attempt count (for (i = 0; i < retries; i++)), so retries = 1 is one attempt and zero retries. Reworded to "attempt".
• CLAUDE.md verify snippet — hard-coded libs/<project>/tsconfig.lib.json, which resolves for neither nested projects (libs/sdk/create-app, which has no tsconfig.lib.json) nor apps (tsconfig.app.json). Replaced with a <projectRoot> placeholder and both caveats.

Notes for reviewers

Three sibling issues in this rollout turned out not to need the work as written, and were resolved separately:

• [03/44] Enable TS strict mode in dotcms #35936 (dotcms) and [04/44] Enable TS strict mode in dot-layout-grid #35937 (dot-layout-grid) — closed as not applicable. Both are dead libraries with zero consumers that do not compile today; removal is tracked in Remove dead core-web libraries (libs/dotcms, libs/dot-layout-grid) #36950.
• The epic description was updated (44 → 42 projects) and corrected: it documented a typescript-strict-plugin / tsc-strict approach that was dropped — the bootstrap [00] Setup typescript-strict-plugin baseline + CI gate #35933 closed without the plugin ever landing. Sub-issues still referencing npx tsc-strict or // @ts-strict-ignore carry stale acceptance criteria; [06/44] Enable TS strict mode in dotcms-js #35939's were corrected on the issue.

Closes #35940
Closes #35939
Closes #35938
Closes #35935

[claude]

Claude finished @nicobytes's task in 4m 23s —— View job

---

Review

I reviewed the full diff against origin/main. This is a careful, well-verified strict-mode rollout — the type changes correct genuinely wrong signatures rather than papering over them, and the two prior Copilot comments are both resolved. I found no bugs introduced by this PR.

New Issues

None.

Resolved

• ✅ core-web/libs/sdk/create-app/src/utils/index.ts:124 — the misleading "retry"/"attempt" wording flagged by Copilot is fixed; the message now says "requires at least 1 attempt" and a comment clarifies retries is the total attempt count. The throw correctly closes the noImplicitReturns gap only for the unreachable retries < 1 case.
• ✅ core-web/CLAUDE.md — the hard-coded libs/<project>/tsconfig.lib.json path is replaced with a <projectRoot> placeholder plus the app (tsconfig.app.json) and no-tsconfig.lib.json caveats.

Notes (non-blocking, verified safe)

• FieldUtil.ts:571 — EMPTY_FIELD.dataType moved from null to ''. This compiles because the legacy DotCMSContentTypeField.dataType is typed string (dot-content-types.model.ts:544), and the runtime clazz-equality checks (isRow/isColumn/isTabDivider) never compare dataType, so behavior is unchanged.
• response-view.ts:71 — removing the try/catch in the constructor is safe: resp.body/resp.headers are plain property reads that cannot throw. The errorsMessages getter's this.bodyJsonObject?.messages.toString() ?? '' preserves prior behavior — when bodyJsonObject is present, messages access is unchanged.
• login.service.ts:322 — getFullAuth already handles loginAsUser being null (!!auth.loginAsUser || ...), consistent with the new User | null type.
• The two ! definite-assignment assertions (LoginService._auth, SiteService.selectedSite) are the honest minimal change here — widening the public getters is correctly deferred to a follow-up, and both carry TODO(#35939) notes.

Nice touch documenting the utils-testing TS2688 masking behavior in CLAUDE.md — that's a real trap that would otherwise recur.

· 35932-enable-strict-mode

[Copilot]

Pull request overview

This PR opts the sdk-create-app library into the workspace’s incremental TypeScript strict-mode rollout (issue #35932), and adjusts docs/runtime code to align with stricter typing and clearer failure modes.

Changes:

• Enabled strict TypeScript compiler flags for core-web/libs/sdk/create-app via its project tsconfig.json.
• Updated fetchWithRetry to throw when misconfigured with < 1 attempts to avoid an implicit undefined return path.
• Updated strict-mode rollout documentation and adjusted DEBUG env access to bracket notation for noPropertyAccessFromIndexSignature.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
core-web/libs/sdk/create-app/tsconfig.json	Enables strict compiler options at the project level for the strict-mode rollout.
core-web/libs/sdk/create-app/src/utils/index.ts	Adds an explicit throw path for invalid retries values in fetchWithRetry.
core-web/libs/sdk/create-app/src/index.ts	Switches DEBUG env access to process.env['DEBUG'] for strict-mode compatibility.
core-web/CLAUDE.md	Documents the strict-mode rollout procedure and clarifies portlet tsconfig guidance.