@lynx-js/genui 0.0.1-rc.0

package/a2ui-catalog-extractor/dist/cli.js

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+// Copyright 2026 The Lynx Authors. All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+import * as fs from 'node:fs';
+import { createRequire } from 'node:module';
+import * as path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { extractCatalogComponentsFromTypeDocJson, extractCatalogFunctionsFromTypeDocJson, findCatalogSourceFiles, writeCatalogArtifacts, writeCatalogComponents, writeCatalogFunctions, } from './index.js';
+const usage = `Usage: a2ui-catalog-extractor [options]
+
+Options:
+  --catalog-dir <dir>  Directory to scan for TypeScript catalog interfaces.
+  --source <path>      Source file or directory to scan. Repeatable.
+  --typedoc-json <file>
+                       Read an existing TypeDoc JSON project instead of
+                       running TypeDoc conversion.
+  --out-dir <dir>      Output directory for component catalog.json files.
+  --version            Print the package version.
+  --help               Print this help message.
+
+Defaults:
+  --catalog-dir src/catalog
+  --out-dir dist/catalog
+`;
+export function parseCliArgs(args) {
+    const options = {
+        catalogDirs: [],
+        help: false,
+        outDir: 'dist/catalog',
+        sourceInputs: [],
+        version: false,
+    };
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        switch (arg) {
+            case 'catalog-extractor':
+                break;
+            case '--catalog-dir':
+                options.catalogDirs.push(readValue(args, ++index, arg));
+                break;
+            case '--source':
+                options.sourceInputs.push(readValue(args, ++index, arg));
+                break;
+            case '--typedoc-json':
+                options.typedocJson = readValue(args, ++index, arg);
+                break;
+            case '--out-dir':
+                options.outDir = readValue(args, ++index, arg);
+                break;
+            case '--help':
+            case '-h':
+                options.help = true;
+                break;
+            case '--version':
+            case '-v':
+                options.version = true;
+                break;
+            default:
+                throw new Error(`Unknown option: ${arg}`);
+        }
+    }
+    return options;
+}
+export async function runCli(args, cwd = process.cwd()) {
+    const options = parseCliArgs(args);
+    if (options.help) {
+        console.info(usage);
+        return 0;
+    }
+    if (options.version) {
+        const require = createRequire(import.meta.url);
+        const packageJson = require('../package.json');
+        console.info(packageJson.version);
+        return 0;
+    }
+    if (options.typedocJson) {
+        const typedocJsonPath = path.resolve(cwd, options.typedocJson);
+        const project = JSON.parse(fs.readFileSync(typedocJsonPath, 'utf8'));
+        const components = extractCatalogComponentsFromTypeDocJson(project, {
+            cwd,
+        });
+        const functions = extractCatalogFunctionsFromTypeDocJson(project, {
+            cwd,
+        });
+        writeCatalogComponents(components, {
+            cwd,
+            outDir: options.outDir,
+        });
+        writeCatalogFunctions(functions, {
+            cwd,
+            outDir: options.outDir,
+        });
+        printGeneratedComponents(components);
+        printGeneratedFunctions(functions);
+        return 0;
+    }
+    const configuredInputs = [
+        ...options.sourceInputs,
+        ...options.catalogDirs,
+    ];
+    const inputs = configuredInputs.length > 0
+        ? configuredInputs
+        : ['src/catalog'];
+    const sourceFiles = inputs.flatMap(input => findCatalogSourceFiles(path.resolve(cwd, input)));
+    const uniqueSourceFiles = [...new Set(sourceFiles)].sort((left, right) => left.localeCompare(right));
+    if (uniqueSourceFiles.length === 0) {
+        throw new Error(`No TypeScript source files found in ${inputs.join(', ')}.`);
+    }
+    const { components, functions } = await writeCatalogArtifacts({
+        cwd,
+        outDir: options.outDir,
+        sourceFiles: uniqueSourceFiles,
+    });
+    printGeneratedComponents(components);
+    printGeneratedFunctions(functions);
+    // Fail loudly if we matched source files but emitted no artifacts —
+    // this used to silently succeed on Windows when TypeDoc rejected
+    // backslash entry-point paths, and downstream packages then failed
+    // to import the missing `catalog.json` files.
+    if (components.length === 0 && functions.length === 0) {
+        console.error(`[a2ui-catalog-extractor] Found ${uniqueSourceFiles.length} `
+            + `source file(s) but emitted 0 component catalogs and 0 `
+            + `function definitions. Make sure each catalog props interface `
+            + `is annotated with \`@a2uiCatalog <Name>\` and each function `
+            + `is annotated with \`@a2uiFunction <name>\`.`);
+        return 1;
+    }
+    return 0;
+}
+function printGeneratedComponents(components) {
+    console.info(`Generated ${components.length} A2UI component catalog files.`);
+    for (const component of components) {
+        console.info(`Generated strict schema for ${component.name}`);
+    }
+}
+function printGeneratedFunctions(functions) {
+    if (functions.length === 0)
+        return;
+    console.info(`Generated ${functions.length} A2UI function definition files.`);
+    for (const fn of functions) {
+        console.info(`Generated function definition for ${fn.name}`);
+    }
+}
+function readValue(args, index, option) {
+    const value = args[index];
+    if (!value || value.startsWith('-')) {
+        throw new Error(`Missing value for ${option}.`);
+    }
+    return value;
+}
+function isEntryScript() {
+    if (!process.argv[1])
+        return false;
+    const entryUrl = pathToFileURL(process.argv[1]).href;
+    if (import.meta.url === entryUrl)
+        return true;
+    // The published bin shim does `import '../dist/cli.js'`. In that case the
+    // entry script is the bin shim, not this module — but we should still run.
+    return /[/\\]bin[/\\]a2ui-catalog-extractor\.[mc]?js$/.test(process.argv[1]);
+}
+try {
+    if (isEntryScript()) {
+        process.exitCode = await runCli(process.argv.slice(2));
+    }
+}
+catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+}
+//# sourceMappingURL=cli.js.map

