@mapomodule/mcp 0.0.0-stage → 1.0.0-beta.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (166) hide show
  1. package/README.md +509 -2
  2. package/bin/mapo-mcp.mjs +3 -0
  3. package/dist/build.d.mts +18 -0
  4. package/dist/build.d.ts +18 -0
  5. package/dist/build.mjs +351 -0
  6. package/dist/cli.d.mts +7 -0
  7. package/dist/cli.d.ts +7 -0
  8. package/dist/cli.mjs +274 -0
  9. package/dist/index.d.mts +68 -0
  10. package/dist/index.d.ts +68 -0
  11. package/dist/index.mjs +1 -0
  12. package/dist/knowledge/api.json +1 -0
  13. package/dist/knowledge/docs.json +1 -0
  14. package/dist/module.d.mts +16 -0
  15. package/dist/module.d.ts +16 -0
  16. package/dist/module.json +9 -0
  17. package/dist/module.mjs +124 -0
  18. package/dist/runtime/core/doctor.d.ts +0 -0
  19. package/dist/runtime/core/doctor.js +128 -0
  20. package/dist/runtime/core/endpoint.d.ts +0 -0
  21. package/dist/runtime/core/endpoint.js +8 -0
  22. package/dist/runtime/core/indexer.d.ts +0 -0
  23. package/dist/runtime/core/indexer.js +194 -0
  24. package/dist/runtime/core/instructions.d.ts +0 -0
  25. package/dist/runtime/core/instructions.js +10 -0
  26. package/dist/runtime/core/knowledge.d.ts +0 -0
  27. package/dist/runtime/core/knowledge.js +76 -0
  28. package/dist/runtime/core/openapi.d.ts +0 -0
  29. package/dist/runtime/core/openapi.js +229 -0
  30. package/dist/runtime/core/overview.d.ts +0 -0
  31. package/dist/runtime/core/overview.js +15 -0
  32. package/dist/runtime/core/prompts.d.ts +0 -0
  33. package/dist/runtime/core/prompts.js +108 -0
  34. package/dist/runtime/core/recipes.d.ts +0 -0
  35. package/dist/runtime/core/recipes.js +496 -0
  36. package/dist/runtime/core/resources.d.ts +0 -0
  37. package/dist/runtime/core/resources.js +92 -0
  38. package/dist/runtime/core/scaffold/fields.d.ts +0 -0
  39. package/dist/runtime/core/scaffold/fields.js +64 -0
  40. package/dist/runtime/core/scaffold/index.d.ts +0 -0
  41. package/dist/runtime/core/scaffold/index.js +74 -0
  42. package/dist/runtime/core/scaffold/templates.d.ts +0 -0
  43. package/dist/runtime/core/scaffold/templates.js +349 -0
  44. package/dist/runtime/core/schema-source.d.ts +0 -0
  45. package/dist/runtime/core/schema-source.js +70 -0
  46. package/dist/runtime/core/search.d.ts +0 -0
  47. package/dist/runtime/core/search.js +173 -0
  48. package/dist/runtime/core/tokenize.d.ts +0 -0
  49. package/dist/runtime/core/tokenize.js +96 -0
  50. package/dist/runtime/core/tool-spec.d.ts +0 -0
  51. package/dist/runtime/core/tool-spec.js +3 -0
  52. package/dist/runtime/core/tools/api.d.ts +0 -0
  53. package/dist/runtime/core/tools/api.js +192 -0
  54. package/dist/runtime/core/tools/app.d.ts +0 -0
  55. package/dist/runtime/core/tools/app.js +141 -0
  56. package/dist/runtime/core/tools/backend.d.ts +0 -0
  57. package/dist/runtime/core/tools/backend.js +143 -0
  58. package/dist/runtime/core/tools/docs.d.ts +0 -0
  59. package/dist/runtime/core/tools/docs.js +154 -0
  60. package/dist/runtime/core/tools/scaffold.d.ts +0 -0
  61. package/dist/runtime/core/tools/scaffold.js +127 -0
  62. package/dist/runtime/core/types.d.ts +0 -0
  63. package/dist/runtime/core/types.js +0 -0
  64. package/dist/runtime/core/write.d.ts +0 -0
  65. package/dist/runtime/core/write.js +53 -0
  66. package/dist/runtime/mcp/handlers/mapo/index.js +7 -0
  67. package/dist/runtime/mcp/handlers/mapo/prompts/crud-page.js +3 -0
  68. package/dist/runtime/mcp/handlers/mapo/prompts/custom-field.js +3 -0
  69. package/dist/runtime/mcp/handlers/mapo/prompts/debug-form.js +3 -0
  70. package/dist/runtime/mcp/handlers/mapo/prompts/migrate-v1.js +3 -0
  71. package/dist/runtime/mcp/handlers/mapo/prompts/theme.js +3 -0
  72. package/dist/runtime/mcp/handlers/mapo/resources/app-manifest.js +19 -0
  73. package/dist/runtime/mcp/handlers/mapo/resources/docs.js +34 -0
  74. package/dist/runtime/mcp/handlers/mapo/resources/fields.js +34 -0
  75. package/dist/runtime/mcp/handlers/mapo/resources/knowledge-index.js +22 -0
  76. package/dist/runtime/mcp/handlers/mapo/resources/overview.js +20 -0
  77. package/dist/runtime/mcp/handlers/mapo/tools/backend-schema.js +3 -0
  78. package/dist/runtime/mcp/handlers/mapo/tools/component-api.js +3 -0
  79. package/dist/runtime/mcp/handlers/mapo/tools/composable-api.js +3 -0
  80. package/dist/runtime/mcp/handlers/mapo/tools/doctor.js +3 -0
  81. package/dist/runtime/mcp/handlers/mapo/tools/get-doc.js +3 -0
  82. package/dist/runtime/mcp/handlers/mapo/tools/inspect-app.js +3 -0
  83. package/dist/runtime/mcp/handlers/mapo/tools/list-field-types.js +3 -0
  84. package/dist/runtime/mcp/handlers/mapo/tools/list-recipes.js +3 -0
  85. package/dist/runtime/mcp/handlers/mapo/tools/scaffold.js +3 -0
  86. package/dist/runtime/mcp/handlers/mapo/tools/search-docs.js +3 -0
  87. package/dist/runtime/nitro/context.d.ts +0 -0
  88. package/dist/runtime/nitro/context.js +21 -0
  89. package/dist/runtime/nitro/to-mcp-prompt.d.ts +0 -0
  90. package/dist/runtime/nitro/to-mcp-prompt.js +23 -0
  91. package/dist/runtime/nitro/to-mcp-tool.d.ts +0 -0
  92. package/dist/runtime/nitro/to-mcp-tool.js +28 -0
  93. package/dist/runtime/types/virtual-modules.d.ts +6 -0
  94. package/dist/types.d.mts +9 -0
  95. package/package.json +73 -4
  96. package/src/__tests__/cli.test.ts +137 -0
  97. package/src/__tests__/doctor.test.ts +145 -0
  98. package/src/__tests__/endpoint.test.ts +31 -0
  99. package/src/__tests__/fixtures/drf-schema.json +142 -0
  100. package/src/__tests__/fixtures.ts +198 -0
  101. package/src/__tests__/indexer.test.ts +114 -0
  102. package/src/__tests__/knowledge.test.ts +225 -0
  103. package/src/__tests__/openapi.test.ts +256 -0
  104. package/src/__tests__/overview.test.ts +105 -0
  105. package/src/__tests__/recipes.test.ts +55 -0
  106. package/src/__tests__/resources.test.ts +69 -0
  107. package/src/__tests__/scaffold.test.ts +153 -0
  108. package/src/__tests__/search.test.ts +105 -0
  109. package/src/__tests__/tools.test.ts +226 -0
  110. package/src/__tests__/write.test.ts +134 -0
  111. package/src/build/extract-components.ts +135 -0
  112. package/src/build/extract-composables.ts +125 -0
  113. package/src/build/extract-fields.ts +250 -0
  114. package/src/build/index.ts +103 -0
  115. package/src/cli.ts +375 -0
  116. package/src/index.ts +65 -0
  117. package/src/module.ts +213 -0
  118. package/src/runtime/core/doctor.ts +204 -0
  119. package/src/runtime/core/endpoint.ts +27 -0
  120. package/src/runtime/core/indexer.ts +285 -0
  121. package/src/runtime/core/instructions.ts +18 -0
  122. package/src/runtime/core/knowledge.ts +121 -0
  123. package/src/runtime/core/openapi.ts +417 -0
  124. package/src/runtime/core/overview.ts +44 -0
  125. package/src/runtime/core/prompts.ts +150 -0
  126. package/src/runtime/core/recipes.ts +574 -0
  127. package/src/runtime/core/resources.ts +150 -0
  128. package/src/runtime/core/scaffold/fields.ts +127 -0
  129. package/src/runtime/core/scaffold/index.ts +120 -0
  130. package/src/runtime/core/scaffold/templates.ts +394 -0
  131. package/src/runtime/core/schema-source.ts +123 -0
  132. package/src/runtime/core/search.ts +282 -0
  133. package/src/runtime/core/tokenize.ts +146 -0
  134. package/src/runtime/core/tool-spec.ts +74 -0
  135. package/src/runtime/core/tools/api.ts +300 -0
  136. package/src/runtime/core/tools/app.ts +201 -0
  137. package/src/runtime/core/tools/backend.ts +197 -0
  138. package/src/runtime/core/tools/docs.ts +218 -0
  139. package/src/runtime/core/tools/scaffold.ts +176 -0
  140. package/src/runtime/core/types.ts +133 -0
  141. package/src/runtime/core/write.ts +119 -0
  142. package/src/runtime/mcp/handlers/mapo/index.ts +16 -0
  143. package/src/runtime/mcp/handlers/mapo/prompts/crud-page.ts +4 -0
  144. package/src/runtime/mcp/handlers/mapo/prompts/custom-field.ts +4 -0
  145. package/src/runtime/mcp/handlers/mapo/prompts/debug-form.ts +4 -0
  146. package/src/runtime/mcp/handlers/mapo/prompts/migrate-v1.ts +4 -0
  147. package/src/runtime/mcp/handlers/mapo/prompts/theme.ts +4 -0
  148. package/src/runtime/mcp/handlers/mapo/resources/app-manifest.ts +28 -0
  149. package/src/runtime/mcp/handlers/mapo/resources/docs.ts +41 -0
  150. package/src/runtime/mcp/handlers/mapo/resources/fields.ts +37 -0
  151. package/src/runtime/mcp/handlers/mapo/resources/knowledge-index.ts +24 -0
  152. package/src/runtime/mcp/handlers/mapo/resources/overview.ts +22 -0
  153. package/src/runtime/mcp/handlers/mapo/tools/backend-schema.ts +4 -0
  154. package/src/runtime/mcp/handlers/mapo/tools/component-api.ts +4 -0
  155. package/src/runtime/mcp/handlers/mapo/tools/composable-api.ts +4 -0
  156. package/src/runtime/mcp/handlers/mapo/tools/doctor.ts +4 -0
  157. package/src/runtime/mcp/handlers/mapo/tools/get-doc.ts +4 -0
  158. package/src/runtime/mcp/handlers/mapo/tools/inspect-app.ts +4 -0
  159. package/src/runtime/mcp/handlers/mapo/tools/list-field-types.ts +4 -0
  160. package/src/runtime/mcp/handlers/mapo/tools/list-recipes.ts +4 -0
  161. package/src/runtime/mcp/handlers/mapo/tools/scaffold.ts +4 -0
  162. package/src/runtime/mcp/handlers/mapo/tools/search-docs.ts +4 -0
  163. package/src/runtime/nitro/context.ts +41 -0
  164. package/src/runtime/nitro/to-mcp-prompt.ts +30 -0
  165. package/src/runtime/nitro/to-mcp-tool.ts +35 -0
  166. package/src/runtime/types/virtual-modules.d.ts +6 -0
