chore(#10224): include docs for Datasource in site

[jkuester]

Description

This is a bit of prep work ahead of #10224 being resolved. When UI Extensions are released, that will be the official first time these cht-datasource APIs are actually available/useful for external configuration code (since the custom UI Extensions have access to the APIs and can leverage the async functionality! Access to these APIs is provided by injecting the result of getDatasource into the extensions at this.cht.

However, as you can see by looking at the docs in the link, we do not actually have very clean documentation for the imperative cht-datasource APIs. The function-level TS doc is not even pulled through into the docs site. 😞 This is because we have not really defined the returned "Datasource" as a formal type/interface (but it is just a return type).

The main goal of this PR is to add proper documentation for a Datasource interface that gets included in the docs site. This involved several changes:

• I exported a top-level Datasource interface to hold the documentation. The getDatasource function returns this type.
• For better maintainability, I broke out all the sub-concept levels (person/place/etc) into their own Datasource interfaces along with their own internal getDatasource functions and moved the code into the related files. Everything still rolls back up through the top-level Datasource, but this is way more maintainable and scalable.
• Instead of using the README as the "root" documentation for the TSDoc site, I have used the @packageDocumentation annotation in the index.ts file to make that file's docs the entry-point for the cht-datasource docs site.
  • This becomes the "public" front for these APIs (with an emphasis on pointing to the Datasource interface, which is what most folks care about).
  • The README focus is now on "internal" documentation regarding cht-datasource details that are really only relevant for cht-core developers.
• I made a few minor tweaks to the existing cht-datasource TSDocs to eliminate the existing warnings when generating the docs site (mostly exporting missing base types).
  • I had to make a small change to the generate-openapi.js script because the new Datasource interface is, of course, not referenced in any of our OpenAPI docs (as expected). The unreferenced schema was causing the OpenAPI json generation to fail.

AI Disclosure

Claude was super useful for producing/implementing the Datasource interfaces. However, if you look at my first commit, you can see that it has all these changes but leaves the unit tests totally untouched (and they still pass). This gave me high confidence that migration was properly executed.

Beyond that, pretty much all of the other minor docs changes, etc are my own doing.

Code review checklist

• Readable: Concise, well named, follows the style guide
• Documented: Configuration and user documentation on cht-docs
• Tested: Unit and/or e2e where appropriate
• Backwards compatible: Works with existing data and configuration or includes a migration. Any breaking changes documented in the release notes.
• AI disclosure: Please disclose use of AI per the guidelines.

License

The software is provided under AGPL-3.0. Contributions to this project are accepted under the same license.

[jkuester]

@sugat009 please do not fear the line-count on this PR! 😅 🙏 I promise it is almost entirely just a very "basic" refactor of how we structure the Datasource code/docs in cht-datasource. (Not really any complexity.) All the details about the changes are up in the description... 👍

[sugat009]

Requesting changes since several findings affect docs site rendering (typos, missing examples on entry point pages, unclosed backticks merging @throws clauses). The rest are advisory questions and nitpicks.

Also worth fixing while you're cleaning up docs (already on master, small enough to bundle in this PR):

• InvalidArrgumentError typo (extra r) at shared-libs/cht-datasource/src/contact.ts:103 and shared-libs/cht-datasource/src/target.ts:121. Should be InvalidArgumentError.

Noticed while reviewing, flagging for awareness (not asks for this PR):

• Cyclic import between shared-libs/cht-datasource/src/person.ts:6 and shared-libs/cht-datasource/src/place.ts:2 (lineage types reference each other; the cycle is purely at the type layer, so import type would break it).
• return await fn(qualifier) at shared-libs/cht-datasource/src/report.ts:204 is the only return await in the curried functions; the rest of the area uses return fn(qualifier).

[sugat009]

issue: The closing backtick after type is missing on this @throws line. The unclosed code span runs forward through the subsequent @throws lines until the next backtick (in `<=0`), merging multiple throw clauses into one garbled <code>-wrapped paragraph in the rendered docs.

Suggested change

	* @throws InvalidArgumentError if the `freetext` is empty or if the `type is invalid for a contact
	* @throws InvalidArgumentError if the `freetext` is empty or if the `type` is invalid for a contact

Same pattern at three other locations in this file:

• shared-libs/cht-datasource/src/contact.ts:195
• shared-libs/cht-datasource/src/contact.ts:229
• shared-libs/cht-datasource/src/contact.ts:238

Worth catching here since --treatWarningsAsErrors was just enabled on gen-docs in package.json:14 and the merged rendering is visible on the generated Contact.v1.Datasource.html page (getUuidsPageByFreetext and getUuidsPageByTypeFreetext properties).

[sugat009]

question (non-blocking): Is it intentional that the published docs site has no usage examples on the getDatasource or Datasource pages now?

The three @example blocks moved from index.ts to the README, and gen-docs now runs with --readme none (package.json:14), so TypeDoc no longer renders those examples anywhere on the docs site.

If unintentional, would it be worth adding back at least the imperative example as an @example on getDatasource so visitors landing on the docs site entry point still see a usage snippet?

[sugat009]

suggestion (non-blocking): Worth expanding this JSDoc to match the doc style of the other public interfaces in cht-datasource (DataContext and SettingsService in libs/data-context.ts both carry multi sentence descriptions explaining what they represent and how they're meant to be used).

Since this interface is the new docs site entry point, a few extra sentences here would give visitors landing on the Datasource page actual orientation. Something like:

/**
 * The CHT datasource API. Provides access to the CHT data model through versioned
 * sub APIs (e.g. `v1.person`, `v1.place`). Obtain an instance via {@link getDatasource}.
 */

[sugat009]

Suggested change

	* A privative value.
	* A primitive value.

[sugat009]

suggestion (non-blocking): UnionToIntersection is a TypeScript utility helper rather than part of the data model. Now that qualifier.ts is re-exported as Qualifier from the package root, this lands on the public surface as Qualifier.UnionToIntersection. Consider marking @internal so --excludeInternal strips it from the docs site.

/**
 * The intersection of the specified types.
 * @internal
 */

[sugat009]

Suggested change

	.map(({ definitions }) => ({ ...definitions, ...SCHEMAS_TO_SKIP }))
	.map(({ definitions }) => ({ ...definitions, ...SCHEMAS_TO_SKIP }))