@opensyntaxhq/autodocs-core 1.0.0

package/README.md

@@ -0,0 +1,17 @@
+# @opensyntaxhq/autodocs-core
+
+Core parsing and extraction engine for Autodocs.
+
+## Installation
+
+```bash
+npm install @opensyntaxhq/autodocs-core
+```
+
+## Usage
+
+```typescript
+import { VERSION } from '@opensyntaxhq/autodocs-core';
+
+console.log(VERSION);
+```

package/dist/index.d.mts

@@ -0,0 +1,236 @@
+import ts from 'typescript';
+
+interface ParserOptions {
+    configFile?: string;
+    compilerOptions?: ts.CompilerOptions;
+    exclude?: string[];
+    include?: string[];
+    skipLibCheck?: boolean;
+}
+interface ParseResult {
+    program: ts.Program;
+    typeChecker: ts.TypeChecker;
+    sourceFiles: ts.SourceFile[];
+    diagnostics: ts.Diagnostic[];
+    rootDir: string;
+}
+declare function createProgram(entryFiles: string[], options?: ParserOptions): ParseResult;
+declare function resolveModules(_program: ts.Program, sourceFile: ts.SourceFile): string[];
+declare function getDependencies(program: ts.Program, filePath: string): string[];
+
+type DocKind = 'interface' | 'type' | 'class' | 'function' | 'enum' | 'variable' | 'guide';
+interface DocEntry {
+    id: string;
+    name: string;
+    kind: DocKind;
+    fileName: string;
+    module?: string;
+    source?: SourceLocation;
+    position: {
+        line: number;
+        column: number;
+    };
+    signature: string;
+    documentation?: DocComment;
+    metadata?: Record<string, unknown>;
+    typeParameters?: TypeParameter[];
+    members?: Member[];
+    parameters?: Parameter[];
+    returnType?: TypeInfo;
+    heritage?: Heritage[];
+    modifiers?: string[];
+    references?: Reference[];
+}
+interface SourceLocation {
+    file: string;
+    line: number;
+    column: number;
+}
+interface DocComment {
+    summary: string;
+    description?: string;
+    tags: DocTag[];
+    examples?: CodeExample[];
+    params?: DocParam[];
+    returns?: string;
+    deprecated?: string;
+}
+interface DocTag {
+    name: string;
+    text: string;
+    type?: string;
+    paramName?: string;
+}
+interface DocParam {
+    name: string;
+    type?: string;
+    text: string;
+}
+interface TypeParameter {
+    name: string;
+    constraint?: string;
+    default?: string;
+}
+interface Member {
+    name: string;
+    type: string;
+    optional: boolean;
+    readonly: boolean;
+    documentation?: string;
+    kind?: 'property' | 'method' | 'enum';
+    value?: string;
+}
+interface Parameter {
+    name: string;
+    type: string;
+    optional: boolean;
+    defaultValue?: string;
+    rest: boolean;
+    documentation?: string;
+}
+interface TypeInfo {
+    text: string;
+    kind: string;
+}
+interface Heritage {
+    id: string;
+    name: string;
+    kind: 'extends' | 'implements';
+}
+interface Reference {
+    id: string;
+    name: string;
+}
+interface CodeExample {
+    code: string;
+    language: string;
+}
+
+interface ExtractOptions {
+    rootDir?: string;
+}
+declare function extractDocs(program: ts.Program, options?: ExtractOptions): DocEntry[];
+declare function extractDocsFromFiles(program: ts.Program, files: string[], options?: ExtractOptions): DocEntry[];
+
+interface JsonGeneratorOptions {
+    pretty?: boolean;
+    splitByModule?: boolean;
+    rootDir?: string;
+}
+declare function generateJson(docs: DocEntry[], outputDir: string, options?: JsonGeneratorOptions): Promise<void>;
+
+declare function generateMarkdown(docs: DocEntry[], outputDir: string): Promise<void>;
+
+declare function generateHtml(docs: DocEntry[], outputDir: string): Promise<void>;
+
+interface Plugin {
+    name: string;
+    version: string;
+    initialize?(context: PluginContext): void | Promise<void>;
+    beforeParse?(files: string[]): string[] | Promise<string[]>;
+    afterParse?(program: ts.Program): void | Promise<void>;
+    beforeExtract?(sourceFiles: ts.SourceFile[]): void | Promise<void>;
+    afterExtract?(docs: DocEntry[]): DocEntry[] | Promise<DocEntry[]>;
+    beforeGenerate?(docs: DocEntry[]): DocEntry[] | Promise<DocEntry[]>;
+    afterGenerate?(outputDir: string): void | Promise<void>;
+    cleanup?(): void | Promise<void>;
+}
+interface PluginContext {
+    config: unknown;
+    logger: Logger;
+    cache: Map<string, unknown>;
+    emitEvent(name: string, data: unknown): void;
+    addHook(name: string, handler: (data: unknown) => void): void;
+}
+interface Logger {
+    info(message: string): void;
+    warn(message: string): void;
+    error(message: string): void;
+    debug(message: string): void;
+}
+
+declare class PluginManager {
+    private plugins;
+    private context;
+    constructor(config: unknown, logger?: Logger);
+    loadPlugin(plugin: Plugin | string): Promise<void>;
+    runHook<T>(hookName: keyof Plugin, value: T): Promise<T>;
+    cleanup(): Promise<void>;
+    private resolvePlugin;
+    private resolvePluginExport;
+    private getModuleExport;
+    private createContext;
+}
+
+interface CacheEntry {
+    fileHash: string;
+    timestamp: number;
+    docsFile: string | null;
+    dependencies: string[];
+    metadata: CacheMetadata;
+}
+interface CacheMetadata {
+    version: string;
+    tsVersion: string;
+    configHash: string;
+}
+interface CacheOptions {
+    cacheDir: string;
+    enabled?: boolean;
+}
+
+declare class FileCache {
+    private index;
+    private options;
+    private indexPath;
+    private docsDir;
+    private ready;
+    constructor(options: CacheOptions);
+    getCacheDir(): string;
+    getEntry(filePath: string): Promise<CacheEntry | null>;
+    readDocs<T = unknown>(entry: CacheEntry): Promise<T[]>;
+    getFileHash(filePath: string): Promise<string>;
+    set(filePath: string, docs: unknown[], dependencies: string[], metadata: CacheMetadata): Promise<void>;
+    invalidate(filePath: string): Promise<void>;
+    clear(): Promise<void>;
+    private normalize;
+    private resolveDocsPath;
+    private createDocsFileName;
+    private writeDocs;
+    private removeDocsFile;
+    private pruneOrphanDocs;
+    private load;
+    private persist;
+    private writeJsonAtomic;
+}
+
+interface IncrementalBuildOptions {
+    files: string[];
+    cache: FileCache;
+    tsconfig?: string;
+    compilerOptions?: ts.CompilerOptions;
+    configHash: string;
+    onProgram?: (program: ts.Program, sourceFiles: ts.SourceFile[]) => Promise<void> | void;
+}
+interface IncrementalBuildResult {
+    docs: DocEntry[];
+    changedFiles: string[];
+    fromCache: number;
+    parsed: number;
+    program: ts.Program;
+    sourceFiles: ts.SourceFile[];
+    rootDir: string;
+    diagnostics: ts.Diagnostic[];
+}
+declare function incrementalBuild(options: IncrementalBuildOptions): Promise<IncrementalBuildResult>;
+
+interface StaticSiteOptions {
+    outputDir: string;
+    siteUrl?: string;
+    siteName: string;
+}
+declare function generateStaticSite(options: StaticSiteOptions): Promise<void>;
+
+declare const VERSION = "1.0.0";
+
+export { type CacheEntry, type CacheMetadata, type CacheOptions, type CodeExample, type DocComment, type DocEntry, type DocKind, type DocTag, FileCache, type Heritage, type Logger, type Member, type Parameter, type ParseResult, type ParserOptions, type Plugin, type PluginContext, PluginManager, type Reference, type StaticSiteOptions, type TypeInfo, type TypeParameter, VERSION, createProgram, extractDocs, extractDocsFromFiles, generateHtml, generateJson, generateMarkdown, generateStaticSite, getDependencies, incrementalBuild, resolveModules };

