`{@link https...}` inside a `@remarks` causes error TS2304: Cannot find name 'https'

Bug Report

🔎 Search Terms

• jsdoc
• tsdoc
• TS2304: Cannot find name ‘https’.
• @link
• @remarks

🕗 Version & Regression Information

• This is the behaviour in every version I tried, and I reviewed the FAQ for entries ✅

I checked on 4.6.4, 4.6.2.

I tried checking on 4.7.0-rc1 but I got unrelated errors.

⏯ Playground Link

I don’t understand how to use the ‘Bug Workbench’, it doesn’t seem to pick up the config I enter.

https://www.typescriptlang.org/dev/bug-workbench/?target=99&allowSyntheticDefaultImports=true&explainFiles=true&forceConsistentCasingInFileNames=true&listEmittedFiles=true&listFiles=true&sourceMap=false&traceResolution=true&noImplicitOverride=true&noFallthroughCasesInSwitch=true&types=["typescript-to-lua%2Flanguage-extensions"%2C "lua-types%2F5.2"%2C "typed-factorio%2Fruntime"]&lib=&ts=4.6.2#code/PTAEAEBcEMCcHMCmkBcpEGcB2iAekAoAkCAMwEsAbRLaAW0TQAdoBjAa2iQDoArDAPZYCAbwKhQAIloNJaSXQCeAWlJtIA2OQHK6AgCaSANOKkA3RLAzascqQAZuAVm73jpyUy1nokRHchYAFdEEwlJDFYtJkgMOzEJcIAjIKpDeVjISndEqX1EMztJTMpQZWUAd19WAAtJUwBfMKkaeHIcOLQExOkDf3kAPwBGABZuIYBOcfqJJo98swARRCYafKxWckx4ufD81ax1ze2u03DKIOhlSEVVzqkAPQAmcaHXHJ6bu6jyGOudC7QIpvMYjD7hL6IfSqdSabTA8bvZoQ26YH4xIpjABs3CeM1AuyklHIrBoGH6UgAqgA5AAyAEkAMIAUWpAGVmYsPp5EJZlgcjlt7iJCZIBDEbNBKPy1jRjsLRSlDtR9DLDnKhXYANoAXQIDSIxDA4Ao1BkjFAsVYQgo8D4giwoFEHgAJJEaog6ED5DVIJAmBgUCBYNAKtw2pAakEUuTYNasH4E9xrXRgAAVVFs9GQNMCWmXYBmSJ9a6oyLRSD-ZSA4BejB+WDAK028jwZTuz3Qe1CbkpphUSwAeQlQmFZykMAQyCKmBw+HBRPISW14-Cs7wkHxEh1yKken0QWoRRTeiw-AXCgMh8QACVMAILpAbEUsH0L5D7lrVxOy9mqzXKGgLB4EuJBlA3MkbDiXdzkuUs7mAFw8Rgn9VmhNRWA0LQBGAYIE3IWRxx3cdPAuNosE-b9ulycJzSKD8-xKZQmDI9ot0SA1cmI3JJClSgBAqNlFATD0n1YZY1EPSB6ToJhNFiAJglCEjMAAWSvah6QTSxxUUkJd0kPAWOgdoADEB3uQJ9JI0hNFJRlR3IesaEgRloGsYCtPM6hqXoE5LSUgziXrZk6HIP0oW8-yrOUnjgsgKLLMCkjXxkliSXCgBBLBFD02KelS2TiU2HMaicvKDMEII40QVToCYOw1EoclKsCElNzQGLWq0TDTKCDYnyEDM7gqkj6x6yBqUPShGQ9DgkusnjAjYW970fZ9OuSnjCvSkq70gaqKNG7aBDS4rwsHCxYC0fJjoKgRTL4yNYAEIJ4BqNzyQwLS2QqcLajyxpmmKetslOOLLjTOAkA6qQkPfUGADVLCSARyTu2iBAACUQaB8lgDGpB287IDZRBKFIQnJEBWklzS+SilgRAAEdUiZ-EDQNIgSBNAdzTQeNAgfbhYiIctfkgbghAAfXacKAAp5YASlAABeAA+UBqNAfj4HlgADfdQCc0A8fyfRLQES0PVADBoAsfWlf1J2gA

But when I set up those 3 files in a directory and run npm install then npm build, I get this error

...
Emitting ...
Emit finished!
node_modules/typed-factorio/generated/classes.d.ts:238:3 - error TS2304: Cannot find name 'https'.

238   on_init(f: (() => void) | undefined): void
      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


Process finished with exit code 2

Here’s a reproduction inside the TSTL playground. You might have to edit the file to trigger it

https://typescripttolua.github.io/play/#code/PQKhCgAIUhRA7ALgJwJ6QA4HsCWTIBmWykyApgOY4DOiZyeFkZAbmfgBYCG8AJgDb1qAOkgBJRJBqQuAY1llq1HACNBkRB2RYArhQ4aOZSBX5YVXfpHMArMrMnwuAWzK9IAA2qyGGRB+EoCGhIAG8AAX48AGtIDkREDGoALmBgfh0uAFouDBxhAjlEYhwsYVksZ3SuOlpgABlMgCEsLERaZFzheOcrADUcMgB3SF4sWR1XJBrS+ABfIMhw+CwAZTJ+AiDgcDw6ZEKFSEauFraO3LCoSFBgyBDw8mcuZGjqa+gPmHqY6khZHiYXD4YoySAAVQASvVkmFIjE4gkkqlgFRNDoVOVKsBnDgfFhqFgCIhgO0xrIFvdoDt7lh4AB9PA4RAACgIsJZLIAlJAALwAPkgLFwvB5XNhwpwvHAC3AFXgtEg3l8klhJzO7RQl15Vyp1gZTMQHIAHjyBZBjdyZeBwMqcH5hHTGfBmZyzYLQhgGEgWQAiIhYX1cuZc8BAA

