Skip to content

Create metadata entries generator #271

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
araujogui opened this issue May 14, 2025 · 4 comments · May be fixed by #272
Open

Create metadata entries generator #271

araujogui opened this issue May 14, 2025 · 4 comments · May be fixed by #272
Assignees
@araujogui

Comments

@araujogui
Copy link
Member

araujogui commented May 14, 2025 •
edited
Loading

I believe parsers should only convert source files to ASTs with minimal or zero transformation. The current AST to metadata entries transformation should be extracted into a separate generator. Other generators can depend on this metadata generator if needed. This would allow generators to choose between working directly with the raw AST or a more structured metadata representation, depending on their needs.
@avivkeller
Copy link
Member

Sounds good to me, however, I don't want to maintain unused code, so is there an actual need for this in our current codebase?

@araujogui
Copy link
Member Author

I believe legacy-json and llms-txt generators can benefit from this. legacy-json for example uses buildHierarchy to transform the flattened entries into a hierarchical structure again.

@araujogui
Copy link
Member Author

araujogui commented May 14, 2025 •
edited
Loading

I can work on this if it sounds like a good idea for the whole team. @nodejs/web-infra

@flakey5
Copy link
Member

flakey5 commented May 14, 2025

+1 to this

The thing for the legacy-json generator though is that it needs the metadata entries. If we switched to using the raw ast for it, it would need to be rewritten almost entirely to use the raw ast, which also means we'd need to do a lot of the stuff in the generator that the metadata parsing is already doing.

The main thing I think that would benefit the generator though (and the new json generator and possibly some others in the future) is some ast-hierarchized generator, where it doesn't pass in flattened entries. The current buildHierarchy impl works off just a hueristic that assumes the order of the entries is the same as in the raw ast (tbf it should be, but there's nothing preventing it from not being like that). But, that's probably for another issue to discuss

@araujogui araujogui self-assigned this May 14, 2025
This was referenced May 14, 2025
Open
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@araujogui araujogui

Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

feat: create metadata entries generator araujogui/api-docs-tooling
3 participants
@avivkeller @araujogui @flakey5