package/dist/index.d.ts

@@ -0,0 +1,236 @@
+import ts from 'typescript';
+
+interface ParserOptions {
+    configFile?: string;
+    compilerOptions?: ts.CompilerOptions;
+    exclude?: string[];
+    include?: string[];
+    skipLibCheck?: boolean;
+}
+interface ParseResult {
+    program: ts.Program;
+    typeChecker: ts.TypeChecker;
+    sourceFiles: ts.SourceFile[];
+    diagnostics: ts.Diagnostic[];
+    rootDir: string;
+}
+declare function createProgram(entryFiles: string[], options?: ParserOptions): ParseResult;
+declare function resolveModules(_program: ts.Program, sourceFile: ts.SourceFile): string[];
+declare function getDependencies(program: ts.Program, filePath: string): string[];
+
+type DocKind = 'interface' | 'type' | 'class' | 'function' | 'enum' | 'variable' | 'guide';
+interface DocEntry {
+    id: string;
+    name: string;
+    kind: DocKind;
+    fileName: string;
+    module?: string;
+    source?: SourceLocation;
+    position: {
+        line: number;
+        column: number;
+    };
+    signature: string;
+    documentation?: DocComment;
+    metadata?: Record<string, unknown>;
+    typeParameters?: TypeParameter[];
+    members?: Member[];
+    parameters?: Parameter[];
+    returnType?: TypeInfo;
+    heritage?: Heritage[];
+    modifiers?: string[];
+    references?: Reference[];
+}
+interface SourceLocation {
+    file: string;
+    line: number;
+    column: number;
+}
+interface DocComment {
+    summary: string;
+    description?: string;
+    tags: DocTag[];
+    examples?: CodeExample[];
+    params?: DocParam[];
+    returns?: string;
+    deprecated?: string;
+}
+interface DocTag {
+    name: string;
+    text: string;
+    type?: string;
+    paramName?: string;
+}
+interface DocParam {
+    name: string;
+    type?: string;
+    text: string;
+}
+interface TypeParameter {
+    name: string;
+    constraint?: string;
+    default?: string;
+}
+interface Member {
+    name: string;
+    type: string;
+    optional: boolean;
+    readonly: boolean;
+    documentation?: string;
+    kind?: 'property' | 'method' | 'enum';
+    value?: string;
+}
+interface Parameter {
+    name: string;
+    type: string;
+    optional: boolean;
+    defaultValue?: string;
+    rest: boolean;
+    documentation?: string;
+}
+interface TypeInfo {
+    text: string;
+    kind: string;
+}
+interface Heritage {
+    id: string;
+    name: string;
+    kind: 'extends' | 'implements';
+}
+interface Reference {
+    id: string;
+    name: string;
+}
+interface CodeExample {
+    code: string;
+    language: string;
+}
+
+interface ExtractOptions {
+    rootDir?: string;
+}
+declare function extractDocs(program: ts.Program, options?: ExtractOptions): DocEntry[];
+declare function extractDocsFromFiles(program: ts.Program, files: string[], options?: ExtractOptions): DocEntry[];
+
+interface JsonGeneratorOptions {
+    pretty?: boolean;
+    splitByModule?: boolean;
+    rootDir?: string;
+}
+declare function generateJson(docs: DocEntry[], outputDir: string, options?: JsonGeneratorOptions): Promise<void>;
+
+declare function generateMarkdown(docs: DocEntry[], outputDir: string): Promise<void>;
+
+declare function generateHtml(docs: DocEntry[], outputDir: string): Promise<void>;
+
+interface Plugin {
+    name: string;
+    version: string;
+    initialize?(context: PluginContext): void | Promise<void>;
+    beforeParse?(files: string[]): string[] | Promise<string[]>;
+    afterParse?(program: ts.Program): void | Promise<void>;
+    beforeExtract?(sourceFiles: ts.SourceFile[]): void | Promise<void>;
+    afterExtract?(docs: DocEntry[]): DocEntry[] | Promise<DocEntry[]>;
+    beforeGenerate?(docs: DocEntry[]): DocEntry[] | Promise<DocEntry[]>;
+    afterGenerate?(outputDir: string): void | Promise<void>;
+    cleanup?(): void | Promise<void>;
+}
+interface PluginContext {
+    config: unknown;
+    logger: Logger;
+    cache: Map<string, unknown>;
+    emitEvent(name: string, data: unknown): void;
+    addHook(name: string, handler: (data: unknown) => void): void;
+}
+interface Logger {
+    info(message: string): void;
+    warn(message: string): void;
+    error(message: string): void;
+    debug(message: string): void;
+}
+
+declare class PluginManager {
+    private plugins;
+    private context;
+    constructor(config: unknown, logger?: Logger);
+    loadPlugin(plugin: Plugin | string): Promise<void>;
+    runHook<T>(hookName: keyof Plugin, value: T): Promise<T>;
+    cleanup(): Promise<void>;
+    private resolvePlugin;
+    private resolvePluginExport;
+    private getModuleExport;
+    private createContext;
+}
+
+interface CacheEntry {
+    fileHash: string;
+    timestamp: number;
+    docsFile: string | null;
+    dependencies: string[];
+    metadata: CacheMetadata;
+}
+interface CacheMetadata {
+    version: string;
+    tsVersion: string;
+    configHash: string;
+}
+interface CacheOptions {
+    cacheDir: string;
+    enabled?: boolean;
+}
+
+declare class FileCache {
+    private index;
+    private options;
+    private indexPath;
+    private docsDir;
+    private ready;
+    constructor(options: CacheOptions);
+    getCacheDir(): string;
+    getEntry(filePath: string): Promise<CacheEntry | null>;
+    readDocs<T = unknown>(entry: CacheEntry): Promise<T[]>;
+    getFileHash(filePath: string): Promise<string>;
+    set(filePath: string, docs: unknown[], dependencies: string[], metadata: CacheMetadata): Promise<void>;
+    invalidate(filePath: string): Promise<void>;
+    clear(): Promise<void>;
+    private normalize;
+    private resolveDocsPath;
+    private createDocsFileName;
+    private writeDocs;
+    private removeDocsFile;
+    private pruneOrphanDocs;
+    private load;
+    private persist;
+    private writeJsonAtomic;
+}
+
+interface IncrementalBuildOptions {
+    files: string[];
+    cache: FileCache;
+    tsconfig?: string;
+    compilerOptions?: ts.CompilerOptions;
+    configHash: string;
+    onProgram?: (program: ts.Program, sourceFiles: ts.SourceFile[]) => Promise<void> | void;
+}
+interface IncrementalBuildResult {
+    docs: DocEntry[];
+    changedFiles: string[];
+    fromCache: number;
+    parsed: number;
+    program: ts.Program;
+    sourceFiles: ts.SourceFile[];
+    rootDir: string;
+    diagnostics: ts.Diagnostic[];
+}
+declare function incrementalBuild(options: IncrementalBuildOptions): Promise<IncrementalBuildResult>;
+
+interface StaticSiteOptions {
+    outputDir: string;
+    siteUrl?: string;
+    siteName: string;
+}
+declare function generateStaticSite(options: StaticSiteOptions): Promise<void>;
+
+declare const VERSION = "1.0.0";
+
+export { type CacheEntry, type CacheMetadata, type CacheOptions, type CodeExample, type DocComment, type DocEntry, type DocKind, type DocTag, FileCache, type Heritage, type Logger, type Member, type Parameter, type ParseResult, type ParserOptions, type Plugin, type PluginContext, PluginManager, type Reference, type StaticSiteOptions, type TypeInfo, type TypeParameter, VERSION, createProgram, extractDocs, extractDocsFromFiles, generateHtml, generateJson, generateMarkdown, generateStaticSite, getDependencies, incrementalBuild, resolveModules };