@transclude/core 0.13.0 → 0.15.0

package/bin/check.js

@@ -3,8 +3,7 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
-import ts from 'typescript';
-import { createChecker, positionAt } from '../src/typecheck.js';
+import { checkAlone, createChecker, positionAt } from '../src/typecheck.js';
 import { emitTypes } from '../src/compiler/types.js';
 import { loadProject } from '../src/project.js';
 import { isMarkdown } from '../src/markdown.js';
@@ -23,34 +22,15 @@ if (!fs.existsSync(types) || fs.readFileSync(types, 'utf8') !== next) {
 }
 
 // Nothing downstream reads this file, so nothing else would notice it being
-// wrong. Parse what we just wrote, or a bad identifier ships silently.
-//
-// `skipLibCheck` has to be off, and it was on. This is a .d.ts, which is the one
-// kind of file that flag skips, so the guard checked nothing at all: every
-// project shipped a file naming `__Cookies` and declaring it nowhere. An editor
-// missed it too, because a jsconfig.json implies the same flag.
-//
-// `types: []` keeps it to this file: whatever `@types` a project happens to have
-// installed is not what is being checked here, and one of them failing to
-// resolve its own dependency would read as our file being broken.
-const emitted = ts.createProgram([types], {
-  noEmit: true,
-  skipLibCheck: false,
-  types: [],
-  target: ts.ScriptTarget.ESNext,
-  lib: ['lib.esnext.d.ts', 'lib.dom.d.ts'],
-});
-const broken = [
-  ...emitted.getSyntacticDiagnostics(),
-  ...emitted.getSemanticDiagnostics(),
-];
+// wrong. Parse what we just wrote, or a bad identifier ships silently. The
+// guard itself lives in `checkAlone`, where the reasons for its options are,
+// and where `test/types.test.js` reads the same answers.
+const broken = checkAlone(types);
 if (broken.length) {
   console.error(`\n${path.relative(root, types)} is not valid TypeScript:`);
   for (const diagnostic of broken.slice(0, 5)) {
-    const at = diagnostic.file?.getLineAndCharacterOfPosition(diagnostic.start ?? 0);
-    console.error(
-      `  ${at ? `line ${at.line + 1}: ` : ''}${ts.flattenDiagnosticMessageText(diagnostic.messageText, ' ')}`,
-    );
+    const at = positionAt(next, diagnostic.offset);
+    console.error(`  line ${at.line}: ${diagnostic.message}`);
   }
   if (broken.length > 5) console.error(`  …and ${broken.length - 5} more`);
   process.exit(1);
@@ -97,6 +77,9 @@ for (const file of files) {
   }
 }
 
+// The compiler is a child process. Closed here, or the exit waits on it.
+checker.dispose();
+
 const plural = (count, word) => `${count} ${word}${count === 1 ? '' : 's'}`;
 
 if (errors + warnings) {

package/bin/dev.js

@@ -264,17 +264,24 @@ const handleAction = async (route, c) => {
     : sendFragment(route, c, region, extra);
 };
 
-const onError = (c, err) => {
+const onError = (c, err, at = null) => {
   // Before anything reads the stack: Vite's transform means the raw one points
   // at generated code, and a reporter given that is worse than none.
   vite.ssrFixStacktrace(err);
   console.error(err);
 
-  // The same seam production has, so a reporter is exercised while you are the
-  // one looking at it rather than first on a live site.
+  // The same seam production has, with the same shape, so a reporter is
+  // exercised while you are the one looking at it rather than first on a live
+  // site. A field dev left null would read as a production bug later.
   if (typeof config.onError === 'function') {
     try {
-      config.onError(err, { request: c.req.raw, url: c.req.url, method: c.req.method });
+      config.onError(err, {
+        request: c.req.raw,
+        url: c.req.url,
+        method: c.req.method,
+        route: at ? { id: at.route.id, pattern: at.route.pattern, params: c.req.param() } : null,
+        phase: at?.phase ?? null,
+      });
     } catch (failed) {
       console.error('[transclude] onError itself threw:', failed);
     }
@@ -389,7 +396,7 @@ async function buildApp() {
         const fragment = fragmentOf(c);
         return fragment === null ? await renderPage(route, c) : await sendFragment(route, c, fragment);
       } catch (err) {
-        return onError(c, err);
+        return onError(c, err, { route, phase: fragmentOf(c) === null ? 'page' : 'fragment' });
       }
     });
 
@@ -400,7 +407,7 @@ async function buildApp() {
       try {
         return await handleAction(route, c);
       } catch (err) {
-        return onError(c, err);
+        return onError(c, err, { route, phase: 'action' });
       }
     });
   }
@@ -422,7 +429,7 @@ async function buildApp() {
           Allow: endpointMethods(mod).join(', '),
         });
       } catch (err) {
-        return onError(c, err);
+        return onError(c, err, { route, phase: 'endpoint' });
       }
     });
   }
