@@ -37,106 +37,14 @@ export function apiGenPlugin(): Plugin {
3737 let configMemo : ApiConfig | null | undefined ;
3838
3939 function loadConfig ( ) : ApiConfig | null {
40- if ( configMemo === undefined ) configMemo = readConfig ( ) ;
40+ if ( configMemo === undefined ) configMemo = readApiConfig ( root ) ;
4141 return configMemo ;
4242 }
4343
44- function readConfig ( ) : ApiConfig | null {
45- const path = configPath ( ) ;
46- if ( ! existsSync ( path ) ) return null ;
47- try {
48- const proj = new Project ( {
49- compilerOptions : { target : ts . ScriptTarget . ES2022 , module : ts . ModuleKind . ESNext } ,
50- } ) ;
51- const sourceFile = proj . addSourceFileAtPath ( path ) ;
52- // We can't trivially evaluate the TS without a runtime; instead lift
53- // the literal passed to `defineApi(...)` via AST traversal. For the
54- // skeleton, every supported field is read as a literal so static
55- // extraction is enough. Read the `export default` expression directly
56- // rather than the first `CallExpression` in the file — otherwise any
57- // helper call before the default export (even a harmless one) would
58- // be parsed as the config.
59- const exportAssignment = sourceFile . getExportAssignment ( ( ea ) => ! ea . isExportEquals ( ) ) ;
60- if ( ! exportAssignment ) return null ;
61- const callExpr = exportAssignment . getExpression ( ) . asKind ( ts . SyntaxKind . CallExpression ) ;
62- if ( ! callExpr ) return null ;
63- const literal = callExpr . getArguments ( ) [ 0 ] ;
64- if ( ! literal || ! literal . asKind ( ts . SyntaxKind . ObjectLiteralExpression ) ) return null ;
65- return parseLiteralAsConfig ( literal as never ) ;
66- } catch ( err ) {
67- console . warn ( '[ngmd-api-gen] failed to load ngmd.api.ts:' , err ) ;
68- return null ;
69- }
70- }
71-
72- function ensureProject ( config : ApiConfig ) : Project {
73- if ( project ) return project ;
74- project = new Project ( {
75- tsConfigFilePath : existsSync ( join ( root , 'tsconfig.json' ) )
76- ? join ( root , 'tsconfig.json' )
77- : undefined ,
78- skipAddingFilesFromTsConfig : true ,
79- } ) ;
80- project . addSourceFilesAtPaths ( [
81- ...config . scope . map ( ( pattern ) => posix . join ( root , pattern ) ) ,
82- ...( config . exclude ?? [ ] ) . map ( ( pattern ) => '!' + posix . join ( root , pattern ) ) ,
83- ] ) ;
84- return project ;
85- }
86-
8744 function extractRecords ( config : ApiConfig ) : SymbolRecord [ ] {
88- if ( recordsMemo ) return recordsMemo ;
89- const proj = ensureProject ( config ) ;
90- const records : SymbolRecord [ ] = [ ] ;
91- const seen = new Set < string > ( ) ;
92- const badgeTags = new Set ( config . badgesFromJsDoc ?? [ ] ) ;
93-
94- for ( const sourceFile of proj . getSourceFiles ( ) ) {
95- for ( const [ exportName , declarations ] of sourceFile . getExportedDeclarations ( ) ) {
96- const decls = declarations . filter ( ( d ) => symbolKindOf ( d ) ) ;
97- const first = decls [ 0 ] ;
98- if ( ! first ) continue ;
99- const declFile = first . getSourceFile ( ) ;
100- if ( declFile . isInNodeModules ( ) || declFile . isDeclarationFile ( ) ) continue ;
101- const kind = symbolKindOf ( first ) ! ;
102- const name =
103- exportName === 'default'
104- ? ( ( first as { getName ?: ( ) => string | undefined } ) . getName ?.( ) ?? exportName )
105- : exportName ;
106- const filePath = posix . relative ( root , declFile . getFilePath ( ) ) ;
107- const key = `${ filePath } :${ first . getStart ( ) } :${ name } ` ;
108- if ( seen . has ( key ) ) continue ;
109- seen . add ( key ) ;
110-
111- const jsDocsPerDecl = decls . map ( ( d ) => {
112- const host = jsDocHostFor ( d ) ;
113- return Node . isJSDocable ( host ) ? host . getJsDocs ( ) : [ ] ;
114- } ) ;
115- const jsDocs = jsDocsPerDecl . flat ( ) ;
116- const description =
117- jsDocsPerDecl
118- . find ( ( docs ) => docs . length )
119- ?. at ( - 1 )
120- ?. getDescription ( )
121- . trim ( ) ?? '' ;
122- const tags = jsDocs . flatMap ( ( d ) => d . getTags ( ) . map ( ( t ) => t . getTagName ( ) ) ) ;
123- const badges = [ ...new Set ( tags . filter ( ( t ) => badgeTags . has ( t ) ) ) ] ;
124-
125- records . push ( {
126- kind,
127- name,
128- filePath,
129- line : first . getStartLineNumber ( ) ,
130- signature : signatureOf ( decls ) ,
131- description,
132- badges,
133- group : groupNameFor ( filePath , config . groupBy ?? 'directory' , kind ) ,
134- } ) ;
135- }
136- }
137-
138- recordsMemo = records ;
139- return records ;
45+ project ??= createApiProject ( root , config ) ;
46+ recordsMemo ??= extractApiRecords ( root , config , project ) ;
47+ return recordsMemo ;
14048 }
14149
14250 return {
@@ -194,6 +102,109 @@ export function apiGenPlugin(): Plugin {
194102 }
195103}
196104
105+ function readApiConfig ( root : string ) : ApiConfig | null {
106+ const path = posix . join ( root , 'ngmd.api.ts' ) ;
107+ if ( ! existsSync ( path ) ) return null ;
108+ try {
109+ const proj = new Project ( {
110+ compilerOptions : { target : ts . ScriptTarget . ES2022 , module : ts . ModuleKind . ESNext } ,
111+ } ) ;
112+ const sourceFile = proj . addSourceFileAtPath ( path ) ;
113+ // We can't trivially evaluate the TS without a runtime; instead lift
114+ // the literal passed to `defineApi(...)` via AST traversal. For the
115+ // skeleton, every supported field is read as a literal so static
116+ // extraction is enough. Read the `export default` expression directly
117+ // rather than the first `CallExpression` in the file — otherwise any
118+ // helper call before the default export (even a harmless one) would
119+ // be parsed as the config.
120+ const exportAssignment = sourceFile . getExportAssignment ( ( ea ) => ! ea . isExportEquals ( ) ) ;
121+ if ( ! exportAssignment ) return null ;
122+ const callExpr = exportAssignment . getExpression ( ) . asKind ( ts . SyntaxKind . CallExpression ) ;
123+ if ( ! callExpr ) return null ;
124+ const literal = callExpr . getArguments ( ) [ 0 ] ;
125+ if ( ! literal || ! literal . asKind ( ts . SyntaxKind . ObjectLiteralExpression ) ) return null ;
126+ return parseLiteralAsConfig ( literal as never ) ;
127+ } catch ( err ) {
128+ console . warn ( '[ngmd-api-gen] failed to load ngmd.api.ts:' , err ) ;
129+ return null ;
130+ }
131+ }
132+
133+ function createApiProject ( root : string , config : ApiConfig ) : Project {
134+ const project = new Project ( {
135+ tsConfigFilePath : existsSync ( join ( root , 'tsconfig.json' ) )
136+ ? join ( root , 'tsconfig.json' )
137+ : undefined ,
138+ skipAddingFilesFromTsConfig : true ,
139+ } ) ;
140+ project . addSourceFilesAtPaths ( [
141+ ...config . scope . map ( ( pattern ) => posix . join ( root , pattern ) ) ,
142+ ...( config . exclude ?? [ ] ) . map ( ( pattern ) => '!' + posix . join ( root , pattern ) ) ,
143+ ] ) ;
144+ return project ;
145+ }
146+
147+ export function apiRoutes ( root : string ) : Array < { route : string ; file : string } > {
148+ const config = readApiConfig ( root ) ;
149+ if ( ! config ) return [ ] ;
150+ return extractApiRecords ( root , config , createApiProject ( root , config ) ) . map ( ( record ) => ( {
151+ route : `/api/${ record . group } /${ record . name } ` ,
152+ file : record . filePath ,
153+ } ) ) ;
154+ }
155+
156+ function extractApiRecords ( root : string , config : ApiConfig , proj : Project ) : SymbolRecord [ ] {
157+ const records : SymbolRecord [ ] = [ ] ;
158+ const seen = new Set < string > ( ) ;
159+ const badgeTags = new Set ( config . badgesFromJsDoc ?? [ ] ) ;
160+
161+ for ( const sourceFile of proj . getSourceFiles ( ) ) {
162+ for ( const [ exportName , declarations ] of sourceFile . getExportedDeclarations ( ) ) {
163+ const decls = declarations . filter ( ( d ) => symbolKindOf ( d ) ) ;
164+ const first = decls [ 0 ] ;
165+ if ( ! first ) continue ;
166+ const declFile = first . getSourceFile ( ) ;
167+ if ( declFile . isInNodeModules ( ) || declFile . isDeclarationFile ( ) ) continue ;
168+ const kind = symbolKindOf ( first ) ! ;
169+ const name =
170+ exportName === 'default'
171+ ? ( ( first as { getName ?: ( ) => string | undefined } ) . getName ?.( ) ?? exportName )
172+ : exportName ;
173+ const filePath = posix . relative ( root , declFile . getFilePath ( ) ) ;
174+ const key = `${ filePath } :${ first . getStart ( ) } :${ name } ` ;
175+ if ( seen . has ( key ) ) continue ;
176+ seen . add ( key ) ;
177+
178+ const jsDocsPerDecl = decls . map ( ( d ) => {
179+ const host = jsDocHostFor ( d ) ;
180+ return Node . isJSDocable ( host ) ? host . getJsDocs ( ) : [ ] ;
181+ } ) ;
182+ const jsDocs = jsDocsPerDecl . flat ( ) ;
183+ const description =
184+ jsDocsPerDecl
185+ . find ( ( docs ) => docs . length )
186+ ?. at ( - 1 )
187+ ?. getDescription ( )
188+ . trim ( ) ?? '' ;
189+ const tags = jsDocs . flatMap ( ( d ) => d . getTags ( ) . map ( ( t ) => t . getTagName ( ) ) ) ;
190+ const badges = [ ...new Set ( tags . filter ( ( t ) => badgeTags . has ( t ) ) ) ] ;
191+
192+ records . push ( {
193+ kind,
194+ name,
195+ filePath,
196+ line : first . getStartLineNumber ( ) ,
197+ signature : signatureOf ( decls ) ,
198+ description,
199+ badges,
200+ group : groupNameFor ( filePath , config . groupBy ?? 'directory' , kind ) ,
201+ } ) ;
202+ }
203+ }
204+
205+ return records ;
206+ }
207+
197208function symbolKindOf ( decl : Node ) : SymbolKind | null {
198209 if ( Node . isClassDeclaration ( decl ) ) return 'class' ;
199210 if ( Node . isInterfaceDeclaration ( decl ) ) return 'interface' ;
0 commit comments