@zvndev/darkmown 0.8.2 → 0.10.0

package/src/builder.js

@@ -6,16 +6,36 @@ import { createPaths } from "./config.js";
 import { discoverRoutes, outputPathForRoute } from "./router.js";
 import { compileSkin } from "./skin.js";
 
+/**
+ * @typedef {import("./config.js").Paths} Paths
+ * @typedef {import("./compiler.js").Assets} Assets
+ */
+
+/**
+ * A built route entry written to `dist/routes.json`.
+ * @typedef {object} RouteManifestEntry
+ * @property {string} route Public route path.
+ * @property {string} file Source file path, relative to cwd, POSIX-separated.
+ * @property {{ skins: string[], scripts: string[], runtime: boolean }} assets
+ */
+
 const moduleDir = path.dirname(fileURLToPath(import.meta.url));
 
+/**
+ * Compile the whole site under `cwd` into `dist`, returning the route manifest.
+ * @param {string} [cwd] Project working directory (defaults to `process.cwd()`).
+ * @returns {{ routes: RouteManifestEntry[], distRoot: string }}
+ */
 export function buildSite(cwd = process.cwd()) {
   const paths = createPaths(cwd);
   fs.rmSync(paths.distRoot, { recursive: true, force: true });
   fs.mkdirSync(paths.distRoot, { recursive: true });
   emitShelfAssets(paths);
   const routes = discoverRoutes(paths.routesRoot);
+  /** @type {RouteManifestEntry[]} */
   const manifest = [];
 
+  /** @type {Set<string>} */
   const warned = new Set();
 
   for (const route of routes) {
@@ -45,12 +65,41 @@ export function buildSite(cwd = process.cwd()) {
   return { routes: manifest, distRoot: paths.distRoot };
 }
 
+/**
+ * Strip JSDoc `/** ... *\/` blocks from the runtime before it ships.
+ * The source keeps full type annotations (for `checkJs` + `.d.ts`), but the
+ * browser never needs to download them — this keeps the shipped runtime lean
+ * and the gzip budget honest (measured against what users actually receive).
+ * Only `/** ... *\/` blocks are removed; code and string literals are untouched.
+ * @param {string} source
+ * @returns {string}
+ */
+export function stripRuntimeComments(source) {
+  return source
+    // Remove the JSDoc block text only — never the surrounding newlines, so an
+    // inline `/** @type {x} */ code` keeps its line and never glues onto a
+    // preceding `//` comment.
+    .replace(/\/\*\*[\s\S]*?\*\//g, "")
+    // Drop the now blank/whitespace-only lines the removed blocks leave behind.
+    .replace(/^[ \t]*\n/gm, "");
+}
+
+/**
+ * @param {Paths} paths
+ * @returns {void}
+ */
 function emitRuntime(paths) {
   const out = path.join(paths.distRoot, "__wd/runtime.js");
   fs.mkdirSync(path.dirname(out), { recursive: true });
-  fs.copyFileSync(path.join(moduleDir, "runtime.js"), out);
+  const source = fs.readFileSync(path.join(moduleDir, "runtime.js"), "utf8");
+  fs.writeFileSync(out, stripRuntimeComments(source));
 }
 
+/**
+ * @param {Assets} assets
+ * @param {Paths} paths
+ * @returns {void}
+ */
 function emitAssets(assets, paths) {
   for (const [source, href] of assets.files) {
     const out = path.join(paths.distRoot, href);
@@ -63,6 +112,11 @@ function emitAssets(assets, paths) {
   }
 }
 
+/**
+ * Copy non-page shelf assets (JSON data, media) into `dist/__wd`.
+ * @param {Paths} paths
+ * @returns {void}
+ */
 function emitShelfAssets(paths) {
   if (!fs.existsSync(paths.shelfRoot)) return;
   for (const file of walk(paths.shelfRoot)) {
@@ -76,7 +130,12 @@ function emitShelfAssets(paths) {
   }
 }
 
+/**
+ * @param {string} dir
+ * @returns {string[]}
+ */
 function walk(dir) {
+  /** @type {string[]} */
   const files = [];
   for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
     const abs = path.join(dir, entry.name);

package/src/cli.js

@@ -20,8 +20,9 @@ if (command === "help" || command === "--help" || command === "-h") {
 } else if (command === "init") {
   const target = process.argv[3] || ".";
   const result = initProject(path.resolve(process.cwd(), target));
-  console.log(`Created Darkmown project at ${path.relative(process.cwd(), result.root) || "."}`);
-  console.log(`Next: cd ${path.relative(process.cwd(), result.root) || "."} && npm install && npm run dev`);
+  const relativeRoot = path.relative(process.cwd(), result.root) || ".";
+  console.log(`Created Darkmown project at ${relativeRoot}`);
+  console.log(`Next: ${nextStep(relativeRoot)}`);
 } else if (command === "build") {
   const result = buildSite();
   console.log(`Built ${result.routes.length} routes into ${path.relative(process.cwd(), result.distRoot)}`);
@@ -29,7 +30,9 @@ if (command === "help" || command === "--help" || command === "-h") {
   const port = Number(process.env.PORT || 5173);
   const distRoot = path.join(process.cwd(), "dist");
   buildSite();
+  /** @type {Set<import("node:http").ServerResponse>} */
   const clients = new Set();
+  /** @type {ReturnType<typeof setTimeout> | undefined} */
   let timer;
 
   // Rebuild in a child process so changes to Darkmown's own src/ always load
@@ -94,7 +97,7 @@ if (command === "help" || command === "--help" || command === "-h") {
       serveDev(distRoot, url, res);
     } catch (error) {
       res.writeHead(500, { "content-type": "text/plain" });
-      res.end(error.stack || String(error));
+      res.end((error instanceof Error && error.stack) || String(error));
     }
   });
   server.listen(port, () => {
@@ -117,6 +120,12 @@ if (command === "help" || command === "--help" || command === "-h") {
   process.exit(1);
 }
 
+/**
+ * @param {string} distRoot
+ * @param {string} url
+ * @param {import("node:http").ServerResponse} res
+ * @returns {void}
+ */
 function serveDev(distRoot, url, res) {
   const file = resolvePublicFile(distRoot, url);
   if (!file || !fs.existsSync(file)) {
@@ -132,6 +141,11 @@ function serveDev(distRoot, url, res) {
   fs.createReadStream(file).pipe(res);
 }
 
+/**
+ * @param {Set<import("node:http").ServerResponse>} clients
+ * @param {string} message
+ * @returns {void}
+ */
 function broadcast(clients, message) {
   for (const client of clients) client.write(message);
 }
@@ -144,6 +158,7 @@ Usage:
   darkmown dev          Start the live compiler dev server
   darkmown build        Compile site/pages into dist
   darkmown serve        Preview the built dist locally
+  darkmown version      Print the installed Darkmown version
   darkmown help         Show this help
 
 Authoring:
@@ -154,3 +169,13 @@ Authoring:
   *.js                Colocated page behavior
 `);
 }
+
+
+/**
+ * @param {string} relativeRoot
+ * @returns {string}
+ */
+function nextStep(relativeRoot) {
+  if (relativeRoot === ".") return "npm install && npm run dev";
+  return `cd ${relativeRoot} && npm install && npm run dev`;
+}