@@ -432,7 +439,7 @@ async function buildApp() {
     try {
       return await renderPage(notFound, c, 404);
     } catch (err) {
-      return onError(c, err);
+      return onError(c, err, { route: notFound, phase: 'page' });
     }
   });
 

package/bin/serve.js

@@ -2,6 +2,7 @@
 // Node adapter. The app is in src/production.js; this listens with it.
 
 import { serve } from '@hono/node-server';
+import { drainOn } from '../src/drain.js';
 import { app, noBuild, port, summary } from '../src/production.js';
 
 if (noBuild) {
@@ -9,4 +10,8 @@ if (noBuild) {
   process.exit(1);
 }
 
-serve({ fetch: app.fetch, port }, ({ port }) => summary(port));
+const server = serve({ fetch: app.fetch, port }, ({ port }) => summary(port));
+
+// A container sends SIGTERM and waits. Node's default is to die on the spot,
+// which cuts a render that was halfway through answering.
+drainOn(server);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@transclude/core",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "An HTML-first server framework. A page is an .html file, the directory tree is the route table, and any fragment of a page is a URL of its own. Runs on Node, Bun, Deno and workerd, and ships no client JavaScript by default.",
   "keywords": [
     "html",
@@ -38,6 +38,7 @@
   "exports": {
     ".": "./src/plugin.js",
     "./app": "./src/app.js",
+    "./compiler": "./src/compiler/index.js",
     "./cookies": "./src/cookies.js",
     "./document": "./src/document.js",
     "./production": "./src/production.js",
@@ -57,6 +58,7 @@
   ],
   "scripts": {
     "test": "node --test \"test/**/*.test.js\"",
+    "crap": "node scripts/crap.js",
     "test:examples": "npm test --prefix examples/showcase && npm test --prefix examples/todomvc && npm test --prefix examples/blog && npm test --prefix examples/search && npm test --prefix examples/htmx && npm test --prefix examples/includes && npm test --prefix examples/auth && npm test --prefix examples/live && npm test --prefix examples/elements && npm test --prefix examples/markdown && npm test --prefix examples/atlas",
     "test:www": "npm test --prefix www",
     "showcase": "npm run dev --prefix examples/showcase",
@@ -82,12 +84,12 @@
     "parse5": "^8.0.1"
   },
   "peerDependencies": {
-    "typescript": "^5.9",
+    "typescript": "^7.0",
     "vite": "^8"
   },
   "devDependencies": {
     "@types/node": "^22.20.1",
-    "typescript": "^5.9.3",
+    "typescript": "7.0.2",
     "vite": "^8.1.5"
   }
 }

package/src/app.js

@@ -35,6 +35,11 @@ import { withDefaults } from './defaults.js';
 
 const IMMUTABLE = 'public, max-age=31536000, immutable';
 const REVALIDATE = 'public, max-age=0, must-revalidate';
+// What a personal render says instead. `public` is an explicit grant, and a
+// page that read a cookie is one visitor's. A conforming shared cache would
+// revalidate and miss on the ETag anyway; this is for the CDN whose edge rule
+// skips revalidation and would hand one visitor's page to the next.
+const PERSONAL = 'private, no-cache';
 
 // One per process rather than one per render. It holds no state between calls.
 const encoder = new TextEncoder();
@@ -220,7 +225,7 @@ export function createApp({
       revalidateTag: cache.revalidateTag,
       // Reported through `report`, so work that fails after the reader is gone
       // is not quieter than work that fails in front of them.
-      after: afterFor(c, (error) => report(error, c)),
+      after: afterFor(c, (error) => report(error, c, { route, phase: 'after' })),
       ...extra,
     };
   };
@@ -316,7 +321,7 @@ export function createApp({
         if (html === null) return c.text(`no fragment "${region}"`, 404);
         return sendRendered(c, html, ctx);
       } catch (err) {
-        return internalError(c, err);
+        return internalError(c, err, { route, phase: 'fragment' });
       }
     });
 
@@ -369,7 +374,7 @@ export function createApp({
         if (html instanceof Response) return withEnvelope(html, ctx);
         return sendRendered(c, html, ctx);
       } catch (err) {
-        return internalError(c, err);
+        return internalError(c, err, { route, phase: 'action' });
       }
     });
   }
@@ -391,7 +396,7 @@ export function createApp({
           Allow: endpointMethods(mod).join(', '),
         });
       } catch (err) {
-        return internalError(c, err);
+        return internalError(c, err, { route, phase: 'endpoint' });
       }
     });
   }
@@ -450,7 +455,7 @@ export function createApp({
         // workerd stops the rebuild when this response is sent, and the entry it
         // leaves in the in-flight map answers every later request with a dead
         // promise.
-        const after = afterFor(c, (error) => report(error, c));
+        const after = afterFor(c, (error) => report(error, c, { route, phase: 'revalidate' }));
         const html = await cache.read(cacheKey(c.req.url), window, render, after);
 
         // A miss rendered through the cache, and that render can answer with a
@@ -462,7 +467,7 @@ export function createApp({
         const ctx = last ? last.ctx : contextFor(route, c);
         return sendRendered(c, html, ctx, preload);
       } catch (err) {
-        return internalError(c, err);
+        return internalError(c, err, { route, phase: 'page' });
       }
     });
   }
