OCPBUGS-56248: Improve Console plugin API doc gen script

[vojtechszocs]

This PR improves the script for generating docs/api.md file that documents APIs exposed to Console dynamic plugins.

• Use TS typeChecker.getExportsOfModule to get all exports of core-api.ts entry module
• Use TS typeChecker.getExportSpecifierLocalTargetSymbol to drill down to actual symbol declaration
• Resolve additional metadata like typeOnly flag and sdkPath for generating Console repo file URL
• Reduce overall code complexity, ensure that TS Program is created once for better performance

Issues fixed:

• All exported symbols are listed, including type-only symbols, enums, etc.
• Each API item has a link to its implementation within the Console repo
• Aliased export names e.g. k8sGetResource as k8sGet are properly included ▶️ OCPBUGS-56248

There should be a follow-up effort to document the APIs which are currently missing a JSDoc comment block.

[openshift-ci-robot]

@vojtechszocs: This pull request references Jira Issue OCPBUGS-56248, which is invalid:

• expected the bug to target the "4.20.0" version, but no target version was set

Comment /jira refresh to re-evaluate validity if changes to the Jira bug are made, or edit the title of this pull request to link to a different bug.

The bug has been updated to refer to the pull request using the external bug tracker.

In response to this:

This PR improves the script for generating docs/api.md file that documents APIs exposed to Console dynamic plugins.

• Use TS typeChecker.getExportsOfModule to get all exports of core-api.ts entry module
• Use TS typeChecker.getExportSpecifierLocalTargetSymbol to drill down to actual symbol declaration
• Resolve additional metadata like typeOnly flag and sdkPath for generating Console repo file URL
• Reduce overall code complexity, ensure that TS Program is created once for better performance

Issues fixed:

• All exported symbols are listed, including type-only symbols, enums, etc.
• Each API item has a link to its implementation within the Console repo
• Aliased export names e.g. k8sGetResource as k8sGet are properly included ▶️ OCPBUGS-56248

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the openshift-eng/jira-lifecycle-plugin repository.

[spadgett]

Thanks @vojtechszocs 👍

[spadgett]

Let's open follow up bugs to address missing docs.

[vojtechszocs]

@spadgett @jhadvig FYI

With the current code, we're generating docs for 74 API symbols (1) - all have a JSDoc comment block.

With this PR applied, we're generating docs for 117 API symbols (2) - 35 of them are missing a JSDoc comment block.

(1) AST-only detection using ts.isVariableStatement assumption, e.g. const a = b statements only

(2) TypeChecker-aware detection based on typeChecker.getExportsOfModule which should cover all exports

[vojtechszocs]

Here's the full list of undocumented API symbol names - mainly TS types and enums:

PerspectiveContextType : src/perspective/perspective-context.ts
ModalComponent : src/app/modal-support/ModalProvider.tsx
OverlayComponent : src/app/modal-support/OverlayProvider.tsx
CamelCaseWrap : src/app/components/utils/camel-case-wrap.tsx
ListPageBody : src/app/components/factory/ListPage/ListPageBody.tsx
ColoredIconProps : src/app/components/status/icons.tsx
ExtensionHook : src/api/common-types.ts
ExtensionHookResult : src/api/common-types.ts
ExtensionK8sModel : src/api/common-types.ts
ExtensionK8sGroupModel : src/api/common-types.ts
ExtensionK8sGroupKindModel : src/api/common-types.ts
ExtensionK8sKindVersionModel : src/api/common-types.ts
K8sModel : src/api/common-types.ts
Operator : src/api/common-types.ts
MatchExpression : src/api/common-types.ts
MatchLabels : src/api/common-types.ts
Selector : src/api/common-types.ts
K8sVerb : src/api/common-types.ts
AlertStates : src/api/common-types.ts
SilenceStates : src/api/common-types.ts
AlertSeverity : src/api/common-types.ts
RuleStates : src/api/common-types.ts
Silence : src/api/common-types.ts
PrometheusAlert : src/api/common-types.ts
Alert : src/api/common-types.ts
Alerts : src/api/common-types.ts
PrometheusRule : src/api/common-types.ts
Rule : src/api/common-types.ts
PrometheusLabels : src/api/common-types.ts
PrometheusValue : src/api/common-types.ts
PrometheusRulesResponse : src/api/common-types.ts
DiscoveryResources : src/api/common-types.ts
AlwaysOnExtension : src/api/common-types.ts
ModelDefinition : src/api/common-types.ts
PrometheusEndpoint : src/api/common-types.ts

[spadgett]

Is it possible to use a relative path so that the right branch is used? (So that release-4.20 docs will always point to source code in the release-4.20 branch?)

[vojtechszocs]

@spadgett That makes sense when viewing the doc on GitHub.

The reason I've used hard coded main branch links is because the generated docs/api.md file gets included in the @openshift-console/dynamic-plugin-sdk package published to npmjs.

So as a plugin developer you can also view this doc locally at

node_modules/@openshift-console/dynamic-plugin-sdk/docs/api.md

[vojtechszocs]

@spadgett That said, if you think these links should use relative paths let me know and I'll change it.

Or maybe we can detect the branch we are building from and reflect this information in the links.

https://github.com/openshift/console/tree/<%- branchName %>/frontend/packages/console-dynamic-plugin-sdk/<%- api.sdkPath %>

[spadgett]

OK, we can table this for now. The release-4.x branches are probably the best target for links if we can figure out what the release we're building. Presumably if we use the git branch if would be the local development branch? Let's consider it for a follow up.

[openshift-ci]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: vojtechszocs

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

• frontend/OWNERS [vojtechszocs]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[vojtechszocs]

/retest

[openshift-ci]

@vojtechszocs: all tests passed!

Full PR test history. Your PR dashboard.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. I understand the commands that are listed here.

[vojtechszocs]

/jira refresh

[openshift-ci-robot]

@vojtechszocs: This pull request references Jira Issue OCPBUGS-56248, which is valid. The bug has been moved to the POST state.

3 validation(s) were run on this bug

• bug is open, matching expected state (open)
• bug target version (4.20.0) matches configured target version for branch (4.20.0)
• bug is in the state ASSIGNED, which is one of the valid states (NEW, ASSIGNED, POST)

In response to this:

/jira refresh

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the openshift-eng/jira-lifecycle-plugin repository.