@transclude/core 0.2.0 → 0.3.0

package/src/typecheck.js

@@ -15,6 +15,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import ts from 'typescript';
+import { AMBIENT_NAMES } from './compiler/ambient.js';
 import { buildEndpointShim, buildShim, originalOffset } from './compiler/shim.js';
 import { splitBlocks, readFlags } from './compiler/index.js';
 import { resolveRoutesDir, scanRoutes } from './routes.js';
@@ -45,14 +46,38 @@ const compilerOptions = (strict) => ({
   types: [],
 });
 
+// `UseFullyQualifiedType` is what makes a name the app declared resolvable
+// somewhere else. Without it a `@typedef {…} Post` in the app prints as `Post`,
+// which means something in the file it came from and nothing in
+// transclude-env.d.ts, where it landed as an undeclared name.
 const TYPE_FORMAT =
   ts.TypeFormatFlags.NoTruncation |
   ts.TypeFormatFlags.InTypeAlias |
+  ts.TypeFormatFlags.UseFullyQualifiedType |
   ts.TypeFormatFlags.UseSingleQuotesForStringLiteralType;
 
 const LAYOUT_FILE = '_layout.html';
 
 /**
+ * The checker, and everything it needs held in one closure.
+ *
+ * This is long and stays long: every helper below reads the language service,
+ * the shim map or the resolved project, and handing each of them five arguments
+ * instead would be more to read rather than less. It is a list of small named
+ * functions, in this order:
+ *
+ *   the language service     host, install, sourceOf
+ *   reading a type back      exportTypeOf, expand, resolveNames, and the four
+ *                            `…TypeOf` shorthands
+ *   finding the project      elementFiles, layoutFiles, ancestorsOf, chainFor
+ *   what a shim is given     contextLiteral, endpointLiteral, mergeTypes
+ *   building them            build, refresh
+ *   what callers use         the returned object
+ *
+ * `build` is the one to read first. It compiles every shim in dependency order,
+ * which is the only order that resolves: an element depends on nothing, a layout
+ * on the layouts above it, a page on its whole chain.
+ *
  * @param {{ root: string, appDir: string, routesDir: string, elementsDir: string,
  *   strict?: boolean }} options
  * @returns {{ files: Function, update: Function, rebuild: Function,
@@ -121,6 +146,53 @@ export function createChecker({
     return text === 'any' ? 'unknown' : text;
   };
 
+  // `UseFullyQualifiedType` prints a named type as `import("/abs/file").Name`.
+  // Inside a shim that resolves and is what keeps a prop structurally checked.
+  // In transclude-env.d.ts it does not: a shim path is `<file>.js` for an .html
+  // file nobody can import, and an absolute path would name this machine.
+  const QUALIFIED = /import\("([^"]+)"\)\.([A-Za-z_$][\w$]*)/g;
+
+  /**
+   * The type a name stands for, expanded. `InTypeAlias` is what stops tsc
+   * printing the alias for the type it was asked to print, so this returns the
+   * shape rather than the name again. A type naming itself terminates: the
+   * placeholder is in place before the expansion is resolved.
+   */
+  const expand = (file, name, into) => {
+    const key = `${file}\0${name}`;
+    const already = into.byKey.get(key);
+    if (already) return already;
+
+    const program = service.getProgram();
+    // tsc prints the path with no extension, and a shim is the source it names
+    // plus `.js`.
+    const source = program?.getSourceFile(file) ?? program?.getSourceFile(`${file}.js`);
+    const checker = program?.getTypeChecker();
+    const moduleSymbol = source && checker?.getSymbolAtLocation(source);
+    const symbol =
+      moduleSymbol && checker.getExportsOfModule(moduleSymbol).find((s) => s.getName() === name);
+    // Two files can each declare a `Post`, and one name cannot mean both.
+    let display = name;
+    for (let n = 2; into.text.has(display); n++) display = `${name}_${n}`;
+    if (!symbol) return display;
+
+    into.byKey.set(key, display);
+    into.text.set(display, '');
+    const declared = checker.getDeclaredTypeOfSymbol(symbol);
+    into.text.set(display, resolveNames(checker.typeToString(declared, undefined, TYPE_FORMAT), into));
+    return display;
+  };
+
+  /**
+   * Every qualified name in a type string, replaced by a bare one. What the
+   * compiler declares for itself is left to the emitted file, which writes the
+   * same shapes from `ambient.js`; anything else is the app's and is expanded.
+   */
+  const resolveNames = (type, into) =>
+    type.replace(QUALIFIED, (_, file, name) =>
+      AMBIENT_NAMES.has(name) ? name : expand(file, name, into),
+    );
+
   const dataTypeOf = (file) => exportTypeOf(file, '__data');
   const propTypeOf = (file) => exportTypeOf(file, '__propTypes');
   const memberTypeOf = (file) => exportTypeOf(file, '__members');
@@ -426,8 +498,18 @@ export function createChecker({
       };
     },
 
-    /** Everything transclude-env.d.ts is written from. */
+    /**
+     * Everything transclude-env.d.ts is written from.
+     *
+     * Every type string is passed through `named`, which turns a qualified
+     * reference into a bare name and collects what that name is. A type the app
+     * declared is reachable from the file it was written in and from nowhere
+     * else, so the emitted file carries its own copy rather than an import: one
+     * declared in an .html file has no module to be imported from at all.
+     */
     describe() {
+      const aliases = { byKey: new Map(), text: new Map() };
+      const named = (type) => resolveNames(type, aliases);
       // Light elements are described separately: they have props but no shadow
       // root, so nothing about `this.shadowRoot` applies to them.
       const partialTags = new Set(
@@ -435,26 +517,38 @@ export function createChecker({
           .filter((file) => !isShadow(file))
           .map((file) => path.basename(file, '.html')),
       );
-      return {
+      const element = ([tag, type]) => {
+        const { members, state, upgrades } = project.componentMembers.get(tag) ?? {};
+        return {
+          tag,
+          type: named(type),
+          upgrades,
+          members: members ? named(members) : members,
+          state: state ? named(state) : state,
+        };
+      };
+
+      const described = {
         components: [...project.componentProps]
           .filter(([tag]) => !partialTags.has(tag))
-          .map(([tag, type]) => ({ tag, type, ...project.componentMembers.get(tag) })),
-        partials: [...project.componentProps]
-          .filter(([tag]) => partialTags.has(tag))
-          .map(([tag, type]) => ({ tag, type, ...project.componentMembers.get(tag) })),
+          .map(element),
+        partials: [...project.componentProps].filter(([tag]) => partialTags.has(tag)).map(element),
         layouts: [...project.layoutData].map(([id, type]) => ({
           id,
-          type,
-          context: contextFor(project.layouts.get(id)),
+          type: named(type),
+          context: named(contextFor(project.layouts.get(id))),
         })),
         pages: [...project.pages].map(([id, { route, context }]) => ({
           id,
           params: route.params,
           pattern: route.pattern,
-          context,
-          type: dataTypeOf(route.file),
+          context: named(context),
+          type: named(dataTypeOf(route.file)),
         })),
       };
+
+      // Collected while the above was named, so it is read after, not during.
+      return { ...described, types: [...aliases.text].map(([name, type]) => ({ name, type })) };
     },
   };
 }