This is a tstl issue.

Thanks for investigating @andrewbranch, I appreciate it.

I thought the error was related to TypeScript because TSTL is producing correct LUA code, it's only the TypeScript compiler that complains. Can you provide more information on how you came to think that? What needs to change in TSTL to fix it?

I’m not 100% sure how it’s happening, but I was unable to reproduce the problem with TypeScript alone (whether with tsc or viewing errors in the editor). Also, I know we don’t issue name resolution errors on @link tags because doing so was a feature request we recently discussed that I argued we should decline. And the fact that the error appeared not on the JSDoc tag itself but on the usage of one of the things it decorated is very bizarre, which reads a lot like someone made a mistake leveraging the TS compiler. My investigation was pretty quick so there’s always a chance I’m wrong, but there was enough evidence that I feel comfortable saying you’d need to give a repro that doesn’t use external tools in order for me to believe the issue is not in the external tools.

This issue has been marked as 'External' and has seen no recent activity. It has been automatically closed for house-keeping purposes.

@andrewbranch I have done some further investigation, this looks to me like we are using the TS API as intended, if not please correct me where we are going wrong:

This diagnostic seems to happen when calling getJsDocTags() on the signature of the CallExpression script.on_init(() =>{ }).

Effectively what we are doing is (where callExpression is the code above):

typeChecker.getResolvedSignature(callExpression).getJsDocTags()

Full stacktrace of my little reproduction scenario is:

Digging a little further with my debugger it seems that getDisplayPartsFromComment is called with the following node:

Node at index 0 seems fine, but the second node seems a bit suspicious. node.kind is 324, which is SyntaxKind.JSDocLink as expected, what is weird that node.name is an identifier 'https'. It then tries to resolve this symbol as if it was referring to a variable in code in using checker.getSymbolAtLocation(link.name) in buildLinkParts which ends up adding the diagnostic via resolveEntityName on this https identifier.

I'm not sure what expected behavior is here, or what we could do to prevent this.

When I change @remarks to remarks then it doesn't trigger the error tstl-playground example

interface LuaBootstrap {
  /**
   * remarks
   *
   * Link {@link https://github.com/microsoft/tsdoc}
   */
  on_init(f: (() => void) ): void
}

const script : LuaBootstrap = {
    on_init: (x) => x()
}

script.on_init(() => { })

When I change remarks back to @remarks it does tstl-playground example (make an incidental edit to trigger the error)

Both examples have the same JSDocLink structure, with a https as an Identifier

The difference between the two is that the @remarks version has a FirstJSDocTagNode, while the other does not.

The error is specifically triggered by an {@link ...} being inside a @remarks block - if the link is in a preceding block, it works tstl-playground example

What does tsc do inside of a @remarks block that's different to a regular JSDoc block?

Additionally, I think I found a workaround: change {@link ... } to {@linkplain ... } when it's referring to a http link. never mind, it causes the same issue tstl playground

@Perryvw the thing that makes me most suspicious is that in the TSTL playground, the error appears on the method signature node itself rather than on the bit of the JSDoc that it tried to resolve and couldn’t. I can’t quite see what could cause that.

I suspect you at least have an order of operations issue. The diagnostic is generated by a language service API call, which I think in an ideal world would not happen, but you can avoid that pitfall by only asking for diagnostics from a clean program; i.e. make sure you ask for diagnostics before running any other language service methods which could modify the checker state.

@andrewbranch Interesting, I was not expecting this order of operations to matter but it seems that at least in our tstl tests we are calling getPreEmitDiagnostics(program) after we are done transforming, which looks like it triggers the issue.

I made the following change which seems to resolve the problem:

     public getLuaResult(): tstl.TranspileVirtualProjectResult {
         const program = this.getProgram();
         const collector = createEmitOutputCollector();
+
+        const preEmitDiagnostics = ts.getPreEmitDiagnostics(program);
+
         const { diagnostics: transpileDiagnostics } = new tstl.Transpiler({ emitHost: this.getEmitHost() }).emit({
             program,
             customTransformers: this.customTransformers,
            writeFile: collector.writeFile,
        });
 
         const diagnostics = ts.sortAndDeduplicateDiagnostics([
-            ...ts.getPreEmitDiagnostics(program),
+            ...preEmitDiagnostics,
             ...transpileDiagnostics,
         ]);

Seems like we are actually doing the same thing everywhere, so it might be an easy workaround for us to just swap some lines around. This does not strike me as intended/expected behavior from TypeScript side either, but at least we can work around it pretty easily for now.

Yeah, double checked with the team and it’s definitely not supposed to happen, though I don’t find it too surprising.

The call to getSymbolAtLocation from buildLinkParts in src/services/utilities.ts is the first thing in the stack that’s possibly suspicious. That call should never be able to trigger an error that getSemanticDiagnostics doesn’t also trigger. I think the checker should probably know based on the location that it shouldn’t trigger name resolution errors there. JSDoc @link tags can probably just be explicitly exempt from errors in resolveEntityName in checker.ts (@sandersn please correct me if that’s not right).

Why this only happens when the @link tag comes after another tag (not just @remarks, happens for any tag) is a total mystery to me.