@transclude/core 0.1.0

package/editor/server.js

@@ -0,0 +1,172 @@
+// Language server for .html files in an transclude project.
+//
+// Hand-written JSON-RPC rather than a dependency. The part of the protocol
+// needed here is small, and keeping it dependency-free means any editor that
+// speaks LSP can use it without the project growing a toolchain.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { createChecker } from '../src/typecheck.js';
+import { loadProject } from '../src/project.js';
+
+let checker = null;
+let root = process.cwd();
+
+// ---- transport -------------------------------------------------------------
+
+let buffer = Buffer.alloc(0);
+
+process.stdin.on('data', (chunk) => {
+  buffer = Buffer.concat([buffer, chunk]);
+
+  for (;;) {
+    const header = buffer.indexOf('\r\n\r\n');
+    if (header === -1) return;
+
+    const length = Number(/Content-Length: (\d+)/i.exec(buffer.slice(0, header).toString())?.[1]);
+    if (!Number.isFinite(length)) return;
+
+    const start = header + 4;
+    if (buffer.length < start + length) return;
+
+    const message = JSON.parse(buffer.slice(start, start + length).toString());
+    buffer = buffer.slice(start + length);
+
+    try {
+      handle(message);
+    } catch (err) {
+      log(`error handling ${message.method}: ${err.stack ?? err.message}`);
+    }
+  }
+});
+
+function send(message) {
+  const body = Buffer.from(JSON.stringify({ jsonrpc: '2.0', ...message }));
+  process.stdout.write(`Content-Length: ${body.length}\r\n\r\n`);
+  process.stdout.write(body);
+}
+
+/** stderr, so it never corrupts the protocol stream on stdout. */
+function log(text) {
+  process.stderr.write(`[transclude] ${text}\n`);
+}
+
+// ---- protocol --------------------------------------------------------------
+
+function handle(message) {
+  switch (message.method) {
+    case 'initialize': {
+      root = message.params?.rootPath ?? fileURLToPath(message.params?.rootUri ?? pathToFileURL(root).href);
+      // The editor says which folder it opened, so the config is loaded from
+      // there. Everything after this needs it, so nothing is answered until it
+      // has arrived.
+      loadProject(root)
+        .then((project) => {
+          checker = createChecker({ root: project.root, ...project.config });
+          log(`watching ${project.root}`);
+        })
+        .catch((err) => log(`no project here: ${err.message}`));
+      send({
+        id: message.id,
+        result: {
+          capabilities: {
+            textDocumentSync: { openClose: true, change: 1, save: true },
+            hoverProvider: true,
+          },
+          serverInfo: { name: 'transclude', version: '0.1.0' },
+        },
+      });
+      return;
+    }
+
+    case 'initialized':
+      return;
+
+    case 'shutdown':
+      send({ id: message.id, result: null });
+      return;
+
+    case 'exit':
+      process.exit(0);
+      return;
+
+    case 'textDocument/didOpen':
+      publish(message.params.textDocument.uri, message.params.textDocument.text);
+      return;
+
+    case 'textDocument/didChange':
+      // Full sync, so the last change carries the whole document.
+      publish(message.params.textDocument.uri, message.params.contentChanges.at(-1).text);
+      return;
+
+    case 'textDocument/didSave':
+      if (message.params.text !== undefined) publish(message.params.textDocument.uri, message.params.text);
+      return;
+
+    case 'textDocument/hover':
+      send({ id: message.id, result: hover(message.params) });
+      return;
+
+    default:
+      // Requests must be answered even when unsupported, or the client waits.
+      if (message.id !== undefined) send({ id: message.id, result: null });
+  }
+}
+
+function publish(uri, text) {
+  if (!checker) return;
+  const file = fileURLToPath(uri);
+  if (!file.endsWith('.html')) return;
+
+  checker.update(file, text);
+
+  const diagnostics = checker.check(file).map((diagnostic) => ({
+    range: rangeOf(text, diagnostic.offset, diagnostic.length),
+    severity: diagnostic.severity === 'error' ? 1 : 2,
+    code: `TS${diagnostic.code}`,
+    source: 'transclude',
+    message: diagnostic.message,
+  }));
+
+  send({ method: 'textDocument/publishDiagnostics', params: { uri, diagnostics } });
+}
+
+function hover({ textDocument, position }) {
+  if (!checker) return null;
+  const file = fileURLToPath(textDocument.uri);
+  if (!fs.existsSync(file)) return null;
+
+  const text = fs.readFileSync(file, 'utf8');
+  const info = checker.quickInfo(file, offsetOf(text, position));
+  if (!info?.text) return null;
+
+  return {
+    contents: {
+      kind: 'markdown',
+      value: `\`\`\`ts\n${info.text}\n\`\`\`${info.documentation ? `\n\n${info.documentation}` : ''}`,
+    },
+  };
+}
+
+// ---- positions -------------------------------------------------------------
+
+/** LSP counts lines and characters from zero. */
+function positionOf(text, offset) {
+  const before = text.slice(0, offset);
+  const line = before.split('\n').length - 1;
+  return { line, character: offset - (before.lastIndexOf('\n') + 1) };
+}
+
+function rangeOf(text, offset, length) {
+  return { start: positionOf(text, offset), end: positionOf(text, offset + Math.max(1, length)) };
+}
+
+function offsetOf(text, position) {
+  const lines = text.split('\n');
+  let offset = 0;
+  for (let i = 0; i < position.line && i < lines.length; i++) offset += lines[i].length + 1;
+  return offset + position.character;
+}
+
+log(`ready (node ${process.version}, cwd ${path.basename(process.cwd())})`);

