From 2edc78721cf5523b9cdd6d5a41290bb51e8dfed1 Mon Sep 17 00:00:00 2001 From: Alexandre Germain Date: Tue, 19 Jul 2022 20:38:12 +0200 Subject: [PATCH] fix: remove hacky MarkdownToSummary Closes #130 See TypeStrong/typedoc#2004 --- .../plugin-monorepo-readmes/src/plugin.ts | 7 +- .../page-tree/page-tree-builder.spec.ts | 10 +-- .../converter/page-tree/page-tree-builder.ts | 4 +- packages/plugin-pages/src/plugin.ts | 3 +- packages/plugintestbed/src/mock-plugin.ts | 1 + packages/pluginutils/src/index.ts | 1 - .../pluginutils/src/markdown-to-summary.ts | 78 ------------------- 7 files changed, 9 insertions(+), 95 deletions(-) delete mode 100644 packages/pluginutils/src/markdown-to-summary.ts diff --git a/packages/plugin-monorepo-readmes/src/plugin.ts b/packages/plugin-monorepo-readmes/src/plugin.ts index 98c61f3d..73323313 100644 --- a/packages/plugin-monorepo-readmes/src/plugin.ts +++ b/packages/plugin-monorepo-readmes/src/plugin.ts @@ -1,16 +1,15 @@ import assert from 'assert'; import { readFileSync } from 'fs'; -import { Application, DeclarationReflection, DefaultTheme, JSX, PageEvent, ProjectReflection, ReflectionKind, RendererEvent } from 'typedoc'; +import { Application, DeclarationReflection, DefaultTheme, JSX, MinimalSourceFile, PageEvent, ProjectReflection, ReflectionKind, RendererEvent } from 'typedoc'; -import { ABasePlugin, CurrentPageMemo, EventsExtra, MarkdownToSummary, reflectionSourceUtils } from '@knodes/typedoc-pluginutils'; +import { ABasePlugin, CurrentPageMemo, EventsExtra, reflectionSourceUtils } from '@knodes/typedoc-pluginutils'; import { findReadmeFile } from './find-readme-file'; import { buildOptions } from './options'; import { isMonorepoReadmesPluginTheme } from './output/theme'; export class MonorepoReadmePlugin extends ABasePlugin { - public readonly markdownToSummary = MarkdownToSummary.for( this ); public readonly pluginOptions = buildOptions( this ); private readonly _currentPageMemo = CurrentPageMemo.for( this ); public constructor( application: Application ){ @@ -70,7 +69,7 @@ export class MonorepoReadmePlugin extends ABasePlugin { source, ]; const fakePageEvent = new PageEvent( props.name ); - fakeProject.readme = this.markdownToSummary.processFromString( readFileSync( absReadme, 'utf-8' ) ); + fakeProject.readme = this.application.converter.parseRawComment( new MinimalSourceFile( readFileSync( absReadme, 'utf-8' ), absReadme ) ).summary; fakePageEvent.filename = props.filename; fakePageEvent.project = props.project; fakePageEvent.url = props.url; diff --git a/packages/plugin-pages/src/converter/page-tree/page-tree-builder.spec.ts b/packages/plugin-pages/src/converter/page-tree/page-tree-builder.spec.ts index 66e8ba73..3535053b 100644 --- a/packages/plugin-pages/src/converter/page-tree/page-tree-builder.spec.ts +++ b/packages/plugin-pages/src/converter/page-tree/page-tree-builder.spec.ts @@ -2,9 +2,7 @@ import { resolve } from 'path'; import { isString, noop, omit } from 'lodash'; import { Class } from 'type-fest'; -import { Comment, DeclarationReflection, LogLevel, ProjectReflection, Reflection, ReflectionKind, SourceReference, normalizePath } from 'typedoc'; - -import { MarkdownToSummary } from '@knodes/typedoc-pluginutils'; +import { DeclarationReflection, LogLevel, ProjectReflection, Reflection, ReflectionKind, SourceReference, normalizePath } from 'typedoc'; import { MockPlugin, createMockProjectWithPackage, mockPlugin, restoreFs, setVirtualFs } from '#plugintestbed'; @@ -26,11 +24,7 @@ const opts = ( pages: IRootPageNode[] ) => ( { source: '', } as IPluginOptions ); beforeEach( () => { - plugin = mockPlugin( { - markdownToSummary: { - processFromString: jest.fn().mockImplementation( v => new Comment( [ { kind: 'text', text: v } ] ) ), - } as jest.MockedObject, - } ); + plugin = mockPlugin(); pageTreeBuilder = new PageTreeBuilder( plugin ); project = createMockProjectWithPackage(); } ); diff --git a/packages/plugin-pages/src/converter/page-tree/page-tree-builder.ts b/packages/plugin-pages/src/converter/page-tree/page-tree-builder.ts index 7abe265e..0c62744d 100644 --- a/packages/plugin-pages/src/converter/page-tree/page-tree-builder.ts +++ b/packages/plugin-pages/src/converter/page-tree/page-tree-builder.ts @@ -1,6 +1,6 @@ import assert from 'assert'; -import { Comment, DeclarationReflection, ProjectReflection, Reflection, normalizePath } from 'typedoc'; +import { DeclarationReflection, MinimalSourceFile, ProjectReflection, Reflection, normalizePath } from 'typedoc'; import { IPluginComponent, getWorkspaces, miscUtils, resolveNamedPath } from '@knodes/typedoc-pluginutils'; @@ -164,7 +164,7 @@ export class PageTreeBuilder implements IPluginComponent { nodePath, normalizePath( join( io.output, getNodeUrl( node ) ) ) ), `Could not generate a page reflection for ${getNodePath( node, actualParent )}` ); - page.comment = new Comment( this.plugin.markdownToSummary.processFromString ( page.content ) ?? [] ); + page.comment = this.plugin.application.converter.parseRawComment( new MinimalSourceFile( page.content, page.sourceFilePath ) ); return page; } return new MenuReflection( diff --git a/packages/plugin-pages/src/plugin.ts b/packages/plugin-pages/src/plugin.ts index 60f866d4..2986d250 100644 --- a/packages/plugin-pages/src/plugin.ts +++ b/packages/plugin-pages/src/plugin.ts @@ -1,6 +1,6 @@ import { Application, Context, Converter, Reflection, RendererEvent } from 'typedoc'; -import { ABasePlugin, EventsExtra, MarkdownToSummary, ReflectionCommentReplacer } from '@knodes/typedoc-pluginutils'; +import { ABasePlugin, EventsExtra, ReflectionCommentReplacer } from '@knodes/typedoc-pluginutils'; import { PageTreeBuilder } from './converter/page-tree'; import { ANodeReflection } from './models/reflections'; @@ -8,7 +8,6 @@ import { buildOptions } from './options'; import { IPagesPluginThemeMethods, bindReplaceMarkdown, getPagesPluginThemeMethods } from './output'; export class PagesPlugin extends ABasePlugin { - public readonly markdownToSummary = MarkdownToSummary.for( this.application ); public readonly pluginOptions = buildOptions( this ); private readonly _reflectionCommentReplacer = new ReflectionCommentReplacer( this ); private _themeMethods?: IPagesPluginThemeMethods; diff --git a/packages/plugintestbed/src/mock-plugin.ts b/packages/plugintestbed/src/mock-plugin.ts index ce3fe703..0095e5c1 100644 --- a/packages/plugintestbed/src/mock-plugin.ts +++ b/packages/plugintestbed/src/mock-plugin.ts @@ -29,6 +29,7 @@ export const mockPlugin = ( props: Partial> }; application.converter = new Converter( application ); application.renderer = new Renderer( application ); + application.application = application; const plugin = Object.create( ABasePlugin.prototype, Object.fromEntries( Object.entries( { application, rootDir: process.cwd(), diff --git a/packages/pluginutils/src/index.ts b/packages/pluginutils/src/index.ts index aa9574c5..22af4ad7 100644 --- a/packages/pluginutils/src/index.ts +++ b/packages/pluginutils/src/index.ts @@ -2,7 +2,6 @@ export * from './autoload'; export * from './base-plugin'; export * from './current-page-memo'; export * from './events-extra'; -export * from './markdown-to-summary'; export * from './options'; export * from './plugin-logger'; export * from './reflection-accessor'; diff --git a/packages/pluginutils/src/markdown-to-summary.ts b/packages/pluginutils/src/markdown-to-summary.ts deleted file mode 100644 index 1918cbf9..00000000 --- a/packages/pluginutils/src/markdown-to-summary.ts +++ /dev/null @@ -1,78 +0,0 @@ -import assert from 'assert'; -import { randomBytes } from 'crypto'; -import { writeFileSync } from 'fs'; -import { tmpdir } from 'os'; -import { join } from 'path'; - -import { Application, Context, Converter, DeclarationReflection, ProjectReflection, normalizePath } from 'typedoc'; - -import { ApplicationAccessor, getApplication } from './base-plugin'; -import { miscUtils } from './utils'; - -const tmpFile = ( prefix: string, ext: `.${string}`, content?: string ) => { - const tempFile = join( tmpdir(), `${prefix}.${randomBytes( 6 ).readUIntLE( 0, 6 ).toString( 36 )}${ext}` ); - content = content ?? ''; - writeFileSync( tempFile, content, 'utf-8' ); - return tempFile; -}; - -export class MarkdownToSummary { - private static readonly _apps = new WeakMap(); - - private _context?: Context; - - /** - * Get markdown to summary for the given application. - * - * @param applicationAccessor - The application accessor to bind. - * @returns the events extra instance. - */ - public static for( applicationAccessor: ApplicationAccessor ){ - const application = getApplication( applicationAccessor ); - const e = this._apps.get( application ) ?? new MarkdownToSummary( application ); - this._apps.set( application, e ); - return e; - } - - public constructor( private readonly _application: Application ){ - _application.converter.on( Converter.EVENT_BEGIN, this._memoizeContext.bind( this ) ); - } - - /** - * Generate comments from a string, by emulating a new project reflection. - * HACK - This method is mostly a hack and should be removed ASAP. - * - * @param str - The string to parse. - * @returns the parsed comment. - */ - public processFromString( str: string ){ - // TODO: Check if `renderer.package` can do the trick; - - assert( this._context, 'Should be constructed before "Converter.EVENT_BEGIN" is triggered' ); - const fakeProject = new ProjectReflection( 'STUB' ); - const fakeContext = new Context( this._context.converter, this._context.programs, fakeProject ); - fakeContext.setActiveProgram( this._context.programs[0] ); - - const readmeFile = tmpFile( MarkdownToSummary.name, '.md', str ); - - const converter = this._application.converter as any; - // const converter: InstanceType<( typeof import( '../../../typedoc/src/lib/converter/converter' ).Converter )> = this._application.converter as any; - const rootDir = normalizePath( miscUtils.rootDir( this._application ) ); - const sourceFile = this._context.programs[0].getSourceFiles().find( src => normalizePath( src.fileName ).startsWith( rootDir ) ); - assert( sourceFile, `Failed to lookup for a file in root dir ${rootDir}` ); - // eslint-disable-next-line @typescript-eslint/dot-notation -- Access private - const ret: Context = converter['convertExports']( fakeContext as any, { program: fakeContext.program, displayName: 'TEMP', sourceFile, readmeFile }, false ); - assert( ret.scope instanceof DeclarationReflection ); - return ret.scope.readme; - } - - /** - * Event callback executed once on {@link Converter.EVENT_BEGIN}. - * Memoize the converter context for later use. - * - * @param context - The converter context. - */ - private _memoizeContext( context: Context ){ - this._context = context; - } -}