Add e2e tests w/ tsgo defs + lib consumption

Author: webpro

.agents/EXPORTS.md

@@ -1,16 +1,14 @@
 # Identifiers, Symbols & Matching
 
-## The v5→v6 shift
-
-v5 used TypeScript's typechecker for binding/symbol identity — two identifiers
-with the same name in different scopes were distinct symbols. v6 migrated to OXC
-(no typechecker), so matching is name-based. This creates false negatives when
-local bindings shadow exported names.
+How knip resolves "is this export used?" across an AST. Matching is name-based;
+the sections below cover the cases that need extra care.
 
 ## Shadow detection
 
-`isShadowed(name, pos)` checks whether a reference at a given position falls
-inside a scope that shadows that name. Shadows are registered via:
+Name-based matching produces false negatives when a local binding shadows an
+exported name of the same spelling. `isShadowed(name, pos)` returns true if the
+reference at `pos` falls inside a scope that shadows `name`. Shadows are
+registered via:
 
 - `_addShadow`: block-scoped variables and nested function declarations
   (uses current `scopeDepth` range from `BlockStatement`)
@@ -23,55 +21,68 @@ inside a scope that shadows that name. Shadows are registered via:
 `_collectBindingNames` recurses into destructuring patterns (ObjectPattern,
 ArrayPattern, AssignmentPattern, RestElement) to extract all bound Identifiers.
 
-## `referencedInExport`
-
-Maps exported identifier → set of export names whose type annotations reference
-it. Only for type-level exports, NOT function signatures. Type→type chains are
-followed; type→function chains do not keep types alive. Interface `extends`
-clauses captured via `addRefInExport`.
+## `ignoreExportsUsedInFile`
 
-## `isReferencedInUsedExport`
+Opt-in config (default `false`).
 
-Called in `analyze.ts` for exports NOT directly imported. Returns true only
-through the `ignoreExportsUsedInFile` chain: a containing export has
-`hasRefsInFile` and is a type/interface (checked recursively).
+**Default semantics match tsc/tsgo.** An export only referenced in its own file
+is reported as unused, because removing the `export` keyword leaves the program
+and `.d.ts` valid. Types are structurally inlined: a consumer importing
+`UserInfo = { address: Address }` does not require `Address` to be exported.
+Same for `typeof X` references inside type aliases. So `Address` is correctly
+flagged. Opting `true` is a code-organization preference, not a correctness
+concern.
 
-Does *not* keep inner exports alive just because the containing export is
-imported externally. Per tsc semantics, types are structurally inlined — a
-consumer importing `UserInfo = { address: Address }` does not require `Address`
-to be exported (tsc will emit a `declare`-private decl in the `.d.ts`). So
-`Address` is correctly flagged as an unused export. Same applies to `typeof X`
-references inside type aliases.
+**With the config on.** `localRefsVisitorObject` populates `localRefs` during
+AST traversal. Exports present in `localRefs` get `hasRefsInFile = true`.
+`shouldCountRefs` gates eligible types. Computed member access
+(`obj[EXPORTED_KEY]`) is handled.
 
-## `ignoreExportsUsedInFile`
+`analyze.ts` reads this via `isReferencedInUsedExport` for exports not directly
+imported: returns true only when a containing export has `hasRefsInFile` and is
+a type/interface (recursively checked). Alive-ness does not cascade through
+external imports; inner refs stay scoped to the in-file relationship.
 
-Opt-in config. When enabled, `localRefsVisitorObject` populates `localRefs`
-during AST traversal. Exports in `localRefs` get `hasRefsInFile = true`.
-`shouldCountRefs` gates eligible types. Handles computed member access
-(`obj[EXPORTED_KEY]`).
+## `referencedInExport` (type-chain refs)
 
-Note: when a namespace/enum has export-level `hasRefsInFile = true` but is NOT
-externally imported, `analyze.ts` skips the member check entirely — unused
-members silently pass. This is by design (the export is considered "used").
+Maps exported identifier → set of export names whose type annotations reference
+it. Type-level only, not function signatures. Type→type chains are followed;
+type→function chains do not keep types alive. Interface `extends` clauses
+captured via `addRefInExport`. Feeds the recursive type/interface check in
+`isReferencedInUsedExport` above.
 
 ## Namespace/enum member `hasRefsInFile`
 
 `ExportMember.hasRefsInFile` (separate from export-level `Export.hasRefsInFile`)
