Fully adapt core package and associated tests to TypeScript

[ryoarmanda]

(Updated as of 21/04/2022)

This is an epic-type issue to track of our TypeScript migration of the core package. Feel free to edit this as we go along.

Interested migration developers can get started by checking out the Migrating to TypeScript page in our developer's guide.

Dependency graph of remaining js files

(There are some files not presented that are still under consideration on whether to be adapted to TypeScript or leave as-is)

Click the image to view it all full resolution:

The green files are ones that do not have any static dependencies to another file and are highly recommended to migrate first. However, the graph is not 100% accurate, as there are green files that have dynamic imports (like in Plugin.js) or have constants documented to be typed as other files' classes (like PageConfig.js and SiteConfig.js)

Which one should I adapt first?

As mentioned, it is highly recommended that we go through files that do not have any dependencies, and collectively work through the dependency graph upwards until the root, meaning that we perform the migration in topological order.

Though possible to migrate not in topological order, the effort will be much more as you have to be able to infer simple types as a "stand-in" of the dependencies that are not yet migrated.

You can adapt multiple related files residing in the same folder in one migration. For example, you might adapt Plugin.js and PluginManager.js together.

Note that when you adapt a file, you also have to adapt the associated tests as well. For example, adapt linkProcessor.js together with linkProcessor.test.js.

Files checklist

(There are some files not presented that are still under consideration on whether to be adapted to TypeScript or leave as-is)

package root

• index.js

src

• errors (Adopt TypeScript for core package #1877)
  • CyclicReferenceError.js
  • index.js
• External
  • External.js
  • ExternalManager.js
• html
  • codeblockProcessor.js
  • constants.js
  • Context.js
  • elements.js
  • FootnoteProcessor.js
  • headerProcessor.js
  • includePanelProcessor.js
  • linkProcessor.js
  • MarkdownProcessor.js
  • MdAttributeRenderer.js
  • NodeProcessor.js
  • scriptAndStyleTagProcessor.js
  • siteAndPageNavProcessor.js
  • SiteLinkManager.js
  • vueSlotSyntaxProcessor.js
  • warnings.js
• Layout (partial work done in this closed PR Migrate Layout File to Typescript #2164)
  • index.js
  • Layout.js
  • LayoutManager.js
• Page
  • index.js
  • PageConfig.js
  • PageSources.js
  • PageVueServerRenderer.js
• lib/markdown-it
  • index.js
  • utils/index.js
  • highlight directory
  • plugins/markdown-it-icons
  • the rest are plugins that has a huge proportion (> 95% source) adapted from somewhere, we originally discussed not to adapt to maintian easy reference. They are also fairly isolated so benefits of TS may not be that great. But this is revisitable.
• plugins
  • Plugin.js
  • PluginManager.js
  • all the plugins (feel free to expand it on an edit)
    • algolia.js
    • disqus.js
    • filterTags.js
    • googleAnalytics.js
    • mathDelimiters.js
    • codeBlockCopyButtons.js
    • codeBlockWrapButtons.js
    • default
      • markbind-plugin-plantuml.js
      • markbind-plugin-anchors.js
      • markbind-plugin-shorthandSyntax.js
      • markbind-plugin-tree.css
      • markbind-plugin-tree.js
• Site
  • constants.js
  • index.js
  • SiteConfig.js
• utils (Adopt TypeScript for core package #1877)
  • async.js
  • delay.js
  • fsUtil.js
  • git.js
  • logger.js
  • urlUtil.js
• variables
  • VariableProcessor.js
  • VariableRenderer.js
• constants.js

template

• template.js

test/unit

• html
  • includePanelProcessor.test.js
  • linkProcessor.test.js
  • NodeProcessor.data.js
  • NodeProcessor.test.js
  • SiteLinkManager.test.js
• plugins/default
  • anchor.test.js
  • plantuml.test.js
  • shorthandSyntax.test.js
  • tree.test.js
• lib/nunjucks-extensions
  • nunjucks-date.test.js
  • set-external.test.js
• utils
  • data.js
  • utils.js
• markdown-it-icons.test.js
• Site.test.js

[ang-zeyu]

@MarkBind/active-devs please help to tackle this ticket if you are interested. Just check any unchecked boxes above, and start implementing away.

Type safety is a very nice prequisite to have to performing larger scale refactors, and can serve as good documentation in of itself. Amongst many other things.

[raysonkoh]

3281 students feel free to help tackle this too! I think it isn't very difficult and it would be a great way to learn the codebase and suggest ways in which it can be improved.

Process-wise, in order to prevent a conflict in work done, you can either open a WIP draft PR, or update the list above with your name.

[yiwen101]

Could I have a try; I wish to try completing the #2164 , migrate the layout to typescript

[yiwen101]

Migration completed excepts for plugins that were decided to not migrate to typescript.