[Draft] plan of action for completing JS->TS

[cacieprins]

In preparation for completing the conversion to TypeScript, defining a shared language to discuss the various states and categories of files and packages is useful for clear communication.

Package Status

• Unknown - this package still has .js files, and/or the state of its .ts files have not been determined. It is still linted by the root .eslintrc.
• Preliminary - this package may still have .js files, but it is set up to be linted at the preliminary level. All files have been categorized in a TYPESCRIPT.md file in the root of that package
• Ready - This package has no .js files, but its .ts files may have @ts-expect-error notations and implicit / explicit any types.
• Incomplete - tsconfig.json rules for any types are enabled, and there are no @ts-expect-error or @ts-ignore notations. There may yet be circular dependencies, implicit dependencies, etc.
• Complete - All .ts files follow the styleguide.

Source File Status

• Unknown - these are files that have not yet been addressed. .js files are Unknown. .ts files are Unknown if they have not yet been categorized as partial, incomplete, or complete.
• Partial - these files have been converted to .ts, but may have @ts-expect-error notations, implicit any types, and explicit any types. They do not yet follow the styleguide.
• Incomplete - these files have been converted to .ts. @ts-expect-error notations have been resolved, and there are no implicit or explicit any types. They do not yet follow the styleguide, however - there may be duplicated type definitions, circular dependencies, undeclared deep imports, etc.
• Complete - these files are considered "gold standard" for TypeScript, and follow the recommended style guide.

Package and File group categories

Packages and files, when considered as nodes in a dependency tree, can be categorized as "leaf," "shared," or "root."

• A Leaf node has no monorepo dependencies
• A Shared node depends on one or more nodes, and is the dependent of one or more node.
• A Root node is not imported by any nodes other than ./cli

Steps to Repo Conversion

• Draft a Styleguide. External style guide examples for reference: Google's TS guide, TSDev, StandardJS
  • Ensure there are rules in the styleguide regarding monorepo design as well: circular dependencies, deep undeclared imports, implicit dependencies, etc.
  • Ensure there are rules regarding promises and asynchronous code, all the better if those rules can be linted
  • Decide on which rules should be governed by each conversion pass. Earlier levels should warn on rules that later levels error on.
  • This styleguide should be saved in ./guides/style-guide.md, and linked to from the primary README.md
• Use ./npm/eslint-plugin-dev and the styleguide to define linting configs based on the package status categories defined above
  • Each package in the repo must have its own .eslintrc and package.json script for linting, as they will have different levels of enforcement
  • Each package's lint script must be called by the root linter script
  • Consider switching to prettier for format linting
• Categorize each package
• Planning Pass: Get to a "Preliminary" state in all packages
  • Leaf packages
  • Shared packages
  • Root Packages
• First Pass: Get to a "Ready" state in all packages
  • Leaf packages
  • Shared packages
  • Root packages
• Second pass: Get to a "Incomplete" state in all packages
  • Leaf packages
  • Shared packages
  • Root packages
• Final pass: Get to a "Complete" state in all packages.
  • Leaf packages
  • Shared packages
  • Root packages

Sample TYPESCRIPT.md

Typescript conversion status of this package: preliminary|ready|incomplete|complete

Check next to each file that meets the criteria for the next conversion level (ready|incomplete|complete):

• src/
  • index.js root
  • foo/
    • bar.ts shared
    • baz.js leaf