@sky.ui/mcp 0.0.1

package/dist/parse-component-ast.js

@@ -0,0 +1,695 @@
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import * as ts from 'typescript';
+function kebabToPascal(kebab) {
+    return kebab
+        .split('-')
+        .map((p) => (p ? p.charAt(0).toUpperCase() + p.slice(1).toLowerCase() : ''))
+        .join('');
+}
+function commentToString(comment) {
+    if (comment == null) {
+        return '';
+    }
+    if (typeof comment === 'string') {
+        return comment.trim();
+    }
+    if (Array.isArray(comment)) {
+        return comment
+            .map((part) => {
+            if (part.kind === ts.SyntaxKind.JSDocText) {
+                return part.text;
+            }
+            return '';
+        })
+            .join('')
+            .trim();
+    }
+    return '';
+}
+function getCustomElementTagName(classNode, _sf) {
+    if (!ts.canHaveDecorators(classNode)) {
+        return null;
+    }
+    const decorators = ts.getDecorators(classNode);
+    if (!decorators?.length) {
+        return null;
+    }
+    for (const dec of decorators) {
+        const ex = dec.expression;
+        if (!ts.isCallExpression(ex)) {
+            continue;
+        }
+        if (!ts.isIdentifier(ex.expression) || ex.expression.text !== 'customElement') {
+            continue;
+        }
+        const arg0 = ex.arguments[0];
+        if (arg0 && ts.isStringLiteralLike(arg0)) {
+            return arg0.text;
+        }
+    }
+    return null;
+}
+function findPrimaryComponentClass(sf, componentFolderName) {
+    const expected = kebabToPascal(componentFolderName);
+    const candidates = [];
+    const visit = (node) => {
+        if (ts.isClassDeclaration(node) && getCustomElementTagName(node, sf)) {
+            candidates.push(node);
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sf);
+    if (candidates.length === 0) {
+        return undefined;
+    }
+    const named = candidates.find((c) => c.name?.text === expected);
+    return named ?? candidates[0];
+}
+/** Parse `{Type} name - description` JSDoc lines, including nested generic braces. */
+function balancedBracedType(text) {
+    const t = text.trimStart();
+    if (!t.startsWith('{'))
+        return null;
+    let depth = 0;
+    for (let i = 0; i < t.length; i++) {
+        const ch = t[i];
+        if (ch === '{')
+            depth++;
+        else if (ch === '}') {
+            depth--;
+            if (depth === 0) {
+                return { type: t.slice(1, i).trim(), rest: t.slice(i + 1).trimStart() };
+            }
+        }
+    }
+    return null;
+}
+function parseGenericPropLike(text) {
+    const t = text.trim();
+    const braced = balancedBracedType(t);
+    if (braced) {
+        const nameMatch = /^(\S+)\s*[-–—]?\s*(.*)$/s.exec(braced.rest);
+        if (nameMatch) {
+            return {
+                type: braced.type,
+                name: nameMatch[1].trim(),
+                description: nameMatch[2]?.trim() || undefined,
+            };
+        }
+    }
+    const loose = /^(\S+)\s*[-–—]?\s*(.*)$/s.exec(t);
+    if (loose) {
+        return { name: loose[1].trim(), description: loose[2]?.trim() || undefined };
+    }
+    return { description: t };
+}
+function pushMisc(misc, tagName, text) {
+    const t = text.trim();
+    if (t) {
+        misc.push({ tag: tagName, text: t });
+    }
+}
+function collectFromTags(classNode, sf, doc) {
+    const tags = ts.getJSDocTags(classNode);
+    for (const tag of tags) {
+        const rawName = tag.tagName.getText(sf).toLowerCase();
+        if (ts.isJSDocPropertyTag(tag)) {
+            const name = tag.name.getText(sf);
+            const typ = tag.typeExpression?.getText(sf);
+            const desc = commentToString(tag.comment);
+            doc.properties.push({ name, type: typ, description: desc || undefined });
+            continue;
+        }
+        const text = commentToString(tag.comment);
+        switch (rawName) {
+            case 'element':
+                doc.element = text || doc.element;
+                break;
+            case 'summary':
+                doc.summary = text || doc.summary;
+                break;
+            case 'status':
+                doc.status = text || doc.status;
+                break;
+            case 'since':
+                doc.since = text || doc.since;
+                break;
+            case 'documentation':
+                doc.documentation = text || doc.documentation;
+                break;
+            case 'slot': {
+                const t = text.trim();
+                if (t.startsWith('-')) {
+                    doc.slots.push({ name: '', description: t.replace(/^\s*-\s+/, '').trim() || undefined });
+                    break;
+                }
+                const m = /^(.+?)\s+-\s+(.+)$/s.exec(t);
+                if (m) {
+                    doc.slots.push({ name: m[1].trim(), description: m[2].trim() });
+                }
+                else if (t) {
+                    doc.slots.push({ name: t, description: undefined });
+                }
+                break;
+            }
+            case 'csspart': {
+                const m = /^\s*([^\s-][^\n]*?)\s+-\s+(.+)$/s.exec(text);
+                if (m) {
+                    doc.cssParts.push({ name: m[1].trim(), description: m[2].trim() });
+                }
+                else {
+                    const name = text.split(/\s+/)[0]?.trim();
+                    if (name) {
+                        doc.cssParts.push({ name, description: text.slice(name.length).trim() || undefined });
+                    }
+                }
+                break;
+            }
+            case 'event':
+            case 'fires': {
+                const parsed = parseGenericPropLike(text);
+                const nm = parsed.name ?? text.split(/\s+/)[0]?.trim() ?? 'event';
+                doc.events.push({
+                    name: nm,
+                    type: parsed.type,
+                    description: parsed.description ?? text.trim()
+                });
+                break;
+            }
+            case 'property':
+            case 'prop': {
+                const parsed = parseGenericPropLike(text);
+                if (parsed.name) {
+                    doc.properties.push({
+                        name: parsed.name,
+                        type: parsed.type,
+                        description: parsed.description
+                    });
+                }
+                else {
+                    pushMisc(doc.miscTags, rawName, text);
+                }
+                break;
+            }
+            case 'example': {
+                const ex = text.trim();
+                if (ex) {
+                    doc.examples.push({ source: ex });
+                }
+                break;
+            }
+            default:
+                pushMisc(doc.miscTags, rawName, text);
+        }
+    }
+}
+function trimExamples(examples, maxCharsPerExample) {
+    let truncated = false;
+    const out = examples.map((e) => {
+        if (e.source.length <= maxCharsPerExample) {
+            return e;
+        }
+        truncated = true;
+        return { source: `${e.source.slice(0, maxCharsPerExample)}\n… [truncated]` };
+    });
+    return { examples: out, truncated };
+}
+function collectPublicMethods(classNode, sf, doc) {
+    for (const member of classNode.members) {
+        if (!ts.isMethodDeclaration(member))
+            continue;
+        if (!member.name || !ts.isIdentifier(member.name))
+            continue;
+        const name = member.name.text;
+        if (!name || name.startsWith('_'))
+            continue;
+        const mods = member.modifiers;
+        if (mods?.some((m) => m.kind === ts.SyntaxKind.PrivateKeyword || m.kind === ts.SyntaxKind.ProtectedKeyword))
+            continue;
+        if (mods?.some((m) => m.kind === ts.SyntaxKind.StaticKeyword))
+            continue;
+        const params = member.parameters.map((p) => ({
+            name: p.name.getText(sf),
+            type: p.type?.getText(sf),
+            optional: !!p.questionToken || !!p.initializer
+        }));
+        const paramDescByName = new Map();
+        const tags = ts.getJSDocTags(member);
+        let returnsDescription;
+        for (const tag of tags) {
+            const raw = tag.tagName.getText(sf).toLowerCase();
+            if (raw === 'param' && ts.isJSDocParameterTag(tag)) {
+                const pName = tag.name.getText(sf);
+                const pDesc = commentToString(tag.comment);
+                if (pName && pDesc)
+                    paramDescByName.set(pName, pDesc);
+            }
+            if (raw === 'returns' || raw === 'return') {
+                const d = commentToString(tag.comment);
+                if (d)
+                    returnsDescription = d;
+            }
+        }
+        const jsDocs = member.jsDoc ?? [];
+        const description = jsDocs
+            .map((d) => commentToString(d.comment))
+            .filter(Boolean)
+            .join('\n')
+            .trim();
+        doc.methods.push({
+            name,
+            description: description || undefined,
+            params: params.map((p) => ({ ...p, description: paramDescByName.get(p.name) })),
+            returns: member.type || returnsDescription
+                ? {
+                    type: member.type?.getText(sf),
+                    description: returnsDescription
+                }
+                : undefined
+        });
+    }
+}
+const BUILTIN_TYPE_NAMES = new Set([
+    'string',
+    'number',
+    'boolean',
+    'null',
+    'undefined',
+    'void',
+    'unknown',
+    'never',
+    'object',
+    'array',
+    'record',
+    'partial',
+    'readonly',
+    'required',
+    'pick',
+    'omit',
+    'exclude',
+    'extract',
+    'nonnullable',
+    'promise',
+    'map',
+    'set',
+    'weakmap',
+    'weakset',
+    'date',
+    'regexp',
+    'customEvent',
+    'event',
+    'htmlelement',
+    'element',
+    'window',
+    'document',
+    'any'
+]);
+function collectTypeRefsFromText(typeText, out) {
+    if (!typeText)
+        return;
+    const re = /\b[A-Za-z_]\w*\b/g;
+    let m;
+    while ((m = re.exec(typeText)) !== null) {
+        const token = m[0];
+        if (!token)
+            continue;
+        const lowered = token.toLowerCase();
+        if (BUILTIN_TYPE_NAMES.has(lowered))
+            continue;
+        if (token === token.toUpperCase())
+            continue; // likely TS keywords-like enums/constants
+        out.add(token);
+    }
+}
+/**
+ * Prefer the better human description when both CEM and JSDoc supply text.
+ * CEM summaries are often terse; JSDoc next to `@property` / `@event` is usually richer—use length + tie-break to AST.
+ */
+export function pickRicherDescription(cemDesc, astDesc) {
+    const c = cemDesc?.trim() ?? '';
+    const a = astDesc?.trim() ?? '';
+    if (!c)
+        return a || undefined;
+    if (!a)
+        return c || undefined;
+    if (a.length > c.length)
+        return a;
+    if (c.length > a.length)
+        return c;
+    return a;
+}
+/** Prefer the more specific / documented type (e.g. `CustomEvent<Foo>` over `Event` or empty). */
+export function pickRicherPropertyOrEventType(a, b) {
+    const x = a?.trim() ?? '';
+    const y = b?.trim() ?? '';
+    if (!x)
+        return y || undefined;
+    if (!y)
+        return x || undefined;
+    if (x === 'any' && y)
+        return y;
+    if (y === 'any' && x)
+        return x;
+    const score = (t) => {
+        let s = t.length;
+        if (t.includes('CustomEvent'))
+            s += 12;
+        if (t.includes('<') || t.includes('|') || t.includes('[]'))
+            s += 6;
+        return s;
+    };
+    return score(y) > score(x) ? y : x;
+}
+/**
+ * When CEM is the primary source, it often omits or weakly types `events` / `properties`,
+ * or carries shorter descriptions than JSDoc.
+ * Merge with the AST (JSDoc) list: union by `name`, richer type via {@link pickRicherPropertyOrEventType},
+ * richer description via {@link pickRicherDescription}, keep CEM order then append AST-only.
+ */
+export function mergeCemWithAstEventLists(cem, ast) {
+    return mergePropOrEventLikeLists(cem, ast);
+}
+export function mergeCemWithAstPropertyLists(cem, ast) {
+    return mergePropOrEventLikeLists(cem, ast);
+}
+function mergePropOrEventLikeLists(cem, ast) {
+    if (ast.length === 0)
+        return cem;
+    if (cem.length === 0)
+        return ast;
+    const mergedByName = new Map();
+    for (const e of cem) {
+        mergedByName.set(e.name, { ...e });
+    }
+    for (const e of ast) {
+        const prev = mergedByName.get(e.name);
+        if (!prev) {
+            mergedByName.set(e.name, { ...e });
+        }
+        else {
+            const t = pickRicherPropertyOrEventType(prev.type, e.type);
+            const description = pickRicherDescription(prev.description, e.description);
+            mergedByName.set(e.name, { name: e.name, type: t, description });
+        }
+    }
+    const cemNames = new Set(cem.map((c) => c.name));
+    const out = [];
+    for (const e of cem) {
+        out.push(mergedByName.get(e.name));
+    }
+    for (const e of ast) {
+        if (!cemNames.has(e.name)) {
+            out.push(mergedByName.get(e.name));
+        }
+    }
+    return out;
+}
+/** Merge slots or cssParts: union by `name`, enrich descriptions (same rules as props/events). */
+export function mergeCemWithAstSlotLikeLists(cem, ast) {
+    if (ast.length === 0)
+        return cem;
+    if (cem.length === 0)
+        return ast;
+    const mergedByName = new Map();
+    for (const e of cem) {
+        mergedByName.set(e.name, { ...e });
+    }
+    for (const e of ast) {
+        const prev = mergedByName.get(e.name);
+        if (!prev) {
+            mergedByName.set(e.name, { ...e });
+        }
+        else {
+            mergedByName.set(e.name, {
+                name: prev.name,
+                description: pickRicherDescription(prev.description, e.description)
+            });
+        }
+    }
+    const cemNames = new Set(cem.map((c) => c.name));
+    const out = [];
+    for (const e of cem) {
+        out.push(mergedByName.get(e.name));
+    }
+    for (const e of ast) {
+        if (!cemNames.has(e.name)) {
+            out.push(mergedByName.get(e.name));
+        }
+    }
+    return out;
+}
+/** Max bytes for echarts-option.ts when printing only the root `EChartsOption` interface for MCP. */
+const SKY_CHART_ECHARTS_OPTION_FILE_MAX_BYTES = 900_000;
+const TYPE_DECL_FILE_MAX_BYTES = 450_000;
+const TYPE_DECL_VISITED = new Set();
+function resolveRelativeImport(fromDir, spec) {
+    if (!spec.startsWith('.'))
+        return undefined;
+    const raw = join(fromDir, spec);
+    const candidates = [
+        raw,
+        `${raw}.ts`,
+        `${raw}.tsx`,
+        join(raw, 'index.ts'),
+        raw.replace(/\.js$/i, '.ts'),
+        raw.replace(/\.js$/i, '.tsx')
+    ];
+    for (const p of candidates) {
+        if (existsSync(p))
+            return p;
+    }
+    return undefined;
+}
+function readTypeSourceFile(path) {
+    if (TYPE_DECL_VISITED.has(path))
+        return undefined;
+    try {
+        const st = statSync(path);
+        if (st.size > TYPE_DECL_FILE_MAX_BYTES)
+            return undefined;
+    }
+    catch {
+        return undefined;
+    }
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    TYPE_DECL_VISITED.add(path);
+    return ts.createSourceFile(path, raw, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+}
+function indexTopLevelTypeDecls(sf, into) {
+    for (const stmt of sf.statements) {
+        if (ts.isTypeAliasDeclaration(stmt) || ts.isInterfaceDeclaration(stmt)) {
+            const name = stmt.name?.text;
+            if (name && !into.has(name))
+                into.set(name, { decl: stmt, sf });
+        }
+    }
+}
+function loadTypeDeclsFromFile(path, into) {
+    const sf = readTypeSourceFile(path);
+    if (!sf)
+        return;
+    indexTopLevelTypeDecls(sf, into);
+    const dir = dirname(sf.fileName);
+    for (const stmt of sf.statements) {
+        if (!ts.isExportDeclaration(stmt) || !stmt.moduleSpecifier || !ts.isStringLiteralLike(stmt.moduleSpecifier)) {
+            continue;
+        }
+        const resolved = resolveRelativeImport(dir, stmt.moduleSpecifier.text);
+        if (!resolved)
+            continue;
+        if (!stmt.exportClause) {
+            loadTypeDeclsFromFile(resolved, into);
+            continue;
+        }
+        if (!ts.isNamedExports(stmt.exportClause))
+            continue;
+        const remote = new Map();
+        loadTypeDeclsFromFile(resolved, remote);
+        for (const el of stmt.exportClause.elements) {
+            const exported = el.propertyName?.text ?? el.name.text;
+            const local = el.name.text;
+            const hit = remote.get(exported);
+            if (hit && !into.has(local))
+                into.set(local, hit);
+        }
+    }
+}
+/** Host file + type-only imports + `export type { … } from` re-exports. */
+function buildTypeDeclLookup(hostSf) {
+    TYPE_DECL_VISITED.clear();
+    const into = new Map();
+    indexTopLevelTypeDecls(hostSf, into);
+    const fromDir = dirname(hostSf.fileName);
+    for (const stmt of hostSf.statements) {
+        if (ts.isImportDeclaration(stmt) && stmt.moduleSpecifier && ts.isStringLiteralLike(stmt.moduleSpecifier)) {
+            const resolved = resolveRelativeImport(fromDir, stmt.moduleSpecifier.text);
+            if (!resolved)
+                continue;
+            const remote = new Map();
+            loadTypeDeclsFromFile(resolved, remote);
+            const bindings = stmt.importClause?.namedBindings;
+            if (!bindings || !ts.isNamedImports(bindings))
+                continue;
+            for (const el of bindings.elements) {
+                const exported = el.propertyName?.text ?? el.name.text;
+                const local = el.name.text;
+                const hit = remote.get(exported);
+                if (hit && !into.has(local))
+                    into.set(local, hit);
+            }
+        }
+        if (ts.isExportDeclaration(stmt) && stmt.exportClause && ts.isNamedExports(stmt.exportClause) && stmt.moduleSpecifier && ts.isStringLiteralLike(stmt.moduleSpecifier)) {
+            const resolved = resolveRelativeImport(fromDir, stmt.moduleSpecifier.text);
+            if (!resolved)
+                continue;
+            const remote = new Map();
+            loadTypeDeclsFromFile(resolved, remote);
+            for (const el of stmt.exportClause.elements) {
+                const exported = el.propertyName?.text ?? el.name.text;
+                const local = el.name.text;
+                const hit = remote.get(exported);
+                if (hit && !into.has(local))
+                    into.set(local, hit);
+            }
+        }
+    }
+    return into;
+}
+/**
+ * For `sky-chart`, append the **`EChartsOption`** root interface from sibling `echarts-option.ts`
+ * without expanding nested types (avoids multi‑MB type payloads while giving agents the top-level field list).
+ */
+function trySkyChartEChartsOptionRootOnly(doc, hostSf) {
+    if (doc.name !== 'sky-chart')
+        return undefined;
+    const optionPath = join(dirname(hostSf.fileName), 'echarts-option.ts');
+    if (!existsSync(optionPath))
+        return undefined;
+    try {
+        const st = statSync(optionPath);
+        if (st.size > SKY_CHART_ECHARTS_OPTION_FILE_MAX_BYTES)
+            return undefined;
+    }
+    catch {
+        return undefined;
+    }
+    let raw;
+    try {
+        raw = readFileSync(optionPath, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    const optSf = ts.createSourceFile(optionPath, raw, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    let decl;
+    for (const stmt of optSf.statements) {
+        if (ts.isInterfaceDeclaration(stmt) && stmt.name.text === 'EChartsOption') {
+            decl = stmt;
+            break;
+        }
+    }
+    if (!decl)
+        return undefined;
+    const printer = ts.createPrinter({ removeComments: false, newLine: ts.NewLineKind.LineFeed });
+    const definition = printer.printNode(ts.EmitHint.Unspecified, decl, optSf).trim();
+    return { name: 'EChartsOption', kind: 'interface', definition };
+}
+export function collectNamedTypeDefinitions(sf, doc) {
+    const echartsOptionRoot = trySkyChartEChartsOptionRootOnly(doc, sf);
+    const refs = new Set();
+    for (const p of doc.properties)
+        collectTypeRefsFromText(p.type, refs);
+    for (const e of doc.events)
+        collectTypeRefsFromText(e.type, refs);
+    for (const m of doc.methods) {
+        for (const p of m.params)
+            collectTypeRefsFromText(p.type, refs);
+        collectTypeRefsFromText(m.returns?.type, refs);
+    }
+    if (refs.size === 0 && !echartsOptionRoot)
+        return undefined;
+    const printer = ts.createPrinter({ removeComments: false, newLine: ts.NewLineKind.LineFeed });
+    const declByName = buildTypeDeclLookup(sf);
+    const out = [];
+    const visited = new Set();
+    const queue = [...refs];
+    while (queue.length) {
+        const name = queue.shift();
+        if (!name || visited.has(name))
+            continue;
+        visited.add(name);
+        const entry = declByName.get(name);
+        if (!entry)
+            continue;
+        const definition = printer.printNode(ts.EmitHint.Unspecified, entry.decl, entry.sf).trim();
+        out.push({
+            name,
+            kind: ts.isTypeAliasDeclaration(entry.decl) ? 'typeAlias' : 'interface',
+            definition
+        });
+        const nested = new Set();
+        collectTypeRefsFromText(definition, nested);
+        for (const token of nested) {
+            if (!visited.has(token) && declByName.has(token)) {
+                queue.push(token);
+            }
+        }
+    }
+    if (echartsOptionRoot && !out.some((r) => r.name === 'EChartsOption')) {
+        out.push(echartsOptionRoot);
+    }
+    if (out.length === 0)
+        return undefined;
+    return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+/**
+ * Parse a Lit core component `.ts` file and return structured documentation from JSDoc + `@customElement`.
+ */
+export function parseLitComponentDocumentation(sourceFilePath, sourceText, componentFolderName, npmImport, options) {
+    const maxEx = options?.maxCharsPerExample ?? 12_000;
+    const sf = ts.createSourceFile(sourceFilePath, sourceText, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const classNode = findPrimaryComponentClass(sf, componentFolderName);
+    if (!classNode) {
+        return { ok: false, error: 'No @customElement class declaration found in file.' };
+    }
+    const tagName = getCustomElementTagName(classNode, sf);
+    if (!tagName) {
+        return { ok: false, error: 'Could not read @customElement tag string.' };
+    }
+    const rawLead = sourceText.slice(classNode.getFullStart(), classNode.getStart(sf)).trim();
+    const doc = {
+        schemaVersion: 1,
+        name: componentFolderName,
+        tagName,
+        npmImport,
+        sourceFile: sourceFilePath,
+        className: classNode.name?.text,
+        slots: [],
+        properties: [],
+        cssParts: [],
+        events: [],
+        methods: [],
+        examples: [],
+        miscTags: [],
+        rawLeadTrivia: rawLead.length > 24_000 ? `${rawLead.slice(0, 24_000)}\n… [raw lead truncated]` : rawLead || undefined
+    };
+    collectFromTags(classNode, sf, doc);
+    collectPublicMethods(classNode, sf, doc);
+    const { examples, truncated } = trimExamples(doc.examples, maxEx);
+    doc.examples = examples;
+    doc.typeDefinitions = collectNamedTypeDefinitions(sf, doc);
+    return { ok: true, doc, truncated };
+}
+/** Lightweight summary for search (parses full file; reuse parseLitComponentDocumentation). */
+export function parseSummaryOnly(sourceFilePath, sourceText, componentFolderName) {
+    const r = parseLitComponentDocumentation(sourceFilePath, sourceText, componentFolderName);
+    return r.ok ? r.doc.summary ?? null : null;
+}
+//# sourceMappingURL=parse-component-ast.js.map