[api-extractor] Preserve copyright notice comment in dts rollup

[jonnycornwell]

Summary

Not sure if this is a bug or enhancement but It would be good if there was a way to preserve a copyright notice comment when doing d.ts rollup. I think it should probably do it by default but would be good to at least have the option. Currently I am having to patch the copyright notice back in after running the rollup.

Repro steps

Run API extractor targeting an entry point d.ts file which contains a copyright notice: index.d.ts

/*!
 * Copyright FOO
 * SPDX-License-Identifier: MIT
 */
export * from './foo';
...

Expected result: Copyright header is preserved

myPackage.d.ts

/*!
 * Copyright FOO
 * SPDX-License-Identifier: MIT
 */
import { ... } from 'foo';

/**
 * @public
...

Actual result: Copyright header is removed myPackage.d.ts

import {...} from 'foo';

/**
 * @public
...

Details

Related links https://github.com/microsoft/TypeScript/issues/12307#issuecomment-311204590 https://github.com/microsoft/TypeScript/issues/4734 zulip thread

Standard questions

Please answer these questions to help us investigate your issue more quickly:

Question	Answer
@microsoft/api-extractor version?	n/a
Operating system?	n/a
API Extractor scenario?	rollups
Would you consider contributing a PR?	Yes but would need to be pointed in the right direction!
TypeScript compiler version?	n/a
Node.js version (node -v)?	n/a

[octogonz]

@jonnycornwell This is a great suggestion. We would definitely use this feature in our own projects.

Design:

How should API Extractor obtain the header? Some possible options:

1. A JSON string configured in api-extractor.json, for example a setting like "fileHeader" under the "dtsRollup" section.
2. It could be inferred automatically. For example look for the first non-doc-comment (i.e. /* or // but not /**) in the entry point file (e.g. src/index.d.ts). If that comment contains the word "Copyright" or "License", then guess that it is probably the copyright banner. For such a heuristic, there should be a setting to disable it (e.g. "disableHeaderDetection": true in api-extractor.json)
3. Or that same idea could be done without a heuristic. For example, you maybe you specify "preserveFirstCommentAsHeader": true under "dtsRollup", and then whatever code comment appears at the top of the entry point (e.g. src/index.d.ts) will be copied to be the first comment in the .d.ts rollup. This would be an off-by-default setting.
4. Another idea would be that the @packageDocumentation comment would specify it somehow (e.g. special TSDoc block like @copyright?)

Edit: The @packageDocumentation comment is already preserved in the output, so I changed the TSDoc tag name.

[octogonz]

We could also combine ideas 2 and 3:

5. The "preserveFirstCommentAsHeader" setting has three possible values:
   • "auto" (the default) - preserves the first comment from the entry point, but only if it contains the word "copyright" or "license" and is not a /** comment
   • "never" - the feature is disabled
   • "always" - the first comment is always preserved

(The reason for ignoring /** comments is that otherwise we need to consider: (1) what if the first comment is the @packageDocumentation comment? (2) what if the first comment is actually API docs and doesn't make sense as a file header?)

Some edge cases:

• If the first comment is entirely absent, should "always" report an error? (I slightly favor Yes)
• If the first comment is a /** comment, should "always" copy it anyway? Yes means if it is the @packageDocumentation comment or an API comment, it might get copied twice. No means developers need to properly format their copyright comment. (I slightly favor No)

[alexweininger]

Following up on this since the issue hasn't had updates for a while.

We'd really like to have this feature to not only add/preserve a copyright header, but also a comment to warn developers that the file is auto generated and to not edit it.