Document --isolate-workspaces + reword principal → program

packages/docs/src/content/docs/guides/performance.md

@@ -51,7 +51,7 @@ messages like this:
 
 ```sh
 ...
-[*] Installed 2 principals for 29 workspaces
+[*] Installed 2 programs for 29 workspaces
 ...
 [*] Analyzing used resolved files [P1/1] (123)
 ...

packages/docs/src/content/docs/reference/cli.md

@@ -59,6 +59,21 @@ Total running time: 5s (mem: 631.27MB)
 - `median`: the median invocation
 - `sum` the accumulated time of all invocations
 
+### `--isolate-workspaces`
+
+By default, Knip optimizes performance by adding eligible workspaces to existing
+TypeScript programs, based on the compatibility of their `compilerOptions`. Use
+this flag to disable this behavior and create one program per workspace.
+
+You can see the behavior in action in [debug mode](#--debug). Look for messages
+like this:
+
+```sh
+[*] Installed 4 programs for 18 workspaces
+...
+[*] Analyzing used resolved files [P1/1] (78)
+```
+
 ## Configuration
 
 ### `--config [file]`

packages/knip/src/index.ts

@@ -265,7 +265,7 @@ export const main = async (unresolvedConfiguration: CommandLineOptions) => {
 
   const principals = factory.getPrincipals();
 
-  debugLog('*', `Installed ${principals.length} principals for ${workspaces.length} workspaces`);
+  debugLog('*', `Created ${principals.length} programs for ${workspaces.length} workspaces`);
 
   const analyzedFiles = new Set<string>();
   const exportedSymbols: Exports = new Map();

packages/knip/src/util/cli-arguments.ts

@@ -19,7 +19,7 @@ Options:
   --fix                    Fix issues
   --fix-type               Fix only issues of type, can be comma-separated or repeated (2)
   --include-entry-exports  Include entry files when reporting unused exports
-  --isolate-workspaces     Isolated workspaces in monorepo
+  --isolate-workspaces     Isolate workspaces into separate programs (default: false)
   -n, --no-progress        Don't show dynamic progress updates (automatically enabled in CI environments)
   --preprocessor           Preprocess the results before providing it to the reporter(s), can be repeated
   --preprocessor-options   Pass extra options to the preprocessor (as JSON string, see --reporter-options example)