@@ -475,19 +480,28 @@ export function createApp({
    * `console.error` is the default and not much of one: a real site sends this
    * to something that can page a person. `onError` is that seam, and it is given
    * the request as well, because an error with no URL and no method is most of
-   * the way to useless.
+   * the way to useless. `route` and `phase` say where: the reader starts at the
+   * loader of `people/[slug]` with `slug: 'ada'` rather than at a URL to
+   * re-derive that from. The phases are page, fragment, action, endpoint,
+   * after and revalidate.
    *
    * It is called inside a `try`. A reporter that throws would otherwise replace
    * the error being reported, which is the one failure mode a reporting hook
    * must not have.
    */
-  function report(err, c) {
+  function report(err, c, at = null) {
     if (typeof config.onError !== 'function') {
       console.error(err);
       return;
     }
     try {
-      config.onError(err, { request: c.req.raw, url: c.req.url, method: c.req.method });
+      config.onError(err, {
+        request: c.req.raw,
+        url: c.req.url,
+        method: c.req.method,
+        route: at ? { id: at.route.id, pattern: at.route.pattern, params: c.req.param() } : null,
+        phase: at?.phase ?? null,
+      });
     } catch (failed) {
       console.error(err);
       console.error('[transclude] onError itself threw:', failed);
@@ -495,8 +509,8 @@ export function createApp({
   }
 
   /** Every `catch` above. One place decides what a failed request looks like. */
-  function internalError(c, err) {
-    report(err, c);
+  function internalError(c, err, at = null) {
+    report(err, c, at);
     // No ETag and no Cache-Control: nothing about a failure should be stored or
     // revalidated, and the same bytes would be sent for an unrelated one next time.
     if (!errorPage) return c.text('Internal error', 500);
@@ -529,7 +543,10 @@ export function createApp({
     const etag = encoding ? `${base.slice(0, -1)}-${encoding}"` : base;
 
     c.header('Vary', varyOn);
-    c.header('Cache-Control', REVALIDATE);
+    // The same test that gates the held-page store. A shareable render is
+    // anyone's; a personal one has to say so, or a cache told `public` would
+    // be within its rights to believe it.
+    c.header('Cache-Control', ctx && !isShareable(html, ctx) ? PERSONAL : REVALIDATE);
     c.header('ETag', etag);
 
     // Whatever the loaders put on `ctx.response`, after the defaults above so a

package/src/compiler/expr.js

@@ -55,14 +55,6 @@ export class Scope {
     }
     return null;
   }
-
-  // Used for the shadowing warning: does an *enclosing* scope already bind this?
-  outerHas(name) {
-    for (let s = this.parent; s; s = s.parent) {
-      if (s.vars.has(name)) return true;
-    }
-    return false;
-  }
 }
 
 /**

package/src/cookies.js

@@ -45,7 +45,9 @@ export function cookiesOf(request, response, secret = null) {
     // `typeof` along the way said `string`, and the config carried it all the
     // way here. The only thing that said otherwise was the length. Reading
     // "needs a secret" while looking at a secret that is plainly set sends you
-    // hunting through the wiring instead of the value.
+    // hunting through the wiring instead of the value. `withDefaults` refuses
+    // the empty string at boot now; this stays for a `cookiesOf` reached
+    // without it.
     if (typeof secret === 'string') {
       throw new Error(
         `[transclude] ${what} needs a secret, and \`cookieSecret\` is set to an ` +
@@ -168,5 +170,18 @@ function overTls(request) {
  * turns the whole thing off. Set it yourself to override either way.
  */
 function withDefaults(options, request) {
-  return { path: '/', httpOnly: true, sameSite: 'Lax', secure: overTls(request), ...options };
+  const merged = { path: '/', httpOnly: true, sameSite: 'Lax', secure: overTls(request), ...options };
+
+  // Every browser drops this pair, silently, so writing it is never right.
+  // `None` is for a cookie sent cross-site, and those are Secure-only
+  // everywhere. Refused here rather than left to the browser, because a cookie
+  // that never arrives reads exactly like a bug somewhere else.
+  if (String(merged.sameSite).toLowerCase() === 'none' && !merged.secure) {
+    throw new Error(
+      `[transclude] a cookie with \`sameSite: 'None'\` needs \`secure: true\`. Every ` +
+        `browser drops the pair without it, silently. Set both, or use 'Lax'.`,
+    );
+  }
+
+  return merged;
 }

package/src/defaults.js

@@ -97,6 +97,19 @@ export function withDefaults(config = {}) {
 
   const merged = { ...DEFAULTS, ...config };
 
+  // Set but empty is refused at boot rather than at the first signed cookie,
+  // because that first read happens in production, at request time, days after
+  // the deploy that broke it. It happened: `wrangler secret put` took a blank
+  // line, so the binding existed and carried nothing. `null` stays fine, since
+  // that is how an app says it signs nothing.
+  if (merged.cookieSecret === '') {
+    throw new Error(
+      `[transclude] \`cookieSecret\` is an empty string. Whatever supplies it handed ` +
+        `over nothing: on a worker that is usually a \`wrangler secret put\` that took ` +
+        `a blank line. Set a real secret, or \`null\` for none.`,
+    );
+  }
+
   // Refused here because there are four places that render a page and only two of
   // them could fall back to a request's origin. Left to the render, `canonical`
   // would work in dev and throw in the build, which is the dev-and-production

package/src/drain.js

@@ -0,0 +1,63 @@
+// Finishing what is in flight when the platform says stop.
+//
+// A container sends SIGTERM and waits a moment before SIGKILL. Node's default
+// for SIGTERM is to die on the spot, so a render halfway through its loader
+// answers nobody, and an action may have happened with its response cut on the
+// wire. Draining instead refuses new connections, finishes what is running,
+// and leaves.
+//
+// No imports. `process` and the timers are globals, and the server arrives as
+// an argument.
+
+/**
+ * Exit cleanly on a stop signal, once the work in flight is done.
+ *
+ * `close` stops the listener and waits for every open connection. A keep-alive
+ * connection counts as open with no request on it, so idle ones are swept
+ * while the close waits; without the sweep, the first browser that ever
+ * connected would hold the wait to the cap. The cap is for a render that
+ * hangs: past it, every connection is cut and the exit code says the drain was
+ * not clean. Both timers are unref'd, so neither keeps a finished process
+ * alive.
+ *
+ * @param {object} server what `serve` returned: a `node:http` server
+ * @param {{ signals?: string[], grace?: number, sweep?: number, exit?: Function }} [options]
+ * @returns {() => void} the drain itself, so a test can run one without a signal
+ */
+export function drainOn(server, options = {}) {
+  const {
+    signals = ['SIGTERM', 'SIGINT'],
+    grace = 10_000,
+    sweep = 500,
+    exit = (code) => process.exit(code),
+  } = options;
+
+  // The cap and the close both want to be the exit. First one wins.
+  let left = false;
+  const leave = (code) => {
+    if (left) return;
+    left = true;
+    exit(code);
+  };
+
+  const drain = () => {
+    const idle = setInterval(() => server.closeIdleConnections?.(), sweep);
+    idle.unref?.();
+
+    const cap = setTimeout(() => {
+      server.closeAllConnections?.();
+      leave(1);
+    }, grace);
+    cap.unref?.();
+
+    server.close(() => {
+      clearInterval(idle);
+      clearTimeout(cap);
+      leave(0);
+    });
+    server.closeIdleConnections?.();
+  };
+
+  for (const signal of signals) process.once(signal, drain);
+  return drain;
+}

package/src/lookup.js

@@ -24,7 +24,7 @@ import { blockedAddress } from './address.js';
  * this is defense behind it.
  *
  * @param {{ resolver?: object }} [deps] injected so a test needs no DNS
- * @returns {(hostname: string) => Promise<string[]>} every address the name answers with
+ * @returns {(hostname: string) => Promise<string|null>} why the name is refused, or null
  */
 export function nodeLookup({ resolver = dns } = {}) {
   return async (hostname) => {

package/src/proxy.js

@@ -33,13 +33,26 @@ const DEFAULTS = {
 
 const STYLE_MODES = new Set(['keep', 'strip']);
 
+/** Every key `proxy` may set. `lookup` has no default: absent means the runtime's. */
+const KEYS = new Set([...Object.keys(DEFAULTS), 'lookup']);
+
 /**
- * Defaults filled in, and the one value worth checking checked. A misspelled
- * `styles` would keep every style attribute and say nothing, which reads exactly
- * like the setting working.
+ * Defaults filled in, and what the author wrote checked. A misspelled `maxage`
+ * would fall back to the default and say nothing, which reads exactly like the
+ * setting working. That is the failure the config's own keys refuse by name,
+ * one level up, and these keys get the same treatment.
  */
 function settings(options) {
   const config = { ...DEFAULTS, ...options };
+
+  const unknown = Object.keys(options ?? {}).filter((key) => !KEYS.has(key));
+  if (unknown.length) {
+    throw new Error(
+      `[transclude] \`proxy\` sets ${unknown.join(', ')}, which nothing reads. ` +
+        `The keys are ${[...KEYS].sort().join(', ')}.`,
+    );
+  }
+
   if (!STYLE_MODES.has(config.styles)) {
     throw new Error(
       `[transclude] proxy.styles is ${JSON.stringify(config.styles)}. It is 'keep' or 'strip'.`,
@@ -289,10 +302,12 @@ export function proxyHandler(options = {}, deps = {}) {
     try {
       const entry = await readForeign(url, config, { ...deps, store });
 
-      // No id is a question about the document rather than a piece of it.
+      // No id is a question about the document rather than a piece of it, so
+      // the answer also says what the cleaning took out. The list was already
+      // kept for exactly this; nothing read it until here.
       if (!id) {
         const { listFragments } = await import('./extract.js');
-        return json(200, { url, fragments: listFragments(entry.doc) });
+        return json(200, { url, fragments: listFragments(entry.doc), removed: entry.removed });
       }
 
       const found = resolveFragment(entry.doc, id);

package/src/rewrite.js

@@ -81,15 +81,15 @@ export function sanitize(root, { styles = 'keep' } = {}) {
           removed.push('@style');
           return false;
         }
-        return true;
-      });
-
-      for (const attr of child.attrs) {
+        // Removed rather than emptied. An empty value still means something:
+        // `href=""` names the page the fragment lands in, and `action=""`
+        // submits to it, neither of which the source wrote.
         if (!allowedUrl(child, attr)) {
           removed.push(`@${attr.name}`);
-          attr.value = '';
+          return false;
         }
-      }
+        return true;
+      });
 
       visit(child);
     }
@@ -100,7 +100,7 @@ export function sanitize(root, { styles = 'keep' } = {}) {
 }
 
 /**
- * Whether a URL-bearing attribute may keep its value.
+ * Whether a URL-bearing attribute may stay.
  *
  * `javascript:` is refused everywhere. `data:` is refused everywhere except an
  * image source, where it is ordinary and cannot navigate anything.

package/src/typecheck.js

@@ -1,4 +1,5 @@
-// Type checking and type extraction, both by TypeScript.
+// Type checking and type extraction, both by TypeScript 7: the Go compiler as
+// a child process, driven through its API over a synchronous channel.
 //
 // Shims live in memory at `<file>.html.js`, never on disk. Naming them after the
 // source file is what makes their relative imports resolve the way the author
@@ -14,7 +15,7 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
-import ts from 'typescript';
+import { version as tsVersion } from 'typescript';
 import { AMBIENT_NAMES } from './compiler/ambient.js';
 import { buildEndpointShim, buildShim, originalOffset } from './compiler/shim.js';
 import { splitBlocks, readFlags } from './compiler/index.js';
@@ -22,6 +23,67 @@ import { resolveRoutesDir, scanRoutes } from './routes.js';
 // Aliased: this file has its own `sourceOf`, which is the one that reads disk.
 import { MARKDOWN_EXT, sourceOf as htmlFrom } from './markdown.js';
 
+// The version is checked before the API is imported, because the import is what
+// fails on the wrong version: `typescript/unstable/sync` is a 7.x export, and a
+// resolution error names a package path rather than the fix.
+if (!/^7\./.test(tsVersion)) {
+  throw new Error(
+    `[transclude] transclude-check drives TypeScript 7 and this project has ${tsVersion}. ` +
+      `Install it: npm install -D typescript@7`,
+  );
+}
+
+// The 7.x API: a Go compiler as a child process, spoken to synchronously. It
+// is exported under `unstable`, which is the API's own warning, so the import
+// and the shape are both checked rather than trusted. A 7.x minor may move the
+// subpath, which fails loudly with the wrong name, or rename a flag, which
+// does not fail at all: an undefined bit ORs into TYPE_FORMAT as nothing and
+// types print wrong without a word. Either way the refusal names what moved
+// and the version that held still.
+const TESTED = '7.0.2';
+
+/**
+ * The unstable module, or the refusal naming what moved.
+ *
+ * Exported for its test, which is the only way to falsify a failure that needs
+ * a TypeScript that does not exist yet.
+ *
+ * @param {object|null} unstable what importing `typescript/unstable/sync` gave
+ * @param {string} version the TypeScript that gave it
+ * @returns {object} the module, once its shape holds
+ * @throws when the subpath or a name this file drives is gone
+ */
+export function refuseMovedAPI(unstable, version) {
+  const missing = ['API', 'DiagnosticCategory', 'NodeBuilderFlags'].filter(
+    (name) => !unstable?.[name],
+  );
+  for (const flag of [
+    'NoTruncation',
+    'InTypeAlias',
+    'UseFullyQualifiedType',
+    'UseSingleQuotesForStringLiteralType',
+  ]) {
+    // Only once the enum itself is there: a missing enum already says enough.
+    if (unstable?.NodeBuilderFlags && typeof unstable.NodeBuilderFlags[flag] !== 'number') {
+      missing.push(`NodeBuilderFlags.${flag}`);
+    }
+  }
+
+  if (missing.length) {
+    throw new Error(
+      `[transclude] TypeScript ${version} moved the unstable API this checker drives: ` +
+        `${missing.join(', ')} ${missing.length === 1 ? 'is' : 'are'} gone. ` +
+        `Pin the version that held still: npm install -D typescript@${TESTED}`,
+    );
+  }
+  return unstable;
+}
+
+const { API, DiagnosticCategory, NodeBuilderFlags } = refuseMovedAPI(
+  await import('typescript/unstable/sync').catch(() => null),
+  tsVersion,
+);
+
 /**
  * Annotations are optional, so `noImplicitAny` is off: an unannotated parameter
  * is `any` rather than an error, and the author writes plain modern JavaScript.
@@ -32,31 +94,40 @@ import { MARKDOWN_EXT, sourceOf as htmlFrom } from './markdown.js';
  * `strictNullChecks` stays on: `querySelector` really can return null, and that
  * is a bug rather than a matter of taste. `strict: true` in the config turns the
  * rest on for anyone who wants it.
+ *
+ * Written as tsconfig JSON rather than option objects, because the 7.x API
+ * loads a project from a config file. Ours never exists: the filesystem the
+ * compiler is given serves it from memory, next to the shims.
  */
-const compilerOptions = (strict) => ({
-  target: ts.ScriptTarget.ESNext,
-  module: ts.ModuleKind.ESNext,
-  moduleResolution: ts.ModuleResolutionKind.Bundler,
-  lib: ['lib.esnext.d.ts', 'lib.dom.d.ts'],
-  strict,
-  strictNullChecks: true,
-  noImplicitAny: strict,
-  noEmit: true,
-  skipLibCheck: true,
-  allowJs: true,
-  checkJs: true,
-  types: [],
-});
+const configJson = (strict, files) =>
+  JSON.stringify({
+    compilerOptions: {
+      target: 'esnext',
+      module: 'esnext',
+      moduleResolution: 'bundler',
+      lib: ['esnext', 'dom'],
+      strict,
+      strictNullChecks: true,
+      noImplicitAny: strict,
+      noEmit: true,
+      skipLibCheck: true,
+      allowJs: true,
+      checkJs: true,
+      types: [],
+    },
+    files,
+  });
 
 // `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.
+// transclude-env.d.ts, where it landed as an undeclared name. These were
+// `TypeFormatFlags` before 7; the four names survived the move.
 const TYPE_FORMAT =
-  ts.TypeFormatFlags.NoTruncation |
-  ts.TypeFormatFlags.InTypeAlias |
-  ts.TypeFormatFlags.UseFullyQualifiedType |
-  ts.TypeFormatFlags.UseSingleQuotesForStringLiteralType;
+  NodeBuilderFlags.NoTruncation |
+  NodeBuilderFlags.InTypeAlias |
+  NodeBuilderFlags.UseFullyQualifiedType |
+  NodeBuilderFlags.UseSingleQuotesForStringLiteralType;
 
 const LAYOUT_FILE = '_layout.html';
 
@@ -83,7 +154,8 @@ const LAYOUT_FILE = '_layout.html';
  * @param {{ root: string, appDir: string, routesDir: string, elementsDir: string,
  *   strict?: boolean, markdown?: ((source: string, file: string) => string)|null }} options
  * @returns {{ files: Function, sourceFor: Function, update: Function,
- *   rebuild: Function, check: Function, quickInfo: Function, describe: Function }}
+ *   rebuild: Function, check: Function, quickInfo: Function, describe: Function,
+ *   dispose: Function }}
  */
 export function createChecker({
   root,
@@ -94,38 +166,63 @@ export function createChecker({
   markdown = null,
 }) {
   const app = path.resolve(root, appDir);
-  const options = compilerOptions(Boolean(strict));
   const shims = new Map();
-  const versions = new Map();
   const overlays = new Map();
 
   const shimPath = (file) => `${file}.js`;
 
-  const host = {
-    getScriptFileNames: () => [...shims.keys()],
-    getScriptVersion: (name) => String(versions.get(name) ?? 0),
-    getScriptSnapshot: (name) => {
-      const shim = shims.get(name);
-      if (shim) return ts.ScriptSnapshot.fromString(shim.code);
-      if (!fs.existsSync(name)) return undefined;
-      return ts.ScriptSnapshot.fromString(fs.readFileSync(name, 'utf8'));
+  // The project file the compiler is asked to open. It never touches disk: the
+  // filesystem below serves it from memory, regenerated whenever the shim set
+  // changes, because its `files` list is the shim list.
+  const configPath = path.join(root, '.transclude-check.tsconfig.json');
+
+  // The compiler, a child process. It sees the real filesystem except where a
+  // callback answers first: the config and the shims come from these maps, and
+  // `undefined` means "ask the disk", which is how the app's own imports and
+  // the libs resolve without this file listing them.
+  const api = new API({
+    cwd: root,
+    fs: {
+      fileExists: (name) => (name === configPath || shims.has(name) ? true : undefined),
+      readFile: (name) => {
+        if (name === configPath) return configJson(Boolean(strict), [...shims.keys()]);
+        return shims.get(name)?.code;
+      },
     },
-    getCurrentDirectory: () => root,
-    getCompilationSettings: () => options,
-    getDefaultLibFileName: (options) => ts.getDefaultLibFilePath(options),
-    fileExists: (name) => shims.has(name) || ts.sys.fileExists(name),
-    readFile: (name) => (shims.has(name) ? shims.get(name).code : ts.sys.readFile(name)),
-    readDirectory: ts.sys.readDirectory,
-    directoryExists: ts.sys.directoryExists,
-    getDirectories: ts.sys.getDirectories,
+  });
+
+  // One snapshot at a time, rebuilt lazily. `install` records what changed and
+  // the next question re-snapshots with exactly those invalidations, so a
+  // build's forty installs cost one program rather than forty.
+  let snapshot = null;
+  const dirty = { changed: new Set(), created: new Set() };
+
+  const current = () => {
+    if (snapshot && !dirty.changed.size && !dirty.created.size) return snapshot;
+
+    const fileChanges = snapshot
+      ? { changed: [...dirty.changed, configPath], created: [...dirty.created] }
+      : undefined;
+    snapshot?.dispose();
+    // The open is ref-counted and persists across snapshots, so the project is
+    // named once and invalidated after.
+    snapshot = api.updateSnapshot({ openProjects: [configPath], fileChanges });
+    dirty.changed.clear();
+    dirty.created.clear();
+
+    const project = snapshot.getProject(configPath);
+    if (!project) throw new Error('[transclude] the compiler did not open the shim project');
+    return snapshot;
   };
 
-  const service = ts.createLanguageService(host, ts.createDocumentRegistry());
+  const projectOf = () => current().getProject(configPath);
+  const programOf = () => projectOf().program;
+  const checkerOf = () => projectOf().checker;
 
   const install = (file, built) => {
     const name = shimPath(file);
+    (shims.has(name) ? dirty.changed : dirty.created).add(name);
     shims.set(name, built);
-    versions.set(name, (versions.get(name) ?? 0) + 1);
     return built;
   };
 
@@ -136,27 +233,27 @@ export function createChecker({
 
   /** The type of one of a shim's marker exports. What tsc made of the file. */
   const exportTypeOf = (file, name) => {
-    const program = service.getProgram();
-    const source = program?.getSourceFile(shimPath(file));
+    const source = programOf().getSourceFile(shimPath(file));
     if (!source) return 'unknown';
 
-    const checker = program.getTypeChecker();
+    const checker = checkerOf();
     const moduleSymbol = checker.getSymbolAtLocation(source);
     const data =
       moduleSymbol &&
-      checker.getExportsOfModule(moduleSymbol).find((symbol) => symbol.getName() === name);
+      checker.getExportsOfModule(moduleSymbol).find((symbol) => symbol.name === name);
     if (!data) return 'unknown';
 
-    const type = checker.getTypeOfSymbolAtLocation(data, data.valueDeclaration ?? source);
-    const text = checker.typeToString(type, undefined, TYPE_FORMAT);
+    const type = checker.getTypeOfSymbol(data);
+    const text = type ? checker.typeToString(type, undefined, TYPE_FORMAT) : 'unknown';
     return text === 'any' ? 'unknown' : text;
   };
 
-  // `UseFullyQualifiedType` prints a named type as `import("/abs/file").Name`.
+  // `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;
+  // Either quote: 5.x printed double and 7 prints single.
+  const QUALIFIED = /import\((["'])([^"']+)\1\)\.([A-Za-z_$][\w$]*)/g;
 
   /**
    * The type a name stands for, expanded. `InTypeAlias` is what stops tsc
@@ -169,14 +266,14 @@ export function createChecker({
     const already = into.byKey.get(key);
     if (already) return already;
 
-    const program = service.getProgram();
+    const program = programOf();
     // 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 source = program.getSourceFile(file) ?? program.getSourceFile(`${file}.js`);
+    const checker = checkerOf();
+    const moduleSymbol = source && checker.getSymbolAtLocation(source);
     const symbol =
-      moduleSymbol && checker.getExportsOfModule(moduleSymbol).find((s) => s.getName() === name);
+      moduleSymbol && checker.getExportsOfModule(moduleSymbol).find((s) => s.name === 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}`;
@@ -195,7 +292,7 @@ export function createChecker({
    * same shapes from `ambient.js`; anything else is the app's and is expanded.
    */
   const resolveNames = (type, into) =>
-    type.replace(QUALIFIED, (_, file, name) =>
+    type.replace(QUALIFIED, (_, quote, file, name) =>
       AMBIENT_NAMES.has(name) ? name : expand(file, name, into),
     );
 
@@ -455,6 +552,17 @@ export function createChecker({
       project = build();
     },
 
+    /**
+     * Stops the compiler. It is a child process, so a caller that finishes,
+     * like `bin/check.js`, closes it rather than leaving the exit to wait on
+     * an orphan. The editor's server never calls this: it dies with the editor.
+     */
+    dispose() {
+      snapshot?.dispose();
+      snapshot = null;
+      api.close();
+    },
+
     check(file) {
       const shim = refresh(file);
       const name = shimPath(file);
@@ -472,12 +580,13 @@ export function createChecker({
         }));
       }
 
+      const program = programOf();
       const out = [];
       for (const diagnostic of [
-        ...service.getSyntacticDiagnostics(name),
-        ...service.getSemanticDiagnostics(name),
+        ...program.getSyntacticDiagnostics(name),
+        ...program.getSemanticDiagnostics(name),
       ]) {
-        const offset = originalOffset(shim.chunks, diagnostic.start ?? 0);
+        const offset = originalOffset(shim.chunks, diagnostic.pos ?? 0);
         // A diagnostic with no home is one about generated scaffolding. Dropping
         // it is right, but it means anything that can carry a diagnostic has to be
         // mapped, or it disappears without a word.
@@ -486,10 +595,10 @@ export function createChecker({
         out.push({
           file,
           offset,
-          length: diagnostic.length ?? 1,
+          length: Math.max(1, (diagnostic.end ?? 0) - (diagnostic.pos ?? 0)),
           code: diagnostic.code,
-          message: ts.flattenDiagnosticMessageText(diagnostic.messageText, ' '),
-          severity: diagnostic.category === ts.DiagnosticCategory.Error ? 'error' : 'warning',
+          message: flatten(diagnostic),
+          severity: diagnostic.category === DiagnosticCategory.Error ? 'error' : 'warning',
         });
       }
       return out.sort((a, b) => a.offset - b.offset);
@@ -506,15 +615,27 @@ export function createChecker({
       );
       if (!target) return null;
 
-      const info = service.getQuickInfoAtPosition(
-        shimPath(file),
-        target.start + (offset - target.source),
-      );
-      if (!info) return null;
+      const name = shimPath(file);
+      const position = target.start + (offset - target.source);
+      const checker = checkerOf();
+
+      // Assembled rather than asked for: the 7.x API has no quick-info call, and
+      // the symbol plus its printed type is what the old one's display parts
+      // said. Documentation rides on the JSDoc tags when the symbol carries any.
+      const symbol = checker.getSymbolAtPosition(name, position);
+      const type = symbol
+        ? checker.getTypeOfSymbol(symbol)
+        : checker.getTypeAtPosition(name, position);
+      if (!type) return null;
+
+      const printed = checker.typeToString(type, undefined, NodeBuilderFlags.NoTruncation);
+      const tags = symbol?.getJsDocTags?.(checker) ?? [];
 
       return {
-        text: ts.displayPartsToString(info.displayParts),
-        documentation: ts.displayPartsToString(info.documentation ?? []),
+        text: symbol ? `${symbol.name}: ${printed}` : printed,
+        documentation: tags
+          .map((tag) => [tag.name, tag.text?.map((part) => part.text).join('')].filter(Boolean).join(' '))
+          .join('\n'),
       };
     },
 
@@ -573,6 +694,69 @@ export function createChecker({
   };
 }
 
+/**
+ * Diagnostics for one TypeScript file, compiled alone.
+ *
+ * The guard `bin/check.js` runs over the emitted transclude-env.d.ts, and what
+ * `test/types.test.js` asserts against, so the two cannot disagree about what
+ * the file is allowed to name. `skipLibCheck` is off on purpose: a .d.ts is
+ * the one kind of file that flag skips, and with it on this guard checked
+ * nothing at all. `types: []` keeps the compile to this file, so a project's
+ * own `@types` failing to resolve does not read as our file being broken.
+ *
+ * @param {string} file an absolute path to a .ts or .d.ts on disk
+ * @returns {Array<{ offset: number, message: string }>}
+ */
+export function checkAlone(file) {
+  const dir = path.dirname(file);
+  const configPath = path.join(dir, '.transclude-alone.tsconfig.json');
+  const api = new API({
+    cwd: dir,
+    fs: {
+      fileExists: (name) => (name === configPath ? true : undefined),
+      readFile: (name) =>
+        name === configPath
+          ? JSON.stringify({
+              compilerOptions: {
+                noEmit: true,
+                skipLibCheck: false,
+                types: [],
+                target: 'esnext',
+                lib: ['esnext', 'dom'],
+              },
+              files: [path.basename(file)],
+            })
+          : undefined,
+    },
+  });
+
+  try {
+    const snapshot = api.updateSnapshot({ openProjects: [configPath] });
+    const program = snapshot.getProject(configPath).program;
+    return [...program.getSyntacticDiagnostics(), ...program.getSemanticDiagnostics()].map(
+      (diagnostic) => ({ offset: diagnostic.pos, message: flatten(diagnostic) }),
+    );
+  } finally {
+    api.close();
+  }
+}
+
+/**
+ * A diagnostic's text with its chained reasons behind it, space-joined.
+ *
+ * The reasons are the useful half: "not assignable" without the "because" is a
+ * verdict with no evidence. 5.x flattened chains before handing them over; 7
+ * sends them structured, so the joining moved here.
+ *
+ * @param {{ text: string, messageChain?: readonly object[] }} diagnostic
+ * @returns {string}
+ */
+function flatten(diagnostic) {
+  const parts = [String(diagnostic.text)];
+  for (const chained of diagnostic.messageChain ?? []) parts.push(flatten(chained));
+  return parts.join(' ');
+}
+
 /**
  * Line and column for an offset, for anything that reports to a human.
  *