slicejs-cli 4.3.0 → 4.4.0
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.
- package/LICENSE +21 -21
- package/README.md +260 -257
- package/client.js +927 -823
- package/commands/Print.js +163 -163
- package/commands/Validations.js +92 -92
- package/commands/build/build.js +97 -107
- package/commands/buildProduction/buildProduction.js +613 -613
- package/commands/bundle/bundle.js +251 -239
- package/commands/createComponent/VisualComponentTemplate.js +55 -55
- package/commands/createComponent/createComponent.js +128 -128
- package/commands/deleteComponent/deleteComponent.js +81 -81
- package/commands/docs/docs.js +365 -365
- package/commands/doctor/doctor.js +677 -563
- package/commands/getComponent/getComponent.js +842 -842
- package/commands/init/init.js +526 -475
- package/commands/lint/lint.js +75 -0
- package/commands/lint/types.js +85 -0
- package/commands/listComponents/listComponents.js +172 -172
- package/commands/seo/check.js +91 -0
- package/commands/seo/images.js +586 -0
- package/commands/seo/sitemap.js +106 -0
- package/commands/seo/support.js +130 -0
- package/commands/setup/lint.js +151 -0
- package/commands/skill/skill.js +236 -236
- package/commands/startServer/startServer.js +240 -240
- package/commands/startServer/watchServer.js +66 -66
- package/commands/typecheck/typecheck.js +83 -0
- package/commands/types/types.js +1378 -1097
- package/commands/utils/JsMinifier.js +230 -230
- package/commands/utils/LocalCliDelegation.js +78 -53
- package/commands/utils/PackageManager.js +148 -148
- package/commands/utils/PathHelper.js +87 -75
- package/commands/utils/ProjectValidation.js +274 -0
- package/commands/utils/SourceDiagnostics.js +201 -201
- package/commands/utils/VersionChecker.js +169 -169
- package/commands/utils/analyzeSource.js +77 -77
- package/commands/utils/bundling/BundleGenerator.js +3748 -3776
- package/commands/utils/bundling/DependencyAnalyzer.js +976 -976
- package/commands/utils/bundling/ExternalModuleBundler.js +298 -298
- package/commands/utils/componentAudit.js +74 -0
- package/commands/utils/compressAssets.js +103 -103
- package/commands/utils/cssScope.js +83 -0
- package/commands/utils/loadConfig.js +31 -31
- package/commands/utils/semver.js +66 -0
- package/commands/utils/sliceConfigSchema.js +72 -0
- package/commands/utils/sliceScripts.js +48 -48
- package/commands/utils/updateManager.js +471 -471
- package/eslint-config.js +128 -0
- package/package.json +19 -13
package/commands/docs/docs.js
CHANGED
|
@@ -1,365 +1,365 @@
|
|
|
1
|
-
import Print from '../Print.js';
|
|
2
|
-
|
|
3
|
-
const DEFAULT_FRAMEWORK_BASE_URL = 'https://raw.githubusercontent.com/VKneider/slicejs_docs/master/';
|
|
4
|
-
const DEFAULT_COMPONENTS_MANIFEST_URL = 'https://raw.githubusercontent.com/VKneider/
|
|
5
|
-
const DEFAULT_COMPONENTS_RAW_BASE_URL = 'https://raw.githubusercontent.com/VKneider/
|
|
6
|
-
|
|
7
|
-
const SOURCE_ALIASES = new Map([
|
|
8
|
-
['framework', 'framework'],
|
|
9
|
-
['slice-docs', 'framework'],
|
|
10
|
-
['slicejs-docs', 'framework'],
|
|
11
|
-
['components', 'components'],
|
|
12
|
-
['visual', 'components'],
|
|
13
|
-
['visual-library', 'components'],
|
|
14
|
-
['slice-components', 'components'],
|
|
15
|
-
['all', 'all']
|
|
16
|
-
]);
|
|
17
|
-
|
|
18
|
-
function normalizeSource(source = 'all') {
|
|
19
|
-
const normalized = SOURCE_ALIASES.get(String(source).trim().toLowerCase());
|
|
20
|
-
if (!normalized) {
|
|
21
|
-
throw new Error(`Unknown documentation source "${source}". Use framework, components, or all.`);
|
|
22
|
-
}
|
|
23
|
-
return normalized;
|
|
24
|
-
}
|
|
25
|
-
|
|
26
|
-
function joinUrl(base, suffix) {
|
|
27
|
-
return `${String(base).replace(/\/+$/, '')}/${String(suffix).replace(/^\/+/, '')}`;
|
|
28
|
-
}
|
|
29
|
-
|
|
30
|
-
async function fetchResponse(url, fetchImpl) {
|
|
31
|
-
const response = await fetchImpl(url);
|
|
32
|
-
if (!response.ok) {
|
|
33
|
-
throw new Error(`HTTP ${response.status} while fetching ${url}`);
|
|
34
|
-
}
|
|
35
|
-
return response;
|
|
36
|
-
}
|
|
37
|
-
|
|
38
|
-
async function fetchText(url, fetchImpl) {
|
|
39
|
-
const response = await fetchResponse(url, fetchImpl);
|
|
40
|
-
return response.text();
|
|
41
|
-
}
|
|
42
|
-
|
|
43
|
-
async function fetchJson(url, fetchImpl) {
|
|
44
|
-
const response = await fetchResponse(url, fetchImpl);
|
|
45
|
-
return response.json();
|
|
46
|
-
}
|
|
47
|
-
|
|
48
|
-
function getTitle(content, fallback) {
|
|
49
|
-
const titleLine = content.split(/\r?\n/).find((line) => line.startsWith('# '));
|
|
50
|
-
return titleLine ? titleLine.slice(2).trim() : fallback;
|
|
51
|
-
}
|
|
52
|
-
|
|
53
|
-
function parseFrameworkLlm(content, baseUrl, revision = 'master') {
|
|
54
|
-
const documents = [];
|
|
55
|
-
const sections = (`\n${content}`).split(/\n=== /).slice(1);
|
|
56
|
-
|
|
57
|
-
for (const section of sections) {
|
|
58
|
-
const lines = section.split('\n');
|
|
59
|
-
const path = lines[0].replace(' ===', '').trim();
|
|
60
|
-
const searchText = lines.slice(1).join('\n').trim();
|
|
61
|
-
if (!path || !searchText) continue;
|
|
62
|
-
|
|
63
|
-
const id = path.replace(/^markdown\//, '').replace(/\.md$/, '');
|
|
64
|
-
documents.push({
|
|
65
|
-
source: 'framework',
|
|
66
|
-
catalog: 'slicejs-docs',
|
|
67
|
-
id,
|
|
68
|
-
title: getTitle(searchText, id.split('/').pop()),
|
|
69
|
-
path,
|
|
70
|
-
sourcePath: path,
|
|
71
|
-
rawUrl: joinUrl(baseUrl, path),
|
|
72
|
-
description: '',
|
|
73
|
-
tags: [],
|
|
74
|
-
revision,
|
|
75
|
-
searchText
|
|
76
|
-
});
|
|
77
|
-
}
|
|
78
|
-
|
|
79
|
-
return documents;
|
|
80
|
-
}
|
|
81
|
-
|
|
82
|
-
function normalizeComponentsManifest(manifest, rawBaseUrl, preferRawBaseUrl = false) {
|
|
83
|
-
if (!manifest || !Array.isArray(manifest.documents)) {
|
|
84
|
-
throw new Error('Components documentation manifest is missing a documents array');
|
|
85
|
-
}
|
|
86
|
-
|
|
87
|
-
return manifest.documents.map((document) => ({
|
|
88
|
-
...document,
|
|
89
|
-
source: 'components',
|
|
90
|
-
catalog: manifest.catalog || 'slicejs-components',
|
|
91
|
-
path: document.sourcePath,
|
|
92
|
-
rawUrl: preferRawBaseUrl || !document.rawUrl
|
|
93
|
-
? joinUrl(rawBaseUrl, `${manifest.revision || 'master'}/${document.sourcePath}`)
|
|
94
|
-
: document.rawUrl,
|
|
95
|
-
searchText: null,
|
|
96
|
-
revision: manifest.revision,
|
|
97
|
-
version: manifest.version
|
|
98
|
-
}));
|
|
99
|
-
}
|
|
100
|
-
|
|
101
|
-
function qualifiedId(document) {
|
|
102
|
-
return `${document.source}:${document.id}`;
|
|
103
|
-
}
|
|
104
|
-
|
|
105
|
-
function matchesDocument(document, requestedId) {
|
|
106
|
-
const value = String(requestedId).trim().toLowerCase();
|
|
107
|
-
return [document.id, document.component, document.title, qualifiedId(document)]
|
|
108
|
-
.filter(Boolean)
|
|
109
|
-
.some((candidate) => String(candidate).toLowerCase() === value);
|
|
110
|
-
}
|
|
111
|
-
|
|
112
|
-
function scoreDocument(document, content, query, maxSnippets) {
|
|
113
|
-
const phrase = query.toLowerCase().trim();
|
|
114
|
-
const terms = [...new Set(phrase.split(/\s+/).filter(Boolean))];
|
|
115
|
-
if (terms.length === 0) return null;
|
|
116
|
-
|
|
117
|
-
const lines = content.split(/\r?\n/);
|
|
118
|
-
const title = String(document.title || '').toLowerCase();
|
|
119
|
-
const tags = Array.isArray(document.tags) ? document.tags.join(' ').toLowerCase() : '';
|
|
120
|
-
const matched = new Set();
|
|
121
|
-
let score = 0;
|
|
122
|
-
|
|
123
|
-
for (const term of terms) {
|
|
124
|
-
if (title.includes(term)) {
|
|
125
|
-
score += 6;
|
|
126
|
-
matched.add(term);
|
|
127
|
-
}
|
|
128
|
-
if (tags.includes(term)) {
|
|
129
|
-
score += 4;
|
|
130
|
-
matched.add(term);
|
|
131
|
-
}
|
|
132
|
-
}
|
|
133
|
-
|
|
134
|
-
if (terms.length > 1 && title.includes(phrase)) score += 10;
|
|
135
|
-
|
|
136
|
-
const hits = [];
|
|
137
|
-
let section = '';
|
|
138
|
-
for (let index = 0; index < lines.length; index += 1) {
|
|
139
|
-
const line = lines[index];
|
|
140
|
-
if (/^#{1,6}\s/.test(line)) section = line.replace(/^#{1,6}\s+/, '').trim();
|
|
141
|
-
|
|
142
|
-
const lower = line.toLowerCase();
|
|
143
|
-
let lineScore = 0;
|
|
144
|
-
for (const term of terms) {
|
|
145
|
-
if (lower.includes(term)) {
|
|
146
|
-
lineScore += /^#{1,6}\s/.test(line) ? 3 : 1;
|
|
147
|
-
matched.add(term);
|
|
148
|
-
}
|
|
149
|
-
}
|
|
150
|
-
if (terms.length > 1 && lower.includes(phrase)) lineScore += 5;
|
|
151
|
-
if (lineScore > 0) {
|
|
152
|
-
score += lineScore;
|
|
153
|
-
hits.push({ line: index + 1, section: section || document.title, text: line.trim(), lineScore });
|
|
154
|
-
}
|
|
155
|
-
}
|
|
156
|
-
|
|
157
|
-
if (matched.size === 0) return null;
|
|
158
|
-
const coverage = matched.size / terms.length;
|
|
159
|
-
score *= 0.5 + 0.5 * coverage;
|
|
160
|
-
|
|
161
|
-
return {
|
|
162
|
-
doc_id: qualifiedId(document),
|
|
163
|
-
source: document.source,
|
|
164
|
-
title: document.title,
|
|
165
|
-
path: document.path,
|
|
166
|
-
relevance_score: Math.round(score * 100) / 100,
|
|
167
|
-
matched_terms: [...matched],
|
|
168
|
-
snippets: hits
|
|
169
|
-
.sort((a, b) => b.lineScore - a.lineScore || a.line - b.line)
|
|
170
|
-
.slice(0, maxSnippets)
|
|
171
|
-
.map(({ line, section: hitSection, text }) => ({ line, section: hitSection, text }))
|
|
172
|
-
};
|
|
173
|
-
}
|
|
174
|
-
|
|
175
|
-
export function createDocsClient(options = {}) {
|
|
176
|
-
const fetchImpl = options.fetchImpl || globalThis.fetch;
|
|
177
|
-
if (typeof fetchImpl !== 'function') {
|
|
178
|
-
throw new Error('A fetch implementation is required to access documentation');
|
|
179
|
-
}
|
|
180
|
-
|
|
181
|
-
const frameworkBaseUrl = options.frameworkBaseUrl || process.env.SLICE_FRAMEWORK_DOCS_BASE_URL || DEFAULT_FRAMEWORK_BASE_URL;
|
|
182
|
-
const frameworkRevision = options.frameworkRevision || process.env.SLICE_FRAMEWORK_DOCS_REVISION || 'master';
|
|
183
|
-
const componentsManifestUrl = options.componentsManifestUrl || process.env.SLICE_COMPONENTS_MANIFEST_URL || DEFAULT_COMPONENTS_MANIFEST_URL;
|
|
184
|
-
const componentsRawBaseOverride = options.componentsRawBaseUrl || process.env.SLICE_COMPONENTS_RAW_BASE_URL || null;
|
|
185
|
-
const componentsRawBaseUrl = componentsRawBaseOverride || DEFAULT_COMPONENTS_RAW_BASE_URL;
|
|
186
|
-
const catalogCache = new Map();
|
|
187
|
-
const contentCache = new Map();
|
|
188
|
-
|
|
189
|
-
async function loadCatalog(source) {
|
|
190
|
-
const normalized = normalizeSource(source);
|
|
191
|
-
if (normalized === 'all') {
|
|
192
|
-
const [framework, components] = await Promise.all([
|
|
193
|
-
loadCatalog('framework'),
|
|
194
|
-
loadCatalog('components')
|
|
195
|
-
]);
|
|
196
|
-
return [...framework, ...components];
|
|
197
|
-
}
|
|
198
|
-
|
|
199
|
-
if (catalogCache.has(normalized)) return catalogCache.get(normalized);
|
|
200
|
-
|
|
201
|
-
const promise = normalized === 'framework'
|
|
202
|
-
? fetchText(joinUrl(frameworkBaseUrl, 'llm.txt'), fetchImpl)
|
|
203
|
-
.then((content) => parseFrameworkLlm(content, frameworkBaseUrl, frameworkRevision))
|
|
204
|
-
: fetchJson(componentsManifestUrl, fetchImpl)
|
|
205
|
-
.then((manifest) => normalizeComponentsManifest(manifest, componentsRawBaseUrl, Boolean(componentsRawBaseOverride)));
|
|
206
|
-
|
|
207
|
-
catalogCache.set(normalized, promise);
|
|
208
|
-
return promise;
|
|
209
|
-
}
|
|
210
|
-
|
|
211
|
-
async function getContent(document) {
|
|
212
|
-
const key = qualifiedId(document);
|
|
213
|
-
if (contentCache.has(key)) return contentCache.get(key);
|
|
214
|
-
|
|
215
|
-
const promise = fetchText(document.rawUrl, fetchImpl);
|
|
216
|
-
contentCache.set(key, promise);
|
|
217
|
-
return promise;
|
|
218
|
-
}
|
|
219
|
-
|
|
220
|
-
async function list(source = 'all') {
|
|
221
|
-
return loadCatalog(source);
|
|
222
|
-
}
|
|
223
|
-
|
|
224
|
-
async function search(query, { source = 'all', maxResults = 5, snippetsPerDoc = 3 } = {}) {
|
|
225
|
-
const documents = await loadCatalog(source);
|
|
226
|
-
const results = [];
|
|
227
|
-
for (const document of documents) {
|
|
228
|
-
const content = document.searchText || await getContent(document);
|
|
229
|
-
const result = scoreDocument(document, content, query, snippetsPerDoc);
|
|
230
|
-
if (result) results.push(result);
|
|
231
|
-
}
|
|
232
|
-
return results
|
|
233
|
-
.sort((a, b) => b.relevance_score - a.relevance_score)
|
|
234
|
-
.slice(0, maxResults);
|
|
235
|
-
}
|
|
236
|
-
|
|
237
|
-
async function get(ids, { source = 'all' } = {}) {
|
|
238
|
-
const requestedIds = Array.isArray(ids) ? ids : [ids];
|
|
239
|
-
const documents = await loadCatalog(source);
|
|
240
|
-
const results = [];
|
|
241
|
-
|
|
242
|
-
for (const requestedId of requestedIds) {
|
|
243
|
-
const document = documents.find((candidate) => matchesDocument(candidate, requestedId));
|
|
244
|
-
if (!document) {
|
|
245
|
-
throw new Error(`Documentation document not found: "${requestedId}" in source "${normalizeSource(source)}"`);
|
|
246
|
-
}
|
|
247
|
-
|
|
248
|
-
const content = await getContent(document);
|
|
249
|
-
results.push({
|
|
250
|
-
doc_id: qualifiedId(document),
|
|
251
|
-
source: document.source,
|
|
252
|
-
catalog: document.catalog,
|
|
253
|
-
id: document.id,
|
|
254
|
-
title: document.title,
|
|
255
|
-
content,
|
|
256
|
-
metadata: {
|
|
257
|
-
path: document.path,
|
|
258
|
-
sourcePath: document.sourcePath,
|
|
259
|
-
rawUrl: document.rawUrl,
|
|
260
|
-
route: document.route || null,
|
|
261
|
-
component: document.component || null,
|
|
262
|
-
kind: document.kind || null,
|
|
263
|
-
tags: document.tags || [],
|
|
264
|
-
version: document.version || null,
|
|
265
|
-
revision: document.revision || null
|
|
266
|
-
}
|
|
267
|
-
});
|
|
268
|
-
}
|
|
269
|
-
|
|
270
|
-
return results;
|
|
271
|
-
}
|
|
272
|
-
|
|
273
|
-
return { list, search, get };
|
|
274
|
-
}
|
|
275
|
-
|
|
276
|
-
function parseMaxResults(value, fallback = 5) {
|
|
277
|
-
const parsed = Number(value);
|
|
278
|
-
if (!Number.isInteger(parsed) || parsed < 1) return fallback;
|
|
279
|
-
return parsed;
|
|
280
|
-
}
|
|
281
|
-
|
|
282
|
-
export async function runDocsList(options = {}) {
|
|
283
|
-
const client = createDocsClient();
|
|
284
|
-
const documents = await client.list(options.source || 'all');
|
|
285
|
-
const entries = documents.map((document) => ({
|
|
286
|
-
doc_id: qualifiedId(document),
|
|
287
|
-
source: document.source,
|
|
288
|
-
catalog: document.catalog,
|
|
289
|
-
id: document.id,
|
|
290
|
-
title: document.title,
|
|
291
|
-
path: document.path,
|
|
292
|
-
sourcePath: document.sourcePath,
|
|
293
|
-
component: document.component,
|
|
294
|
-
kind: document.kind,
|
|
295
|
-
route: document.route || null,
|
|
296
|
-
tags: document.tags || [],
|
|
297
|
-
version: document.version || null,
|
|
298
|
-
revision: document.revision || null
|
|
299
|
-
}));
|
|
300
|
-
if (options.json) {
|
|
301
|
-
console.log(JSON.stringify(entries));
|
|
302
|
-
return entries;
|
|
303
|
-
}
|
|
304
|
-
|
|
305
|
-
Print.title(`Documentation (${normalizeSource(options.source || 'all')})`);
|
|
306
|
-
for (const document of documents) {
|
|
307
|
-
const suffix = document.component ? ` [${document.kind}]` : '';
|
|
308
|
-
console.log(`- ${document.source}:${document.id} — ${document.title}${suffix}`);
|
|
309
|
-
}
|
|
310
|
-
return entries;
|
|
311
|
-
}
|
|
312
|
-
|
|
313
|
-
export async function runDocsSearch(query, options = {}) {
|
|
314
|
-
if (!query || !query.trim()) throw new Error('A search query is required');
|
|
315
|
-
const client = createDocsClient();
|
|
316
|
-
const results = await client.search(query, {
|
|
317
|
-
source: options.source || 'all',
|
|
318
|
-
maxResults: parseMaxResults(options.maxResults),
|
|
319
|
-
snippetsPerDoc: parseMaxResults(options.snippetsPerDoc, 3)
|
|
320
|
-
});
|
|
321
|
-
|
|
322
|
-
if (options.json) {
|
|
323
|
-
console.log(JSON.stringify(results));
|
|
324
|
-
return results;
|
|
325
|
-
}
|
|
326
|
-
|
|
327
|
-
Print.title(`Documentation search: ${query}`);
|
|
328
|
-
for (const result of results) {
|
|
329
|
-
console.log(`- ${result.doc_id} — ${result.title} (${result.relevance_score})`);
|
|
330
|
-
for (const snippet of result.snippets) {
|
|
331
|
-
console.log(` ${snippet.section}: ${snippet.text}`);
|
|
332
|
-
}
|
|
333
|
-
}
|
|
334
|
-
if (results.length === 0) Print.info('No matching documentation found.');
|
|
335
|
-
return results;
|
|
336
|
-
}
|
|
337
|
-
|
|
338
|
-
export async function runDocsGet(ids, options = {}) {
|
|
339
|
-
if (!ids || ids.length === 0) throw new Error('At least one documentation ID is required');
|
|
340
|
-
const client = createDocsClient();
|
|
341
|
-
const results = await client.get(ids, { source: options.source || 'all' });
|
|
342
|
-
|
|
343
|
-
if (options.json) {
|
|
344
|
-
console.log(JSON.stringify(results.length === 1 ? results[0] : results));
|
|
345
|
-
return results;
|
|
346
|
-
}
|
|
347
|
-
|
|
348
|
-
if (options.stdout) {
|
|
349
|
-
for (let index = 0; index < results.length; index += 1) {
|
|
350
|
-
if (index > 0) process.stdout.write('\n\n---\n\n');
|
|
351
|
-
process.stdout.write(results[index].content);
|
|
352
|
-
}
|
|
353
|
-
if (results.length > 0 && !results[results.length - 1].content.endsWith('\n')) process.stdout.write('\n');
|
|
354
|
-
return results;
|
|
355
|
-
}
|
|
356
|
-
|
|
357
|
-
for (const result of results) {
|
|
358
|
-
Print.title(`${result.title} (${result.doc_id})`);
|
|
359
|
-
console.log(result.content);
|
|
360
|
-
Print.info(`Source: ${result.metadata.rawUrl}`);
|
|
361
|
-
}
|
|
362
|
-
return results;
|
|
363
|
-
}
|
|
364
|
-
|
|
365
|
-
export { normalizeSource, parseFrameworkLlm, scoreDocument };
|
|
1
|
+
import Print from '../Print.js';
|
|
2
|
+
|
|
3
|
+
const DEFAULT_FRAMEWORK_BASE_URL = 'https://raw.githubusercontent.com/VKneider/slicejs_docs/master/';
|
|
4
|
+
const DEFAULT_COMPONENTS_MANIFEST_URL = 'https://raw.githubusercontent.com/VKneider/slicejs-components/master/agent/docs-manifest.json';
|
|
5
|
+
const DEFAULT_COMPONENTS_RAW_BASE_URL = 'https://raw.githubusercontent.com/VKneider/slicejs-components';
|
|
6
|
+
|
|
7
|
+
const SOURCE_ALIASES = new Map([
|
|
8
|
+
['framework', 'framework'],
|
|
9
|
+
['slice-docs', 'framework'],
|
|
10
|
+
['slicejs-docs', 'framework'],
|
|
11
|
+
['components', 'components'],
|
|
12
|
+
['visual', 'components'],
|
|
13
|
+
['visual-library', 'components'],
|
|
14
|
+
['slice-components', 'components'],
|
|
15
|
+
['all', 'all']
|
|
16
|
+
]);
|
|
17
|
+
|
|
18
|
+
function normalizeSource(source = 'all') {
|
|
19
|
+
const normalized = SOURCE_ALIASES.get(String(source).trim().toLowerCase());
|
|
20
|
+
if (!normalized) {
|
|
21
|
+
throw new Error(`Unknown documentation source "${source}". Use framework, components, or all.`);
|
|
22
|
+
}
|
|
23
|
+
return normalized;
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
function joinUrl(base, suffix) {
|
|
27
|
+
return `${String(base).replace(/\/+$/, '')}/${String(suffix).replace(/^\/+/, '')}`;
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
async function fetchResponse(url, fetchImpl) {
|
|
31
|
+
const response = await fetchImpl(url);
|
|
32
|
+
if (!response.ok) {
|
|
33
|
+
throw new Error(`HTTP ${response.status} while fetching ${url}`);
|
|
34
|
+
}
|
|
35
|
+
return response;
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
async function fetchText(url, fetchImpl) {
|
|
39
|
+
const response = await fetchResponse(url, fetchImpl);
|
|
40
|
+
return response.text();
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
async function fetchJson(url, fetchImpl) {
|
|
44
|
+
const response = await fetchResponse(url, fetchImpl);
|
|
45
|
+
return response.json();
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
function getTitle(content, fallback) {
|
|
49
|
+
const titleLine = content.split(/\r?\n/).find((line) => line.startsWith('# '));
|
|
50
|
+
return titleLine ? titleLine.slice(2).trim() : fallback;
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
function parseFrameworkLlm(content, baseUrl, revision = 'master') {
|
|
54
|
+
const documents = [];
|
|
55
|
+
const sections = (`\n${content}`).split(/\n=== /).slice(1);
|
|
56
|
+
|
|
57
|
+
for (const section of sections) {
|
|
58
|
+
const lines = section.split('\n');
|
|
59
|
+
const path = lines[0].replace(' ===', '').trim();
|
|
60
|
+
const searchText = lines.slice(1).join('\n').trim();
|
|
61
|
+
if (!path || !searchText) continue;
|
|
62
|
+
|
|
63
|
+
const id = path.replace(/^markdown\//, '').replace(/\.md$/, '');
|
|
64
|
+
documents.push({
|
|
65
|
+
source: 'framework',
|
|
66
|
+
catalog: 'slicejs-docs',
|
|
67
|
+
id,
|
|
68
|
+
title: getTitle(searchText, id.split('/').pop()),
|
|
69
|
+
path,
|
|
70
|
+
sourcePath: path,
|
|
71
|
+
rawUrl: joinUrl(baseUrl, path),
|
|
72
|
+
description: '',
|
|
73
|
+
tags: [],
|
|
74
|
+
revision,
|
|
75
|
+
searchText
|
|
76
|
+
});
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
return documents;
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
function normalizeComponentsManifest(manifest, rawBaseUrl, preferRawBaseUrl = false) {
|
|
83
|
+
if (!manifest || !Array.isArray(manifest.documents)) {
|
|
84
|
+
throw new Error('Components documentation manifest is missing a documents array');
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
return manifest.documents.map((document) => ({
|
|
88
|
+
...document,
|
|
89
|
+
source: 'components',
|
|
90
|
+
catalog: manifest.catalog || 'slicejs-components',
|
|
91
|
+
path: document.sourcePath,
|
|
92
|
+
rawUrl: preferRawBaseUrl || !document.rawUrl
|
|
93
|
+
? joinUrl(rawBaseUrl, `${manifest.revision || 'master'}/${document.sourcePath}`)
|
|
94
|
+
: document.rawUrl,
|
|
95
|
+
searchText: null,
|
|
96
|
+
revision: manifest.revision,
|
|
97
|
+
version: manifest.version
|
|
98
|
+
}));
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
function qualifiedId(document) {
|
|
102
|
+
return `${document.source}:${document.id}`;
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
function matchesDocument(document, requestedId) {
|
|
106
|
+
const value = String(requestedId).trim().toLowerCase();
|
|
107
|
+
return [document.id, document.component, document.title, qualifiedId(document)]
|
|
108
|
+
.filter(Boolean)
|
|
109
|
+
.some((candidate) => String(candidate).toLowerCase() === value);
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
function scoreDocument(document, content, query, maxSnippets) {
|
|
113
|
+
const phrase = query.toLowerCase().trim();
|
|
114
|
+
const terms = [...new Set(phrase.split(/\s+/).filter(Boolean))];
|
|
115
|
+
if (terms.length === 0) return null;
|
|
116
|
+
|
|
117
|
+
const lines = content.split(/\r?\n/);
|
|
118
|
+
const title = String(document.title || '').toLowerCase();
|
|
119
|
+
const tags = Array.isArray(document.tags) ? document.tags.join(' ').toLowerCase() : '';
|
|
120
|
+
const matched = new Set();
|
|
121
|
+
let score = 0;
|
|
122
|
+
|
|
123
|
+
for (const term of terms) {
|
|
124
|
+
if (title.includes(term)) {
|
|
125
|
+
score += 6;
|
|
126
|
+
matched.add(term);
|
|
127
|
+
}
|
|
128
|
+
if (tags.includes(term)) {
|
|
129
|
+
score += 4;
|
|
130
|
+
matched.add(term);
|
|
131
|
+
}
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
if (terms.length > 1 && title.includes(phrase)) score += 10;
|
|
135
|
+
|
|
136
|
+
const hits = [];
|
|
137
|
+
let section = '';
|
|
138
|
+
for (let index = 0; index < lines.length; index += 1) {
|
|
139
|
+
const line = lines[index];
|
|
140
|
+
if (/^#{1,6}\s/.test(line)) section = line.replace(/^#{1,6}\s+/, '').trim();
|
|
141
|
+
|
|
142
|
+
const lower = line.toLowerCase();
|
|
143
|
+
let lineScore = 0;
|
|
144
|
+
for (const term of terms) {
|
|
145
|
+
if (lower.includes(term)) {
|
|
146
|
+
lineScore += /^#{1,6}\s/.test(line) ? 3 : 1;
|
|
147
|
+
matched.add(term);
|
|
148
|
+
}
|
|
149
|
+
}
|
|
150
|
+
if (terms.length > 1 && lower.includes(phrase)) lineScore += 5;
|
|
151
|
+
if (lineScore > 0) {
|
|
152
|
+
score += lineScore;
|
|
153
|
+
hits.push({ line: index + 1, section: section || document.title, text: line.trim(), lineScore });
|
|
154
|
+
}
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
if (matched.size === 0) return null;
|
|
158
|
+
const coverage = matched.size / terms.length;
|
|
159
|
+
score *= 0.5 + 0.5 * coverage;
|
|
160
|
+
|
|
161
|
+
return {
|
|
162
|
+
doc_id: qualifiedId(document),
|
|
163
|
+
source: document.source,
|
|
164
|
+
title: document.title,
|
|
165
|
+
path: document.path,
|
|
166
|
+
relevance_score: Math.round(score * 100) / 100,
|
|
167
|
+
matched_terms: [...matched],
|
|
168
|
+
snippets: hits
|
|
169
|
+
.sort((a, b) => b.lineScore - a.lineScore || a.line - b.line)
|
|
170
|
+
.slice(0, maxSnippets)
|
|
171
|
+
.map(({ line, section: hitSection, text }) => ({ line, section: hitSection, text }))
|
|
172
|
+
};
|
|
173
|
+
}
|
|
174
|
+
|
|
175
|
+
export function createDocsClient(options = {}) {
|
|
176
|
+
const fetchImpl = options.fetchImpl || globalThis.fetch;
|
|
177
|
+
if (typeof fetchImpl !== 'function') {
|
|
178
|
+
throw new Error('A fetch implementation is required to access documentation');
|
|
179
|
+
}
|
|
180
|
+
|
|
181
|
+
const frameworkBaseUrl = options.frameworkBaseUrl || process.env.SLICE_FRAMEWORK_DOCS_BASE_URL || DEFAULT_FRAMEWORK_BASE_URL;
|
|
182
|
+
const frameworkRevision = options.frameworkRevision || process.env.SLICE_FRAMEWORK_DOCS_REVISION || 'master';
|
|
183
|
+
const componentsManifestUrl = options.componentsManifestUrl || process.env.SLICE_COMPONENTS_MANIFEST_URL || DEFAULT_COMPONENTS_MANIFEST_URL;
|
|
184
|
+
const componentsRawBaseOverride = options.componentsRawBaseUrl || process.env.SLICE_COMPONENTS_RAW_BASE_URL || null;
|
|
185
|
+
const componentsRawBaseUrl = componentsRawBaseOverride || DEFAULT_COMPONENTS_RAW_BASE_URL;
|
|
186
|
+
const catalogCache = new Map();
|
|
187
|
+
const contentCache = new Map();
|
|
188
|
+
|
|
189
|
+
async function loadCatalog(source) {
|
|
190
|
+
const normalized = normalizeSource(source);
|
|
191
|
+
if (normalized === 'all') {
|
|
192
|
+
const [framework, components] = await Promise.all([
|
|
193
|
+
loadCatalog('framework'),
|
|
194
|
+
loadCatalog('components')
|
|
195
|
+
]);
|
|
196
|
+
return [...framework, ...components];
|
|
197
|
+
}
|
|
198
|
+
|
|
199
|
+
if (catalogCache.has(normalized)) return catalogCache.get(normalized);
|
|
200
|
+
|
|
201
|
+
const promise = normalized === 'framework'
|
|
202
|
+
? fetchText(joinUrl(frameworkBaseUrl, 'llm.txt'), fetchImpl)
|
|
203
|
+
.then((content) => parseFrameworkLlm(content, frameworkBaseUrl, frameworkRevision))
|
|
204
|
+
: fetchJson(componentsManifestUrl, fetchImpl)
|
|
205
|
+
.then((manifest) => normalizeComponentsManifest(manifest, componentsRawBaseUrl, Boolean(componentsRawBaseOverride)));
|
|
206
|
+
|
|
207
|
+
catalogCache.set(normalized, promise);
|
|
208
|
+
return promise;
|
|
209
|
+
}
|
|
210
|
+
|
|
211
|
+
async function getContent(document) {
|
|
212
|
+
const key = qualifiedId(document);
|
|
213
|
+
if (contentCache.has(key)) return contentCache.get(key);
|
|
214
|
+
|
|
215
|
+
const promise = fetchText(document.rawUrl, fetchImpl);
|
|
216
|
+
contentCache.set(key, promise);
|
|
217
|
+
return promise;
|
|
218
|
+
}
|
|
219
|
+
|
|
220
|
+
async function list(source = 'all') {
|
|
221
|
+
return loadCatalog(source);
|
|
222
|
+
}
|
|
223
|
+
|
|
224
|
+
async function search(query, { source = 'all', maxResults = 5, snippetsPerDoc = 3 } = {}) {
|
|
225
|
+
const documents = await loadCatalog(source);
|
|
226
|
+
const results = [];
|
|
227
|
+
for (const document of documents) {
|
|
228
|
+
const content = document.searchText || await getContent(document);
|
|
229
|
+
const result = scoreDocument(document, content, query, snippetsPerDoc);
|
|
230
|
+
if (result) results.push(result);
|
|
231
|
+
}
|
|
232
|
+
return results
|
|
233
|
+
.sort((a, b) => b.relevance_score - a.relevance_score)
|
|
234
|
+
.slice(0, maxResults);
|
|
235
|
+
}
|
|
236
|
+
|
|
237
|
+
async function get(ids, { source = 'all' } = {}) {
|
|
238
|
+
const requestedIds = Array.isArray(ids) ? ids : [ids];
|
|
239
|
+
const documents = await loadCatalog(source);
|
|
240
|
+
const results = [];
|
|
241
|
+
|
|
242
|
+
for (const requestedId of requestedIds) {
|
|
243
|
+
const document = documents.find((candidate) => matchesDocument(candidate, requestedId));
|
|
244
|
+
if (!document) {
|
|
245
|
+
throw new Error(`Documentation document not found: "${requestedId}" in source "${normalizeSource(source)}"`);
|
|
246
|
+
}
|
|
247
|
+
|
|
248
|
+
const content = await getContent(document);
|
|
249
|
+
results.push({
|
|
250
|
+
doc_id: qualifiedId(document),
|
|
251
|
+
source: document.source,
|
|
252
|
+
catalog: document.catalog,
|
|
253
|
+
id: document.id,
|
|
254
|
+
title: document.title,
|
|
255
|
+
content,
|
|
256
|
+
metadata: {
|
|
257
|
+
path: document.path,
|
|
258
|
+
sourcePath: document.sourcePath,
|
|
259
|
+
rawUrl: document.rawUrl,
|
|
260
|
+
route: document.route || null,
|
|
261
|
+
component: document.component || null,
|
|
262
|
+
kind: document.kind || null,
|
|
263
|
+
tags: document.tags || [],
|
|
264
|
+
version: document.version || null,
|
|
265
|
+
revision: document.revision || null
|
|
266
|
+
}
|
|
267
|
+
});
|
|
268
|
+
}
|
|
269
|
+
|
|
270
|
+
return results;
|
|
271
|
+
}
|
|
272
|
+
|
|
273
|
+
return { list, search, get };
|
|
274
|
+
}
|
|
275
|
+
|
|
276
|
+
function parseMaxResults(value, fallback = 5) {
|
|
277
|
+
const parsed = Number(value);
|
|
278
|
+
if (!Number.isInteger(parsed) || parsed < 1) return fallback;
|
|
279
|
+
return parsed;
|
|
280
|
+
}
|
|
281
|
+
|
|
282
|
+
export async function runDocsList(options = {}) {
|
|
283
|
+
const client = createDocsClient();
|
|
284
|
+
const documents = await client.list(options.source || 'all');
|
|
285
|
+
const entries = documents.map((document) => ({
|
|
286
|
+
doc_id: qualifiedId(document),
|
|
287
|
+
source: document.source,
|
|
288
|
+
catalog: document.catalog,
|
|
289
|
+
id: document.id,
|
|
290
|
+
title: document.title,
|
|
291
|
+
path: document.path,
|
|
292
|
+
sourcePath: document.sourcePath,
|
|
293
|
+
component: document.component,
|
|
294
|
+
kind: document.kind,
|
|
295
|
+
route: document.route || null,
|
|
296
|
+
tags: document.tags || [],
|
|
297
|
+
version: document.version || null,
|
|
298
|
+
revision: document.revision || null
|
|
299
|
+
}));
|
|
300
|
+
if (options.json) {
|
|
301
|
+
console.log(JSON.stringify(entries));
|
|
302
|
+
return entries;
|
|
303
|
+
}
|
|
304
|
+
|
|
305
|
+
Print.title(`Documentation (${normalizeSource(options.source || 'all')})`);
|
|
306
|
+
for (const document of documents) {
|
|
307
|
+
const suffix = document.component ? ` [${document.kind}]` : '';
|
|
308
|
+
console.log(`- ${document.source}:${document.id} — ${document.title}${suffix}`);
|
|
309
|
+
}
|
|
310
|
+
return entries;
|
|
311
|
+
}
|
|
312
|
+
|
|
313
|
+
export async function runDocsSearch(query, options = {}) {
|
|
314
|
+
if (!query || !query.trim()) throw new Error('A search query is required');
|
|
315
|
+
const client = createDocsClient();
|
|
316
|
+
const results = await client.search(query, {
|
|
317
|
+
source: options.source || 'all',
|
|
318
|
+
maxResults: parseMaxResults(options.maxResults),
|
|
319
|
+
snippetsPerDoc: parseMaxResults(options.snippetsPerDoc, 3)
|
|
320
|
+
});
|
|
321
|
+
|
|
322
|
+
if (options.json) {
|
|
323
|
+
console.log(JSON.stringify(results));
|
|
324
|
+
return results;
|
|
325
|
+
}
|
|
326
|
+
|
|
327
|
+
Print.title(`Documentation search: ${query}`);
|
|
328
|
+
for (const result of results) {
|
|
329
|
+
console.log(`- ${result.doc_id} — ${result.title} (${result.relevance_score})`);
|
|
330
|
+
for (const snippet of result.snippets) {
|
|
331
|
+
console.log(` ${snippet.section}: ${snippet.text}`);
|
|
332
|
+
}
|
|
333
|
+
}
|
|
334
|
+
if (results.length === 0) Print.info('No matching documentation found.');
|
|
335
|
+
return results;
|
|
336
|
+
}
|
|
337
|
+
|
|
338
|
+
export async function runDocsGet(ids, options = {}) {
|
|
339
|
+
if (!ids || ids.length === 0) throw new Error('At least one documentation ID is required');
|
|
340
|
+
const client = createDocsClient();
|
|
341
|
+
const results = await client.get(ids, { source: options.source || 'all' });
|
|
342
|
+
|
|
343
|
+
if (options.json) {
|
|
344
|
+
console.log(JSON.stringify(results.length === 1 ? results[0] : results));
|
|
345
|
+
return results;
|
|
346
|
+
}
|
|
347
|
+
|
|
348
|
+
if (options.stdout) {
|
|
349
|
+
for (let index = 0; index < results.length; index += 1) {
|
|
350
|
+
if (index > 0) process.stdout.write('\n\n---\n\n');
|
|
351
|
+
process.stdout.write(results[index].content);
|
|
352
|
+
}
|
|
353
|
+
if (results.length > 0 && !results[results.length - 1].content.endsWith('\n')) process.stdout.write('\n');
|
|
354
|
+
return results;
|
|
355
|
+
}
|
|
356
|
+
|
|
357
|
+
for (const result of results) {
|
|
358
|
+
Print.title(`${result.title} (${result.doc_id})`);
|
|
359
|
+
console.log(result.content);
|
|
360
|
+
Print.info(`Source: ${result.metadata.rawUrl}`);
|
|
361
|
+
}
|
|
362
|
+
return results;
|
|
363
|
+
}
|
|
364
|
+
|
|
365
|
+
export { normalizeSource, parseFrameworkLlm, scoreDocument };
|