@writedocs/generator 0.4.11 → 0.5.0

package/src/cli/run-astro.js

@@ -1,57 +1,87 @@
-import { createRequire } from 'node:module';
 import path from 'node:path';
 import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const workerPath = path.join(path.dirname(fileURLToPath(import.meta.url)), 'astro-worker.js');
 
 /**
- * Resolves the astro CLI entrypoint relative to this package (not the
- * consumer's project), so it works regardless of how writedocs was
- * installed (flat or nested node_modules).
+ * Runs Astro (`command`: 'dev' or 'build') in a child process -
+ * astro-worker.js - and turns everything it reports into events for
+ * `onEvent`, so the CLI decides what reaches the terminal:
+ *
+ *   { type: 'astro-log', level, label, message } - an Astro/Vite log line
+ *   { type: 'report', level, message, where }     - writedocs' own code
+ *                                                   (lib/cli-report.js)
+ *   { type: 'raw', stream, line }                 - anything printed directly
+ *   { type: 'ready', urls } / { type: 'done' } / { type: 'fatal', error }
+ *
+ * A raw "[writedocs] ..." line is turned into a 'report' too, so a
+ * console.warn that doesn't go through cli-report.js still shows up.
+ *
+ * Returns { child, exited } - `exited` resolves with the exit code.
  */
