[api-extractor] wrong model reference from an interface to a property variable

[sranka]

Summary

Having a symbol variable that is used in an interface as a property key, when I run api-extractor, the model json file contains an invalid pointer from the interface to the variable.

Repro steps

It is reproducible with a simple ts file on input:

export const FLUX_VALUE = Symbol("FLUX_VALUE");
export interface FluxParameterLike {
  [FLUX_VALUE](): string;
}

I created a complete project so that it is easy to reproduce:

git clone [email protected]:sranka/api_extractor_defect2.git
yarn
yarn build
yarn extract
yarn document

Expected result: The model JSON file references FLUX_VALUE using a canonicalReference that is defined, i.e:

"canonicalReference": "api_extractor_defect!FLUX_VALUE:var "

Actual result: The model JSON file references FLUX_VALUE (https://github.com/sranka/api_extractor_defect2/blob/master/docs/api_extractor_defect.api.json#L260) wrongly as

"canonicalReference": "api_extractor_defect!FLUX_VALUE"

, but it was defined in https://github.com/sranka/api_extractor_defect2/blob/master/docs/api_extractor_defect.api.json#L177 as

"canonicalReference": "api_extractor_defect!FLUX_VALUE:var"

Details

This issue actually happens in @influxdata/influxdb-client-js, it validates references in the api model files by a simple node.js script. The same script, as a workaround, is also capable to repair wrong references.

I posted the defect just to let you know about it.

Standard questions

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

Question	Answer
@microsoft/api-extractor version?	7.31.0
Operating system?	Linux
API Extractor scenario?	docs (.api.json)
Would you consider contributing a PR?	yes, if I would know the way of how to fix it
TypeScript compiler version?	4.7 and 4.8
Node.js version (node -v)?	16

[zelliott]

I haven't looked closely, but I'm guessing that "api_extractor_defect!FLUX_VALUE:var" is the right reference.

The reference "api_extractor_defect!FLUX_VALUE" is generated by the DeclarationReferenceGenerator class. The missing :var piece is called the "meaning". If you're interested in investigating & contributing a fix, a first step would to be to see why Meaning.Variable isn't being applied by DeclarationReferenceGenerator when constructing the reference for this item.

[sranka]

@zelliott it would be nice to have a document that describes how to contribute, something like this would help. Anyway, after a few failed best guesses, I was able to setup the project with rush install followed by rush build.

[zelliott]

Ah - there's https://rushstack.io/pages/contributing/get_started, sorry for not sharing that with you. Is that helpful?