ajvincent / ts-morph-structures Goto Github PK

It will help a lot with both verifying the types match via automated tests, and confirming we're ready to go into statement generation.

Whoops. The mixin classes implement the tighter property definitions I want, but the type definitions constraining them are the original ones from ts-morph. This caused a test I was going to port from stage 1 to stage 2 for #21 to just blow up with TypeScript errors.

Easy fix, but I need to remember to actually do the fix.

Note #6 (comment)

I also need an integration test for the MemberedTypeToClass code.

Alternatively, make the name "copyFields" into a symbol.

Hi, everyone! One nice-to-have for this project is code documentation. I've built a tool to generate it, but it needs data.

TSDocMap is a definition of TSDoc comments for structure and decorator classes which don't exist until later stages. Here's one example of the output.

I need help with people going through the stage 2 snapshot files and filling in the blanks, so to speak.

Here's how to get started:

1. Do a git clone of this repository, and run npm install.
2. Run npm run build. This will generate stage_2_fullset/snapshot/coverage/tsdocs.json, which is git-ignored. The output describes the current documentation state.
3. Update TSDocMap with your new metadata.
4. Run npm run build again to see the results.
5. Submit a pull request!

There's a special wildcard, className: "*", which should apply changes across all decorators or all structures. static [COPY_FIELDS] is a good use-case for this, as it's supposed to be @internal.

During your npm run build commands, you may notice a "Coverage report: TSDoc comments" section. This is specifically checking for completeness in the documentation. Green dots are good. Yellow slashes are incomplete, and red X's are missing altogether.

Thanks!

(Clarification: I do not expect one person to do every single structure class and every single decorator class. This really is a tracking ticket for a bunch of pull requests...)

Several of the class decorators I built for the prototype were just adding single boolean properties, and applying them in clone operations. It'd be better to have a simple JSON file to specify what structures define simple boolean mix-ins. Then it's a simple matter of testing one. If one works, all of them work.

This is going to be fun. 😄

Spin-off of #28. This is about sending type structures from one thread or process to another. I'm not sure we need it...

• moveMembersTo(interfaceOrObjectLiteral)
• ClassMembersMap::fromTypeMembers(typeMembers: TypeMembersMap): ClassMembersMap

Top priority is TypeParameterDeclarationImpl and TypeParameterConstraintMode, for blocking #28.

This is an optimization for later in the stage.

As I develop this, I need some way of measuring how closely stage 3's snapshot is converging on stage 2's snapshot. Various things I need to check for:

• Missing files
• Extra files
• Base files not matching
• Missing or different class properties (type, initializer)
• Static methods missed or different (parameter names, types, return type, body)
• Constructor missed or different (parameter names, types, return type, body)
• Missing or different TSDoc comments
• Missing or different Markdown documentation
• Decorators: wrapper function different parameters, return type, body
• Structures: mixin class different
• Hash of file

There should be three modes of output:

• Console with ANSI color-escaped characters
• Markdown file for details
• JSON file for Jasmine tests to check

The statements property is probably too loose with the StatementStructures type.

In order to implement #19, I need to convert every structure instance from SourceFileImpl on down into its equivalent structure, without writer functions.

This is because NodeJS can't send objects or functions to child processes.

A mix-in decorator class may have properties like typeStructure, but if we don't report that in the decorator class's fields, TypeScript won't know about it.

See #19. This will be useful for parallelizing ts-morph runs in stage 2.

The stage_2_docs directory was a mistake. Well-intentioned, but ignoring the need to add the equivalent of stage_1_bootstrap/prototype-snapshot/bootstrap into the second stage.

I was just bitten by TypeStrong/ts-node#1997 for development. This isn't necessarily fatal (thank you, nvm), but it does make me question whether general use of this project is possible.

In particular, when people should use the structures ("new code"), versus when they should directly use ts-morph ("existing code").

It would be a very good replacement for LiteralTypeStructureImpl, especially since it's easier to check type: number than type: string.

Edit: Maybe not a replacement. I'm rethinking the deprecation of LiteralTypeStructureImpl.

Because it could be really useful. A need for a type-to-class generator started me down this path with ts-morph in the first place.

TypeScript playground for illustration

Example: ModuleNamedNodeStructureMixin. We could just replace that with NamedNodeStructureMixin.

I also need to make sure no file contains "#stage_two" in stage_two/snapshot.

Certain existing build utilities (ImportManager, ExportManager, probably ClassMembersMap) are proving useful enough to make part of the source code. Others, such as a type-to-class feature (#13), and a structures factory (#5) are going to be useful in the future.

If a decorator only has one user, it's better to merge that decorator's fields into the user and not generate the decorator mixin.

export function createSourceFile(...): SourceFileImpl {
}

export function createClassDeclaration(...): ClassDeclarationImpl {
}

Then, in exports.ts,

export * as StructuresFactory from "./snapshot/StructuresFactory.js";

I've reserved snapshot/docs for drafting GitHub Pages documentation. I need to be able to show the impact of changing structure fields.

One possibility: GitHub Markdown supports the diff language.

See #6 for TSDoc.

We need a type structure walker. They can become quite complex.

• Enter and leave traps
• Filter based on structure kind
• Accept on enter structure filter
• Accept on leave structure filter

https://www.npmjs.com/package/ts-node#swc-1

It might be too soon to do it now. But with Visual Studio Code (and probably rollup later on), I already have the type checking in place.

TypeStrong/ts-node#1997 (comment) provided important clues.
7c5216c is the commit to back out.

https://api-extractor.com/

I've been struggling conceptually about how to generate code samples for these class structures. One option I've been considering is using the stage 2 snapshot to modify itself.

So I'm going to create a stage_2_docs directory, whose sole purpose is to host two copies of the output from stage 1. The first copy I'll use to modify the second copy, adding documentation. The second copy will go on to become the stage 2 snapshot.

Bonus: more dogfooding.

TypeScript's SyntaxKind enum has a few conflicts in it, which led me to confusion when looking up AssertEntry (301) and not finding examples of it. The updated name is ImportAttribute (also 301), which this repository does generate a structure for.

The fixes need to go in stage_1_bootstrap/build/structureToSyntax.ts.

I'm getting locked into a pattern that isn't scalable. The final rolled-up bundle won't care, but I'm already starting to write documentation which will care.

Benefits:

• Conciseness and clarity: new MethodDeclarationImpl("foo", true);
• ClassMembersMap could be a public utility

Downside:

• Sacrificing a little flexibility.

https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#onschedule

I'd really like to set up a weekly build against release candidates of TypeScript and ts-morph. The idea is when I'm away, we can catch bustages up front.

This is more of a "nice to have" than an actual requirement.

This tool is centered on generating the structures classes via ts-morph and using existing structure classes. The downside is this means it will be harder to create human-readable documentation, including tsdoc and examples of each structure's attributes impact on the resulting generated code.

For instance, it's obvious what AsyncableNodeStructure provides: an isAsync attribute for adding the async keyword. But if you don't know this field exists, how are you going to discover it, or what its value does to ts-morph?

A not-so-obvious example is assertElements from ImportDeclarationImpl. The prototype snapshot initially thought this had to be defined as an array, but this led to unexpected assert {} at the end of the import statement.

Example: MethodDeclarationImpl.

This is about occasionally needing as FooDeclarationImpl[] in using ts-morph-structures.

If not possible, explain why in a README file.