-is set via deferred resolution: during the walk, same-file member references
+is set via deferred resolution. During the walk, same-file member references
 (e.g. `Bar.value`) are pushed as interleaved pairs to a flat
 `memberRefsInFile: string[]` on `WalkState`. After the walk, pairs are resolved
 against the final `exports` map.
 
-Deferred because the AST visitor walks source-order — forward references to
+Deferred because the AST visitor walks source-order; forward references to
 namespace members defined later in the file would miss inline resolution. Same
 pattern as `bareExprRefs`.
 
 Collection: `handleMemberExpression` (3 depth levels) and
 `coreVisitorObject.TSQualifiedName` push pairs to `memberRefsInFile`.
 `localRefsVisitorObject.TSQualifiedName` only adds the namespace name to
-`localRefs` (no member push — core handler covers it). Resolution in `walkAST`
-post-walk.
+`localRefs` (no member push, core handler covers it). Resolution happens in
+`walkAST` post-walk.
 
 In `analyze.ts`: for referenced namespace/enum exports, members without
 `hasRefsInFile` are checked via `explorer.isReferenced(filePath, "Ns.member")`.
 If neither, reported as unused.
+
+**Edge case:** when a namespace/enum has export-level `hasRefsInFile = true`
+but is NOT externally imported, `analyze.ts` skips the member check entirely.
+Unused members silently pass. By design (the export itself is considered
+"used").
+
+## E2E
+
+`packages/knip/test/e2e/fix-tsgo.test.ts` is the safety net for the resolution
+paths above. Each fixture builds clean under tsgo, has `knip --fix` run on it,
+then must build clean under tsgo again. A failing post-fix build means knip
+removed something tsc/tsgo still needs: a false positive in one of these
+mechanisms. The `e2e-lib-*` variants extend the round-trip to a consumer so
+type-visibility regressions also fail.

packages/knip/fixtures/e2e-lib-namespace-subpaths/_index.ts

@@ -0,0 +1,7 @@
+import * as Lib from '@fixtures/e2e-lib-namespace-subpaths';
+import { greet, type Greeting } from '@fixtures/e2e-lib-namespace-subpaths/utils';
+
+const a: Greeting = greet('world');
+const b: Lib.Greeting = Lib.Utils.greet('hello');
+a;
+b;

packages/knip/fixtures/e2e-lib-namespace-subpaths/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@fixtures/e2e-lib-namespace-subpaths",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./utils": {
+      "types": "./dist/utils/index.d.ts",
+      "default": "./dist/utils/index.js"
+    }
+  }
+}

packages/knip/fixtures/e2e-lib-namespace-subpaths/src/index.ts

@@ -0,0 +1,2 @@
+export * as Utils from './utils/index.js';
+export type { Greeting } from './utils/types.js';

packages/knip/fixtures/e2e-lib-namespace-subpaths/src/utils/greet.ts

@@ -0,0 +1,5 @@
+import type { Greeting } from './types';
+
+export const greet = (name: string): Greeting => ({ name });
+
+export const internalUnused = 1;

packages/knip/fixtures/e2e-lib-namespace-subpaths/src/utils/index.ts

@@ -0,0 +1,2 @@
+export { greet } from './greet.js';
+export type { Greeting } from './types.js';

packages/knip/fixtures/e2e-lib-namespace-subpaths/src/utils/types.ts

@@ -0,0 +1,5 @@
+export type Greeting = {
+  name: string;
+};
+
+export type DraftGreeting = string;

packages/knip/fixtures/e2e-lib-namespace-subpaths/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+  },
+  "include": ["src/**/*.ts"]
+}

packages/knip/fixtures/e2e-lib-public-surface/_index.ts

@@ -0,0 +1,3 @@
+import { pickFruit, type Fruit } from '@fixtures/e2e-lib-public-surface';
+const x: Fruit = pickFruit('apple');
+x;

packages/knip/fixtures/e2e-lib-public-surface/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "@fixtures/e2e-lib-public-surface",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  }
+}