chore(docs): eslint migration + extractor updates
Migrate docs to eslint flat config (build-script console override); doc extractor points at configs/eslint.
This commit is contained in:
+420
-260
@@ -1,42 +1,73 @@
|
||||
/**
|
||||
* ts-morph based metadata extractor for @robonen/tools packages.
|
||||
*
|
||||
* Scans package source files, extracts JSDoc annotations and TypeScript signatures,
|
||||
* and produces a structured JSON metadata file consumed by the Nuxt docs site.
|
||||
* Each package declares a {@link PackageKind} so it can be documented in the way
|
||||
* that fits it best:
|
||||
* - `api` → scans source for exported functions / classes / types + JSDoc
|
||||
* - `components` → walks `.vue` parts and extracts per-part props / emits (anatomy)
|
||||
* - `guide` → collects co-located Markdown files into prose sections
|
||||
*
|
||||
* Produces a single structured JSON metadata file consumed by the Nuxt docs site.
|
||||
*/
|
||||
|
||||
import { resolve, relative, dirname } from 'node:path';
|
||||
import { existsSync, readFileSync } from 'node:fs';
|
||||
import { basename, dirname, relative, resolve } from 'node:path';
|
||||
import { existsSync, readFileSync, readdirSync } from 'node:fs';
|
||||
import { Project } from 'ts-morph';
|
||||
import type { SourceFile, FunctionDeclaration, ClassDeclaration, InterfaceDeclaration, TypeAliasDeclaration, JSDoc, JSDocTag, MethodDeclaration, PropertyDeclaration, PropertySignature } from 'ts-morph';
|
||||
import type { ClassDeclaration, FunctionDeclaration, InterfaceDeclaration, JSDoc, JSDocTag, MethodDeclaration, PropertyDeclaration, PropertySignature, SourceFile, TypeAliasDeclaration } from 'ts-morph';
|
||||
import type {
|
||||
DocsMetadata,
|
||||
PackageMeta,
|
||||
CategoryMeta,
|
||||
ComponentMeta,
|
||||
ComponentPartMeta,
|
||||
DocsMetadata,
|
||||
EmitMeta,
|
||||
GuideSection,
|
||||
ItemMeta,
|
||||
MethodMeta,
|
||||
PackageGroup,
|
||||
PackageKind,
|
||||
PackageMeta,
|
||||
ParamMeta,
|
||||
PropertyMeta,
|
||||
ReturnMeta,
|
||||
TypeParamMeta,
|
||||
MethodMeta,
|
||||
PropertyMeta,
|
||||
} from './types';
|
||||
|
||||
/** Repository root — docs/modules/extractor → three levels up */
|
||||
const ROOT = resolve(import.meta.dirname, '..', '..', '..');
|
||||
|
||||
/** Packages to document — relative paths from repo root */
|
||||
const PACKAGES: PackageConfig[] = [
|
||||
{ path: 'core/stdlib', slug: 'stdlib' },
|
||||
{ path: 'core/platform', slug: 'platform' },
|
||||
{ path: 'vue/toolkit', slug: 'vue' },
|
||||
{ path: 'configs/oxlint', slug: 'oxlint' },
|
||||
];
|
||||
|
||||
interface PackageConfig {
|
||||
/** Path relative to repo root */
|
||||
path: string;
|
||||
/** URL slug */
|
||||
slug: string;
|
||||
/** Presentation kind */
|
||||
kind: PackageKind;
|
||||
/** Sidebar group */
|
||||
group: PackageGroup;
|
||||
/** For `guide` kind: markdown sources relative to the package dir.
|
||||
* Supports exact files (`README.md`) and single-level globs (`rules/*.md`). */
|
||||
guideSources?: string[];
|
||||
}
|
||||
|
||||
/** Packages to document. */
|
||||
const PACKAGES: PackageConfig[] = [
|
||||
// ── core ──
|
||||
{ path: 'core/stdlib', slug: 'stdlib', kind: 'api', group: 'core' },
|
||||
{ path: 'core/platform', slug: 'platform', kind: 'api', group: 'core' },
|
||||
{ path: 'core/fetch', slug: 'fetch', kind: 'api', group: 'core' },
|
||||
{ path: 'core/encoding', slug: 'encoding', kind: 'api', group: 'core' },
|
||||
// ── vue ──
|
||||
{ path: 'vue/toolkit', slug: 'vue', kind: 'api', group: 'vue' },
|
||||
{ path: 'vue/editor', slug: 'editor', kind: 'api', group: 'vue' },
|
||||
{ path: 'vue/primitives', slug: 'primitives', kind: 'components', group: 'vue' },
|
||||
// ── configs ──
|
||||
{ path: 'configs/eslint', slug: 'eslint', kind: 'guide', group: 'configs', guideSources: ['README.md', 'rules/*.md'] },
|
||||
{ path: 'configs/tsconfig', slug: 'tsconfig', kind: 'guide', group: 'configs', guideSources: ['README.md'] },
|
||||
{ path: 'configs/tsdown', slug: 'tsdown', kind: 'guide', group: 'configs', guideSources: ['README.md'] },
|
||||
// ── infra ──
|
||||
{ path: 'infra/renovate', slug: 'renovate', kind: 'guide', group: 'infra', guideSources: ['README.md'] },
|
||||
];
|
||||
|
||||
// ── Helpers ────────────────────────────────────────────────────────────────
|
||||
|
||||
function toKebabCase(str: string): string {
|
||||
@@ -50,6 +81,14 @@ function slugify(name: string): string {
|
||||
return toKebabCase(name);
|
||||
}
|
||||
|
||||
function toPascalCase(slug: string): string {
|
||||
return slug
|
||||
.split(/[-_]/)
|
||||
.filter(Boolean)
|
||||
.map(s => s.charAt(0).toUpperCase() + s.slice(1))
|
||||
.join('');
|
||||
}
|
||||
|
||||
function getJsDocTags(jsdocs: JSDoc[]): JSDocTag[] {
|
||||
return jsdocs.flatMap(doc => doc.getTags());
|
||||
}
|
||||
@@ -62,11 +101,9 @@ function getTagValue(tags: JSDocTag[], tagName: string): string {
|
||||
}
|
||||
|
||||
function getDescription(jsdocs: JSDoc[], tags: JSDocTag[]): string {
|
||||
// Try @description tag first
|
||||
const descTag = getTagValue(tags, 'description');
|
||||
if (descTag) return descTag;
|
||||
|
||||
// Fall back to the main JSDoc comment text
|
||||
for (const doc of jsdocs) {
|
||||
const desc = doc.getDescription().trim();
|
||||
if (desc) return desc;
|
||||
@@ -80,7 +117,6 @@ function getExamples(tags: JSDocTag[]): string[] {
|
||||
.filter(t => t.getTagName() === 'example')
|
||||
.map((t) => {
|
||||
const text = t.getCommentText()?.trim() ?? '';
|
||||
// Strip surrounding ```ts ... ``` if present
|
||||
return text.replace(/^```(?:ts|typescript)?\n?/, '').replace(/\n?```$/, '').trim();
|
||||
})
|
||||
.filter(Boolean);
|
||||
@@ -96,16 +132,11 @@ function extractParams(tags: JSDocTag[], node: FunctionDeclaration | MethodDecla
|
||||
const optional = param.isOptional();
|
||||
const defaultValue = param.getInitializer()?.getText() ?? null;
|
||||
|
||||
// Find matching @param tag
|
||||
const paramTag = paramTags.find((t) => {
|
||||
const tagText = t.getText();
|
||||
return tagText.includes(name);
|
||||
});
|
||||
const paramTag = paramTags.find(t => t.getText().includes(name));
|
||||
|
||||
let description = '';
|
||||
if (paramTag) {
|
||||
const comment = paramTag.getCommentText() ?? '';
|
||||
// Remove leading {type} annotation and param name
|
||||
description = comment
|
||||
.replace(/^\{[^}]*\}\s*/, '')
|
||||
.replace(new RegExp(`^${name}\\s*[-–—]?\\s*`), '')
|
||||
@@ -121,8 +152,7 @@ function extractParams(tags: JSDocTag[], node: FunctionDeclaration | MethodDecla
|
||||
}
|
||||
|
||||
function extractTypeParams(node: FunctionDeclaration | ClassDeclaration | InterfaceDeclaration | TypeAliasDeclaration): TypeParamMeta[] {
|
||||
const typeParams = node.getTypeParameters();
|
||||
return typeParams.map(tp => ({
|
||||
return node.getTypeParameters().map(tp => ({
|
||||
name: tp.getName(),
|
||||
constraint: tp.getConstraint()?.getText() ?? null,
|
||||
default: tp.getDefault()?.getText() ?? null,
|
||||
@@ -143,20 +173,14 @@ function extractReturnMeta(tags: JSDocTag[], node: FunctionDeclaration | MethodD
|
||||
function extractMethodMeta(method: MethodDeclaration): MethodMeta {
|
||||
const jsdocs = method.getJsDocs();
|
||||
const tags = getJsDocTags(jsdocs);
|
||||
const name = method.getName();
|
||||
|
||||
// Simplified signature
|
||||
const signature = method.getText().split('{')[0]?.trim() ?? '';
|
||||
|
||||
const visibility = method.getScope() ?? 'public';
|
||||
|
||||
return {
|
||||
name,
|
||||
name: method.getName(),
|
||||
description: getDescription(jsdocs, tags),
|
||||
signatures: [signature],
|
||||
signatures: [method.getText().split('{')[0]?.trim() ?? ''],
|
||||
params: extractParams(tags, method),
|
||||
returns: extractReturnMeta(tags, method),
|
||||
visibility,
|
||||
visibility: method.getScope() ?? 'public',
|
||||
};
|
||||
}
|
||||
|
||||
@@ -175,50 +199,42 @@ function extractPropertyMeta(prop: PropertyDeclaration | PropertySignature): Pro
|
||||
}
|
||||
|
||||
function getSourceDir(itemPath: string): string {
|
||||
// Get the directory containing the item's index.ts
|
||||
return dirname(itemPath);
|
||||
}
|
||||
|
||||
function hasDemoFile(sourceFilePath: string): boolean {
|
||||
const dir = getSourceDir(sourceFilePath);
|
||||
return existsSync(resolve(dir, 'demo.vue'));
|
||||
return existsSync(resolve(getSourceDir(sourceFilePath), 'demo.vue'));
|
||||
}
|
||||
|
||||
function readDemoSource(sourceFilePath: string): string {
|
||||
const dir = getSourceDir(sourceFilePath);
|
||||
const demoPath = resolve(dir, 'demo.vue');
|
||||
const demoPath = resolve(getSourceDir(sourceFilePath), 'demo.vue');
|
||||
if (!existsSync(demoPath)) return '';
|
||||
return readFileSync(demoPath, 'utf-8');
|
||||
}
|
||||
|
||||
function hasTestFile(sourceFilePath: string): boolean {
|
||||
const dir = getSourceDir(sourceFilePath);
|
||||
return existsSync(resolve(dir, 'index.test.ts'));
|
||||
return existsSync(resolve(dir, 'index.test.ts')) || existsSync(resolve(dir, '__test__'));
|
||||
}
|
||||
|
||||
// ── Extraction ─────────────────────────────────────────────────────────────
|
||||
// ── API Extraction ───────────────────────────────────────────────────────────
|
||||
|
||||
function extractFunction(fn: FunctionDeclaration, sourceFilePath: string, entryPoint: string): ItemMeta | null {
|
||||
const name = fn.getName();
|
||||
if (!name) return null;
|
||||
|
||||
// Skip private/internal functions
|
||||
if (name.startsWith('_')) return null;
|
||||
if (!name || name.startsWith('_')) return null;
|
||||
|
||||
const jsdocs = fn.getJsDocs();
|
||||
const tags = getJsDocTags(jsdocs);
|
||||
const description = getDescription(jsdocs, tags);
|
||||
|
||||
// Get signature text without body
|
||||
const signatureText = fn.getOverloads().length > 0
|
||||
? fn.getOverloads().map(o => o.getText().trim())
|
||||
: [fn.getText().split('{')[0]?.trim() + '{ ... }'];
|
||||
: [`${fn.getText().split('{')[0]?.trim()}{ ... }`];
|
||||
|
||||
return {
|
||||
name,
|
||||
slug: slugify(name),
|
||||
kind: 'function',
|
||||
description,
|
||||
description: getDescription(jsdocs, tags),
|
||||
since: getTagValue(tags, 'since'),
|
||||
signatures: signatureText,
|
||||
params: extractParams(tags, fn),
|
||||
@@ -252,7 +268,6 @@ function extractClass(cls: ClassDeclaration, sourceFilePath: string, entryPoint:
|
||||
.filter(p => (p.getScope() ?? 'public') === 'public')
|
||||
.map(p => extractPropertyMeta(p));
|
||||
|
||||
// Also include get accessors as readonly properties
|
||||
const getters = cls.getGetAccessors()
|
||||
.filter(g => (g.getScope() ?? 'public') === 'public')
|
||||
.map(g => ({
|
||||
@@ -264,11 +279,8 @@ function extractClass(cls: ClassDeclaration, sourceFilePath: string, entryPoint:
|
||||
readonly: true,
|
||||
}));
|
||||
|
||||
// Build class signature
|
||||
const typeParams = cls.getTypeParameters();
|
||||
const typeParamStr = typeParams.length > 0
|
||||
? `<${typeParams.map(tp => tp.getText()).join(', ')}>`
|
||||
: '';
|
||||
const typeParamStr = typeParams.length > 0 ? `<${typeParams.map(tp => tp.getText()).join(', ')}>` : '';
|
||||
const extendsClause = cls.getExtends() ? ` extends ${cls.getExtends()!.getText()}` : '';
|
||||
const implementsClause = cls.getImplements().length > 0
|
||||
? ` implements ${cls.getImplements().map(i => i.getText()).join(', ')}`
|
||||
@@ -307,13 +319,9 @@ function extractInterface(iface: InterfaceDeclaration, sourceFilePath: string, e
|
||||
const properties = iface.getProperties().map(p => extractPropertyMeta(p));
|
||||
|
||||
const typeParams = iface.getTypeParameters();
|
||||
const typeParamStr = typeParams.length > 0
|
||||
? `<${typeParams.map(tp => tp.getText()).join(', ')}>`
|
||||
: '';
|
||||
const typeParamStr = typeParams.length > 0 ? `<${typeParams.map(tp => tp.getText()).join(', ')}>` : '';
|
||||
const extendsExprs = iface.getExtends();
|
||||
const extendsStr = extendsExprs.length > 0
|
||||
? ` extends ${extendsExprs.map(e => e.getText()).join(', ')}`
|
||||
: '';
|
||||
const extendsStr = extendsExprs.length > 0 ? ` extends ${extendsExprs.map(e => e.getText()).join(', ')}` : '';
|
||||
const signature = `interface ${name}${typeParamStr}${extendsStr}`;
|
||||
|
||||
return {
|
||||
@@ -345,15 +353,13 @@ function extractTypeAlias(typeAlias: TypeAliasDeclaration, sourceFilePath: strin
|
||||
const jsdocs = typeAlias.getJsDocs();
|
||||
const tags = getJsDocTags(jsdocs);
|
||||
|
||||
const signature = typeAlias.getText().trim();
|
||||
|
||||
return {
|
||||
name,
|
||||
slug: slugify(name),
|
||||
kind: 'type',
|
||||
description: getDescription(jsdocs, tags),
|
||||
since: getTagValue(tags, 'since'),
|
||||
signatures: [signature],
|
||||
signatures: [typeAlias.getText().trim()],
|
||||
params: [],
|
||||
returns: null,
|
||||
typeParams: extractTypeParams(typeAlias),
|
||||
@@ -369,34 +375,25 @@ function extractTypeAlias(typeAlias: TypeAliasDeclaration, sourceFilePath: strin
|
||||
};
|
||||
}
|
||||
|
||||
// ── Source Tree Walking ────────────────────────────────────────────────────
|
||||
|
||||
function collectExportedItems(
|
||||
sourceFile: SourceFile,
|
||||
entryPoint: string,
|
||||
visited: Set<string> = new Set(),
|
||||
): ItemMeta[] {
|
||||
function collectExportedItems(sourceFile: SourceFile, entryPoint: string, visited: Set<string> = new Set()): ItemMeta[] {
|
||||
const filePath = sourceFile.getFilePath();
|
||||
if (visited.has(filePath)) return [];
|
||||
visited.add(filePath);
|
||||
|
||||
const items: ItemMeta[] = [];
|
||||
|
||||
// Direct exports from this file
|
||||
for (const fn of sourceFile.getFunctions()) {
|
||||
if (!fn.isExported()) continue;
|
||||
|
||||
// Skip implementation signatures that have overloads
|
||||
const overloads = fn.getOverloads();
|
||||
if (overloads.length > 0) {
|
||||
// Use the first overload's doc for metadata, but collect all signatures
|
||||
const firstOverload = overloads[0]!;
|
||||
const jsdocs = firstOverload.getJsDocs();
|
||||
const tags = getJsDocTags(jsdocs);
|
||||
const name = fn.getName();
|
||||
if (!name || name.startsWith('_')) continue;
|
||||
|
||||
const item: ItemMeta = {
|
||||
items.push({
|
||||
name,
|
||||
slug: slugify(name),
|
||||
kind: 'function',
|
||||
@@ -415,8 +412,7 @@ function collectExportedItems(
|
||||
relatedTypes: [],
|
||||
sourcePath: relative(ROOT, filePath),
|
||||
entryPoint,
|
||||
};
|
||||
items.push(item);
|
||||
});
|
||||
}
|
||||
else {
|
||||
const item = extractFunction(fn, filePath, entryPoint);
|
||||
@@ -432,11 +428,9 @@ function collectExportedItems(
|
||||
|
||||
for (const iface of sourceFile.getInterfaces()) {
|
||||
if (!iface.isExported()) continue;
|
||||
// Skip internal interfaces (e.g. Options, Return types that are documented inline)
|
||||
const jsdocs = iface.getJsDocs();
|
||||
const tags = getJsDocTags(jsdocs);
|
||||
const hasCategory = getTagValue(tags, 'category') !== '';
|
||||
// Only include interfaces with @category or that have significant documentation
|
||||
if (!hasCategory && jsdocs.length === 0) continue;
|
||||
const item = extractInterface(iface, filePath, entryPoint);
|
||||
if (item) items.push(item);
|
||||
@@ -452,73 +446,344 @@ function collectExportedItems(
|
||||
if (item) items.push(item);
|
||||
}
|
||||
|
||||
// Follow barrel re-exports: export * from './...'
|
||||
for (const exportDecl of sourceFile.getExportDeclarations()) {
|
||||
const moduleSpecifier = exportDecl.getModuleSpecifierValue();
|
||||
if (!moduleSpecifier) continue;
|
||||
|
||||
if (!exportDecl.getModuleSpecifierValue()) continue;
|
||||
const referencedFile = exportDecl.getModuleSpecifierSourceFile();
|
||||
if (referencedFile) {
|
||||
items.push(...collectExportedItems(referencedFile, entryPoint, visited));
|
||||
}
|
||||
if (referencedFile) items.push(...collectExportedItems(referencedFile, entryPoint, visited));
|
||||
}
|
||||
|
||||
return items;
|
||||
}
|
||||
|
||||
// ── Co-located Type Grouping ───────────────────────────────────────────────
|
||||
|
||||
/**
|
||||
* Groups types/interfaces from `types.ts` files with their sibling
|
||||
* class/function items from the same directory.
|
||||
*
|
||||
* For example, Transition and TransitionConfig from StateMachine/types.ts
|
||||
* get attached as relatedTypes of StateMachine and AsyncStateMachine.
|
||||
* class/function items from the same directory as `relatedTypes`.
|
||||
*/
|
||||
function groupCoLocatedTypes(items: ItemMeta[]): ItemMeta[] {
|
||||
// Build a map: directory → items from types.ts
|
||||
const typesByDir = new Map<string, ItemMeta[]>();
|
||||
// Build a map: directory → primary items (classes, functions)
|
||||
const primaryByDir = new Map<string, ItemMeta[]>();
|
||||
|
||||
for (const item of items) {
|
||||
const dir = dirname(item.sourcePath);
|
||||
const isTypesFile = item.sourcePath.endsWith('/types.ts');
|
||||
const isSecondary = isTypesFile && (item.kind === 'type' || item.kind === 'interface');
|
||||
const isSecondary = item.sourcePath.endsWith('/types.ts') && (item.kind === 'type' || item.kind === 'interface');
|
||||
|
||||
if (isSecondary) {
|
||||
const existing = typesByDir.get(dir) ?? [];
|
||||
existing.push(item);
|
||||
typesByDir.set(dir, existing);
|
||||
}
|
||||
else {
|
||||
const existing = primaryByDir.get(dir) ?? [];
|
||||
existing.push(item);
|
||||
primaryByDir.set(dir, existing);
|
||||
}
|
||||
const target = isSecondary ? typesByDir : primaryByDir;
|
||||
const existing = target.get(dir) ?? [];
|
||||
existing.push(item);
|
||||
target.set(dir, existing);
|
||||
}
|
||||
|
||||
// Attach co-located types to their primary items
|
||||
const absorbed = new Set<string>();
|
||||
for (const entry of Array.from(typesByDir.entries())) {
|
||||
const [dir, types] = entry;
|
||||
for (const [dir, types] of Array.from(typesByDir.entries())) {
|
||||
const primaries = primaryByDir.get(dir);
|
||||
if (!primaries || primaries.length === 0) continue;
|
||||
|
||||
// Distribute types to all primary items in the same directory
|
||||
for (const primary of primaries) {
|
||||
primary.relatedTypes = [...types];
|
||||
}
|
||||
for (const t of types) {
|
||||
absorbed.add(`${t.entryPoint}:${t.name}`);
|
||||
}
|
||||
for (const primary of primaries) primary.relatedTypes = [...types];
|
||||
for (const t of types) absorbed.add(`${t.entryPoint}:${t.name}`);
|
||||
}
|
||||
|
||||
// Return items without the absorbed types
|
||||
return items.filter(item => !absorbed.has(`${item.entryPoint}:${item.name}`));
|
||||
}
|
||||
|
||||
// ── Package Extraction ─────────────────────────────────────────────────────
|
||||
function inferCategoryFromItem(item: ItemMeta): string {
|
||||
const parts = item.sourcePath.split('/src/');
|
||||
if (parts.length < 2) return 'General';
|
||||
|
||||
const segments = parts[1]!.split('/');
|
||||
|
||||
if (segments[0] === 'composables' && segments.length >= 3) {
|
||||
const cat = segments[1]!;
|
||||
return cat.charAt(0).toUpperCase() + cat.slice(1);
|
||||
}
|
||||
if (segments[0] && segments.length >= 2) {
|
||||
const cat = segments[0];
|
||||
return cat.charAt(0).toUpperCase() + cat.slice(1);
|
||||
}
|
||||
return 'General';
|
||||
}
|
||||
|
||||
/** Resolve a package's export subpaths to source entry files. */
|
||||
function resolveEntryPoints(pkgDir: string, exportsField: Record<string, any>): Array<{ subpath: string; filePath: string }> {
|
||||
const entryPoints: Array<{ subpath: string; filePath: string }> = [];
|
||||
|
||||
for (const [subpath, value] of Object.entries(exportsField)) {
|
||||
if (typeof value !== 'object' || value === null) continue;
|
||||
|
||||
let entry: any = (value as Record<string, any>).import ?? (value as Record<string, any>).types;
|
||||
if (typeof entry === 'object' && entry !== null) entry = entry.types || entry.default;
|
||||
if (!entry || typeof entry !== 'string') continue;
|
||||
// Wildcard exports (e.g. "./*") can't be resolved to a single file here.
|
||||
if (entry.includes('*')) continue;
|
||||
|
||||
const srcPath = entry
|
||||
.replace(/^\.\/dist\//, 'src/')
|
||||
.replace(/\.m?js$/, '.ts')
|
||||
.replace(/\.d\.m?ts$/, '.ts');
|
||||
|
||||
const fullPath = resolve(pkgDir, srcPath);
|
||||
if (existsSync(fullPath)) {
|
||||
entryPoints.push({ subpath, filePath: fullPath });
|
||||
}
|
||||
else {
|
||||
const altPath = resolve(pkgDir, srcPath.replace(/\.ts$/, '/index.ts'));
|
||||
if (existsSync(altPath)) entryPoints.push({ subpath, filePath: altPath });
|
||||
}
|
||||
}
|
||||
|
||||
// Fallback: a conventional src/index.ts entry.
|
||||
if (entryPoints.length === 0) {
|
||||
const idx = resolve(pkgDir, 'src/index.ts');
|
||||
if (existsSync(idx)) entryPoints.push({ subpath: '.', filePath: idx });
|
||||
}
|
||||
|
||||
return entryPoints;
|
||||
}
|
||||
|
||||
function buildApiCategories(pkgDir: string): CategoryMeta[] {
|
||||
const pkgJson = JSON.parse(readFileSync(resolve(pkgDir, 'package.json'), 'utf-8'));
|
||||
const entryPoints = resolveEntryPoints(pkgDir, pkgJson.exports ?? {});
|
||||
if (entryPoints.length === 0) return [];
|
||||
|
||||
const tsconfigPath = resolve(pkgDir, 'tsconfig.json');
|
||||
const project = new Project({
|
||||
tsConfigFilePath: existsSync(tsconfigPath) ? tsconfigPath : undefined,
|
||||
skipAddingFilesFromTsConfig: true,
|
||||
});
|
||||
|
||||
for (const ep of entryPoints) project.addSourceFileAtPath(ep.filePath);
|
||||
project.resolveSourceFileDependencies();
|
||||
|
||||
const allItems: ItemMeta[] = [];
|
||||
for (const ep of entryPoints) {
|
||||
const sourceFile = project.getSourceFile(ep.filePath);
|
||||
if (!sourceFile) continue;
|
||||
allItems.push(...collectExportedItems(sourceFile, ep.subpath));
|
||||
}
|
||||
|
||||
const seen = new Set<string>();
|
||||
const uniqueItems = allItems.filter((item) => {
|
||||
const key = `${item.entryPoint}:${item.name}`;
|
||||
if (seen.has(key)) return false;
|
||||
seen.add(key);
|
||||
return true;
|
||||
});
|
||||
|
||||
const groupedItems = groupCoLocatedTypes(uniqueItems);
|
||||
|
||||
const categoryMap = new Map<string, ItemMeta[]>();
|
||||
for (const item of groupedItems) {
|
||||
const cat = inferCategoryFromItem(item);
|
||||
const existing = categoryMap.get(cat) ?? [];
|
||||
existing.push(item);
|
||||
categoryMap.set(cat, existing);
|
||||
}
|
||||
|
||||
return Array.from(categoryMap.entries())
|
||||
.map(([name, items]) => ({
|
||||
name,
|
||||
slug: slugify(name),
|
||||
items: items.sort((a, b) => a.name.localeCompare(b.name)),
|
||||
}))
|
||||
.sort((a, b) => a.name.localeCompare(b.name));
|
||||
}
|
||||
|
||||
// ── Component Extraction ───────────────────────────────────────────────────────
|
||||
|
||||
/** Pull a named `<script>` block's inner content out of an SFC string. */
|
||||
function extractScriptBlock(sfc: string, setup: boolean): string {
|
||||
// Match <script ... lang="ts"> ... </script>; distinguish setup vs plain.
|
||||
const re = /<script\b([^>]*)>([\s\S]*?)<\/script>/g;
|
||||
let match: RegExpExecArray | null;
|
||||
while ((match = re.exec(sfc)) !== null) {
|
||||
const attrs = match[1] ?? '';
|
||||
const isSetup = /\bsetup\b/.test(attrs);
|
||||
if (isSetup === setup) return match[2] ?? '';
|
||||
}
|
||||
return '';
|
||||
}
|
||||
|
||||
/** Parse `defineEmits<{ 'a': [x: T]; b: [] }>()` from a setup block. */
|
||||
function extractEmits(setupScript: string): EmitMeta[] {
|
||||
const m = setupScript.match(/defineEmits<\{([\s\S]*?)\}>\s*\(\s*\)/);
|
||||
if (!m) return [];
|
||||
const body = m[1] ?? '';
|
||||
const emits: EmitMeta[] = [];
|
||||
// Split on ; or newlines, then match `name: [payload]`
|
||||
for (const raw of body.split(/[;\n]/)) {
|
||||
const line = raw.trim();
|
||||
if (!line) continue;
|
||||
const em = line.match(/^['"]?([\w:-]+)['"]?\s*:\s*(\[[\s\S]*\])\s*$/);
|
||||
if (em) emits.push({ name: em[1]!, payload: em[2]!, description: '' });
|
||||
}
|
||||
return emits;
|
||||
}
|
||||
|
||||
let partProjectCounter = 0;
|
||||
|
||||
/** Parse the `XxxProps` interface from a `.vue` part using ts-morph in-memory. */
|
||||
function extractPartProps(plainScript: string): { props: PropertyMeta[]; description: string } {
|
||||
if (!plainScript.trim()) return { props: [], description: '' };
|
||||
|
||||
// Strip imports — types they reference are unresolved here, which is fine:
|
||||
// getText() on property type nodes still yields the written type text.
|
||||
const project = new Project({ useInMemoryFileSystem: true, skipAddingFilesFromTsConfig: true, compilerOptions: { allowJs: true, skipLibCheck: true } });
|
||||
const sf = project.createSourceFile(`__part_${partProjectCounter++}.ts`, plainScript);
|
||||
|
||||
const propsIface = sf.getInterfaces().find(i => i.getName().endsWith('Props'));
|
||||
if (!propsIface) return { props: [], description: '' };
|
||||
|
||||
const jsdocs = propsIface.getJsDocs();
|
||||
const description = getDescription(jsdocs, getJsDocTags(jsdocs));
|
||||
|
||||
const props = propsIface.getProperties().map((p) => {
|
||||
const pj = p.getJsDocs();
|
||||
const ptags = getJsDocTags(pj);
|
||||
return {
|
||||
name: p.getName(),
|
||||
// Use the written type text (declared), not the resolved type.
|
||||
type: p.getTypeNode()?.getText() ?? p.getType().getText(p),
|
||||
description: getDescription(pj, ptags),
|
||||
optional: p.hasQuestionToken(),
|
||||
defaultValue: getTagValue(ptags, 'default') || null,
|
||||
readonly: p.isReadonly(),
|
||||
} satisfies PropertyMeta;
|
||||
});
|
||||
|
||||
return { props, description };
|
||||
}
|
||||
|
||||
/** Read default-export component names from an index.ts barrel, in source order. */
|
||||
function readPartOrder(indexPath: string): string[] {
|
||||
if (!existsSync(indexPath)) return [];
|
||||
const src = readFileSync(indexPath, 'utf-8');
|
||||
const order: string[] = [];
|
||||
const re = /export\s*\{\s*default\s+as\s+(\w+)\s*\}\s*from\s*['"]\.\/([\w.-]+)\.vue['"]/g;
|
||||
let m: RegExpExecArray | null;
|
||||
while ((m = re.exec(src)) !== null) order.push(m[1]!);
|
||||
return order;
|
||||
}
|
||||
|
||||
function roleFromName(componentName: string, base: string): string {
|
||||
// AccordionRoot + base "Accordion" → "Root"; AccordionItem → "Item"
|
||||
let role = componentName;
|
||||
if (componentName.startsWith(base)) role = componentName.slice(base.length);
|
||||
return role || 'Root';
|
||||
}
|
||||
|
||||
function buildComponents(pkgDir: string): ComponentMeta[] {
|
||||
const srcDir = resolve(pkgDir, 'src');
|
||||
if (!existsSync(srcDir)) return [];
|
||||
|
||||
const components: ComponentMeta[] = [];
|
||||
|
||||
for (const entry of readdirSync(srcDir, { withFileTypes: true })) {
|
||||
if (!entry.isDirectory()) continue;
|
||||
const dir = resolve(srcDir, entry.name);
|
||||
|
||||
// A component group is any dir that ships at least one .vue file.
|
||||
const vueFiles = readdirSync(dir).filter(f => f.endsWith('.vue'));
|
||||
if (vueFiles.length === 0) continue;
|
||||
|
||||
const slug = entry.name;
|
||||
const base = toPascalCase(slug);
|
||||
|
||||
// Preserve the anatomy order declared in index.ts; fall back to filenames.
|
||||
const order = readPartOrder(resolve(dir, 'index.ts'));
|
||||
const orderedFiles = [
|
||||
...order.map(name => `${name}.vue`).filter(f => vueFiles.includes(f)),
|
||||
...vueFiles.filter(f => !order.includes(f.replace(/\.vue$/, ''))),
|
||||
];
|
||||
|
||||
const parts: ComponentPartMeta[] = [];
|
||||
let groupDescription = '';
|
||||
|
||||
for (const file of orderedFiles) {
|
||||
const sfc = readFileSync(resolve(dir, file), 'utf-8');
|
||||
const plain = extractScriptBlock(sfc, false);
|
||||
const setup = extractScriptBlock(sfc, true);
|
||||
const { props, description } = extractPartProps(plain);
|
||||
const name = file.replace(/\.vue$/, '');
|
||||
const role = roleFromName(name, base);
|
||||
if (role === 'Root' && description && !groupDescription) groupDescription = description;
|
||||
parts.push({ name, role, description, props, emits: extractEmits(setup) });
|
||||
}
|
||||
|
||||
const entryPoint = `./${slug}`;
|
||||
const demoPath = resolve(dir, 'demo.vue');
|
||||
const hasDemo = existsSync(demoPath);
|
||||
|
||||
components.push({
|
||||
name: base,
|
||||
slug,
|
||||
description: groupDescription,
|
||||
entryPoint,
|
||||
parts,
|
||||
hasDemo,
|
||||
demoSource: hasDemo ? readFileSync(demoPath, 'utf-8') : '',
|
||||
sourcePath: relative(ROOT, dir),
|
||||
});
|
||||
}
|
||||
|
||||
return components.sort((a, b) => a.name.localeCompare(b.name));
|
||||
}
|
||||
|
||||
// ── Guide Extraction ───────────────────────────────────────────────────────────
|
||||
|
||||
/** Resolve guide source patterns (exact files + single-level `dir/*.md`). */
|
||||
function resolveGuideFiles(pkgDir: string, patterns: string[]): string[] {
|
||||
const files: string[] = [];
|
||||
for (const pattern of patterns) {
|
||||
if (pattern.includes('*')) {
|
||||
const dir = resolve(pkgDir, dirname(pattern));
|
||||
if (!existsSync(dir)) continue;
|
||||
const ext = pattern.slice(pattern.lastIndexOf('.'));
|
||||
const matched = readdirSync(dir)
|
||||
.filter(f => f.endsWith(ext) && f.toLowerCase() !== 'readme.md')
|
||||
.sort()
|
||||
.map(f => resolve(dir, f));
|
||||
files.push(...matched);
|
||||
}
|
||||
else {
|
||||
const full = resolve(pkgDir, pattern);
|
||||
if (existsSync(full)) files.push(full);
|
||||
}
|
||||
}
|
||||
return files;
|
||||
}
|
||||
|
||||
function titleFromMarkdown(md: string, fallback: string): string {
|
||||
const m = md.match(/^\s*#\s+(.+)$/m);
|
||||
return m ? m[1]!.trim() : fallback;
|
||||
}
|
||||
|
||||
function buildGuideSections(pkgDir: string, patterns: string[], pkgDescription: string): GuideSection[] {
|
||||
const files = resolveGuideFiles(pkgDir, patterns);
|
||||
const sections: GuideSection[] = [];
|
||||
|
||||
for (const file of files) {
|
||||
const markdown = readFileSync(file, 'utf-8');
|
||||
const fileSlug = basename(file).replace(/\.md$/i, '');
|
||||
const slug = /readme/i.test(fileSlug) ? 'overview' : slugify(fileSlug);
|
||||
const fallbackTitle = slug === 'overview' ? 'Overview' : fileSlug;
|
||||
sections.push({ title: titleFromMarkdown(markdown, fallbackTitle), slug, markdown });
|
||||
}
|
||||
|
||||
// Ensure an overview exists even when there's no README.
|
||||
if (!sections.some(s => s.slug === 'overview')) {
|
||||
sections.unshift({
|
||||
title: 'Overview',
|
||||
slug: 'overview',
|
||||
markdown: `# Overview\n\n${pkgDescription || 'Documentation for this package.'}\n`,
|
||||
});
|
||||
}
|
||||
else {
|
||||
// Move overview to the front.
|
||||
sections.sort((a, b) => (a.slug === 'overview' ? -1 : b.slug === 'overview' ? 1 : 0));
|
||||
}
|
||||
|
||||
return sections;
|
||||
}
|
||||
|
||||
// ── Package Extraction ─────────────────────────────────────────────────────────
|
||||
|
||||
function extractPackage(config: PackageConfig): PackageMeta | null {
|
||||
const pkgDir = resolve(ROOT, config.path);
|
||||
@@ -530,136 +795,31 @@ function extractPackage(config: PackageConfig): PackageMeta | null {
|
||||
}
|
||||
|
||||
const pkgJson = JSON.parse(readFileSync(pkgJsonPath, 'utf-8'));
|
||||
const exports = pkgJson.exports ?? {};
|
||||
|
||||
// Determine entry points
|
||||
const entryPoints: Array<{ subpath: string; filePath: string }> = [];
|
||||
|
||||
for (const [subpath, value] of Object.entries(exports)) {
|
||||
if (typeof value === 'object' && value !== null) {
|
||||
const entry = (value as Record<string, string>).import ?? (value as Record<string, string>).types;
|
||||
if (entry) {
|
||||
// Map dist path back to source path
|
||||
// e.g. "./dist/index.js" → "src/index.ts" or "./dist/browsers.js" → "src/browsers/index.ts"
|
||||
const srcPath = entry
|
||||
.replace(/^\.\/dist\//, 'src/')
|
||||
.replace(/\.js$/, '.ts')
|
||||
.replace(/\.d\.ts$/, '.ts');
|
||||
|
||||
const fullPath = resolve(pkgDir, srcPath);
|
||||
if (existsSync(fullPath)) {
|
||||
entryPoints.push({ subpath, filePath: fullPath });
|
||||
}
|
||||
else {
|
||||
// Try index.ts in subdirectory
|
||||
const altPath = resolve(pkgDir, srcPath.replace(/\.ts$/, '/index.ts'));
|
||||
if (existsSync(altPath)) {
|
||||
entryPoints.push({ subpath, filePath: altPath });
|
||||
}
|
||||
else {
|
||||
console.warn(`[extractor] Entry point not found: ${fullPath} or ${altPath}`);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
if (entryPoints.length === 0) {
|
||||
console.warn(`[extractor] No entry points found for ${pkgJson.name}`);
|
||||
return null;
|
||||
}
|
||||
|
||||
// Create ts-morph project for this package
|
||||
const tsconfigPath = resolve(pkgDir, 'tsconfig.json');
|
||||
const project = new Project({
|
||||
tsConfigFilePath: existsSync(tsconfigPath) ? tsconfigPath : undefined,
|
||||
skipAddingFilesFromTsConfig: true,
|
||||
});
|
||||
|
||||
// Add entry files
|
||||
for (const ep of entryPoints) {
|
||||
project.addSourceFileAtPath(ep.filePath);
|
||||
}
|
||||
|
||||
// Resolve all referenced files
|
||||
project.resolveSourceFileDependencies();
|
||||
|
||||
// Extract items from all entry points
|
||||
const allItems: ItemMeta[] = [];
|
||||
for (const ep of entryPoints) {
|
||||
const sourceFile = project.getSourceFile(ep.filePath);
|
||||
if (!sourceFile) continue;
|
||||
const items = collectExportedItems(sourceFile, ep.subpath);
|
||||
allItems.push(...items);
|
||||
}
|
||||
|
||||
// Deduplicate by name (overloaded functions may appear once already)
|
||||
const seen = new Set<string>();
|
||||
const uniqueItems = allItems.filter((item) => {
|
||||
const key = `${item.entryPoint}:${item.name}`;
|
||||
if (seen.has(key)) return false;
|
||||
seen.add(key);
|
||||
return true;
|
||||
});
|
||||
|
||||
// Group co-located types with their parent class/function.
|
||||
// Types/interfaces from a types.ts file in the same directory as a
|
||||
// class or function become relatedTypes of that primary item.
|
||||
const groupedItems = groupCoLocatedTypes(uniqueItems);
|
||||
|
||||
// Group by category
|
||||
const categoryMap = new Map<string, ItemMeta[]>();
|
||||
for (const item of groupedItems) {
|
||||
// Infer category from source path if not set
|
||||
const jsdocCategory = inferCategoryFromItem(item);
|
||||
const existing = categoryMap.get(jsdocCategory) ?? [];
|
||||
existing.push(item);
|
||||
categoryMap.set(jsdocCategory, existing);
|
||||
}
|
||||
|
||||
const categories: CategoryMeta[] = Array.from(categoryMap.entries())
|
||||
.map(([name, items]) => ({
|
||||
name,
|
||||
slug: slugify(name),
|
||||
items: items.sort((a, b) => a.name.localeCompare(b.name)),
|
||||
}))
|
||||
.sort((a, b) => a.name.localeCompare(b.name));
|
||||
|
||||
return {
|
||||
const base: PackageMeta = {
|
||||
name: pkgJson.name,
|
||||
version: pkgJson.version,
|
||||
description: pkgJson.description ?? '',
|
||||
slug: config.slug,
|
||||
entryPoints: entryPoints.map(ep => ep.subpath),
|
||||
categories,
|
||||
kind: config.kind,
|
||||
group: config.group,
|
||||
entryPoints: Object.keys(pkgJson.exports ?? { '.': {} }),
|
||||
categories: [],
|
||||
components: [],
|
||||
sections: [],
|
||||
};
|
||||
}
|
||||
|
||||
function inferCategoryFromItem(item: ItemMeta): string {
|
||||
// Parse from source path
|
||||
const parts = item.sourcePath.split('/src/');
|
||||
if (parts.length < 2) return 'General';
|
||||
|
||||
const segments = parts[1]!.split('/');
|
||||
|
||||
// Patterns:
|
||||
// composables/browser/useIntervalFn/index.ts → "Browser"
|
||||
// arrays/cluster/index.ts → "Arrays"
|
||||
// patterns/behavioral/PubSub/index.ts → "Patterns"
|
||||
// types/js/primitives.ts → "Types"
|
||||
// structs/Stack/index.ts → "Data Structures" (use @category if available)
|
||||
|
||||
if (segments[0] === 'composables' && segments.length >= 3) {
|
||||
const cat = segments[1]!;
|
||||
return cat.charAt(0).toUpperCase() + cat.slice(1);
|
||||
if (config.kind === 'api') {
|
||||
base.categories = buildApiCategories(pkgDir);
|
||||
}
|
||||
else if (config.kind === 'components') {
|
||||
base.components = buildComponents(pkgDir);
|
||||
}
|
||||
else if (config.kind === 'guide') {
|
||||
base.sections = buildGuideSections(pkgDir, config.guideSources ?? ['README.md'], base.description);
|
||||
}
|
||||
|
||||
if (segments[0] && segments.length >= 2) {
|
||||
const cat = segments[0];
|
||||
return cat.charAt(0).toUpperCase() + cat.slice(1);
|
||||
}
|
||||
|
||||
return 'General';
|
||||
return base;
|
||||
}
|
||||
|
||||
// ── Main ───────────────────────────────────────────────────────────────────
|
||||
@@ -670,31 +830,31 @@ export function extract(): DocsMetadata {
|
||||
const packages: PackageMeta[] = [];
|
||||
|
||||
for (const config of PACKAGES) {
|
||||
console.log(`[extractor] Processing ${config.path}...`);
|
||||
const pkg = extractPackage(config);
|
||||
if (pkg) {
|
||||
const itemCount = pkg.categories.reduce((sum, c) => sum + c.items.length, 0);
|
||||
console.log(`[extractor] → ${pkg.name}@${pkg.version}: ${itemCount} items in ${pkg.categories.length} categories`);
|
||||
packages.push(pkg);
|
||||
if (!pkg) continue;
|
||||
|
||||
let summary: string;
|
||||
if (pkg.kind === 'api') {
|
||||
const itemCount = pkg.categories.reduce((s, c) => s + c.items.length, 0);
|
||||
summary = `${itemCount} items / ${pkg.categories.length} categories`;
|
||||
}
|
||||
else if (pkg.kind === 'components') {
|
||||
const partCount = pkg.components.reduce((s, c) => s + c.parts.length, 0);
|
||||
summary = `${pkg.components.length} components / ${partCount} parts`;
|
||||
}
|
||||
else {
|
||||
summary = `${pkg.sections.length} sections`;
|
||||
}
|
||||
console.log(`[extractor] → ${pkg.name}@${pkg.version} [${pkg.kind}]: ${summary}`);
|
||||
packages.push(pkg);
|
||||
}
|
||||
|
||||
const metadata: DocsMetadata = {
|
||||
packages,
|
||||
generatedAt: new Date().toISOString(),
|
||||
};
|
||||
console.log(`[extractor] Done — ${packages.length} packages`);
|
||||
|
||||
const totalItems = packages.reduce(
|
||||
(sum, pkg) => sum + pkg.categories.reduce((s, c) => s + c.items.length, 0),
|
||||
0,
|
||||
);
|
||||
console.log(`[extractor] Done — ${totalItems} items across ${packages.length} packages`);
|
||||
|
||||
return metadata;
|
||||
return { packages, generatedAt: new Date().toISOString() };
|
||||
}
|
||||
|
||||
// Allow running directly — prints metadata as JSON to stdout
|
||||
if (import.meta.filename === process.argv[1]) {
|
||||
const metadata = extract();
|
||||
console.log(JSON.stringify(metadata, null, 2));
|
||||
console.log(JSON.stringify(extract(), null, 2));
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user