@transclude/core 0.1.1 → 0.3.0

package/src/server.js

@@ -1,7 +1,7 @@
 // The Hono app both servers start from.
 //
 // One function rather than two `new Hono()` calls, because the order things are
-// registered in *is* the behaviour: a guard registered after the static handler
+// registered in *is* the behavior: a guard registered after the static handler
 // does not guard a prerendered page. Two copies of that order is two servers
 // that disagree, which has happened twice in this codebase already.
 
@@ -83,7 +83,7 @@ export function baseApp(options = {}) {
   if (csrfOption) app.use('*', csrf(csrfOption === true ? undefined : csrfOption));
 
   /**
-   * The one security header with no judgement in it.
+   * The one security header with no judgment in it.
    *
    * Without it a browser may sniff a response's bytes and decide the declared
    * type was wrong, so a text file an app serves can be read as HTML and a

package/src/sitemap.js

@@ -6,6 +6,8 @@
 // else (a route with no `paths`, an endpoint, an error page) is not a page a
 // crawler can reach by guessing, so it is left out.
 
+import { urlFor } from './document.js';
+
 /** The protocol's cap for one file. Past it the response is an index of files. */
 const LIMIT = 50000;
 
@@ -56,9 +58,7 @@ export async function sitemapEntries(manifest, pages, { entries = [], exclude =
     if (typeof page?.paths !== 'function') continue;
 
     for (const params of (await page.paths()) ?? []) {
-      found.push({
-        path: route.pattern.replace(/:(\w+)(\{[^}]*\})?/g, (_, name) => String(params[name] ?? '')),
-      });
+      found.push({ path: urlFor(route, params) });
     }
   }
 

package/src/static-cache.js

@@ -41,7 +41,7 @@ const TYPES = {
  * @property {number} onDisk left on disk because the budget ran out
  * @property {number} encoded how many have a precompressed variant
  * @property {Map<string, Entry|{ file: string }>} entries for the build, which
- *   serialises these for a runtime with no filesystem
+ *   serializes these for a runtime with no filesystem
  * @property {(pathname: string) => Entry|null} get
  */
 
@@ -94,7 +94,7 @@ function load(dir, urlFor, { maxBytes = DEFAULT_MAX_BYTES } = {}) {
     count: entries.size,
     bytes,
     onDisk,
-    /** For the build, which serialises these for runtimes with no filesystem. */
+    /** For the build, which serializes these for runtimes with no filesystem. */
     entries,
     encoded: [...entries.values()].filter((e) => e.encodings?.size).length,
 
@@ -139,7 +139,10 @@ function read(file) {
  * @returns {string} a quoted ETag
  */
 export function etagOf(body) {
-  return `"${createHash('sha1').update(body).digest('base64url').slice(0, 20)}"`;
+  const digest = createHash('sha1').update(body).digest('base64url');
+  // Twenty characters of base64url is 120 bits, which is far more than a cache
+  // key needs and short enough to read in a header.
+  return `"${digest.slice(0, 20)}"`;
 }
 
 function variantSize(file) {

package/src/typecheck.js

@@ -6,7 +6,7 @@
 // and rewriting is where source mapping breaks down.
 //
 // JavaScript rather than TypeScript because a JSDoc `@type` in the author's own
-// `<script props>` is honoured in a .js file and silently ignored in a .ts one.
+// `<script props>` is honored in a .js file and silently ignored in a .ts one.
 //
 // Shims are self-contained: route contexts and component props are inlined as
 // type literals rather than imported. transclude-env.d.ts is written *from* the shims,
@@ -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 })) };
     },
   };
 }