package/editor/vscode/extension.js

@@ -0,0 +1,49 @@
+// Starts the language server for workspaces that look like an transclude
+// project. Anything else is left alone. The grammar is harmless everywhere, and
+// the checker only makes sense where transclude.config.js exists.
+
+const path = require('node:path');
+const fs = require('node:fs');
+const vscode = require('vscode');
+const { LanguageClient, TransportKind } = require('vscode-languageclient/node');
+
+let client;
+
+function activate(context) {
+  if (!vscode.workspace.getConfiguration('transclude').get('enable')) return;
+
+  const folder = vscode.workspace.workspaceFolders?.[0];
+  if (!folder) return;
+
+  const root = folder.uri.fsPath;
+  if (!fs.existsSync(path.join(root, 'transclude.config.js'))) return;
+
+  // Installed, the server is in the package. In the framework's own repo it is
+  // beside this file. Try both rather than assume a layout.
+  const server = [
+    path.join(root, 'node_modules/transclude/editor/server.js'),
+    path.join(root, 'editor/server.js'),
+  ].find((file) => fs.existsSync(file));
+  if (!server) return;
+
+  client = new LanguageClient(
+    'transclude',
+    'transclude',
+    {
+      run: { module: server, transport: TransportKind.stdio },
+      debug: { module: server, transport: TransportKind.stdio },
+    },
+    {
+      documentSelector: [{ scheme: 'file', language: 'html' }],
+      synchronize: { fileEvents: vscode.workspace.createFileSystemWatcher('**/*.html') },
+    },
+  );
+
+  context.subscriptions.push(client.start());
+}
+
+function deactivate() {
+  return client?.stop();
+}
+
+module.exports = { activate, deactivate };

package/editor/vscode/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "transclude",
+  "displayName": "transclude",
+  "description": "Diagnostics, hovers and highlighting for transclude .html files",
+  "version": "0.1.0",
+  "private": true,
+  "engines": { "vscode": "^1.85.0" },
+  "categories": ["Programming Languages"],
+  "activationEvents": ["onLanguage:html"],
+  "main": "./extension.js",
+  "contributes": {
+    "grammars": [
+      {
+        "scopeName": "transclude.injection",
+        "path": "./syntaxes/transclude.injection.json",
+        "injectTo": ["text.html.basic", "text.html.derivative"],
+        "embeddedLanguages": { "meta.embedded.expression.transclude": "javascript" }
+      }
+    ],
+    "configuration": {
+      "title": "transclude",
+      "properties": {
+        "transclude.enable": {
+          "type": "boolean",
+          "default": true,
+          "description": "Type check .html files in an transclude project."
+        }
+      }
+    }
+  },
+  "dependencies": { "vscode-languageclient": "^9.0.1" }
+}

