docs(reanalyze): add DCE refactor plan

[cristianoc]

This PR introduces a planning document for refactoring the reanalyze dead code analysis into a pure, order-independent pipeline.

• Adds , which:
  • Describes the desired end-state architecture for dead code analysis.
  • Catalogues current sources of mutation and order dependence.
  • Breaks the refactor into small, behaviour-preserving steps that can be tackled in independent PRs.

There are no behavioural changes in this PR: it only adds documentation to coordinate subsequent work on the dead code analysis pipeline.

[pkg-pr-new]

Open in StackBlitz

rescript

npm i https://pkg.pr.new/rescript-lang/rescript@8043

@rescript/darwin-arm64

npm i https://pkg.pr.new/rescript-lang/rescript/@rescript/darwin-arm64@8043

@rescript/darwin-x64

npm i https://pkg.pr.new/rescript-lang/rescript/@rescript/darwin-x64@8043

@rescript/linux-arm64

npm i https://pkg.pr.new/rescript-lang/rescript/@rescript/linux-arm64@8043

@rescript/linux-x64

npm i https://pkg.pr.new/rescript-lang/rescript/@rescript/linux-x64@8043

@rescript/runtime

npm i https://pkg.pr.new/rescript-lang/rescript/@rescript/runtime@8043

@rescript/win32-x64

npm i https://pkg.pr.new/rescript-lang/rescript/@rescript/win32-x64@8043

commit: 176d7cc

[fhammerschmidt]

I don't see an explicit mention of monorepos or npm/yarn/pnpm workspaces. In this context "dependencies" only refer to other files, but there is still the missing use case when one has shared code like this:

.
├── common
│   ├── package.json
│   ├── rescript.json
│   └── src/
├── mobile
│   ├── package.json
│   ├── rescript.json
│   └── src/
├── web
│   ├── package.json
│   ├── rescript.json
│   └── src/
├── package.json
└── rescript.json

where the root package.json contains a workspace field like so:

"workspaces": [
  "common",
  "mobile",
  "web"
]

and the root rescript.json has

"dependencies": [
  "common",
  "mobile",
  "web",
]

And common/rescript.json is independent of any internal package (may still have external dependencies in a real-world setup):

"dependencies": []

Whereas both web/rescript.json and mobile/rescript.json are dependent on the common package and thus contain:

"dependencies": [
  "common"
]

And we want DCE to mark stuff as dead that is part of common but not used anywhere in the mobile or web package.

This needs to be an option to configure because when e.g. developing a library with tests, I might have tests dependent on the main package, but not 100 % coverage.

The knowledge about package manager monorepos is mostly in rewatch. I imagine if this is all pure and separated now the final result can be recalculated based on a reanalyze includeDependencies: ["common"] option or something.

Also tagging @nojaf and @DZakh who are users of bun and pnpm monorepos.

[cristianoc]

I don't see an explicit mention of monorepos or npm/yarn/pnpm workspaces. In this context "dependencies" only refer to other files, but there is still the missing use case when one has shared code like this:

.

├── common

│   ├── package.json

│   ├── rescript.json

│   └── src/

├── mobile

│   ├── package.json

│   ├── rescript.json

│   └── src/

├── web

│   ├── package.json

│   ├── rescript.json

│   └── src/

├── package.json

└── rescript.json

where the root package.json contains a workspace field like so:

"workspaces": [

  "common",

  "mobile",

  "web"

]

and the root rescript.json has

"dependencies": [

  "common",

  "mobile",

  "web",

]

And common/rescript.json is independent of any internal package (may still have external dependencies in a real-world setup):

"dependencies": []

Whereas both web/rescript.json and mobile/rescript.json are dependent on the common package and thus contain:

"dependencies": [

  "common"

]

And we want DCE to mark stuff as dead that is part of common but not used anywhere in the mobile or web package.

This needs to be an option to configure because when e.g. developing a library with tests, I might have tests dependent on the main package, but not 100 % coverage.

The knowledge about package manager monorepos is mostly in rewatch. I imagine if this is all pure and separated now the final result can be recalculated based on a reanalyze includeDependencies: ["common"] option or something.

Also tagging @nojaf and @DZakh who are users of bun and pnpm monorepos.

This is a behavior preserving refactor.
Which btw makes it easier to add features in future.