@brandon_m_behring/book-scaffold-astro 5.0.0 → 5.2.0

package/scripts/init-qa.mjs

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+/**
+ * Generate the portfolio QA engine's deterministic guide registry.
+ *
+ * This module deliberately owns only guide_qa.yaml generation. The scaffold
+ * QA command does not execute the generated shell commands, and this script
+ * never spawns npm or performs network work itself.
+ */
+import { access, writeFile } from 'node:fs/promises';
+import { constants as fsConstants } from 'node:fs';
+import { relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadResolvedBookConfig } from './resolve-book-config.mjs';
+
+export const GUIDE_QA_FILENAME = 'guide_qa.yaml';
+export const GUIDE_QA_HEADER =
+  '# Generated by book-scaffold init-qa.\n' +
+  '# Regenerate with: book-scaffold init-qa --force\n';
+
+export const INIT_QA_USAGE = `Usage: book-scaffold init-qa [--force]
+
+Create a deterministic guide_qa.yaml for the implicit single book or every
+registered corpus book. Generated checks use the locally installed scaffold
+binary in npm offline mode.
+
+Options:
+  --force       Replace an existing guide_qa.yaml. No other file is changed.
+  --help, -h    Print this message and exit without writing a file.
+`;
+
+const BOOK_ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const COMMAND_PREFIX = 'npm --offline exec -- book-scaffold qa';
+
+export class InitQaUsageError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'InitQaUsageError';
+  }
+}
+
+export class GuideQaExistsError extends Error {
+  constructor(path) {
+    super(`${GUIDE_QA_FILENAME} already exists; rerun with --force to replace it.`);
+    this.name = 'GuideQaExistsError';
+    this.code = 'EEXIST';
+    this.path = path;
+  }
+}
+
+/** Parse only the flags owned by init-qa. */
+export function parseInitQaArgs(argv) {
+  if (!Array.isArray(argv)) {
+    throw new TypeError('init-qa arguments must be an array.');
+  }
+
+  let force = false;
+  let help = false;
+  for (const arg of argv) {
+    if (arg === '--force') {
+      if (force) throw new InitQaUsageError('--force may be specified only once.');
+      force = true;
+    } else if (arg === '--help' || arg === '-h') {
+      help = true;
+    } else {
+      throw new InitQaUsageError(`unknown argument ${JSON.stringify(arg)}.`);
+    }
+  }
+  return Object.freeze({ force, help });
+}
+
+function guideIds(toolingConfig) {
+  if (toolingConfig === null || typeof toolingConfig !== 'object' || Array.isArray(toolingConfig)) {
+    throw new TypeError('init-qa requires resolved book tooling configuration.');
+  }
+
+  if (toolingConfig.corpus == null) return Object.freeze(['book']);
+  const books = toolingConfig.corpus.books;
+  if (!Array.isArray(books) || books.length === 0) {
+    throw new TypeError('init-qa requires a non-empty resolved corpus book list.');
+  }
+
+  const ids = [];
+  const seen = new Set();
+  for (const [index, book] of books.entries()) {
+    const id = book?.id;
+    if (typeof id !== 'string' || !BOOK_ID_PATTERN.test(id)) {
+      throw new TypeError(`init-qa received an invalid corpus book id at index ${index}.`);
+    }
+    if (seen.has(id)) {
+      throw new TypeError(`init-qa received duplicate corpus book id ${JSON.stringify(id)}.`);
+    }
+    seen.add(id);
+    ids.push(id);
+  }
+  return Object.freeze(ids);
+}
+
+/** Render the exact, stable interoperability document for resolved config. */
+export function renderGuideQa(toolingConfig) {
+  const ids = guideIds(toolingConfig);
+  const corpus = toolingConfig.corpus != null;
+  const lines = [GUIDE_QA_HEADER.trimEnd(), 'version: 1', 'guides:'];
+
+  for (const id of ids) {
+    lines.push(`  - id: ${id}`);
+    const selector = corpus ? ` --book ${id}` : '';
+    lines.push(`    check_cmd: ${COMMAND_PREFIX}${selector} --format json`);
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+async function pathExists(path) {
+  try {
+    await access(path, fsConstants.F_OK);
+    return true;
+  } catch (error) {
+    if (error?.code === 'ENOENT') return false;
+    throw error;
+  }
+}
+
+/**
+ * Resolve the consumer config and write only guide_qa.yaml.
+ *
+ * `loadConfig` is injectable so callers and tests can reuse this filesystem
+ * boundary without evaluating an Astro config more than once.
+ */
+export async function initGuideQa({
+  projectRoot = process.cwd(),
+  force = false,
+  loadConfig = loadResolvedBookConfig,
+} = {}) {
+  if (typeof projectRoot !== 'string' || projectRoot.length === 0) {
+    throw new TypeError('init-qa projectRoot must be a non-empty string.');
+  }
+  if (typeof force !== 'boolean') {
+    throw new TypeError('init-qa force must be a boolean.');
+  }
+  if (typeof loadConfig !== 'function') {
+    throw new TypeError('init-qa loadConfig must be a function.');
+  }
+
+  const root = resolve(projectRoot);
+  const outputPath = resolve(root, GUIDE_QA_FILENAME);
+  if (!force && (await pathExists(outputPath))) {
+    throw new GuideQaExistsError(outputPath);
+  }
+
+  const toolingConfig = await loadConfig(root);
+  const contents = renderGuideQa(toolingConfig);
+  try {
+    await writeFile(outputPath, contents, {
+      encoding: 'utf8',
+      flag: force ? 'w' : 'wx',
+    });
+  } catch (error) {
+    if (!force && error?.code === 'EEXIST') throw new GuideQaExistsError(outputPath);
+    throw error;
+  }
+
+  return Object.freeze({
+    path: outputPath,
+    contents,
+    guideIds: guideIds(toolingConfig),
+  });
+}
+
+/** Run the command with injectable streams and return its contract exit code. */
+export async function runInitQaCli({
+  argv = process.argv.slice(2),
+  projectRoot = process.cwd(),
+  stdout = process.stdout,
+  stderr = process.stderr,
+  loadConfig = loadResolvedBookConfig,
+} = {}) {
+  let options;
+  try {
+    options = parseInitQaArgs(argv);
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    stderr.write(`init-qa: ${detail}\n\n${INIT_QA_USAGE}`);
+    return 2;
+  }
+
+  if (options.help) {
+    stdout.write(INIT_QA_USAGE);
+    return 0;
+  }
+
+  try {
+    const result = await initGuideQa({ projectRoot, force: options.force, loadConfig });
+    const label = relative(resolve(projectRoot), result.path) || GUIDE_QA_FILENAME;
+    stdout.write(`init-qa: wrote ${label}\n`);
+    return 0;
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    if (error instanceof GuideQaExistsError || error?.code === 'EEXIST') {
+      stderr.write(`init-qa: ${detail}\n`);
+      return 1;
+    }
+    stderr.write(`init-qa: fatal: ${detail}\n`);
+    return 2;
+  }
+}
+
+const invokedPath = process.argv[1] ? resolve(process.argv[1]) : null;
+if (invokedPath === fileURLToPath(import.meta.url)) {
+  process.exitCode = await runInitQaCli();
+}