💻 Code

An MRE is below, but the error originates in the TSDoc of the Typed Factorio project, in classes.d.ts.

  /**
   * Register a function to be run on mod initialization...
   *
   * {@link https://lua-api.factorio.com/latest/LuaBootstrap.html#LuaBootstrap.on_init View documentation}
   * @param f The handler for this event. Passing `nil` will unregister it.
   * @remarks For more context, refer to the {@link https://lua-api.factorio.com/latest/Data-Lifecycle.html Data Lifecycle} page.
   * @example Initialize a `players` table in `global` for later use.
   *
   * ```
   * script.on_init(function()
   *   global.players = {}
   * end)
   * ```
   */
  on_init(f: (() => void) | undefined): void

If I remove the {@link ...} from the @remarks, then it works!

  /**
   * Register a function to be run on mod initialization...
   *
   * {@link https://lua-api.factorio.com/latest/LuaBootstrap.html#LuaBootstrap.on_init View documentation}
   * @param f The handler for this event. Passing `nil` will unregister it.
   * @remarks For more context, refer to the xxxxxxxxxxxxxxxxxx page.
   * @example Initialize a `players` table in `global` for later use.
   *
   * ```
   * script.on_init(function()
   *   global.players = {}
   * end)
   * ```
   */
  on_init(f: (() => void) | undefined): void

The @remarks and the {@link ...} was added last week:

https://github.com/GlassBricks/typed-factorio/commit/f18205f70d75f88b02c14fff7a70abcc562e721b#diff-9e3b31eca93c33b0d77c73d8688a93f48e81e18d86efdc4c57ac1d5d76ce8845R229

If I revert Typed Factorio to v1.0.0, then again, there’s no error.

Minimal, reproducible example

click to expand

./control.ts

script.on_init(() => {
  log(`mod is added to the save`)
})

./package.json

{
  "name": "my-factorio-mod",
  "version": "0.5.0",
  "private": true,
  "scripts": {
    "build": "tstl",
    "dev": "tstl --watch"
  },
  "engines": {
    "node": "~14.19.1"
  },
  "devDependencies": {},
  "dependencies": {
    "lua-types": "^2.11.0",
    "typescript-to-lua": "1.4.4",
    "typed-factorio": "1.1.0",
    "typescript": "4.6.2"
  },
  "license": "UNLICENSED",
  "peerDependencies": {},
  "optionalDependencies": {},
  "bundledDependencies": []
}

./tsconfig.json

{
  "$schema": "https://raw.githubusercontent.com/TypeScriptToLua/vscode-typescript-to-lua/master/tsconfig-schema.json",
  "compilerOptions": {
    "target": "esnext",
    "lib": [
      "esnext"
    ],
    "module": "commonjs",
    "moduleResolution": "node",
    "types": [
      "typescript-to-lua/language-extensions",
      "lua-types/5.2",
      "typed-factorio/runtime"
    ],
    "plugins": [
      {
        "name": "typescript-tstl-plugin"
      }
    ],
    "allowSyntheticDefaultImports": true,
    "esModuleInterop": true,
    "explainFiles": true,
    "forceConsistentCasingInFileNames": true,
    "listEmittedFiles": true,
    "listFiles": true,
    "noImplicitAny": true,
    "noImplicitThis": true,
    "sourceMap": false,
    "strict": true,
    "strictFunctionTypes": true,
    "strictNullChecks": true,
    "traceResolution": true,
    "noImplicitReturns": true,
    "noImplicitOverride": true,
    "noFallthroughCasesInSwitch": true
  },
  "tstl": {
    "luaTarget": "5.2",
    "tstlVerbose": true,
    "noHeader": true,
    "noImplicitSelf": true,
    "luaLibImport": "require"
  }
}

🙁 Actual behavior

TSDoc with a {@link https:...} inside of a @remark block causes an error

   * @remarks For more context, refer to the {@link https://lua-api.factorio.com/latest/Data-Lifecycle.html Data Lifecycle} page.

node_modules/typed-factorio/generated/classes.d.ts:238:3 - error TS2304: Cannot find name 'https'.

238   on_init(f: (() => void) | undefined): void
      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


Process finished with exit code 2

🙂 Expected behavior

TSDoc with a {@link https:...} inside of a @remark block does not cause an error

Workaround

A workaround is to add "skipLibCheck": true to tsconfig.json > compilerOptions.

See also

• https://github.com/GlassBricks/typed-factorio/issues/13
• https://github.com/microsoft/tsdoc/issues/9
• https://github.com/TypeScriptToLua/TypeScriptToLua/issues/1058

[andrewbranch]

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.

[sandersn]

I looked briefly at the code and

1. @link tags are checked the same regardless of whether they’re inside a tag or just the top-level comment text.
2. They are explicitly exempt from errors in resolveEntityName in that code path, which is the one the compiler uses. The one where they’re not obviously exempted is only used by the language service – but editors don’t seem to report those? At least I couldn’t get them to in a simple test.

Edit: re-reading @andrewbranch 's comment, the problem might be the language service code in getSymbolOfNameOrPropertyAccessExpression, which might make getSemanticDiagnostics give no error, but getSymbolAtLocation give an error.