chore(ts-sdk): regenerate Knowledge Graph API types from upstream spec

[adnanrhussain]

Regenerates sdks/typescript/src/knowledge-graph/kg-api.d.ts from the live spec at docs.learningcommons.org, which had drifted from the checked-in copy. Split out from #157 to keep that security bump scoped.

What actually changed in the spec

The raw diff is ~1800 lines, but almost all of it is the curriculum path block (/courses, /lessons, /assessments, …) moving from the top of paths to the bottom. All 26 endpoints are unchanged. Filtering comments and ignoring order leaves three real changes, all in StandardsFrameworkItem:

Change	Breaking?
hasChildren: boolean added (required)	No — additive on responses; we project a subset
gradeLevel?: string[] → GradeLevelENUM[] | null (6 sites)	No — types.ts widens to string[] by design
jurisdiction?: string | null → JurisdictionENUM	No — we only send it as a query param

GradeLevelENUM and JurisdictionENUM member lists are unchanged. The narrowing is absorbed because types.ts deliberately declares these as string/string[] so the API can return values outside the current spec — the comment at the top of that file already states this.

Verification

tsc --noEmit, lint, and build clean; 321 tests pass (318 + 3 new). Also test-merged into the open KG PRs — clean merge and green on both:

• fix: harden Knowledge Graph client pagination, code normalization, and ambiguity detection #148 (sdk-kg-hardening) — 346 pass
• feat: add public StandardsCatalog for listing and validating academic standards #149 (sdk-standards-api, stacked on fix: harden Knowledge Graph client pagination, code normalization, and ambiguity detection #148) — 380 pass

Based on main rather than stacked: no open PR touches kg-api.d.ts or eslint.config.js, so there is nothing to conflict with.

New test: tests/unit/knowledge-graph/spec-conformance.test.ts

Guards the seam between the generated types and the hand-written ones in types.ts, so the next regeneration fails loudly instead of silently changing behaviour. Both type-level guards were verified to actually fail:

• Jurisdiction enum ↔ spec JurisdictionENUM mutual assignability. All 52 values currently match exactly. Confirmed a bogus added member fails tsc. This is the one real gap — client.ts only ever casts jurisdiction, so nothing else would have caught drift in that hand-maintained enum.
• The getStandardsByGrade projection mirrored against the spec schema; confirmed a renamed spec field fails tsc.
• Runtime: a fixture carrying every currently-required field (including the new hasChildren) still projects to exactly the six AcademicStandard keys, so future required-field additions can't leak into the public shape.

Lint config

no-irregular-whitespace began erroring on the regenerated file — the upstream spec text contains a U+00A0 in a statementCode description. Rather than strip the character (it would return on the next regeneration), the generated file is now excluded from lint. Nothing hand-maintained lives in it, and upstream prose shouldn't be able to break our lint gate.

Notes for follow-up (not in this PR)

• No drift detection exists. Nothing in scripts/checks/ or CI regenerates and diffs kg-api.d.ts, which is why it went stale. A check would need to hit the live spec URL, coupling CI to an external service — worth deciding deliberately rather than bundling here.
• PaginatedResponse.data is typed Record<string, never>[] in the spec, intersected with the concrete StandardsFrameworkItem[] override. Reading through the intersection works, but the element type can't be constructed, which is why the fixtures pin to the schema directly. Upstream spec wart worth reporting.
• hasChildren may simplify fix: harden Knowledge Graph client pagination, code normalization, and ambiguity detection #148/feat: add public StandardsCatalog for listing and validating academic standards #149. They distinguish organizational groupings from leaf standards via normalizedStatementType plus learning-component-set comparison; hasChildren now exposes this directly. Adjacent, not overlapping — no change made here.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[Copilot]

Pull request overview

Regenerates the TypeScript Knowledge Graph OpenAPI type definitions to match the current upstream spec, and adds a conformance test to prevent future spec/type drift from silently changing SDK behavior.

Changes:

• Regenerated kg-api.d.ts from the upstream Knowledge Graph OpenAPI spec (notably including the new required hasChildren field on StandardsFrameworkItem and enum-type tightening).
• Added a unit test that type-checks and runtime-checks the seam between generated spec types and hand-written SDK types/projections.
• Excluded the generated kg-api.d.ts from ESLint to avoid upstream-doc-text characters breaking lint (e.g., NBSP / irregular whitespace).

Reviewed changes

Copilot reviewed 2 out of 3 changed files in this pull request and generated 1 comment.

File	Description
sdks/typescript/src/knowledge-graph/kg-api.d.ts	Updated generated OpenAPI types to match the live upstream Knowledge Graph spec.
sdks/typescript/tests/unit/knowledge-graph/spec-conformance.test.ts	Adds compile-time and runtime guards to detect spec/type drift and projection changes.
sdks/typescript/eslint.config.js	Ignores the generated OpenAPI types file to prevent upstream doc text from failing lint.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[czi-fsisenda]

LGTM! 🚀
We should add kg-api.d.ts to a .gitattributes file as a generated file too

[adnanrhussain]

Good call — done in f593b75b. There was already a root .gitattributes using exactly this convention for the Python generated settings, so I followed it:

sdks/typescript/src/knowledge-graph/kg-api.d.ts linguist-generated=true

Also added the file to the header comment listing each generated path and the command that produces it (npm run generate:kg-types), matching the existing entries.

Verified with git check-attr: the generated file resolves to true, hand-written client.ts stays unspecified, and the existing Python patterns are unaffected. Future regenerations will collapse in the PR diff by default, which would have made this one far easier to review — the 3598-line diff here was almost entirely a path reordering.