Allow tools to add information about objects

[magwas]

Suggestion

🔍 Search Terms

label:"Domain: Declaration Emit"

✅ Viability Checklist

My suggestion meets these guidelines:

• [x ] This wouldn't be a breaking change in existing TypeScript/JavaScript code
• [x ] This wouldn't change the runtime behavior of existing JavaScript code
• [x ] This could be implemented without emitting different JS based on the types of the expressions
• [x ] This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
• [x ] This feature would agree with the rest of TypeScript's Design Goals.

⭐ Suggestion

NO, this is NOT a duplicate of #41165 in any way.

Clean Code rules say that comments should not be written, the purpose of classes/functions/etc should be apparent from name, and the use of them should be apparent from appropriately named /annotatedtests/contracts. This rule have very good reasons.

The UI helps coders by showing the comments in the declaration file.

That means that in a Clean Code project, important informations for the coder can be harder to retrieve.

A solution to this is to use information provided by testing/contract checking frameworks to pass information to the compiler, which it can emit as comment in the declaration file.

Probably a json file containing the generated description for the emitted items would be a nice interface.

As the developer of https://github.com/kode-konveyor/cdd-ts a contract-checking framework I would be happy to discuss how such an interface should look like, provide reference implementation generating it, and even make a pull request to the compiler if I get some hints on where to put the changes.

📃 Motivating Example

I have my "check" function, written in Clean code, about which vscode now tells me the following: (method) Check<T extends SutType>.check(contract: ContractEntity<T>, sut: T): number

Note that there is nothing there beyond the call signature.

I could add a comment saying something like the following, which would be dutifully displayed by vscode, and be outdated at the moment I write it down.:

/*
check checks whether the contract actually corresponds to the behaviour of the SUT
 * it returns the number of runs checked in the contract"
 * if there is no ifCalledWith, a 'no ifCalledWith' error is thrown
 * if the return value is not according to the contract a 'return value mismatch' error is thrown
 * if a return value check fails, a 'return value check did not hold' error is thrown
 * with a 'when' we can use an environment manipulator to set up the environment
*/

Meanwhile I have the following contract for my check function, containing all the above information, and checked in each build. And the contract checker could easily provide the content of the above comment, up to date and checked to be true at all times.

export const CheckContract = 
    new Contract<(contract: Contract<typeof testedFunction>,fun: typeof testedFunction) =>number>()
    .setTitle("check checks whether the contract actually corresponds to the behaviour of the SUT")

    .ifCalledWith(getContract(),testedFunction)
    .thenReturn("it returns the number of runs checked in the contract",1)

    .ifCalledWith(getContractWithoutIfcalledWith(),testedFunction)
    .thenThrow("if there is no ifCalledWith, a 'no ifCalledWith' error is thrown",RUN_IDENTIFICATION+" no ifcalledWith")


    .ifCalledWith(getContractWithOtherReturnValue(),testedFunction)
    .thenThrow("if the return value is not according to the contract a 'return value mismatch' error is thrown",RegExp(RUN_IDENTIFICATION+" return value mismatch:.*expected:.2.*actual  :.1","ms"))
 
    .ifCalledWith(getContractWithFailingReturnvalueCheck(),testedFunction)
    .thenThrow("if a return value check fails, a 'return value check did not hold' error is thrown",RUN_IDENTIFICATION+" fail: return value check did not hold")
 
    .ifCalledWith(getContractWithACase(),testedFunction)
    .thenReturn("with a 'when' we can use an environment manipulator to set up the environment",2)

💻 Use Cases

I would like to use it to "end discrimination of Clean Code projects by the IDE" :), as today users of libraries of clean code projects have less information available than old-style projects with comments.

In the meantime I look up tests/contracts, try to keep the info in my head, or experiment with code as workarounds.

[MartinJohns]

Duplicate of #53205.

[magwas]

Duplicate of #53205.

Which is erroneously closed, as a duplicate of #41165, which it is not.

[MartinJohns]

What you want can already be achieved by writing a language service plugin.

[magwas]

Now, this is an answer. Closing as invalid.