@writedocs/generator 0.4.10 → 0.4.12

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/mdx-inline-react.js

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import crypto from 'node:crypto';
 import { parse as acornParse } from 'acorn';
+import { report } from './cli-report.js';
 import { writedocsTempDir } from './writedocs-temp-dir.js';
 import { MINTLIFY_HOOKS } from './mdx-mintlify.js';
 import { BUILTIN_COMPONENT_NAMES } from './mdx-inject-builtins.js';
@@ -137,7 +138,7 @@ export function remarkExtractInlineReactComponents() {
     const relPath = path.relative(contentDir, file.path).split(path.sep).join('/');
     for (const use of simplified) {
       const line = source.slice(0, use.offset).split('\n').length;
-      console.warn(`[writedocs] ${relPath}:${line} - ${simplifiedBuiltinMessage(use).message}`);
+      report('warn', simplifiedBuiltinMessage(use).message, `${relPath}:${line}`);
     }
 
     const pageDir = path.dirname(file.path);

package/src/lib/mdx-unknown-components.js

@@ -2,6 +2,7 @@ import path from 'node:path';
 import { visit } from 'unist-util-visit';
 import { parse as acornParse } from 'acorn';
 import { BUILTIN_COMPONENT_NAMES } from './mdx-inject-builtins.js';
+import { report } from './cli-report.js';
 
 // Which JSX elements in an MDX file are components writedocs can't resolve
 // - neither a built-in nor something the file imports or defines itself.
@@ -120,9 +121,10 @@ export function remarkUnknownComponentFallback() {
       : '(unknown file)';
     const stubs = new Set();
     for (const { node, name, line, inCode, root } of found) {
-      console.warn(
-        `[writedocs] ${filePath}${line ? `:${line}` : ''} - unknown component <${name}>, showing only its content. ` +
-          'Remove it, or define it in a snippet.'
+      report(
+        'warn',
+        `Unknown component <${name}> - showing only its content. Remove it, or define it in a snippet.`,
+        `${filePath}${line ? `:${line}` : ''}`
       );
       if (inCode) {
         stubs.add(root);