Module/interface augmentation doesn't preserve import for declaration emit

[OliverJAsh]

🔎 Search Terms

• project references
• module/interface augmentation

🕗 Version & Regression Information

• This is the behavior in every version I tried, and I reviewed the FAQ for entries about project references.

⏯ Playground Link

No response

💻 Code

Full reduced test case (contents inlined below): https://github.com/OliverJAsh/ts-project-references-augmentation-bug

package.json:

{
  "dependencies": {
    "fp-ts": "^2.16.1",
    "typescript": "^5.2.2"
  }
}

app/tsconfig.json:

{
    "compilerOptions": {
        "rootDir": "../",
        "outDir": "../target",
        "composite": true
    }
}

app/index.ts:

import * as ReadonlyTuple from 'fp-ts/ReadonlyTuple';

export const Apply = ReadonlyTuple.getApply({ concat: a => a });

demos/tsconfig.json:

{
    "compilerOptions": {
        "rootDir": "../",
        "outDir": "../target"
    },
    "references": [
        { "path": "../app/tsconfig.json" },
    ]
}

demos/index.ts:

import { Apply } from "../app/index";

Apply;

🙁 Actual behavior

A module in the "app" project imports the file node_modules/fp-ts/lib/ReadonlyTuple.d.ts. This file uses module and interface augmentation. Excerpt:

export declare const URI = 'ReadonlyTuple'
/**
 * @category type lambdas
 * @since 2.5.0
 */
export type URI = typeof URI
declare module './HKT' {
  interface URItoKind2<E, A> {
    readonly [URI]: readonly [A, E]
  }
}

When I later try to reference the "app" project from another project ("demos") using project references, I get a type error because the module/interface augmentation is not being applied:

$ yarn run tsc --build --verbose demos/tsconfig.json
yarn run v1.22.19
warning package.json: No license field
$ /Users/oliver/Code/reduced-test-cases/ts-project-references-augmentation-bug/node_modules/.bin/tsc --build --verbose demos/tsconfig.json
[13:49:06] Projects in this build:
    * app/tsconfig.json
    * demos/tsconfig.json

[13:49:06] Project 'app/tsconfig.json' is out of date because output file 'target/app/tsconfig.tsbuildinfo' does not exist

[13:49:06] Building project '/Users/oliver/Code/reduced-test-cases/ts-project-references-augmentation-bug/app/tsconfig.json'...

[13:49:06] Project 'demos/tsconfig.json' is out of date because output file 'target/demos/index.js' does not exist

[13:49:06] Building project '/Users/oliver/Code/reduced-test-cases/ts-project-references-augmentation-bug/demos/tsconfig.json'...

target/app/index.d.ts:1:63 - error TS2344: Type '"ReadonlyTuple"' does not satisfy the constraint 'keyof URItoKind2<any, any>'.

1 export declare const Apply: import("fp-ts/lib/Apply").Apply2C<"ReadonlyTuple", unknown>;
                                                                ~~~~~~~~~~~~~~~


Found 1 error.

🙂 Expected behavior

No error. The module/interface augmentation should be applied in the dependant project when it consumes the type declarations of the referenced project.

Additional information about the issue

I am able to workaround the issue by adding an explicit import of fp-ts/ReadonlyTuple in demos/index.ts.

[sheetalkamat]

The issue here is not project references but how d.ts is emitted. Assigning to @weswigham who knows more about this area to see if this is working as intended or there should be error or import should be preserved and can it even be determined.

For repro purposes you just need to build "app" and you will see that:

// app/index.ts
import * as ReadonlyTuple from 'fp-ts/ReadonlyTuple';
export const Apply = ReadonlyTuple.getApply({ concat: a => a });

generates following d.ts

// app/index.d.ts
export declare const Apply: import("fp-ts/lib/Apply").Apply2C<"ReadonlyTuple", unknown>;

Error goes away if the import is preserved.

[weswigham]

We used to have machinery to preserve required augmentations by adding /// <references to the declaration file (though determining this one is required would certainly be weird, with how indirect it is) - but we gave that up, reasoning that consumers should have to include those augmentations manually.

I'm not sure we have a viable remediation since we did #57681. We could add imports, but isn't that basically the same as adding /// references?

[weswigham]

@jakebailey thoughts?

[sheetalkamat]

I see .. I forgot about that PR .. but even the. I thought this would preserve the import as needed.. instead of generating .. but given how this type materializes may be not ..

[sheetalkamat]

I also think among users write these imports is better than we generating something but not biased towards either approach

[jakebailey]

I guess we didn't think about import elision, yeah. Under ID, the imports are never erased, but obviously there's no way to force it to stay otherwise besides verbatimModuleSyntax, writing import 'fp-ts/ReadonlyTuple' (maybe), or writing a plain reference.

I'm not sure how we can do this properly; the whole point of #57681 was to explicitly not rely on whole program info for preserving imports. That implies that manual intervention could be needed, but TS is clearly removing an import too.