Behavior difference: Block comments on `@typedef` structural types are not preserved, if they are imported and reconstructed as inline types in another file

[hkleungai]

A follow-up on #4235.

---

Steps to reproduce

1. Start a plain new project
   • "@typescript/native-preview": "7.0.0-dev.20260617.2",
   • "typescript": "6.0.3"
2. Run npx tsgo --init to get the default tsconfig. Turn on these flags as well.
   • "allowJs": true,
   • "checkJs": true,
   • "stableTypeOrdering": true,
3. Add the below files. Run npx tsc & npx tsgo to see the difference.

/** ========> src/lib.js <======== */
/**
 * @typedef {Object} Foo
 * @property {boolean} bool Whether `.bool` is true or not
 */
export class C {
    /** @returns {Foo} */
    getFoo() { return { bool: false }; }

    /**
     * @typedef {Object} Bar
     * @property {boolean} bool Whether `.bool` is true or not
     */
    /** @returns {Bar} */
    getBar() { return { bool: false }; }
}

/** ========> src/mainJs.js <======== */
import { C } from './lib.js';

export class MainJs {
    constructor() {
        this.c = new C();
    };

    getFoo() { return { ...this.c.getFoo() }; }
    getBar() { return { ...this.c.getBar() }; }
}

/** ========> src/mainTs.ts <======== */
import { C } from './lib.js';

export class MainTs {
    constructor(public c: C) {};

    getFoo() { return { ...this.c.getFoo() }; }
    getBar() { return { ...this.c.getBar() }; }
}

Behavior with typescript@6.0

/** ========> dist/mainJs.d.ts <======== */
export class MainJs {
    c: C;
    getFoo(): {
        /**
         * Whether `.bool` is true or not
         */
        bool: boolean;
    };
    getBar(): {
        /**
         * Whether `.bool` is true or not
         */
        bool: boolean;
    };
}
import { C } from './lib.js';

/** ========> dist/mainTs.d.ts <======== */
import { C } from './lib.js';
export declare class MainTs {
    c: C;
    constructor(c: C);
    getFoo(): {
        /**
         * Whether `.bool` is true or not
         */
        bool: boolean;
    };
    getBar(): {
        /**
         * Whether `.bool` is true or not
         */
        bool: boolean;
    };
}

Behavior with tsgo

/** ========> dist/mainJs.d.ts <======== */
import { C } from './lib.js';
export declare class MainJs {
    c: C;
    constructor();
    getFoo(): {
        bool: boolean;
    };
    getBar(): {
        bool: boolean;
    };
}

/** ========> dist/mainTs.d.ts <======== */
import { C } from './lib.js';
export declare class MainTs {
    c: C;
    constructor(c: C);
    getFoo(): {
        bool: boolean;
    };
    getBar(): {
        bool: boolean;
    };
}

[jakebailey]

You're expecting the comments from another file to come along? If that was happening, I feel like that is a bug in the old codebase.

[hkleungai]

But why not? If the transpiler is reconstructing an existing type in-place, shouldn't the original block comment be brought over to the new types as well? 😕

[jakebailey]

We don't do that for TS, no?

[hkleungai]

Without any meaningful insight on how the transpiler works, my thought (as a consumer) goes like this.

1. A structural object shape can be established via jsdoc, and become an actual valid type in the emit.
2. Then, consuming this typedef in another lines or files should work just fine.
   a. Each attribute type can be identified when being consumed or referred.
   b. Each attribute comment (as well as top comment for the whole type itself) can be inherited, so that they remain visible to IDE / LSP users.

The fact that the above codes I give has each attribute type done right is accomplishing (2a); I think it should be reasonable to expect (2b) done right too.

In fact we have both perfectly in TS 6, when consuming such type in both .js and .ts file.

Of course, my expectation here may not align with the actual transpiler design, since I never really look into how these things are implemented... 😅

[weswigham]

The old JS .d.ts emitter operated symbolically and went out of its' way to copy comments on property signatures and type aliases - see the preserveCommentsOn helper and other uses of setSyntheticLeadingComments in the checker in the old codebase. The current node builder in corsa largely predates us adding support for setSyntheticLeadingComments, which finally got ported along with the class fields transform, which'd be the only reason the functionality's missing, afaik.

Complicating this a bit is that typedefs are transformed in the reparser now, but there's no emit context available to attach the synthetic comment to the reparsed node... (property signatures, meanwhile, should be fine - just reimplement preserveCommentsOn inside addPropertyToElementList instead of using a raw setCommentRange)