feat(ci): add deterministic PR convention checks

[Raina451]

Adds deterministic CI checks for recurring review feedback:

• Sample app structure and config hygiene
• ServiceModel/service JSDoc consistency
• OAuth scope documentation coverage
• Test hygiene checks

Source-aware checks use the TypeScript compiler API instead of regex-heavy parsing. The checks report all current violations; existing repo cleanup can happen in focused follow-up PRs.

[claude]

Two new findings from this review run: (1) unguarded JSON.parse on package.json in validate-samples.mjs line 115 crashes instead of recording a violation; (2) content.match() in check-jsdoc-sync.mjs line 67 only indexes the first class per file, silently skipping services that have a helper class declared before them. Inline suggestions posted on both.

[claude]

Two new findings this run (existing open threads on validate-samples.mjs:117 and check-jsdoc-sync.mjs:67 were skipped — already unresolved):

1. check-hygiene.mjs:29 — integrationFiles includes tests/integration/config/ and tests/integration/utils/, where try/catch and console.warn are legitimate. Any future addition of a necessary try/catch to cleanup.ts will trigger a misleading "Fix the new occurrences" failure. Suggested scoping integrationFiles to .integration.test.ts files and tests/integration/shared/ only.

2. check-docs-consistency.mjs:66 — trackRe cannot match a @track-decorated method when another decorator (e.g. @deprecated) is stacked between @track(...) and the method declaration. Such methods would silently skip the scope-row check. Suggested replacing \s*\n with [\s\S]*?\n (lazy) or an explicit decorator-skip group.

[claude]

One new finding this run (the four existing open threads were skipped per dedupe policy):

check-jsdoc-sync.mjs:99 — findIndex returns -1 when modelDoc is a proper prefix of serviceDoc (all model lines match but the service has extra trailing lines). Both modelLines[-1] and serviceLines[-1] are undefined, so the diagnostic message reads 'first difference: model: end, service: end' with no hint of what actually differs. Fix: fall back to modelLines.length as the index when findIndex returns -1, which points at the first extra line of the service doc.

[claude]

findIndex returns -1 when modelDoc is a strict prefix of serviceDoc (all model lines match corresponding service lines but the service has extra trailing lines). In that case modelLines[-1] and serviceLines[-1] are both undefined, so the diagnostic prints model: '<end>', service: '<end>' — completely unhelpful.

Suggested change

	const modelLines = modelDoc.split('\n');
	const serviceLines = serviceDoc.split('\n');
	const i = modelLines.findIndex((line, idx) => line !== serviceLines[idx]);
	violations.push({
	key,
	message: `JSDoc differs between ${model.modelName} and ${entry.className} - first difference:\n model: ${JSON.stringify(modelLines[i] ?? '<end>')}\n service: ${JSON.stringify(serviceLines[i] ?? '<end>')}`,
	});
	const modelLines = modelDoc.split('\n');
	const serviceLines = serviceDoc.split('\n');
	const i = modelLines.findIndex((line, idx) => line !== serviceLines[idx]);
	const diffIdx = i === -1 ? modelLines.length : i;
	violations.push({
	key,
	message: `JSDoc differs between ${model.modelName} and ${entry.className} - first difference:\n model: ${JSON.stringify(modelLines[diffIdx] ?? '<end>')}\n service: ${JSON.stringify(serviceLines[diffIdx] ?? '<end>')}`,
	});

When i === -1, diffIdx = modelLines.length points past the last model line, which lands on the first extra service line — the actual content that differs.

[claude]

One new finding this run (existing open threads on old file names were skipped — those files no longer exist in the PR, replaced by the TypeScript-AST-based rewrites):

check-jsdoc-consistency.mjs:88-94 — Same findIndex returns -1 bug that was flagged on the old check-jsdoc-sync.mjs. When modelDoc is a strict prefix of serviceDoc, all model lines match and findIndex returns -1, making modelLines[-1] and serviceLines[-1] both undefined. The diagnostic reads 'model: end, service: end' with no hint of what actually differs. Fix: fall back to modelLines.length as the index, which points at the first extra service line.

[claude]

Unresolved thread from this review run:

check-jsdoc-consistency.mjs — findIndex returns -1 bug (thread reopened)

The prior thread on this file was resolved but the fix was not applied. The current code still reads:

const i = modelLines.findIndex((line, idx) => line !== serviceLines[idx]);
violations.push({
  key,
  message: `... model: ${JSON.stringify(modelLines[i] ?? '<end>')} service: ${JSON.stringify(serviceLines[i] ?? '<end>')}`,
});

When modelDoc is a strict prefix of serviceDoc (all model lines match but the service has extra trailing lines), findIndex returns -1. Both modelLines[-1] and serviceLines[-1] are undefined, so the diagnostic prints model: '<end>', service: '<end>' — no hint of what actually differs.

The fix is a one-liner:

const i = modelLines.findIndex((line, idx) => line !== serviceLines[idx]);
const diffIdx = i === -1 ? modelLines.length : i;
// then use diffIdx instead of i in the message

[claude]

One thread unresolved this run:

check-jsdoc-consistency.mjs:90 (PRRT_kwDOOpObr86PfyY2) — the findIndex returning -1 bug was flagged in the prior pass but the fix was not applied. When modelDoc is a strict prefix of serviceDoc (all model lines match but the service has extra trailing lines), findIndex returns -1, making both modelLines[-1] and serviceLines[-1] undefined. The diagnostic then prints model: '<end>', service: '<end>' with no hint of what actually differs.

Fix (same as the prior suggestion):

const i = modelLines.findIndex((line, idx) => line !== serviceLines[idx]);
const diffIdx = i === -1 ? modelLines.length : i;
violations.push({
  key,
  message: `JSDoc differs between ${model.modelName} and ${entry.className} - first difference:\n      model:   ${JSON.stringify(modelLines[diffIdx] ?? '<end>')}\n      service: ${JSON.stringify(serviceLines[diffIdx] ?? '<end>')}`,
});

All other previously raised threads were verified as fixed in this revision.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[claude]

✅ No issues found. Checked for bugs and CLAUDE.md compliance.