package/a2ui-catalog-extractor/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/a2ui-catalog-extractor/dist/index.d.ts

@@ -0,0 +1,140 @@
+import type { ProjectReflection } from 'typedoc';
+export interface JsonSchema {
+    $ref?: string;
+    additionalProperties?: boolean | JsonSchema;
+    default?: unknown;
+    deprecated?: boolean;
+    description?: string;
+    enum?: Array<boolean | number | string>;
+    items?: JsonSchema;
+    oneOf?: JsonSchema[];
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    type?: string;
+}
+export interface CatalogComponent {
+    filePath: string;
+    interfaceName: string;
+    name: string;
+    schema: JsonSchema;
+}
+export interface ExtractCatalogOptions {
+    cwd?: string;
+    sourceFiles: string[];
+    tsconfig?: string;
+}
+export interface ExtractCatalogFromTypeDocOptions {
+    cwd?: string;
+}
+export interface WriteComponentCatalogOptions extends ExtractCatalogOptions {
+    outDir: string;
+}
+export interface A2UICatalog {
+    catalogId: string;
+    components?: Record<string, JsonSchema>;
+    functions?: FunctionDefinition[];
+    theme?: Record<string, JsonSchema>;
+}
+export interface FunctionDefinition {
+    description?: string;
+    name: string;
+    parameters: JsonSchema;
+    returnType: 'string' | 'number' | 'boolean' | 'array' | 'object' | 'any' | 'void';
+}
+/** A function discovered in source via `@a2uiFunction`, with its origin path. */
+export interface CatalogFunction extends FunctionDefinition {
+    filePath: string;
+}
+export interface TypeDocProject {
+    children?: TypeDocReflection[];
+}
+export interface TypeDocReflection {
+    children?: TypeDocReflection[];
+    comment?: TypeDocComment;
+    flags?: {
+        isOptional?: boolean;
+    };
+    inheritedFrom?: unknown;
+    kind?: number;
+    kindString?: string;
+    name: string;
+    parameters?: TypeDocReflection[];
+    signatures?: TypeDocSignature[];
+    sources?: TypeDocSource[];
+    type?: TypeDocType;
+}
+export interface TypeDocSignature {
+    comment?: TypeDocComment;
+    kind?: number;
+    kindString?: string;
+    name?: string;
+    parameters?: TypeDocReflection[];
+    type?: TypeDocType;
+}
+export interface TypeDocSource {
+    character?: number;
+    fileName?: string;
+    fullFileName?: string;
+    line?: number;
+}
+export interface TypeDocComment {
+    blockTags?: TypeDocCommentTag[];
+    modifierTags?: Iterable<string> | Record<string, boolean>;
+    summary?: TypeDocCommentDisplayPart[];
+}
+export interface TypeDocCommentTag {
+    content?: TypeDocCommentDisplayPart[];
+    tag: string;
+}
+export interface TypeDocCommentDisplayPart {
+    code?: string;
+    content?: TypeDocCommentDisplayPart[];
+    kind?: string;
+    tag?: string;
+    target?: unknown;
+    text?: string;
+}
+export interface TypeDocType {
+    declaration?: TypeDocReflection;
+    elementType?: TypeDocType;
+    name?: string;
+    qualifiedName?: string;
+    target?: TypeDocType;
+    type: string;
+    typeArguments?: TypeDocType[];
+    types?: TypeDocType[];
+    value?: bigint | boolean | number | string | null;
+}
+export declare function findCatalogSourceFiles(inputPath: string): string[];
+export declare function extractCatalogComponents(options: ExtractCatalogOptions): Promise<CatalogComponent[]>;
+export declare function extractCatalogComponentsFromTypeDocProject(project: ProjectReflection | TypeDocProject, options?: ExtractCatalogFromTypeDocOptions): CatalogComponent[];
+export declare function extractCatalogComponentsFromTypeDocJson(project: TypeDocProject, options?: ExtractCatalogFromTypeDocOptions): CatalogComponent[];
+export declare function extractCatalogFunctions(options: ExtractCatalogOptions): Promise<CatalogFunction[]>;
+export declare function extractCatalogFunctionsFromTypeDocProject(project: ProjectReflection | TypeDocProject, options?: ExtractCatalogFromTypeDocOptions): CatalogFunction[];
+export declare function extractCatalogFunctionsFromTypeDocJson(project: TypeDocProject, options?: ExtractCatalogFromTypeDocOptions): CatalogFunction[];
+export declare function writeComponentCatalogs(options: WriteComponentCatalogOptions): Promise<CatalogComponent[]>;
+export declare function writeCatalogComponents(components: CatalogComponent[], options: {
+    cwd?: string;
+    outDir: string;
+}): void;
+export declare function writeCatalogFunctionDefinitions(options: WriteComponentCatalogOptions): Promise<CatalogFunction[]>;
+export interface CatalogArtifacts {
+    components: CatalogComponent[];
+    functions: CatalogFunction[];
+}
+/**
+ * Bootstrap TypeDoc once and emit both component and function catalog files.
+ * Preferred entry point for the CLI — running the conversion twice doubles
+ * cold-start latency on large catalogs.
+ */
+export declare function writeCatalogArtifacts(options: WriteComponentCatalogOptions): Promise<CatalogArtifacts>;
+export declare function writeCatalogFunctions(functions: CatalogFunction[], options: {
+    cwd?: string;
+    outDir: string;
+}): void;
+export declare function createA2UICatalog(options: {
+    catalogId: string;
+    components: CatalogComponent[] | Record<string, JsonSchema>;
+    functions?: FunctionDefinition[];
+    theme?: Record<string, JsonSchema>;
+}): A2UICatalog;