Skip to content

Commit 263ccfd

Browse files
clintandrewhallclintandrewhall
committed
[future] Plan to reorganize code in @kbn/docs-utils
The code in @kbn/docs-utils is currently organized in a way that is not optimal for maintenance and development. This plan is to reorganize the code into a more logical and maintainable structure. The plan is to reorganize the code into the following domains: - analysis: API analysis and declaration building using ts-morph. - cli: Command line interface for building API documentation and validating code. - discovery: Discovery of plugins and their API. - metrics: Metrics collection and reporting. - output: Output writing and formatting. - types: Types for the code. Each domain will have its own directory and files. The files will be organized into the following directories: - builders: Individual declaration builders, one per node type. - lib: Shared utilities for builders. - tests: Tests for the code. - index.ts: Barrel export for the domain. The plan is written primarily for an agent to execute; indeed, I had a commit that an Agent completed, but decided to hold off until code was more fully reviewed.
1 parent cbf480c commit 263ccfd

1 file changed

Lines changed: 340 additions & 0 deletions

File tree

‎packages/kbn-docs-utils/CODE_ORGANIZATION.md‎

Lines changed: 340 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,340 @@
1+
# Code Organization Plan
2+
3+
This document describes the domain-based code organization implemented for `@kbn/docs-utils`.
4+
5+
## Goals
6+
7+
1. **Domain clarity**: Group related functionality into cohesive directories.
8+
2. **Package extraction readiness**: Each domain should function as a potential standalone package.
9+
3. **Import clarity**: Use barrel exports to define public APIs; avoid deep imports across domains.
10+
4. **Test co-location**: Place test files alongside the modules they test.
11+
12+
## Domain Structure
13+
14+
### `analysis/`
15+
API analysis and declaration building using `ts-morph`.
16+
17+
- `build_declaration.ts` - Main dispatcher for building API declarations.
18+
- `get_plugin_api.ts` - Extracts API from a single plugin.
19+
- `get_plugin_api_map.ts` - Builds API map across multiple plugins.
20+
- `stats.ts` - Collects validation statistics (missing comments, any types, etc.).
21+
- `paths.ts` - Contains `pathsOutsideScopes` for tracking non-standard import paths.
22+
- `tsmorph_utils.ts` - Utilities for working with `ts-morph` nodes.
23+
24+
#### `analysis/builders/`
25+
Individual declaration builders, one per node type.
26+
27+
| File | Purpose |
28+
|------|---------|
29+
| `arrow_fn.ts` | Arrow function declarations |
30+
| `basic.ts` | Basic API declaration structure |
31+
| `call_signature.ts` | Call signature declarations |
32+
| `class.ts` | Class declarations |
33+
| `fn.ts` | Function declarations |
34+
| `fn_type.ts` | Function type declarations |
35+
| `interface.ts` | Interface declarations |
36+
| `multiple_call_signatures.ts` | Overloaded function signatures |
37+
| `parameters.ts` | Parameter extraction |
38+
| `type_literal.ts` | Type literal declarations |
39+
| `variable.ts` | Variable declarations |
40+
| `types.ts` | Builder-specific types (`BuildApiDecOpts`) |
41+
42+
#### `analysis/builders/lib/`
43+
Shared utilities for builders.
44+
45+
| File | Purpose |
46+
|------|---------|
47+
| `extract_import_refs.ts` | Extracts import references from signatures |
48+
| `get_references.ts` | Collects cross-references between APIs |
49+
| `get_signature.ts` | Generates type signatures |
50+
| `get_type_kind.ts` | Determines `TypeKind` from nodes |
51+
| `js_doc_utils.ts` | JSDoc parsing utilities |
52+
| `utils.ts` | Helper functions (paths, IDs, etc.) |
53+
54+
### `cli/`
55+
Command-line interface entry points and tasks.
56+
57+
- `build_api_docs.ts` - Main CLI for building API documentation.
58+
- `check_package_docs.ts` - CLI for validating package documentation.
59+
- `parse_flags.ts` - Flag parsing and normalization.
60+
- `types.ts` - CLI-specific types (`CliFlags`, `CliContext`, etc.).
61+
62+
#### `cli/tasks/`
63+
Modular tasks extracted from the CLI.
64+
65+
| File | Purpose |
66+
|------|---------|
67+
| `setup_project.ts` | Project initialization, plugin discovery |
68+
| `build_api_map.ts` | Building the plugin API map |
69+
| `collect_stats.ts` | Collecting validation statistics |
70+
| `write_docs.ts` | Writing documentation files |
71+
| `report_metrics.ts` | Reporting metrics to CI |
72+
| `flat_stats.ts` | Flattening stats for output |
73+
74+
### `discovery/`
75+
Plugin and package discovery.
76+
77+
| File | Purpose |
78+
|------|---------|
79+
| `find_plugins.ts` | Finds plugins and packages in the repo |
80+
| `get_paths_by_package.ts` | Groups file paths by package |
81+
| `get_declaration_nodes_for_plugin.ts` | Gets exportable nodes for a plugin scope |
82+
83+
### `metrics/`
84+
Code health metrics collection.
85+
86+
#### `metrics/count_enzyme_imports/`
87+
Counts Enzyme imports for migration tracking.
88+
89+
#### `metrics/count_eslint_disable/`
90+
Counts ESLint disable comments.
91+
92+
### `output/`
93+
Documentation output generation.
94+
95+
- `auto_generated_warning.ts` - Warning banner for generated files.
96+
- `trim_deleted_docs_from_nav.ts` - Removes deleted docs from navigation.
97+
98+
#### `output/mdx/`
99+
MDX documentation generation.
100+
101+
- `get_all_doc_file_ids.ts` - Extracts doc IDs from existing MDX files.
102+
- `types.ts` - Output-specific types (`WritePluginDocsOpts`).
103+
104+
#### `output/mdx/deprecations/`
105+
Deprecation documentation.
106+
107+
| File | Purpose |
108+
|------|---------|
109+
| `build_table.ts` | Builds deprecation tables |
110+
| `write_by_api.ts` | Writes deprecations grouped by API |
111+
| `write_by_plugin.ts` | Writes deprecations grouped by plugin |
112+
| `write_by_team.ts` | Writes deprecations grouped by team |
113+
114+
#### `output/mdx/plugin/`
115+
Plugin documentation.
116+
117+
| File | Purpose |
118+
|------|---------|
119+
| `write_mdx.ts` | Writes plugin MDX documentation |
120+
| `write_directory.ts` | Writes plugin directory listing |
121+
| `write_by_folder.ts` | Splits plugin docs by service folder |
122+
123+
### `types/`
124+
Shared type definitions.
125+
126+
| File | Purpose |
127+
|------|---------|
128+
| `api.ts` | API declaration types (`ApiDeclaration`, `TypeKind`, etc.) |
129+
| `deprecations.ts` | Deprecation tracking types |
130+
| `plugin.ts` | Plugin and package types (`PluginOrPackage`, etc.) |
131+
| `stats.ts` | Statistics types (`ApiStats`, etc.) |
132+
133+
## Import Patterns
134+
135+
### Barrel Exports
136+
Each domain has an `index.ts` that exports its public API:
137+
138+
```typescript
139+
// Import from domain barrels, not individual files
140+
import { getPluginApiMap, collectApiStatsForPlugin } from '../analysis';
141+
import { findPlugins, getPathsByPackage } from '../discovery';
142+
import { writePluginDocs, trimDeletedDocsFromNav } from '../output';
143+
import { countEslintDisableLines, countEnzymeImports } from '../metrics';
144+
```
145+
146+
### No Re-exports from Parent Directories
147+
Subdirectories should not create `types.ts` or `utils.ts` files that simply re-export from parent directories. Instead, import directly from the source:
148+
149+
```typescript
150+
// Good: Import directly from source
151+
import type { ApiDeclaration } from '../../../types';
152+
import { getPluginApiDocId } from '../../../utils';
153+
154+
// Bad: Re-exporting in subdirectory
155+
// output/mdx/types.ts that just does: export * from '../../types';
156+
```
157+
158+
### Within-Domain Imports
159+
Within a domain, relative imports to sibling files are acceptable:
160+
161+
```typescript
162+
// Within analysis/builders/
163+
import { buildBasicApiDeclaration } from './basic';
164+
import { getTypeKind } from './lib/get_type_kind';
165+
```
166+
167+
## Test Co-location
168+
169+
Test files are placed alongside the modules they test:
170+
171+
```
172+
analysis/
173+
├── stats.ts
174+
├── stats.test.ts
175+
├── build_declaration.ts
176+
├── build_declaration.test.ts
177+
├── builders/
178+
│ ├── lib/
179+
│ │ ├── js_doc_utils.ts
180+
│ │ ├── js_doc_utils.test.ts
181+
│ │ ├── extract_import_refs.ts
182+
│ │ └── extract_import_refs.test.ts
183+
```
184+
185+
### Test File Naming
186+
- Unit tests: `{module}.test.ts`
187+
- Integration/run tests: `{module}.run.test.ts`
188+
189+
## File Naming Conventions
190+
191+
### Builders
192+
- Simplified names without `build_` prefix or `_dec` suffix.
193+
- `function` renamed to `fn` to avoid reserved word issues.
194+
- `function_type` renamed to `fn_type` for consistency.
195+
196+
### Output Writers
197+
- Removed redundant `write_` prefix where the directory context is clear.
198+
- Grouped by output type (deprecations, plugin).
199+
200+
## Directory Structure
201+
202+
```
203+
src/
204+
├── analysis/
205+
│ ├── builders/
206+
│ │ ├── lib/
207+
│ │ │ ├── extract_import_refs.ts
208+
│ │ │ ├── extract_import_refs.test.ts
209+
│ │ │ ├── get_references.ts
210+
│ │ │ ├── get_signature.ts
211+
│ │ │ ├── get_type_kind.ts
212+
│ │ │ ├── js_doc_utils.ts
213+
│ │ │ ├── js_doc_utils.test.ts
214+
│ │ │ ├── utils.ts
215+
│ │ │ └── index.ts
216+
│ │ ├── arrow_fn.ts
217+
│ │ ├── basic.ts
218+
│ │ ├── call_signature.ts
219+
│ │ ├── class.ts
220+
│ │ ├── fn.ts
221+
│ │ ├── fn_type.ts
222+
│ │ ├── interface.ts
223+
│ │ ├── multiple_call_signatures.ts
224+
│ │ ├── parameters.ts
225+
│ │ ├── type_literal.ts
226+
│ │ ├── variable.ts
227+
│ │ ├── types.ts
228+
│ │ └── index.ts
229+
│ ├── build_declaration.ts
230+
│ ├── build_declaration.test.ts
231+
│ ├── get_plugin_api.ts
232+
│ ├── get_plugin_api_map.ts
233+
│ ├── get_plugin_api_map.test.ts
234+
│ ├── paths.ts
235+
│ ├── stats.ts
236+
│ ├── stats.test.ts
237+
│ ├── tsmorph_utils.ts
238+
│ └── index.ts
239+
├── cli/
240+
│ ├── tasks/
241+
│ │ ├── build_api_map.ts
242+
│ │ ├── build_api_map.test.ts
243+
│ │ ├── collect_stats.ts
244+
│ │ ├── collect_stats.test.ts
245+
│ │ ├── flat_stats.ts
246+
│ │ ├── report_metrics.ts
247+
│ │ ├── report_metrics.test.ts
248+
│ │ ├── setup_project.ts
249+
│ │ ├── setup_project.test.ts
250+
│ │ ├── write_docs.ts
251+
│ │ ├── write_docs.test.ts
252+
│ │ └── index.ts
253+
│ ├── build_api_docs.ts
254+
│ ├── build_api_docs.test.ts
255+
│ ├── check_package_docs.ts
256+
│ ├── check_package_docs.test.ts
257+
│ ├── check_package_docs.run.test.ts
258+
│ ├── parse_flags.ts
259+
│ ├── parse_flags.test.ts
260+
│ ├── types.ts
261+
│ └── index.ts
262+
├── discovery/
263+
│ ├── find_plugins.ts
264+
│ ├── find_plugins.test.ts
265+
│ ├── get_declaration_nodes_for_plugin.ts
266+
│ ├── get_declaration_nodes_for_plugin.test.ts
267+
│ ├── get_paths_by_package.ts
268+
│ ├── get_paths_by_package.test.ts
269+
│ └── index.ts
270+
├── metrics/
271+
│ ├── count_enzyme_imports/
272+
│ │ ├── count_enzyme_imports.ts
273+
│ │ ├── count_enzyme_imports.test.ts
274+
│ │ ├── test_enzyme_import.test.ts
275+
│ │ └── index.ts
276+
│ ├── count_eslint_disable/
277+
│ │ ├── count_eslint_disable.ts
278+
│ │ ├── count_eslint_disable.test.ts
279+
│ │ └── index.ts
280+
│ └── index.ts
281+
├── output/
282+
│ ├── mdx/
283+
│ │ ├── deprecations/
284+
│ │ │ ├── build_table.ts
285+
│ │ │ ├── build_table.test.ts
286+
│ │ │ ├── write_by_api.ts
287+
│ │ │ ├── write_by_api.test.ts
288+
│ │ │ ├── write_by_plugin.ts
289+
│ │ │ ├── write_by_plugin.test.ts
290+
│ │ │ ├── write_by_team.ts
291+
│ │ │ ├── write_by_team.test.ts
292+
│ │ │ └── index.ts
293+
│ │ ├── plugin/
294+
│ │ │ ├── write_by_folder.ts
295+
│ │ │ ├── write_by_folder.test.ts
296+
│ │ │ ├── write_directory.ts
297+
│ │ │ ├── write_directory.test.ts
298+
│ │ │ ├── write_mdx.ts
299+
│ │ │ ├── write_mdx.test.ts
300+
│ │ │ └── index.ts
301+
│ │ ├── get_all_doc_file_ids.ts
302+
│ │ ├── get_all_doc_file_ids.test.ts
303+
│ │ ├── types.ts
304+
│ │ └── index.ts
305+
│ ├── auto_generated_warning.ts
306+
│ ├── trim_deleted_docs_from_nav.ts
307+
│ ├── trim_deleted_docs_from_nav.test.ts
308+
│ └── index.ts
309+
├── types/
310+
│ ├── api.ts
311+
│ ├── deprecations.ts
312+
│ ├── plugin.ts
313+
│ ├── stats.ts
314+
│ └── index.ts
315+
├── integration_tests/
316+
│ ├── __fixtures__/
317+
│ ├── api_doc_suite.test.ts
318+
│ └── kibana_platform_plugin_mock.ts
319+
├── __test_helpers__/
320+
│ └── mocks.ts
321+
├── index.ts
322+
├── types.ts
323+
├── utils.ts
324+
└── utils.test.ts
325+
```
326+
327+
## Implementation Status
328+
329+
- [ ] Created domain directories (`analysis/`, `cli/`, `discovery/`, `metrics/`, `output/`, `types/`)
330+
- [ ] Restructured builders with simplified naming
331+
- [ ] Moved helpers to `analysis/builders/lib/`
332+
- [ ] Reorganized CLI with tasks in `cli/tasks/`
333+
- [ ] Consolidated output writers into `output/mdx/deprecations/` and `output/mdx/plugin/`
334+
- [ ] Created barrel exports for each domain
335+
- [ ] Eliminated re-export patterns
336+
- [ ] Refactored deep imports to use barrel exports
337+
- [ ] Co-located test files with modules
338+
- [ ] All 303 tests passing
339+
- [ ] 82.66% line coverage, 90.08% function coverage
340+

0 commit comments

Comments
 (0)