Translate namespaced type references in jsdoc

[evmar]

Input:

import {SomeClass} from './foo';

function bar(x: SomeClass) {}
bar(new SomeClass());

Current sickle output is something like:

var foo_1 = require('./foo');

/** @param {SomeClass} x */
function bar(x) {}
bar(new foo_1.SomeClass());

The problem is that SomeClass is known as foo_1.SomeClass in the output, so the type annotation in the comment is wrong. We need foo_1.SomeClass in the JSDoc.

One idea is to emit something like this in the TS:

SomeClass; // sickle:SomeClass

which will become (after TS compilation)

foo_1.SomeClass; // sickle:SomeClass

and then we could regex for these lines to build up the mapping between SomeClass and foo_1.SomeClass. Pretty crazy hacks though.

Related: #111

[evmar]

Causes warning:
WARNING - Bad type annotation. Unknown type SomeClass

[evmar]

We could probably find a way to hack around this with some terrible regexes, but it's make more sense to fix it in the compiler. So I filed this upstream:
microsoft/TypeScript#8120

[evmar]

I think a better fix for this is to undo the namespacing that TypeScript does.

E.g. the input is:

import {foo} from ...;
let x = foo;

TypeScript produces:

[module goop];
var x = bar_1.foo;

I'm suggesting we translate that back to:

[module goop]; var foo = bar_1.foo;
var x = foo;

To be honest, I'm not sure why TypeScript does the namespacing thing it does.

[evmar]

What's tricky about my proposal above is:

Input:

import {foo} from 'foo';
import * as bar from 'bar';

let x = foo;
let y = bar.a;

Current output:

var foo_1 = require('foo');
var bar = require('bar');
var x = foo_1.foo;
var y = bar.a;

I was suggesting identifying foo_1.foo as special and rewriting it, but somehow we'd need to know to leave bar.a alone.

[mprobst]

Idea: if TSC choses a non-predictable prefix, can we just prime it on a prefix that we can predict?

import {Symbol} from 'module';
import * as prefix from 'module';

Symbol.access();
prefix.Symbol.access();

Gives:

"use strict";
var module_1 = require('module');
var prefix = require('module');
module_1.Symbol.access();
prefix.Symbol.access();

There's an API to find all code locations of a particular symbol:

languageService.getDocumentHighlights(fileName, positionOfSymbol, [fileName]);

So change imports to always be prefix imports, make up a prefix (_tsickle_import_123), and rewrite all locations where mentioned.

The second problem of TS dropping imports that are only used in type locations could maybe be detected with the same API?

[evmar]

(I thought more about the dropping imports problem and I think we're actually ok -- because in Closure-land there's a single namespace, types always show up in the value namespace. For any type Foo we import tsickle also must create a var Foo on that side for Closure, and then TS will preserve the import of Foo because of the value.)

Let me think about your renaming idea. You're saying we rewrite every import to be like import * as _tsickle_import_${origName} from ... so that we can find that name?

[mprobst]

Yeah, but will the dropped import have the same name, i.e. will Closure understand which {Symbol} you're referring to in the @param annotation?

Re rewrite idea, yeah, that's it.

[evmar]

Upstream TS said they're not gonna help with this, so we need to do something. I will investigate your renaming idea. It looks promising.

[evmar]

It occurs to me that another fix for this would be to use Closure's ES6 imports mode.

[evmar]

Closure has ES6 modules issues though:
https://github.com/google/closure-compiler/issues?q=is%3Aissue+is%3Aopen+label%3AModules

[evmar]

Fixed! The final fix was to make local name references, like so:

import {Foo} from 'bar';

becomes

import {Foo as tsickle_Foo} from 'bar';
const Foo = tsickle_Foo;  // if it's a value
type Foo = tsickle_Foo;  // if it's a type