package/editor/vscode/syntaxes/transclude.injection.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "https://raw.githubusercontent.com/martinring/tmlanguage/master/tmlanguage.json",
+  "scopeName": "transclude.injection",
+  "injectionSelector": "L:text.html -comment",
+  "patterns": [
+    { "include": "#interpolation" },
+    { "include": "#directive" },
+    { "include": "#server-block" }
+  ],
+  "repository": {
+    "interpolation": {
+      "name": "meta.embedded.expression.transclude",
+      "begin": "(?<!\\\\)\\$\\{",
+      "end": "\\}",
+      "beginCaptures": { "0": { "name": "punctuation.section.embedded.begin.transclude" } },
+      "endCaptures": { "0": { "name": "punctuation.section.embedded.end.transclude" } },
+      "patterns": [{ "include": "source.js" }]
+    },
+    "directive": {
+      "match": "(?<=\\s)(each|if|else-if|else)(?=[\\s=>/])",
+      "name": "keyword.control.directive.transclude"
+    },
+    "server-block": {
+      "begin": "(<)(script)\\s+(server|props)\\s*(>)",
+      "end": "(</)(script)\\s*(>)",
+      "beginCaptures": {
+        "1": { "name": "punctuation.definition.tag.begin.html" },
+        "2": { "name": "entity.name.tag.script.html" },
+        "3": { "name": "entity.other.attribute-name.html" },
+        "4": { "name": "punctuation.definition.tag.end.html" }
+      },
+      "endCaptures": {
+        "1": { "name": "punctuation.definition.tag.begin.html" },
+        "2": { "name": "entity.name.tag.script.html" },
+        "3": { "name": "punctuation.definition.tag.end.html" }
+      },
+      "contentName": "source.js",
+      "patterns": [{ "include": "source.js" }]
+    }
+  }
+}

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@transclude/core",
+  "version": "0.1.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",
+    "hypermedia",
+    "fragments",
+    "ssr",
+    "server-side-rendering",
+    "framework",
+    "custom-elements",
+    "declarative-shadow-dom",
+    "htmx",
+    "hono",
+    "vite"
+  ],
+  "homepage": "https://transclude.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/transclude-dev/transclude.git"
+  },
+  "bugs": {
+    "url": "https://github.com/transclude-dev/transclude/issues"
+  },
+  "license": "MIT",
+  "author": "Joe Dakroub",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "transclude-build": "./bin/build.js",
+    "transclude-check": "./bin/check.js",
+    "transclude-dev": "./bin/dev.js",
+    "transclude-serve": "./bin/serve.js"
+  },
+  "exports": {
+    ".": "./src/plugin.js",
+    "./app": "./src/app.js",
+    "./cookies": "./src/cookies.js",
+    "./document": "./src/document.js",
+    "./production": "./src/production.js",
+    "./routes": "./src/routes.js",
+    "./runtime": "./src/runtime/index.js",
+    "./serve.bun": "./bin/serve.bun.js",
+    "./serve.deno": "./bin/serve.deno.js",
+    "./typecheck": "./src/typecheck.js",
+    "./worker": "./src/worker.js"
+  },
+  "files": [
+    "LICENSE",
+    "bin",
+    "editor",
+    "src"
+  ],
+  "scripts": {
+    "test": "node --test \"test/**/*.test.js\"",
+    "test:examples": "npm test --prefix examples/showcase",
+    "test:docs": "npm test --prefix docs",
+    "showcase": "npm run dev --prefix examples/showcase",
+    "docs": "npm run dev --prefix docs",
+    "check:src": "tsc -p tsconfig.src.json",
+    "release": "node bin/release.js"
+  },
+  "dependencies": {
+    "@hono/node-server": "^2.0.12",
+    "acorn": "^8.18.0",
+    "hono": "^4.12.32",
+    "jsep": "^1.4.0",
+    "parse5": "^8.0.1"
+  },
+  "peerDependencies": {
+    "typescript": "^5.9",
+    "vite": "^8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.1",
+    "typescript": "^5.9.3",
+    "vite": "^8.1.5"
+  }
+}

