Merge pull request #41 from PolymerLabs/distinguish

Use type checker to identify msg function and lit-localize module

Author: aomarks

README.md

@@ -6,6 +6,16 @@
 
 The `lit-localize` module exports the following functions:
 
+> Note that lit-localize relies on distinctive, annotated TypeScript type
+> signatures to identify calls to `msg` and other APIs during analysis of your
+> code. Casting a lit-localize function to a type that does not include its
+> annotation will prevent lit-localize from being able to extract and transform
+> templates from your application. For example, a cast like
+> `(msg as any)("greeting", "Hello")` will not be identified. It is safe to
+> re-assign lit-localize functions or pass them as parameters, as long as the
+> distinctive type signature is preserved. If needed, you can reference each
+> function's distinctive type with e.g. `typeof msg`.
+
 ### `configureLocalization(configuration)`
 
 Set configuration parameters for lit-localize when in runtime mode. Returns an

src/outputters/transform.ts

@@ -52,7 +52,7 @@ export function transformOutput(
     }
     opts.outDir = pathLib.join(outRoot, '/', locale);
     program.emit(undefined, undefined, undefined, undefined, {
-      before: [litLocalizeTransform(translations)],
+      before: [litLocalizeTransform(translations, program)],
     });
   }
 }
@@ -61,10 +61,11 @@ export function transformOutput(
  * Return a TypeScript TransformerFactory for the lit-localize transformer.
  */
 export function litLocalizeTransform(
-  translations: Map<string, Message> | undefined
+  translations: Map<string, Message> | undefined,
+  program: ts.Program
 ): ts.TransformerFactory<ts.SourceFile> {
   return (context) => {
-    const transformer = new Transformer(context, translations);
+    const transformer = new Transformer(context, translations, program);
     return (file) => ts.visitNode(file, transformer.boundVisitNode);
   };
 }
@@ -75,21 +76,24 @@ export function litLocalizeTransform(
 class Transformer {
   private context: ts.TransformationContext;
   private translations: Map<string, Message> | undefined;
+  private typeChecker: ts.TypeChecker;
   boundVisitNode = this.visitNode.bind(this);
 
   constructor(
     context: ts.TransformationContext,
-    translations: Map<string, Message> | undefined
+    translations: Map<string, Message> | undefined,
+    program: ts.Program
   ) {
     this.context = context;
     this.translations = translations;
+    this.typeChecker = program.getTypeChecker();
   }
 
   /**
    * Top-level delegating visitor for all nodes.
    */
   visitNode(node: ts.Node): ts.VisitResult<ts.Node> {
-    if (isMsgCall(node)) {
+    if (isMsgCall(node, this.typeChecker)) {
       return this.replaceMsgCall(node);
     }
     if (isLitTemplate(node)) {
@@ -101,8 +105,8 @@ class Transformer {
         )
       );
     }
-    if (ts.isImportDeclaration(node)) {
-      return this.removeMsgImport(node);
+    if (this.isLitLocalizeImport(node)) {
+      return undefined;
     }
     return ts.visitEachChild(node, this.boundVisitNode, this.context);
   }
@@ -329,29 +333,29 @@ class Transformer {
   }
 
   /**
-   * Remove import declarations for the lit-localize `msg` function, because we
-   * are transforming away all calls to that function.
+   * Return whether the given node is an import for the lit-localize module.
    */
-  removeMsgImport(
-    imprt: ts.ImportDeclaration
-  ): ts.ImportDeclaration | undefined {
-    const clause = imprt.importClause;
-    if (clause === undefined) {
-      return imprt;
+  isLitLocalizeImport(node: ts.Node): node is ts.ImportDeclaration {
+    if (!ts.isImportDeclaration(node)) {
+      return false;
     }
-    const bindings = clause.namedBindings;
-    if (bindings === undefined || !ts.isNamedImports(bindings)) {
-      return imprt;
+    const moduleSymbol = this.typeChecker.getSymbolAtLocation(
+      node.moduleSpecifier
+    );
+    if (!moduleSymbol || !moduleSymbol.exports) {
+      return false;
     }
-    // TODO(aomarks) This is too crude. We should do better to identify only our
-    // `msg` function.
-    if (
-      bindings.elements.length === 1 &&
-      bindings.elements[0].name.text === 'msg'
-    ) {
-      return undefined;
+    const exports = moduleSymbol.exports.values();
+    for (const xport of exports as typeof exports & {
+      [Symbol.iterator](): Iterator<ts.Symbol>;
+    }) {
+      const type = this.typeChecker.getTypeAtLocation(xport.valueDeclaration);
+      const props = this.typeChecker.getPropertiesOfType(type);
+      if (props.some((prop) => prop.escapedName === '_LIT_LOCALIZE_MSG_')) {
+        return true;
+      }
     }
-    return imprt;
+    return false;
   }
 }
 

src/program-analysis.ts

@@ -18,11 +18,11 @@ import {createDiagnostic} from './typescript';
  * Extract translation messages from all files in a TypeScript program.
  */
 export function extractMessagesFromProgram(
-  node: ts.Program
+  program: ts.Program
 ): {messages: ProgramMessage[]; errors: ts.Diagnostic[]} {
   const messages: ProgramMessage[] = [];
   const errors: ts.Diagnostic[] = [];
-  for (const sourcefile of node.getSourceFiles()) {
+  for (const sourcefile of program.getSourceFiles()) {
     extractMessagesFromNode(sourcefile, sourcefile, messages, errors, []);
   }
   const deduped = dedupeMessages(messages);
@@ -493,14 +493,23 @@ export function isLitTemplate(
 /**
  * Return whether this is a call to the lit-localize `msg` function.
  */
-export function isMsgCall(node: ts.Node): node is ts.CallExpression {
-  // TODO(aomarks) This is too crude. We should do better to identify only our
-  // `msg` function.
-  return (
-    ts.isCallExpression(node) &&
-    ts.isIdentifier(node.expression) &&
-    node.expression.escapedText === 'msg'
-  );
+export function isMsgCall(
+  node: ts.Node,
+  typeChecker?: ts.TypeChecker
+): node is ts.CallExpression {
+  if (!ts.isCallExpression(node)) {
+    return false;
+  }
+  if (typeChecker === undefined) {
+    // TODO(aomarks) Remove this branch once migration to static lit-localize
+    // library is done.
+    return (
+      ts.isIdentifier(node.expression) && node.expression.escapedText === 'msg'
+    );
+  }
+  const type = typeChecker.getTypeAtLocation(node.expression);
+  const props = typeChecker.getPropertiesOfType(type);
+  return props.some((prop) => prop.escapedName === '_LIT_LOCALIZE_MSG_');
 }
 
 /**

src/tests/compile-ts-fragment.ts

@@ -42,7 +42,7 @@ export function compileTsFragment(
   inputCode: string,
   options: ts.CompilerOptions,
   cache: CompilerHostCache,
-  transformers?: ts.CustomTransformers
+  transformers?: (program: ts.Program) => ts.CustomTransformers
 ): CompileResult {
   const dummyTsFilename = '__DUMMY__.ts';
   const dummyJsFilename = '__DUMMY__.js';
@@ -124,7 +124,7 @@ export function compileTsFragment(
     undefined,
     undefined,
     undefined,
-    transformers
+    transformers ? transformers(program) : undefined
   );
   return {
     code: outputCode,