Fix a bunch of bugs with APIDocs system

[stacey-gammon]

Partially fix #99586.

Unfortunately it looks like the only way to fix this is with a hack, because of the way the Typescript Compiler typeToString function works.

Before

After

Fix #99585

The fix required special handling for Type Aliases that don't have initializers, but still have call signatures. Tests added for coverage.

You can see the fix in the above two screenshots. In the second one, props is a child.

Fix #99588

Found a way to use TypeFormatFlags to remove a whole bunch of custom code that tried to patch the links together. Unfortunately, if a type alias is referenced that uses something like ReturnType or typeof, the entire type is expanded, and this ends up looking pretty ugly. The fix for that is to use explicit interfaces more instead.

Before

After

Removed an artificial limit on the signature.

I must have accidentally left that in to debug a ninfinite loop

[spalger]

That hack is nasty, but I assume you've delved into the other ways that might allow us to understand from the AST node that we should drop or ignore some nodes from the tree before printing the signature instead of effectively find/replacing the specific string that's annoying us. If you think there still might be a chance that we could use the AST for this I'd be happy to take a look, but I'd probably need a few minutes of your time to setup and explore a few things to understand exactly what we're working with rather than spending hours getting up to speed.

I assume this won't address any of the non-deterministic "References to deprecated APIs" metrics?

[stacey-gammon]

That hack is nasty, but I assume you've delved into the other ways that might allow us to understand from the AST node that we should drop or ignore some nodes from the tree before printing the signature instead of effectively find/replacing the specific string that's annoying us.

Very nasty. Any other hack, that I can think of, would still be a hack, and require a lot more complicated code. I wanted it to be fixed naturally, using the system itself, but I don't think that's possible. Given the system is still experimental and we're in the "prove value" phase, I went with the very quick, very small amount of code, and yes, very nasty hack.

If you think there still might be a chance that we could use the AST for this I'd be happy to take a look, but I'd probably need a few minutes of your time to setup and explore a few things to understand exactly what we're working with rather than spending hours getting up to speed.

I'd love to get a second pair of eyes on it! I'm happy to pair program with you on it, to help get you up to speed. I'll look to set something up on the cal.

To unblock this PR on that, would you prefer I remove that code, or merge it and then we try to improve it in another PR?

I assume this won't address any of the non-deterministic "References to deprecated APIs" metrics?

No, @brianseeders started looking into that before GAH week. The suspicion is that master ci runs operations in a different order than PR ci, which caused different numbers. The numbers seemed to be the same for every PR. The benchmark numbers were always different than the number in the PR ci run. The numbers were deterministic, just deterministically always different.

[kibanamachine]

💚 Build Succeeded

• continuous-integration/kibana-ci/pull-request
• Commit: 028a6d8
• Storybooks Preview

Metrics [docs]

Public APIs missing comments

Total count of every public API that lacks a comment. Target amount is 0. Run node scripts/build_api_docs --plugin [yourplugin] --stats comments for more detailed information.

id	before	after	diff
actions	115	116	+1
advancedSettings	17	22	+5
alerting	203	211	+8
apm	36	37	+1
bfetch	47	58	+11
cases	368	374	+6
charts	132	137	+5
core	984	1076	+92
dashboard	128	132	+4
data	2959	3262	+303
discover	48	51	+3
embeddable	363	381	+18
encryptedSavedObjects	18	28	+10
esUiShared	82	86	+4
expressions	1362	1456	+94
features	90	94	+4
fileUpload	122	128	+6
fleet	950	972	+22
globalSearch	13	14	+1
indexPatternFieldEditor	27	29	+2
infra	12	20	+8
inspector	77	78	+1
kibanaLegacy	84	85	+1
kibanaReact	209	219	+10
kibanaUtils	301	385	+84
lens	152	154	+2
licensing	40	44	+4
lists	191	196	+5
management	35	38	+3
maps	188	191	+3
metricsEntities	5	6	+1
ml	282	283	+1
monitoring	9	10	+1
navigation	29	31	+2
observability	188	192	+4
presentationUtil	107	123	+16
runtimeFields	17	19	+2
savedObjects	159	197	+38
savedObjectsManagement	82	85	+3
savedObjectsTaggingOss	42	50	+8
screenshotMode	9	11	+2
security	32	36	+4
securityOss	8	9	+1
share	60	61	+1
spacesOss	0	5	+5
telemetryCollectionManager	24	29	+5
telemetryManagementSection	12	13	+1
triggersActionsUi	212	236	+24
uiActionsEnhanced	135	147	+12
uptime	5	6	+1
urlForwarding	14	15	+1
usageCollection	1	16	+15
visTypeTimeseries	7	10	+3
visualizations	219	228	+9
total			+881

