@glint/ember-tsc 1.0.0

package/src/transform/diagnostics/augmentation.ts

@@ -0,0 +1,333 @@
+import type ts from 'typescript';
+import GlimmerASTMappingTree, { MappingSource } from '../template/glimmer-ast-mapping-tree.js';
+import TransformedModule from '../template/transformed-module.js';
+import { Diagnostic } from './index.js';
+
+export function augmentDiagnostics<T extends Diagnostic>(
+  transformedModule: TransformedModule,
+  diagnostics: T[],
+): T[] {
+  const mappingForDiagnostic = (diagnostic: ts.Diagnostic): GlimmerASTMappingTree[] => {
+    if (!transformedModule) {
+      return [];
+    }
+
+    if (!diagnostic.start || !diagnostic.length) {
+      return [];
+    }
+
+    const start = diagnostic.start;
+    const end = start + diagnostic.length;
+
+    return transformedModule.getExactTransformedRanges(
+      transformedModule.originalFileName,
+      start,
+      end,
+    );
+  };
+
+  const augmentedDiagnostics: Diagnostic[] = [];
+
+  for (const diagnostic of diagnostics) {
+    const augmentedDiagnostic = rewriteMessageText(diagnostic, mappingForDiagnostic);
+
+    augmentedDiagnostics.push(augmentedDiagnostic);
+  }
+
+  // @ts-expect-error not sure how to fix
+  return augmentedDiagnostics;
+}
+
+type DiagnosticHandler<T extends Diagnostic> = (
+  diagnostic: T,
+  mapping: GlimmerASTMappingTree,
+) => T | undefined;
+
+function rewriteMessageText(
+  diagnostic: Diagnostic,
+  mappingGetter: (diagnostic: Diagnostic) => GlimmerASTMappingTree[],
+): Diagnostic {
+  const handler = diagnosticHandlers[diagnostic.code?.toString() ?? ''];
+  if (!handler) {
+    return diagnostic;
+  }
+
+  for (let mapping of mappingGetter(diagnostic)) {
+    const augmentedDiagnostic = handler(diagnostic, mapping);
+    if (augmentedDiagnostic) {
+      return augmentedDiagnostic;
+    }
+  }
+
+  return diagnostic;
+}
+
+const diagnosticHandlers: Record<string, DiagnosticHandler<Diagnostic> | undefined> = {
+  '2307': checkGlintLibImports, // TS2307: An import cannot be found.
+  '2322': checkAssignabilityError, // TS2322: Type 'X' is not assignable to type 'Y'.
+  '2345': checkAssignabilityError, // TS2345: Argument of type 'X' is not assignable to parameter of type 'Y'.
+  '2554': noteNamedArgsAffectArity, // TS2554: Expected N arguments, but got M.
+  '2555': noteNamedArgsAffectArity, // TS2555: Expected at least N arguments, but got M.
+  '2769': checkResolveError, // TS2769: No overload matches this call.
+  '4111': checkIndexAccessError, // TS4111: Property 'x' comes from an index signature, so it must be accessed with ['x'].
+  '7053': checkImplicitAnyError, // TS7053: Element implicitly has an 'any' type because expression of type '"X"' can't be used to index type 'Y'.
+};
+
+const bindHelpers = ['component', 'helper', 'modifier'];
+
+function checkGlintLibImports(
+  diagnostic: Diagnostic,
+  _mapping: GlimmerASTMappingTree,
+): Diagnostic | undefined {
+  let messageText =
+    typeof diagnostic.messageText === 'string'
+      ? diagnostic.messageText
+      : diagnostic.messageText.messageText;
+
+  const typesModules = '@glint/ember-tsc/-private/dsl';
+
+  if (messageText.includes(typesModules)) {
+    return addGlintDetails(
+      diagnostic,
+      'You appear to be using version 2 of the Glint VS Code extension ' +
+        '(or a v2 Glint plugin for another IDE), but your package.json still ' +
+        'references version 1 Glint dependencies (or they are missing). You need to either upgrade your `@glint/core` ' +
+        'and `@glint/template` project dependencies, or downgrade your VS Code Glint extension to version 1.x. ' +
+        'Please see the Glint v2 release notes and upgrade guide for more information.',
+    );
+  } else {
+    return diagnostic;
+  }
+}
+
+function checkAssignabilityError(
+  diagnostic: Diagnostic,
+  mapping: GlimmerASTMappingTree,
+): Diagnostic | undefined {
+  let node = mapping.sourceNode;
+  let parentNode = mapping.parent?.sourceNode;
+  if (!parentNode) return;
+
+  if (parentNode.type === node.type) {
+    // For Volar, we added a few more artificial nestings / wrappings around Handlebars
+    // AST nodes to provide more hookpoints for TS diagnostics to correctly source-map
+    // back to .gts/.hbs source code. The result of this is that sometimes you have
+    // things like MustacheNodes being "parents" of MustacheNodes, which we try and
+    // detect here.
+    //
+    // This can go away if/when we refactor the `transformModule` code.
+    parentNode = mapping.parent?.parent?.sourceNode;
+
+    if (!parentNode) return;
+  }
+
+  if (
+    node.type === 'Identifier' &&
+    parentNode.type === 'AttrNode' &&
+    !/^(@|\.)/.test(parentNode.name)
+  ) {
+    // If the assignability issue is on an attribute name and it's not an `@arg`
+    // or `...attributes`, then it's an HTML attribute type issue.
+    return addGlintDetails(
+      diagnostic,
+      'Only primitive values (see `AttrValue` in `@glint/template`) are assignable as HTML attributes. ' +
+        'If you want to set an event listener, consider using the `{{on}}` modifier instead.',
+    );
+  } else if (
+    node.type === 'AttrNode' &&
+    parentNode.type === 'ElementNode' &&
+    !/^(@|\.)/.test(node.name)
+  ) {
+    // If the assignability issue is on an attribute name and it's not an `@arg`
+    // or `...attributes`, then it's an HTML attribute type issue.
+    return addGlintDetails(
+      diagnostic,
+      'An Element must be specified in the component signature in order to pass in HTML attributes.',
+    );
+  } else if (
+    node.type === 'MustacheStatement' &&
+    (parentNode.type === 'Template' ||
+      parentNode.type === 'BlockStatement' ||
+      parentNode.type === 'ElementNode') &&
+    !(node.path.type === 'PathExpression' && node.path.original === 'yield')
+  ) {
+    // If we're looking at a top-level {{mustache}}, we first double check whether
+    // it's an attempted inline {{component 'foo'}} invocation...
+    if (node.path.type === 'PathExpression' && node.path.original === 'component') {
+      return addGlintDetails(
+        diagnostic,
+        `The {{component}} helper can't be used to directly invoke a component under Glint. ` +
+          `Consider first binding the result to a variable, e.g. ` +
+          `'{{#let (component 'component-name') as |ComponentName|}}' and then invoking it as ` +
+          `'<ComponentName @arg={{value}} />'.`,
+      );
+    }
+
+    // Otherwise, it's a DOM content type issue.
+    return addGlintDetails(
+      diagnostic,
+      'Only primitive values and certain DOM objects (see `ContentValue` in `@glint/template`) are ' +
+        'usable as top-level template content.',
+    );
+  } else if (
+    (mapping?.sourceNode.type === 'SubExpression' ||
+      mapping?.sourceNode.type === 'MustacheStatement') &&
+    mapping.sourceNode.path.type === 'PathExpression' &&
+    bindHelpers.includes(mapping.sourceNode.path.original)
+  ) {
+    // If we're looking at a binding helper subexpression like `(component ...)`, error messages
+    // may be very straightforward or may be horrendously complex when users start playing games
+    // with parametrized types, so we add a hint here.
+    let kind = mapping.sourceNode.path.original;
+    return {
+      ...diagnostic,
+      messageText: `Unable to pre-bind the given args to the given ${kind}. This likely indicates a type mismatch between its signature and the values you're passing.`,
+    };
+  }
+}
+
+function noteNamedArgsAffectArity(
+  diagnostic: Diagnostic,
+  mapping: GlimmerASTMappingTree,
+): Diagnostic | undefined {
+  // In normal template entity invocations, named args (if specified) are effectively
+  // passed as the final positional argument. Because of this, the reported "expected
+  // N arguments, but got M" message may appear to be off-by-one to the developer.
+
+  // Since this treatment of named args as a final "options hash" argument is user
+  // visible in cases like type errors, we can't just paper over this by subtracting
+  // 1 from the numbers in the message. Instead, if the invocation has named args, we
+  // explicitly note that they're effectively the final positional parameter.
+
+  let callNode = findAncestor(mapping, 'MustacheStatement', 'SubExpression');
+  if (callNode?.path.type === 'PathExpression' && callNode.path.original === 'yield') {
+    // Yield is directly transformed rather than being treated as a normal mustache
+    return;
+  }
+
+  let hasNamedArgs = !!callNode?.hash.pairs.length;
+  if (hasNamedArgs) {
+    let note =
+      'Note that named args are passed together as a final argument, so they ' +
+      'collectively increase the given arg count by 1.';
+
+    return {
+      ...diagnostic,
+      messageText: `${diagnostic.messageText} ${note}`,
+    };
+  }
+}
+
+function checkResolveError(
+  diagnostic: Diagnostic,
+  mapping: GlimmerASTMappingTree,
+): Diagnostic | undefined {
+  // The diagnostic might fall on a lone identifier or a full path; if the former,
+  // we need to traverse up through the path to find the true parent.
+  let sourceMapping = mapping.sourceNode.type === 'Identifier' ? mapping.parent : mapping;
+  let parentNode = sourceMapping?.parent?.sourceNode;
+
+  // If this error is on the first param to a {{component}} or other bind invocation, this means
+  // we either have a non-component value or a string that's missing from the registry.
+  if (
+    (parentNode?.type === 'SubExpression' || parentNode?.type === 'MustacheStatement') &&
+    parentNode.path.type === 'PathExpression' &&
+    bindHelpers.includes(parentNode.path.original) &&
+    parentNode.params[0] === sourceMapping?.sourceNode
+  ) {
+    let kind = parentNode.path.original;
+
+    if (sourceMapping.sourceNode.type === 'StringLiteral') {
+      return addGlintDetails(
+        diagnostic,
+        `Unknown ${kind} name '${sourceMapping.sourceNode.value}'. If this isn't a typo, you may be ` +
+          `missing a registry entry for this name; see the Template Registry page in the Glint ` +
+          `documentation for more details.`,
+      );
+    } else {
+      return addGlintDetails(
+        diagnostic,
+        `The type of this expression doesn't appear to be a valid value to pass the {{${kind}}} ` +
+          `helper. If possible, you may need to give the expression a narrower type, ` +
+          `for example \`'thing-a' | 'thing-b'\` rather than \`string\`.`,
+      );
+    }
+  }
+
+  // Otherwise if this is on a top level invocation, we're trying to use a template-unaware
+  // value in a template-specific way.
+  let nodeType = sourceMapping?.sourceNode.type;
+  if (nodeType === 'ElementNode' || nodeType === 'PathExpression' || nodeType === 'Identifier') {
+    return addGlintDetails(
+      diagnostic,
+      'The given value does not appear to be usable as a component, modifier or helper.',
+    );
+  }
+}
+
+function checkImplicitAnyError(
+  diagnostic: Diagnostic,
+  mapping: GlimmerASTMappingTree,
+): Diagnostic | undefined {
+  let message = diagnostic.messageText;
+
+  // We don't want to bake in assumptions about the exact format of TS error messages,
+  // but we can assume that the name of the type we're indexing (`Globals`) will appear
+  // in the text in the case we're interested in.
+  if (typeof message === 'string' && message.includes('Globals')) {
+    let { sourceNode } = mapping;
+
+    // This error may appear either on `<Foo />` or `{{foo}}`/`(foo)`
+    let globalName =
+      sourceNode.type === 'ElementNode'
+        ? sourceNode.path.head.original
+        : sourceNode.type === 'PathExpression' && sourceNode.head.type === 'VarHead'
+          ? sourceNode.head.name
+          : null;
+
+    if (globalName) {
+      return addGlintDetails(
+        diagnostic,
+        `Unknown name '${globalName}'. If this isn't a typo, you may be missing a registry entry ` +
+          `for this value; see the Template Registry page in the Glint documentation for more details.`,
+      );
+    }
+  }
+}
+
+function checkIndexAccessError(
+  diagnostic: Diagnostic,
+  mapping: GlimmerASTMappingTree,
+): Diagnostic | undefined {
+  if (mapping.sourceNode.type === 'Identifier' && typeof diagnostic.messageText === 'string') {
+    let message = diagnostic.messageText;
+
+    // "accessed with ['x']" => "accessed with {{get ... 'x'}}"
+    return {
+      ...diagnostic,
+      messageText: message.replace(/\[(['"])(.*)\1\]/, `{{get ... $1$2$1}}`),
+    };
+  }
+}
+
+function addGlintDetails(diagnostic: Diagnostic, details: string): Diagnostic {
+  return {
+    ...diagnostic,
+    messageText: `${details}\n${diagnostic.messageText}`,
+  };
+}
+
+// Find the nearest mapping node at or above the given one whose `source` AST node
+// matches one of the given types.
+function findAncestor<K extends MappingSource['type']>(
+  mapping: GlimmerASTMappingTree,
+  ...types: Array<K>
+): Extract<MappingSource, { type: K }> | null {
+  let current: GlimmerASTMappingTree | null = mapping;
+  do {
+    if (types.includes(current.sourceNode.type as K)) {
+      return current.sourceNode as Extract<MappingSource, { type: K }>;
+    }
+  } while ((current = current.parent));
+  return null;
+}

package/src/transform/diagnostics/index.ts

@@ -0,0 +1,5 @@
+import type * as ts from 'typescript';
+
+export type Diagnostic = ts.Diagnostic & {
+  isContentTagError?: boolean;
+};

package/src/transform/index.ts

@@ -0,0 +1,4 @@
+export type { Directive, default as TransformedModule } from './template/transformed-module.js';
+export type { Diagnostic } from './diagnostics/index.js';
+
+export { rewriteModule } from './template/rewrite-module.js';

package/src/transform/template/code-features.ts

@@ -0,0 +1,30 @@
+import { CodeInformation } from '@volar/language-server/node.js';
+
+/**
+ * Based on https://github.com/machty/vue-language-tools/blob/deff856aa8c15f691544e646519215a15aacbef1/packages/language-core/lib/codegen/codeFeatures.ts
+ *
+ * This file exports a "code features" object which provides a useful shorthand/shortcut
+ * for specifying a nubmer of Volar CodeInformation configuration options in the code
+ * we use for mapping between source code (e.g. .gts files) and transformed (i.e. type-checkable TS) code.
+ *
+ * Volar uses the CodeInformation we pass along with each mapping to determine what sort of language
+ * features should be activated/processed for a given span of code.
+ */
+const raw = {
+  all: {
+    verification: true,
+    completion: true,
+    semantic: true,
+    navigation: true,
+  },
+  withoutHighlight: {
+    semantic: { shouldHighlight: () => false },
+    verification: true,
+    navigation: true,
+    completion: true,
+  },
+} satisfies Record<string, CodeInformation>;
+
+export const codeFeatures = raw as {
+  [K in keyof typeof raw]: CodeInformation;
+};

package/src/transform/template/glimmer-ast-mapping-tree.ts

@@ -0,0 +1,173 @@
+import { AST } from '@glimmer/syntax';
+import { Range } from './transformed-module.js';
+import { Identifier } from './map-template-contents.js';
+import { CodeInformation } from '@volar/language-server/node.js';
+
+export type MappingSource = AST.Node | TemplateEmbedding | TextContent | Identifier | ParseError;
+
+/**
+ * In cases where we're unable to parse a template, we still want to
+ * be able to hold a placeholder mapping so that we can respond sensibly
+ * to offset transformation queries. This class acts as a standin for
+ * the proper AST node we were unable to obtain in such cases.
+ */
+export class ParseError {
+  public readonly type = 'ParseError';
+}
+
+/**
+ * The Glimmer AST uses `TextNode` for both string arg values on elements
+ * and for top-level text content floating in the DOM itself. Since we
+ * want to treat the two differently (namely, string args may have useful
+ * completion suggestions but plain text doesn't), we use a stand-in
+ * node for the latter.
+ */
+export class TextContent {
+  public readonly type = 'TextContent';
+}
+
+/**
+ * This node represents the root of an embedded template, including
+ * the surrounding `<template>...</template>` boilerplate that designates
+ * the surrounded contents as a template.
+ */
+export class TemplateEmbedding {
+  public readonly type = 'TemplateEmbedding';
+}
+
+/**
+ * A `MappingTree` maintains a hierarchy of mappings between ranges of
+ * locations in original and transformed source strings. These mappings
+ * are naturally hierarchical due to the tree structure of the underlying
+ * code.
+ *
+ * For instance, given an expression like `{{foo.bar}}` in a template, a
+ * corresponding expression in TypeScript might be `foo?.bar`. The individual
+ * identifiers `foo` and `bar` map directly to one another, but the full
+ * expressions do as well. By maintaining a full hierarchy of these mappings,
+ * we can always report diagnostics in the template at roughly the same
+ * level of granularity as TS itself uses when reporting on the transformed
+ * output.
+ */
+export default class GlimmerASTMappingTree {
+  public parent: GlimmerASTMappingTree | null = null;
+
+  public constructor(
+    public transformedRange: Range,
+    public originalRange: Range,
+    public children: Array<GlimmerASTMappingTree> = [],
+    public sourceNode: MappingSource,
+    public codeInformation?: CodeInformation,
+  ) {
+    children.forEach((child) => (child.parent = this));
+  }
+
+  /**
+   * Returns the mapping corresponding to the smallest span in the transformed source
+   * that contains the given range, or `null` if that range doesn't fall within
+   * this mapping tree.
+   */
+  public narrowestMappingForTransformedRange(range: Range): GlimmerASTMappingTree | null {
+    if (range.start < this.transformedRange.start || range.end > this.transformedRange.end) {
+      return null;
+    }
+
+    for (let child of this.children) {
+      let mapping = child.narrowestMappingForTransformedRange(range);
+      if (mapping) {
+        return mapping;
+      }
+    }
+
+    return this;
+  }
+
+  /**
+   * Returns the mapping corresponding to the smallest span in the original source
+   * that contains the given range, or `null` if that range doesn't fall within
+   * this mapping tree.
+   */
+  public narrowestMappingForOriginalRange(range: Range): GlimmerASTMappingTree | null {
+    if (range.start < this.originalRange.start || range.end > this.originalRange.end) {
+      return null;
+    }
+
+    for (let child of this.children) {
+      let mapping = child.narrowestMappingForOriginalRange(range);
+      if (mapping) {
+        return mapping;
+      }
+    }
+
+    return this;
+  }
+
+  /**
+   * Returns all mappings that exactly match the provided range.
+   */
+  public exactMappingsForOriginalRange(range: Range): GlimmerASTMappingTree[] {
+    const results: GlimmerASTMappingTree[] = [];
+
+    if (range.start < this.originalRange.start || range.end > this.originalRange.end) {
+      return results;
+    }
+
+    if (range.start == this.originalRange.start && range.end == this.originalRange.end) {
+      results.push(this);
+    }
+
+    for (let child of this.children) {
+      results.push(...child.exactMappingsForOriginalRange(range));
+    }
+
+    return results;
+  }
+
+  public toDebugString(options: {
+    originalStart: number;
+    originalSource: string;
+    transformedStart: number;
+    transformedSource: string;
+    indent?: string;
+  }): string {
+    let { originalSource, transformedSource, indent = '| ' } = options;
+    let { sourceNode, originalRange, transformedRange, children } = this;
+    let hbsStart = options.originalStart + originalRange.start;
+    let hbsEnd = options.originalStart + originalRange.end;
+    let tsStart = options.transformedStart + transformedRange.start;
+    let tsEnd = options.transformedStart + transformedRange.end;
+    let lines = [];
+
+    lines.push(`${indent}Mapping: ${sourceNode.type}`);
+
+    lines.push(
+      `${indent}${` hbs(${hbsStart}:${hbsEnd}):`.padEnd(15)}${this.getSourceRange(
+        originalSource,
+        originalRange,
+      )}`,
+    );
+
+    lines.push(
+      `${indent}${` ts(${tsStart}:${tsEnd}):`.padEnd(15)}${this.getSourceRange(
+        transformedSource,
+        transformedRange,
+      )}`,
+    );
+
+    lines.push(indent);
+
+    for (let child of children) {
+      lines.push(child.toDebugString({ ...options, indent: indent + '| ' }));
+    }
+
+    if (children.length) {
+      lines.push(indent);
+    }
+
+    return lines.map((line) => line.trimEnd()).join('\n');
+  }
+
+  private getSourceRange(source: string, range: Range): string {
+    return source.slice(range.start, range.end).trim().replace(/\n/g, '\\n').replace(/\r/g, '\\r');
+  }
+}

package/src/transform/template/inlining/index.ts

@@ -0,0 +1,33 @@
+import type ts from 'typescript';
+import { CorrelatedSpan, Directive, TransformError } from '../transformed-module.js';
+import { TSLib } from '../../util.js';
+
+export type PartialCorrelatedSpan = Omit<CorrelatedSpan, 'transformedStart' | 'transformedLength'>;
+
+export type CorrelatedSpansResult = {
+  errors: Array<TransformError>;
+  directives: Array<Directive>;
+  partialSpans: Array<PartialCorrelatedSpan>;
+};
+
+/**
+ * Given an AST node for an embedded template, determines whether it's embedded
+ * within a class in such a way that that class should be treated as its backing
+ * value.
+ */
+export function isEmbeddedInClass(ts: TSLib, node: ts.Node): boolean {
+  let current: ts.Node | null = node;
+  do {
+    // TODO: this should likely actually filter on whether the template appears in a
+    // static block or property definition, but just "am I in a class body" is the
+    // current status quo and has been ok so far.
+    if (ts.isHeritageClause(current)) {
+      return false;
+    }
+    if (ts.isClassLike(current)) {
+      return true;
+    }
+  } while ((current = current.parent));
+
+  return false;
+}