-function resolveAstroBin(packageRoot) {
-  const require = createRequire(path.join(packageRoot, 'package.json'));
-  const astroPkgPath = require.resolve('astro/package.json');
-  const astroPkg = require(astroPkgPath);
-  return path.join(path.dirname(astroPkgPath), astroPkg.bin.astro);
-}
+export function runAstro(command, { packageRoot, contentDir, port, onEvent }) {
+  const child = spawn(process.execPath, [workerPath, command], {
+    stdio: ['ignore', 'pipe', 'pipe', 'ipc'],
+    // Explicit, not inherited: astro.config.mjs's own `outDir` lives
+    // inside packageRoot (writedocsBuildStagingDir() - see its own
+    // comment in writedocs-temp-dir.js for the full EXDEV story this is
+    // one half of), and Astro's static builder only stages its
+    // prerendered output *inside* that outDir - rather than falling
+    // back to `<process.cwd()>/.astro/.prerender/` - when outDir starts
+    // with process.cwd() (getOutDirWithinCwd, astro/dist/core/build/
+    // common.js). Left unset, this child would just inherit whatever
+    // directory the *parent* writedocs CLI process happened to be
+    // launched from - unrelated to packageRoot for a real globally-
+    // installed CLI invoked from wherever the user's shell happens to
+    // be - so the fallback branch would fire regardless, staging
+    // outside packageRoot again and reintroducing the exact module-
+    // resolution problem this whole design is meant to avoid. Pinning
+    // cwd to packageRoot here guarantees the "starts with cwd" check
+    // passes deterministically, independent of the parent process's own
+    // cwd.
+    cwd: packageRoot,
+    env: {
+      ...process.env,
+      WRITEDOCS_CONTENT_DIR: contentDir,
+      // Astro is always run with root: packageRoot (astro-worker.js), so
+      // every CollectionEntry's `filePath` comes back relative to *this*,
+      // not to contentDir or the process's cwd. Exposed so lib/config.ts's
+      // fileIdForEntry() can resolve it back into a docs/-relative file id
+      // - see that function for why.
+      WRITEDOCS_PACKAGE_ROOT: packageRoot,
+      ...(port ? { WRITEDOCS_PORT: String(port) } : {}),
+    },
+  });
 
-export function runAstro(args, { packageRoot, contentDir }) {
-  const astroBin = resolveAstroBin(packageRoot);
-  return new Promise((resolve, reject) => {
-    const child = spawn(process.execPath, [astroBin, ...args], {
-      stdio: 'inherit',
-      // Explicit, not inherited: astro.config.mjs's own `outDir` lives
-      // inside packageRoot (writedocsBuildStagingDir() - see its own
-      // comment in writedocs-temp-dir.js for the full EXDEV story this is
-      // one half of), and Astro's static builder only stages its
-      // prerendered output *inside* that outDir - rather than falling
-      // back to `<process.cwd()>/.astro/.prerender/` - when outDir starts
-      // with process.cwd() (getOutDirWithinCwd, astro/dist/core/build/
-      // common.js). Left unset, this child would just inherit whatever
-      // directory the *parent* writedocs CLI process happened to be
-      // launched from - unrelated to packageRoot for a real globally-
-      // installed CLI invoked from wherever the user's shell happens to
-      // be - so the fallback branch would fire regardless, staging
-      // outside packageRoot again and reintroducing the exact module-
-      // resolution problem this whole design is meant to avoid. Pinning
-      // cwd to packageRoot here guarantees the "starts with cwd" check
-      // passes deterministically, independent of the parent process's own
-      // cwd.
-      cwd: packageRoot,
-      env: {
-        ...process.env,
-        WRITEDOCS_CONTENT_DIR: contentDir,
-        // Astro is always invoked with `--root packageRoot` (see build.js/
-        // dev.js), so every CollectionEntry's `filePath` comes back
-        // relative to *this*, not to contentDir or the process's cwd.
-        // Exposed so lib/config.ts's fileIdForEntry() can resolve it back
-        // into a docs/-relative file id - see that function for why.
-        WRITEDOCS_PACKAGE_ROOT: packageRoot,
-      },
+  child.on('message', (message) => {
+    if (message && typeof message === 'object' && typeof message.type === 'string') onEvent(message);
+  });
+
+  for (const streamName of ['stdout', 'stderr']) {
+    let pending = '';
+    const emit = (line) => {
+      if (line.trim() === '') return;
+      const own = line.match(/^\[writedocs\]\s+(?:(\S+:\d+(?::\d+)?) - )?(.*)$/);
+      if (own) onEvent({ type: 'report', level: streamName === 'stderr' ? 'warn' : 'info', message: own[2], where: own[1] ?? null });
+      else onEvent({ type: 'raw', stream: streamName, line });
+    };
+    child[streamName].setEncoding('utf8');
+    child[streamName].on('data', (chunk) => {
+      pending += chunk;
+      const lines = pending.split(/\r?\n/);
+      pending = lines.pop();
+      lines.forEach(emit);
     });
-    child.on('exit', (code) => {
-      if (code === 0) resolve();
-      else reject(new Error(`astro ${args[0]} exited with code ${code}`));
+    child[streamName].on('end', () => {
+      if (pending) emit(pending);
+      pending = '';
     });
+  }
+
+  const exited = new Promise((resolve, reject) => {
     child.on('error', reject);
+    child.on('close', (code, signal) => resolve(code ?? (signal ? 1 : 0)));
   });
+  return { child, exited };
 }

package/src/cli/run-pagefind.js

@@ -7,12 +7,11 @@ import { spawn } from 'node:child_process';
  * directories from packageRoot - the same lookup algorithm Node itself
  * uses for bare-specifier resolution, just done by hand with fs instead
  * of require.resolve()/import.meta.resolve(). This is necessary (rather
- * than mirroring resolveAstroBin()'s simpler require.resolve()-based
- * approach in run-astro.js) because pagefind's own package.json declares
- * an "exports" map with only a "." entry scoped to the "import"
- * condition: require.resolve('pagefind/package.json') is blocked
- * outright (exports doesn't list a package.json subpath at all), and
- * require.resolve('pagefind') also fails under CJS require() semantics
+ * than a require.resolve()-based lookup) because pagefind's own
+ * package.json declares an "exports" map with only a "." entry scoped to
+ * the "import" condition: require.resolve('pagefind/package.json') is
+ * blocked outright (exports doesn't list a package.json subpath at all),
+ * and require.resolve('pagefind') also fails under CJS require() semantics
  * (no "require"/"default" condition for it to satisfy).
  * import.meta.resolve() would sidestep both, but needs Node 20.6+ -
  * newer than this package's documented minimum (20.3.0, see engines in
@@ -50,16 +49,22 @@ function resolvePagefindBin(packageRoot) {
  * `.wd-article`) - without that scoping, Pagefind falls back to indexing
  * every page's entire <body>, polluting every result with sidebar/topbar
  * chrome text repeated on every page.
+ *
+ * Pagefind's output is captured, not printed: the CLI prints its own step
+ * line, and Pagefind's text only when it fails (in the rejected Error).
  */
 export function runPagefind(siteDir, { packageRoot }) {
   const bin = resolvePagefindBin(packageRoot);
   return new Promise((resolve, reject) => {
     const child = spawn(process.execPath, [bin, '--site', siteDir, '--quiet'], {
-      stdio: 'inherit',
+      stdio: ['ignore', 'pipe', 'pipe'],
     });
-    child.on('exit', (code) => {
+    let output = '';
+    child.stdout.on('data', (d) => (output += d));
+    child.stderr.on('data', (d) => (output += d));
+    child.on('close', (code) => {
       if (code === 0) resolve();
-      else reject(new Error(`pagefind exited with code ${code}`));
+      else reject(new Error(`pagefind exited with code ${code}${output.trim() ? `:\n${output.trim()}` : ''}`));
     });
     child.on('error', reject);
   });

package/src/components/AppIcon.astro

@@ -8,6 +8,7 @@
 // don't each need their own copy of the resolveIcon() call + branch.
 import { Icon } from 'astro-icon/components';
 import { resolveIcon, iconExists } from '../lib/config';
+import { report } from '../lib/cli-report.js';
 
 interface Props {
   icon?: string;
@@ -30,7 +31,7 @@ if (icon && resolved?.kind === 'iconify' && !iconExists(icon)) {
   const warned: Set<string> = ((globalThis as any).__wdWarnedIcons ??= new Set());
   if (!warned.has(icon)) {
     warned.add(icon);
-    console.warn(`[writedocs] unknown icon "${icon}" - no installed icon set has it, so it's left out.`);
+    report('warn', `Unknown icon "${icon}" - no installed icon set has it, so it's left out.`);
   }
   resolved = null;
 }

package/src/lib/astro-log-destination.js

@@ -0,0 +1,25 @@
+// Astro logger destination for the writedocs CLI (Astro's `logger` config -
+// see src/cli/astro-worker.js, which sets it). Every message Astro and Vite
+// log - build steps, route lists, dev request logs, warnings, errors - comes
+// through write() as a { level, label, message } event; instead of printing
+// it, this hands the event to the writedocs CLI process over IPC, and the CLI
+// (src/cli/output.js) decides what the author actually sees.
+//
+// Plain JS with no imports: Astro also bundles this module into the build's
+// own server code (virtual:astro:logger), and it has to load there too.
+// Outside the CLI - no IPC channel - it falls back to printing the message,
+// so nothing is ever lost silently.
+export default function writedocsLogDestination() {
+  return {
+    write(event) {
+      const message = String(event.message ?? '');
+      if (typeof process !== 'undefined' && typeof process.send === 'function' && process.connected) {
+        process.send({ type: 'astro-log', level: event.level, label: event.label ?? null, message });
+        return;
+      }
+      const line = event.label && event.label !== 'SKIP_FORMAT' ? `[${event.label}] ${message}` : message;
+      if (event.level === 'error' || event.level === 'warn') console.error(line);
+      else console.log(line);
+    },
+  };
+}

package/src/lib/cli-report.js

@@ -0,0 +1,20 @@
+// How writedocs code that runs inside Astro - astro.config.mjs, remark
+// plugins, components - tells the author something. Under the writedocs CLI
+// the message goes over IPC to the CLI process (src/cli/run-astro.js), which
+// prints it in its own format: warnings are listed at the end of a build,
+// or as they happen in `writedocs dev`. Anywhere else (Astro run directly,
+// a test) it's printed with a [writedocs] prefix.
+//
+// level: 'warn' - something the author should fix or know about;
+//        'info' - a note about how the site was built (shown after a build);
+//        'debug' - only with --verbose.
+// where: optional "file:line" the message is about, relative to the project.
+export function report(level, message, where) {
+  if (typeof process !== 'undefined' && typeof process.send === 'function' && process.connected) {
+    process.send({ type: 'report', level, message, where: where ?? null });
+    return;
+  }
+  const text = `[writedocs] ${where ? `${where} - ` : ''}${message}`;
+  if (level === 'warn') console.warn(text);
+  else console.log(text);
+}

package/src/lib/content-check.js

@@ -9,6 +9,7 @@
 //   - an .mdx file doesn't parse as MDX
 //   - writedocs.json's navigation lists a page that doesn't exist
 //   - a redirect is a pattern (`/old/:slug`) rather than one exact path
+//   - a Markdown image with a relative path names a file that doesn't exist
 // Warnings - the build succeeds, but not as written:
 //   - an unknown component (the build shows only its content - see
 //     lib/mdx-unknown-components.js)
@@ -118,6 +119,28 @@ async function checkPage(contentDir, rel, errors, warnings) {
     );
     return;
   }
+  // A Markdown image with a relative path is imported by the build (Astro's
+  // image pipeline), so a missing file fails the whole build.
+  visit(tree, 'image', (node) => {
+    const url = String(node.url ?? '');
+    if (!url || url.startsWith('/') || url.startsWith('#') || /^[a-z][a-z0-9+.-]*:/i.test(url) || url.startsWith('//')) return;
+    let target;
+    try {
+      target = path.resolve(path.dirname(path.join(contentDir, rel)), decodeURI(url.split(/[?#]/)[0]));
+    } catch {
+      return;
+    }
+    if (fs.existsSync(target)) return;
+    const line = node.position?.start?.line;
+    errors.push(
+      issue(
+        rel,
+        line ? line + lineOffset : undefined,
+        `Image ${url} doesn't exist - the build fails on it.`,
+        'The path is relative to this page\'s folder. Fix it, or use a path from the project root, like "/images/example.png".'
+      )
+    );
+  });
   for (const { name, line } of findUnknownComponents(tree)) {
     warnings.push(
       issue(