@@ -0,0 +1,125 @@
1
+ /**
2
+ * Extracts the composables each Mapo module auto-imports.
3
+ *
4
+ * The module's `addImports([...])` calls are the authoritative list of what an
5
+ * app can call without importing anything — exactly what an assistant needs to
6
+ * know, and what it cannot infer from `node_modules`.
7
+ */
8
+ import { existsSync, readFileSync, readdirSync } from "node:fs";
9
+ import { join, relative } from "node:path";
10
+ import ts from "typescript";
11
+ import type { ComposableApi } from "../runtime/core/types.js";
12
+
13
+ const PACKAGES_ROOT = "packages/@mapomodule";
14
+ const MAX_SIGNATURE_LENGTH = 220;
15
+
16
+ /** `{ name: "useCrud", from: resolver.resolve("./runtime/api/crud") }` */
17
+ const ADD_IMPORT_ENTRY =
18
+ /name:\s*"([A-Za-z_$][\w$]*)"[\s\S]{0,160}?from:[\s\S]{0,120}?"(\.[^"]+)"/g;
19
+
20
+ function shorten(value: string): string {
21
+ const collapsed = value.replace(/\s+/g, " ").trim();
22
+ return collapsed.length > MAX_SIGNATURE_LENGTH
23
+ ? `${collapsed.slice(0, MAX_SIGNATURE_LENGTH)}…`
24
+ : collapsed;
25
+ }
26
+
27
+ interface Candidate {
28
+ name: string;
29
+ pkg: string;
30
+ file: string;
31
+ }
32
+
33
+ /** Reads every `addImports` entry declared by the Mapo modules. */
34
+ function collectCandidates(repoRoot: string): Candidate[] {
35
+ const packagesDir = join(repoRoot, PACKAGES_ROOT);
36
+ if (!existsSync(packagesDir)) return [];
37
+
38
+ const candidates: Candidate[] = [];
39
+
40
+ for (const entry of readdirSync(packagesDir, { withFileTypes: true })) {
41
+ if (!entry.isDirectory()) continue;
42
+
43
+ const moduleFile = join(packagesDir, entry.name, "src", "module.ts");
44
+ if (!existsSync(moduleFile)) continue;
45
+
46
+ const source = readFileSync(moduleFile, "utf-8");
47
+ const packageRoot = join(packagesDir, entry.name);
48
+
49
+ for (const match of source.matchAll(ADD_IMPORT_ENTRY)) {
50
+ const [, name, from] = match;
51
+ if (!name || !from) continue;
52
+
53
+ const base = join(packageRoot, "src", from.replace(/^\.\//, ""));
54
+ const file = [".ts", ".mts", "/index.ts"]
55
+ .map((suffix) => `${base}${suffix}`)
56
+ .find((path) => existsSync(path));
57
+
58
+ if (file)
59
+ candidates.push({ name, pkg: `@mapomodule/${entry.name}`, file });
60
+ }
61
+ }
62
+
63
+ return candidates;
64
+ }
65
+
66
+ export function extractComposables(
67
+ repoRoot: string,
68
+ docsFor: (symbol: string) => string[],
69
+ ): ComposableApi[] {
70
+ const candidates = collectCandidates(repoRoot);
71
+ if (!candidates.length) return [];
72
+
73
+ const program = ts.createProgram(
74
+ candidates.map((candidate) => candidate.file),
75
+ {
76
+ target: ts.ScriptTarget.ESNext,
77
+ module: ts.ModuleKind.ESNext,
78
+ moduleResolution: ts.ModuleResolutionKind.Bundler,
79
+ strict: true,
80
+ noEmit: true,
81
+ skipLibCheck: true,
82
+ allowJs: true,
83
+ },
84
+ );
85
+ const checker = program.getTypeChecker();
86
+
87
+ const composables: ComposableApi[] = [];
88
+
89
+ for (const candidate of candidates) {
90
+ const source = program.getSourceFile(candidate.file);
91
+ const moduleSymbol = source
92
+ ? checker.getSymbolAtLocation(source)
93
+ : undefined;
94
+ const exported = moduleSymbol
95
+ ? checker
96
+ .getExportsOfModule(moduleSymbol)
97
+ .find((symbol) => symbol.getName() === candidate.name)
98
+ : undefined;
99
+
100
+ const declaration =
101
+ exported?.valueDeclaration ?? exported?.declarations?.[0];
102
+ const signature =
103
+ exported && declaration
104
+ ? checker.typeToString(
105
+ checker.getTypeOfSymbolAtLocation(exported, declaration),
106
+ )
107
+ : undefined;
108
+ const description = exported
109
+ ? ts
110
+ .displayPartsToString(exported.getDocumentationComment(checker))
111
+ .trim()
112
+ : "";
113
+
114
+ composables.push({
115
+ name: candidate.name,
116
+ pkg: candidate.pkg,
117
+ file: relative(repoRoot, candidate.file),
118
+ ...(signature ? { signature: shorten(signature) } : {}),
119
+ ...(description ? { description: description.replace(/\s+/g, " ") } : {}),
120
+ docs: docsFor(candidate.name),
121
+ });
122
+ }
123
+
124
+ return composables.sort((a, b) => a.name.localeCompare(b.name));
125
+ }
@@ -0,0 +1,250 @@
1
+ /**
2
+ * Extracts the form field contract from `@mapomodule/form` source:
3
+ * the registry (which component renders each `type`, plus its default attrs)
4
+ * and the descriptor interfaces (which `attrs` each type accepts, with docs).
5
+ *
6
+ * These are exactly the details models invent, so they come from source, never
7
+ * from prose.
8
+ */
9
+ import { existsSync } from "node:fs";
10
+ import { join } from "node:path";
11
+ import { pathToFileURL } from "node:url";
12
+ import ts from "typescript";
13
+ import type { ApiMember, FieldTypeApi } from "../runtime/core/types.js";
14
+
15
+ const FORM_PACKAGE = "packages/@mapomodule/form";
16
+ const DESCRIPTOR_FILE = "src/runtime/types/descriptor.ts";
17
+ const REGISTRY_FILE = "src/runtime/registry/defaults.ts";
18
+
19
+ const MAX_TYPE_LENGTH = 160;
20
+
21
+ interface RegistryShape {
22
+ mapping: Record<string, unknown>;
23
+ attrs: Record<string, Record<string, unknown>>;
24
+ accessor: Record<string, unknown>;
25
+ }
26
+
27
+ interface DescriptorInfo {
28
+ interfaceName: string;
29
+ description?: string;
30
+ types: string[];
31
+ attrs: ApiMember[];
32
+ }
33
+
34
+ function shorten(value: string): string {
35
+ // Source-declared types can carry inline JSDoc on their members; drop it.
36
+ const collapsed = value
37
+ .replace(/\/\*[\s\S]*?\*\//g, "")
38
+ .replace(/\s+/g, " ")
39
+ .trim();
40
+ return collapsed.length > MAX_TYPE_LENGTH
41
+ ? `${collapsed.slice(0, MAX_TYPE_LENGTH)}…`
42
+ : collapsed;
43
+ }
44
+
45
+ function docOf(
46
+ symbol: ts.Symbol | undefined,
47
+ checker: ts.TypeChecker,
48
+ ): string | undefined {
49
+ if (!symbol) return undefined;
50
+ const text = ts
51
+ .displayPartsToString(symbol.getDocumentationComment(checker))
52
+ .trim();
53
+ return text ? text.replace(/\s+/g, " ") : undefined;
54
+ }
55
+
56
+ /** Turns `"text" | "textarea"` into `["text", "textarea"]`. */
57
+ function literalsOf(typeText: string): string[] {
58
+ return [...typeText.matchAll(/"([^"]+)"/g)].map((match) => match[1]!);
59
+ }
60
+
61
+ function membersOf(type: ts.Type, checker: ts.TypeChecker): ApiMember[] {
62
+ return checker.getPropertiesOfType(type).map((property) => {
63
+ const declaration = property.valueDeclaration ?? property.declarations?.[0];
64
+
65
+ // Prefer the type as written in the source: the checker expands mapped
66
+ // types (`DeepKeyOf<T>` becomes an unreadable wall of conditionals).
67
+ const declared =
68
+ declaration && ts.isPropertySignature(declaration) && declaration.type
69
+ ? declaration.type.getText()
70
+ : undefined;
71
+ const resolved = declaration
72
+ ? checker.typeToString(
73
+ checker.getTypeOfSymbolAtLocation(property, declaration),
74
+ )
75
+ : undefined;
76
+ const type_ = declared ?? resolved;
77
+
78
+ return {
79
+ name: property.getName(),
80
+ ...(type_ ? { type: shorten(type_) } : {}),
81
+ required: !(property.flags & ts.SymbolFlags.Optional),
82
+ ...(docOf(property, checker)
83
+ ? { description: docOf(property, checker)! }
84
+ : {}),
85
+ };
86
+ });
87
+ }
88
+
89
+ /** Reads every `*Descriptor` interface plus the shared `FieldBase` members. */
90
+ function readDescriptors(descriptorPath: string): {
91
+ descriptors: DescriptorInfo[];
92
+ common: ApiMember[];
93
+ } {
94
+ const program = ts.createProgram([descriptorPath], {
95
+ target: ts.ScriptTarget.ESNext,
96
+ module: ts.ModuleKind.ESNext,
97
+ moduleResolution: ts.ModuleResolutionKind.Bundler,
98
+ strict: true,
99
+ noEmit: true,
100
+ skipLibCheck: true,
101
+ });
102
+
103
+ const checker = program.getTypeChecker();
104
+ const source = program.getSourceFile(descriptorPath);
105
+ if (!source) return { descriptors: [], common: [] };
106
+
107
+ const descriptors: DescriptorInfo[] = [];
108
+ let common: ApiMember[] = [];
109
+
110
+ for (const statement of source.statements) {
111
+ if (!ts.isInterfaceDeclaration(statement)) continue;
112
+
113
+ const name = statement.name.text;
114
+ const type = checker.getTypeAtLocation(statement.name);
115
+
116
+ if (name === "FieldBase") {
117
+ // `key`/`type` are per-descriptor; everything else is shared behaviour.
118
+ common = membersOf(type, checker).filter(
119
+ (member) => member.name !== "type",
120
+ );
121
+ continue;
122
+ }
123
+
124
+ const extendsFieldBase = statement.heritageClauses?.some((clause) =>
125
+ clause.types.some(
126
+ (heritage) => heritage.expression.getText(source) === "FieldBase",
127
+ ),
128
+ );
129
+ if (!extendsFieldBase) continue;
130
+
131
+ const properties = checker.getPropertiesOfType(type);
132
+ const typeProperty = properties.find(
133
+ (property) => property.getName() === "type",
134
+ );
135
+ const attrsProperty = properties.find(
136
+ (property) => property.getName() === "attrs",
137
+ );
138
+
139
+ const typeDeclaration =
140
+ typeProperty?.valueDeclaration ?? typeProperty?.declarations?.[0];
141
+ const typeText = typeDeclaration
142
+ ? checker.typeToString(
143
+ checker.getTypeOfSymbolAtLocation(typeProperty!, typeDeclaration),
144
+ )
145
+ : "";
146
+
147
+ const attrsDeclaration =
148
+ attrsProperty?.valueDeclaration ?? attrsProperty?.declarations?.[0];
149
+ const attrs = attrsDeclaration
150
+ ? membersOf(
151
+ checker.getNonNullableType(
152
+ checker.getTypeOfSymbolAtLocation(attrsProperty!, attrsDeclaration),
153
+ ),
154
+ checker,
155
+ )
156
+ : [];
157
+
158
+ descriptors.push({
159
+ interfaceName: name,
160
+ ...(docOf(checker.getSymbolAtLocation(statement.name), checker)
161
+ ? {
162
+ description: docOf(
163
+ checker.getSymbolAtLocation(statement.name),
164
+ checker,
165
+ )!,
166
+ }
167
+ : {}),
168
+ types: literalsOf(typeText),
169
+ attrs,
170
+ });
171
+ }
172
+
173
+ return { descriptors, common };
174
+ }
175
+
176
+ /** `() => import("../components/fields/MapoDateField.vue")` → `MapoDateField`. */
177
+ function componentNameOf(entry: unknown): string | undefined {
178
+ if (typeof entry === "string") return entry;
179
+ if (typeof entry !== "function") return undefined;
180
+ const match = /([\w-]+)\.vue/.exec(String(entry));
181
+ return match?.[1];
182
+ }
183
+
184
+ export async function extractFieldTypes(
185
+ repoRoot: string,
186
+ docsFor: (symbol: string) => string[],
187
+ ): Promise<{ fieldTypes: FieldTypeApi[]; fieldCommon: ApiMember[] }> {
188
+ const descriptorPath = join(repoRoot, FORM_PACKAGE, DESCRIPTOR_FILE);
189
+ const registryPath = join(repoRoot, FORM_PACKAGE, REGISTRY_FILE);
190
+
191
+ if (!existsSync(descriptorPath) || !existsSync(registryPath)) {
192
+ console.warn(
193
+ "[mapo-mcp] form package sources not found — skipping field extraction",
194
+ );
195
+ return { fieldTypes: [], fieldCommon: [] };
196
+ }
197
+
198
+ const { descriptors, common } = readDescriptors(descriptorPath);
199
+
200
+ // The registry's lazy `() => import(...)` entries are never invoked here, so
201
+ // importing the module has no side effect beyond building the object.
202
+ const { createJiti } = await import("jiti");
203
+ const module_ = (await createJiti(import.meta.url).import(
204
+ pathToFileURL(registryPath).href,
205
+ )) as { defaultRegistry: RegistryShape };
206
+ const registry = module_.defaultRegistry;
207
+
208
+ const byType = new Map<string, FieldTypeApi>();
209
+
210
+ for (const descriptor of descriptors) {
211
+ for (const type of descriptor.types) {
212
+ byType.set(type, {
213
+ type,
214
+ descriptor: descriptor.interfaceName,
215
+ ...(descriptor.description
216
+ ? { description: descriptor.description }
217
+ : {}),
218
+ attrs: descriptor.attrs,
219
+ docs: docsFor(type),
220
+ });
221
+ }
222
+ }
223
+
224
+ // Types present in the registry but without a dedicated descriptor still
225
+ // exist at runtime — report them rather than hiding them.
226
+ for (const type of Object.keys(registry.mapping ?? {})) {
227
+ if (!byType.has(type))
228
+ byType.set(type, { type, attrs: [], docs: docsFor(type) });
229
+ }
230
+
231
+ for (const [type, entry] of byType) {
232
+ const component = componentNameOf(registry.mapping?.[type]);
233
+ if (component) entry.component = component;
234
+
235
+ const defaults = {
236
+ ...(registry.attrs?.All ?? {}),
237
+ ...(registry.attrs?.[type] ?? {}),
238
+ };
239
+ if (Object.keys(defaults).length) entry.defaultAttrs = defaults;
240
+
241
+ if (registry.accessor?.[type]) entry.hasAccessor = true;
242
+ }
243
+
244
+ return {
245
+ fieldTypes: [...byType.values()].sort((a, b) =>
246
+ a.type.localeCompare(b.type),
247
+ ),
248
+ fieldCommon: common,
249
+ };
250
+ }
@@ -0,0 +1,103 @@
1
+ /**
2
+ * Build-time knowledge generation.
3
+ *
4
+ * Bundled as its own entry (`dist/build.mjs`) so the heavy, source-reading
5
+ * dependencies — `vue-component-meta`, `typescript`, `jiti` — never end up in
6
+ * the Nitro or CLI bundles.
7
+ */
8
+ import { mkdirSync, writeFileSync } from "node:fs";
9
+ import { join } from "node:path";
10
+ import { buildDocsKnowledge } from "../runtime/core/indexer.js";
11
+ import { API_KNOWLEDGE_VERSION } from "../runtime/core/knowledge.js";
12
+ import { extractComponents } from "./extract-components.js";
13
+ import { extractComposables } from "./extract-composables.js";
14
+ import { extractFieldTypes } from "./extract-fields.js";
15
+ import type {
16
+ ApiKnowledge,
17
+ DocChunk,
18
+ DocsKnowledge,
19
+ } from "../runtime/core/types.js";
20
+
21
+ export const DOCS_FILE = "docs.json";
22
+ export const API_FILE = "api.json";
23
+
24
+ /** How many doc references to attach to a symbol. */
25
+ const MAX_DOC_LINKS = 3;
26
+
27
+ /**
28
+ * Resolves "which documentation sections talk about this symbol".
29
+ * Heading matches beat body mentions, so `MapoList` resolves to the section
30
+ * that documents it rather than to every page that happens to use it.
31
+ */
32
+ function makeDocsResolver(knowledge: DocsKnowledge) {
33
+ const chunks = knowledge.chunks;
34
+
35
+ return (symbol: string, pathPrefix?: string): string[] => {
36
+ const needle = symbol.toLowerCase();
37
+ const scored: Array<{ chunk: DocChunk; score: number }> = [];
38
+
39
+ for (const chunk of chunks) {
40
+ if (pathPrefix && !chunk.path.startsWith(pathPrefix)) continue;
41
+
42
+ const heading = chunk.heading.toLowerCase();
43
+ const tags = chunk.tags.map((tag) => tag.toLowerCase());
44
+
45
+ let score = 0;
46
+ if (heading === needle || heading === `\`${needle}\``) score = 3;
47
+ else if (heading.includes(needle)) score = 2;
48
+ else if (tags.includes(needle)) score = 1;
49
+
50
+ if (score) scored.push({ chunk, score });
51
+ }
52
+
53
+ return scored
54
+ .sort((a, b) => b.score - a.score)
55
+ .slice(0, MAX_DOC_LINKS)
56
+ .map(({ chunk }) =>
57
+ chunk.anchor ? `${chunk.path}#${chunk.anchor}` : chunk.path,
58
+ );
59
+ };
60
+ }
61
+
62
+ export interface BuildKnowledgeOptions {
63
+ docsRoot: string;
64
+ repoRoot: string;
65
+ outDir: string;
66
+ }
67
+
68
+ export interface BuildKnowledgeResult {
69
+ docs: DocsKnowledge;
70
+ api: ApiKnowledge;
71
+ }
72
+
73
+ /** Generates `docs.json` and `api.json` into `outDir`. */
74
+ export async function buildKnowledge({
75
+ docsRoot,
76
+ repoRoot,
77
+ outDir,
78
+ }: BuildKnowledgeOptions): Promise<BuildKnowledgeResult> {
79
+ const docs = buildDocsKnowledge(docsRoot);
80
+ const docsFor = makeDocsResolver(docs);
81
+
82
+ const components = extractComponents(repoRoot, (name) => docsFor(name));
83
+ const { fieldTypes, fieldCommon } = await extractFieldTypes(
84
+ repoRoot,
85
+ (type) => docsFor(type, "uikit/form"),
86
+ );
87
+ const composables = extractComposables(repoRoot, (name) => docsFor(name));
88
+
89
+ const api: ApiKnowledge = {
90
+ version: API_KNOWLEDGE_VERSION,
91
+ generatedAt: new Date().toISOString(),
92
+ components,
93
+ fieldTypes,
94
+ fieldCommon,
95
+ composables,
96
+ };
97
+
98
+ mkdirSync(outDir, { recursive: true });
99
+ writeFileSync(join(outDir, DOCS_FILE), JSON.stringify(docs));
100
+ writeFileSync(join(outDir, API_FILE), JSON.stringify(api));
101
+
102
+ return { docs, api };
103
+ }