Any counts in public APIs

Total count of every any typed public API. Target amount is 0. Run node scripts/build_api_docs --plugin [yourplugin] --stats any for more detailed information.

id	before	after	diff
core	146	148	+2
data	80	107	+27
embeddable	2	4	+2
expressions	44	57	+13
indexPatternFieldEditor	0	1	+1
kibanaReact	0	1	+1
kibanaUtils	3	5	+2
presentationUtil	0	1	+1
savedObjectsTaggingOss	0	3	+3
uiActionsEnhanced	0	2	+2
visTypeTimeseries	0	1	+1
total			+55

Public APIs missing exports

Total count of every type that is part of your API that should be exported but is not. This will cause broken links in the API documentation system. Target amount is 0. Run node scripts/build_api_docs --plugin [yourplugin] --stats exports for more detailed information.

id	before	after	diff
actions	6	7	+1
alerting	10	15	+5
apm	8	30	+22
canvas	2	3	+1
charts	2	1	-1
encryptedSavedObjects	4	3	-1
esUiShared	4	1	-3
expressions	7	5	-2
features	3	2	-1
fileUpload	0	1	+1
fleet	10	8	-2
globalSearch	6	5	-1
indexManagement	4	3	-1
infra	2	4	+2
lens	13	17	+4
licensing	10	8	-2
lists	55	53	-2
ml	30	34	+4
monitoring	0	2	+2
navigation	3	2	-1
observability	10	7	-3
presentationUtil	4	3	-1
reporting	18	19	+1
ruleRegistry	4	5	+1
savedObjectsManagement	1	0	-1
taskManager	3	7	+4
triggersActionsUi	28	29	+1
uiActions	9	11	+2
uiActionsEnhanced	11	10	-1
usageCollection	0	2	+2
visualizations	6	12	+6
total			+36

Unknown metric groups

API count

id	before	after	diff
actions	115	116	+1
advancedSettings	18	23	+5
alerting	203	211	+8
apm	36	37	+1
bfetch	58	69	+11
cases	381	387	+6
charts	157	165	+8
core	2187	2288	+101
dashboard	140	144	+4
data	3452	3762	+310
devTools	9	10	+1
discover	61	64	+3
embeddable	431	449	+18
encryptedSavedObjects	20	30	+10
esUiShared	84	88	+4
expressions	1756	1871	+115
features	202	206	+4
fileUpload	122	128	+6
fleet	1040	1062	+22
globalSearch	67	68	+1
indexPatternFieldEditor	29	31	+2
infra	15	23	+8
inspector	97	101	+4
kibanaLegacy	92	93	+1
kibanaReact	235	245	+10
kibanaUtils	465	551	+86
lens	163	165	+2
licensing	116	120	+4
lists	210	215	+5
management	35	38	+3
maps	189	192	+3
metricsEntities	8	9	+1
ml	286	287	+1
monitoring	9	10	+1
navigation	29	31	+2
observability	188	192	+4
presentationUtil	109	125	+16
runtimeFields	22	24	+2
savedObjects	173	211	+38
savedObjectsManagement	93	96	+3
savedObjectsTaggingOss	81	89	+8
screenshotMode	13	15	+2
security	73	77	+4
securityOss	11	12	+1
share	66	67	+1
spaces	95	96	+1
spacesOss	64	71	+7
telemetry	40	41	+1
telemetryCollectionManager	24	29	+5
telemetryManagementSection	13	14	+1
triggersActionsUi	221	245	+24
uiActionsEnhanced	193	205	+12
uptime	5	6	+1
urlForwarding	14	15	+1
usageCollection	42	57	+15
visTypeTimeseries	7	10	+3
visualizations	237	246	+9
total			+931

References to deprecated APIs

id	before	after	diff
canvas	29	25	-4
crossClusterReplication	8	6	-2
fleet	22	20	-2
globalSearch	4	2	-2
indexManagement	12	7	-5
infra	261	149	-112
lens	67	45	-22
licensing	18	15	-3
maps	286	208	-78
ml	121	115	-6
monitoring	109	56	-53
stackAlerts	101	95	-6
total			-295

History

• 💚 Build #126072 succeeded 05af8a0
• 💚 Build #125421 succeeded 50f033e
• 💚 Build #124937 succeeded 76faba3

To update your PR or re-run it, just comment with:
@elasticmachine merge upstream

[spalger]

I'm on board with unblocking and taking a look with you next week!

[kibanamachine]

💔 Backport failed

Status	Branch	Result
❌	7.x	Commit could not be cherrypicked due to conflicts

To backport manually run:
node scripts/backport --pr 99589