package/src/address.js

@@ -0,0 +1,183 @@
+// Which addresses a server may be asked to fetch from.
+//
+// A server that fetches a URL somebody sent it can be pointed at things only it
+// can reach: another service on the same host, a database on the private
+// network, or the cloud metadata endpoint that hands out credentials. Refusing
+// those is the whole job here.
+//
+// No `node:` imports and no DNS. This decides what an address means; resolving
+// a name to one is the runtime's job, and one of the four runtimes cannot do it
+// at all.
+
+/**
+ * Ranges that are not the public internet, as [test, why].
+ *
+ * @type {Array<[(a: number[]) => boolean, string]>}
+ */
+const V4_BLOCKED = [
+  [(a) => a[0] === 0, 'this network'],
+  [(a) => a[0] === 10, 'private'],
+  [(a) => a[0] === 127, 'loopback'],
+  [(a) => a[0] === 100 && a[1] >= 64 && a[1] <= 127, 'carrier-grade NAT'],
+  [(a) => a[0] === 169 && a[1] === 254, 'link-local, and the metadata endpoint'],
+  [(a) => a[0] === 172 && a[1] >= 16 && a[1] <= 31, 'private'],
+  [(a) => a[0] === 192 && a[1] === 0 && a[2] === 0, 'protocol assignments'],
+  [(a) => a[0] === 192 && a[1] === 168, 'private'],
+  [(a) => a[0] === 198 && (a[1] === 18 || a[1] === 19), 'benchmarking'],
+  [(a) => a[0] >= 224, 'multicast or reserved'],
+];
+
+/**
+ * An IPv4 address as four numbers, or null if the text is not one.
+ *
+ * @param {string} text
+ * @returns {number[]|null} four octets, or null when it is not one
+ */
+export function parseV4(text) {
+  const parts = text.split('.');
+  if (parts.length !== 4) return null;
+
+  const octets = parts.map((part) => {
+    if (!/^\d{1,3}$/.test(part)) return NaN;
+    return Number(part);
+  });
+  if (octets.some((n) => Number.isNaN(n) || n > 255)) return null;
+  return octets;
+}
+
+/**
+ * An IPv6 address as eight groups, or null.
+ *
+ * Only enough of the format to classify one. An address with a trailing IPv4
+ * part is handled, because `::ffff:169.254.169.254` is the obvious way around a
+ * checker that only reads the hex form.
+ *
+ * @param {string} text
+ * @returns {number[]|null} sixteen bytes, or null
+ */
+export function parseV6(text) {
+  let body = text;
+  let tail = null;
+
+  const dotted = body.lastIndexOf(':');
+  if (body.slice(dotted + 1).includes('.')) {
+    tail = parseV4(body.slice(dotted + 1));
+    if (!tail) return null;
+    body = body.slice(0, dotted + 1) + '0:0';
+  }
+
+  const halves = body.split('::');
+  if (halves.length > 2) return null;
+
+  const read = (part) =>
+    part === '' ? [] : part.split(':').map((g) => (/^[0-9a-f]{1,4}$/i.test(g) ? parseInt(g, 16) : NaN));
+
+  const head = read(halves[0]);
+  const rest = halves.length === 2 ? read(halves[1]) : [];
+  if ([...head, ...rest].some(Number.isNaN)) return null;
+
+  let groups;
+  if (halves.length === 2) {
+    const gap = 8 - head.length - rest.length;
+    if (gap < 0) return null;
+    groups = [...head, ...Array(gap).fill(0), ...rest];
+  } else {
+    groups = head;
+  }
+  if (groups.length !== 8) return null;
+
+  if (tail) {
+    groups[6] = (tail[0] << 8) | tail[1];
+    groups[7] = (tail[2] << 8) | tail[3];
+  }
+  return groups;
+}
+
+/**
+ * Why this address may not be fetched from, or null if it may.
+ *
+ * Takes the text of a host, with no brackets. A name that is not an address
+ * returns null: whether a *name* is allowed is the allowlist's question, and
+ * where it resolves to is the runtime's.
+ *
+ * @param {string} host a literal address, not a name
+ * @returns {string|null} why it is refused, or null when it is allowed
+ */
+export function blockedAddress(host) {
+  const v4 = parseV4(host);
+  if (v4) {
+    for (const [test, why] of V4_BLOCKED) if (test(v4)) return why;
+    return null;
+  }
+
+  const v6 = parseV6(host);
+  if (!v6) return null;
+
+  const [a, b] = v6;
+  if (v6.every((g) => g === 0)) return 'unspecified';
+  if (v6.slice(0, 7).every((g) => g === 0) && v6[7] === 1) return 'loopback';
+  // An IPv4 address wearing an IPv6 hat. `::ffff:10.0.0.1` reaches the same
+  // host `10.0.0.1` does.
+  if (v6.slice(0, 5).every((g) => g === 0) && v6[5] === 0xffff) {
+    const mapped = [v6[6] >> 8, v6[6] & 255, v6[7] >> 8, v6[7] & 255];
+    for (const [test, why] of V4_BLOCKED) if (test(mapped)) return `${why}, through an IPv4-mapped address`;
+    return null;
+  }
+  if ((a & 0xfe00) === 0xfc00) return 'unique local';
+  if ((a & 0xffc0) === 0xfe80) return 'link-local';
+  if (a === 0x2001 && b === 0x0db8) return 'documentation';
+  return null;
+}
+
+/**
+ * Whether a hostname is one the config named.
+ *
+ * Default deny. An entry is an exact hostname, or `*.example.com`, which covers
+ * any subdomain but not the bare domain: naming a wildcard should not quietly
+ * hand over the apex too.
+ *
+ * @param {string} host
+ * @param {string[]} [allow] names, and `*.` wildcards
+ * @returns {boolean} false unless something on the list names it
+ */
+export function allowedHost(host, allow = []) {
+  const name = String(host).toLowerCase().replace(/\.$/, '');
+
+  return allow.some((entry) => {
+    const rule = String(entry).toLowerCase().replace(/\.$/, '');
+    if (rule.startsWith('*.')) return name.endsWith(rule.slice(1)) && name !== rule.slice(2);
+    return name === rule;
+  });
+}
+
+/**
+ * The one place a URL is judged before anything connects.
+ *
+ * Order matters. The allowlist is checked before the address, so a host nobody
+ * permitted is refused without this having formed an opinion about where it
+ * points.
+ *
+ * @param {string} url
+ * @param {{ allow?: string[] }} [options]
+ * @returns {string|null} why it is refused, or null when it may be fetched
+ */
+export function checkUrl(url, { allow = [] } = {}) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return 'not a URL';
+  }
+
+  if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+    return `${parsed.protocol} is not a scheme this fetches`;
+  }
+  if (parsed.username || parsed.password) return 'credentials in a URL are not passed on';
+  if (!allowedHost(parsed.hostname, allow)) return `${parsed.hostname} is not an allowed host`;
+
+  // Brackets are the URL syntax for a v6 host and are not part of the address.
+  const blocked = blockedAddress(parsed.hostname.replace(/^\[|\]$/g, ''));
+  if (blocked) return `${parsed.hostname} is ${blocked}`;
+
+  return null;
+}