@nowline/cli 0.8.5 → 0.9.0

package/src/commands/render.ts

@@ -1,20 +1,17 @@
 import { promises as fs } from 'node:fs';
 import * as path from 'node:path';
+import type { ResolveDiagnostic } from '@nowline/core';
 import {
+    acceptStagedRoadmap,
     type ExportFormat,
-    exportDocument,
+    exportStaged,
     type HostEnv,
     type RenderInputs,
+    type StageResult,
+    stageForExport,
 } from '@nowline/export';
-import { lengthToPoints, parseLength } from '@nowline/export-core';
-import {
-    type NormalizedZone,
-    normalizeThemeName,
-    normalizeZone,
-    resolveToday,
-    type ThemeName,
-    TimezoneError,
-} from '@nowline/layout';
+import type { PdfPageSize } from '@nowline/export-core';
+import type { NonWorkingDisplay, ThemeName } from '@nowline/layout';
 import type { AssetResolver } from '@nowline/renderer';
 import type { ParsedArgs } from '../cli/args.js';
 import {
@@ -23,20 +20,28 @@ import {
     type OutputFormat,
     resolveFormat,
 } from '../cli/formats.js';
+import { type PdfOrientation, resolveCliOptions } from '../cli/options.js';
 import { resolveRenderOutputPath } from '../cli/output-path.js';
 import { parseNowlineJson } from '../convert/parse-json.js';
 import { printNowlineFile } from '../convert/printer.js';
 import { serializeToJson } from '../convert/schema.js';
-import { parseSource } from '../core/parse.js';
-import { type DiagnosticSource, formatDiagnostics } from '../diagnostics/index.js';
+import { getServices, parseSource } from '../core/parse.js';
+import {
+    adaptResolveDiagnostic,
+    type CliDiagnostic,
+    type DiagnosticFormat,
+    type DiagnosticSource,
+    formatDiagnostics,
+} from '../diagnostics/index.js';
 import {
     describeContentLocaleSource,
     operatorLocale,
     readDirectiveLocale,
     resolveLocaleOverride,
 } from '../i18n/locale.js';
-import { loadConfig } from '../io/config.js';
+import { type LoadConfigResult, loadConfig } from '../io/config.js';
 import { CliError, ExitCode } from '../io/exit-codes.js';
+import { createLog, type Log } from '../io/log.js';
 import { readInput } from '../io/read.js';
 import { writeOutput } from '../io/write.js';
 
@@ -63,18 +68,20 @@ export async function renderHandler(options: RenderHandlerOptions): Promise<void
     }
 
     const isStdoutOutput = args.output === '-';
-    const config = await loadConfigFor(args.positional, cwd);
+    const log = createLog(args.logLevel);
+    const { config, path: rcPath } = await loadConfigFor(args.positional, cwd);
+    // Every rc-backed setting resolves flag > .nowlinerc > default; a bad
+    // value is reported by `assertValid` below, where it always has been.
+    const cliOptions = resolveCliOptions(args, config, { rcPath });
 
     const format = resolveFormatOrThrow({
         flag: args.format,
         outputPath: args.output,
-        configFormat: typeof config?.defaultFormat === 'string' ? config.defaultFormat : undefined,
+        configFormat: cliOptions.defaultFormat,
         isStdout: isStdoutOutput,
     });
 
-    if (args.logLevel === 'verbose') {
-        process.stderr.write(`nowline: format=${format} (resolved)\n`);
-    }
+    log.verbose(`nowline: format=${format} (resolved)`);
 
     const resolvedOutput = resolveRenderOutputPath({
         outputArg: args.output,
@@ -92,10 +99,11 @@ export async function renderHandler(options: RenderHandlerOptions): Promise<void
     const resolved = resolveLocaleOverride({
         flag: args.locale,
         env: process.env,
-        rc: stringFromConfig(config, 'locale'),
+        rc: cliOptions.rcLocale,
     });
     const locale = resolved.tag;
     const opLocale = operatorLocale(resolved);
+    cliOptions.assertValid();
 
     const { rendered, isBinary } = await produce({
         format,
@@ -104,33 +112,34 @@ export async function renderHandler(options: RenderHandlerOptions): Promise<void
         displayPath: input.displayPath,
         absInputPath: input.isStdin ? path.resolve(cwd, 'stdin.nowline') : input.path,
         isStdin: input.isStdin,
-        theme: parseTheme(args.theme),
-        today: resolveNowCli(args),
-        width: parseWidthArg(args.width),
+        theme: cliOptions.surface.theme,
+        today: cliOptions.surface.today,
+        width: cliOptions.surface.width,
+        nonWorking: cliOptions.surface.nonWorking,
         noLinks: args.noLinks,
         strict: args.strict,
-        assetRoot: args.assetRoot,
-        // m2c format-specific options. Strings get parsed inside the format
-        // dispatch; the CLI just passes them through.
-        pageSize: args.pageSize ?? stringFromConfig(config, 'pdfPageSize'),
-        orientation: args.orientation ?? stringFromConfig(config, 'pdfOrientation'),
-        margin: args.margin ?? stringFromConfig(config, 'pdfMargin'),
-        fontSans: args.fontSans ?? stringFromConfig(config, 'fontSans'),
-        fontMono: args.fontMono ?? stringFromConfig(config, 'fontMono'),
-        headless: args.headless || boolFromConfig(config, 'headlessFonts'),
-        useSystemFonts: args.useSystemFonts || boolFromConfig(config, 'useSystemFonts'),
+        assetRoot: cliOptions.assetRoot,
+        // m2c format-specific options. The PDF settings parse in `produce`,
+        // after validation, for every format.
+        pageSize: cliOptions.surface.pageSize,
+        orientation: cliOptions.orientation,
+        marginPt: cliOptions.margin,
+        assertPdfSettingsValid: () => cliOptions.assertPdfSettingsValid(),
+        fontSans: cliOptions.fontSans,
+        fontMono: cliOptions.fontMono,
+        headless: cliOptions.headless,
+        useSystemFonts: cliOptions.useSystemFonts,
         scale: args.scale,
         start: args.start,
         locale,
         operatorLocale: opLocale,
         resolvedLocale: resolved,
-        verbose: args.logLevel === 'verbose',
+        log,
+        diagnosticFormat: resolveDiagnosticFormat(args),
     });
 
     if (args.dryRun) {
-        if (args.logLevel === 'verbose') {
-            process.stderr.write('nowline: --dry-run; skipping write\n');
-        }
+        log.verbose('nowline: --dry-run; skipping write');
         return;
     }
 
@@ -141,8 +150,8 @@ export async function renderHandler(options: RenderHandlerOptions): Promise<void
         { cwd },
     );
 
-    if (args.logLevel === 'verbose' && !resolvedOutput.isStdout) {
-        process.stderr.write(`nowline: wrote ${resolvedOutput.path}\n`);
+    if (!resolvedOutput.isStdout) {
+        log.verbose(`nowline: wrote ${resolvedOutput.path}`);
     }
 }
 
@@ -194,13 +203,17 @@ interface ProduceArgs {
     theme: ThemeName;
     today?: Date;
     width?: number;
+    nonWorking?: NonWorkingDisplay;
     noLinks: boolean;
     strict: boolean;
     assetRoot?: string;
     // m2c format-specific
-    pageSize?: string;
-    orientation?: string;
-    margin?: string;
+    pageSize?: PdfPageSize;
+    orientation?: PdfOrientation;
+    /** Page margin in points. */
+    marginPt?: number;
+    /** Reports a bad PDF setting; run after validation so its error follows any diagnostics. */
+    assertPdfSettingsValid: () => void;
     fontSans?: string;
     fontMono?: string;
     headless: boolean;
@@ -214,8 +227,10 @@ interface ProduceArgs {
     operatorLocale: string;
     /** Resolved locale override metadata, used for the verbose-mode source line. */
     resolvedLocale: import('../i18n/locale.js').ResolvedLocale;
-    /** True for `--verbose`. Gates the `nowline: locale=...` source-line emission. */
-    verbose: boolean;
+    /** `-v` / `-q` gate: verbose lines, warnings, and text-mode warning diagnostics. */
+    log: Log;
+    /** How diagnostics are written to stderr. See `resolveDiagnosticFormat`. */
+    diagnosticFormat: DiagnosticFormat;
 }
 
 interface ProduceResult {
@@ -238,17 +253,38 @@ async function produce(args: ProduceArgs): Promise<ProduceResult> {
             ? jsonToNowlineText(args.contents, args.displayPath)
             : args.contents;
 
-    // Pre-validate with locale-aware diagnostic formatting so validation
-    // errors reach the operator in their locale. The kernel will re-parse
-    // the same source below — double work accepted in exchange for faithful
-    // stderr output.
-    await parseAndValidate(sourceText, args);
-
     const assetRoot = args.assetRoot
         ? path.resolve(args.assetRoot)
         : path.dirname(args.absInputPath);
 
-    const host = createNodeHostEnv(assetRoot);
+    // Included files' text, kept for the code frames of routed diagnostics.
+    const included = new Map<string, string>();
+    const nodeHost = createNodeHostEnv(assetRoot);
+    const host: HostEnv = {
+        ...nodeHost,
+        readSource: async (absPath) => {
+            const text = await nodeHost.readSource(absPath);
+            included.set(absPath, text);
+            return text;
+        },
+    };
+
+    // What the stage lays out with; the export below must ask for the same.
+    const layoutInputs: RenderInputs = {
+        sourcePath: args.absInputPath,
+        today: args.today,
+        locale: args.locale ?? 'und',
+        theme: args.theme,
+        width: args.width,
+        nonWorking: args.nonWorking,
+    };
+
+    // Parse and stage once. Validation diagnostics come out in the operator's
+    // locale, and routed include-resolver diagnostics join the validator's
+    // here, so they are reported at the same point and in the same report.
+    const { stage, stageFailure } = await parseAndValidate(sourceText, args, {
+        stage: { inputs: layoutInputs, host, included },
+    });
 
     // Resolve fonts lazily — only for formats that rasterize or embed them.
     let fonts: RenderInputs['fonts'];
@@ -256,29 +292,28 @@ async function produce(args: ProduceArgs): Promise<ProduceResult> {
         fonts = await resolveNodeFonts(args);
     }
 
+    args.assertPdfSettingsValid();
+
     const kernelInputs: RenderInputs = {
-        sourcePath: args.absInputPath,
-        today: args.today,
-        locale: args.locale ?? 'und',
-        theme: args.theme,
+        ...layoutInputs,
         fonts,
-        width: args.width,
         noLinks: args.noLinks,
         strict: args.strict,
         pageSize: args.pageSize,
-        orientation: parseOrientation(args.orientation),
-        marginPt: parseMargin(args.margin),
+        orientation: args.orientation,
+        marginPt: args.marginPt,
         pngScale: parseScale(args.scale),
         msprojStart: args.start,
+        onNotice: (message) => args.log.notice(message),
+        onWarning: (message) => args.log.notice(`warning: ${message}`),
     };
 
     try {
-        const bytes = await exportDocument(
-            sourceText,
-            args.format as ExportFormat,
-            kernelInputs,
-            host,
-        );
+        // A stage failure or an uncoded include error was held back until
+        // here, so a bad font or PDF setting is still reported first.
+        if (!stage) throw stageFailure;
+        const staged = acceptStagedRoadmap(stage, kernelInputs);
+        const bytes = await exportStaged(staged, args.format as ExportFormat, kernelInputs, host);
         const isBinary = BINARY_FORMATS.has(args.format);
         const rendered: string | Uint8Array = isBinary
             ? bytes
@@ -294,6 +329,18 @@ async function produce(args: ProduceArgs): Promise<ProduceResult> {
     }
 }
 
+/**
+ * How an included file is named in diagnostics: relative to the input's
+ * display path, so `examples/a.nowline` including `./teams/b.nowline` prints
+ * `examples/teams/b.nowline` (absolute when the input was given absolute).
+ */
+function includeDisplayPath(absPath: string, args: ProduceArgs): string {
+    const rel = path.relative(path.dirname(args.absInputPath), absPath);
+    if (path.isAbsolute(rel)) return rel;
+    const base = args.isStdin ? '' : path.dirname(args.displayPath);
+    return path.join(base, rel);
+}
+
 // ---- Node HostEnv -----------------------------------------------------------
 
 function createNodeHostEnv(assetRoot: string): HostEnv {
@@ -364,20 +411,20 @@ async function resolveNodeFonts(
         if (args.strict) {
             throw new CliError(ExitCode.InputError, `nowline: ${message}`);
         }
-        process.stderr.write(`warning: ${message}\n`);
+        args.log.notice(`warning: ${message}`);
     }
 
     // Bundled fallback after an opted-in probe found no usable system font.
     // Only meaningful when --use-system-fonts is set; warn under --strict.
     if (args.strict) {
         if (result.sansFellBackToBundled) {
-            process.stderr.write(
-                'warning: sans font fell back to bundled DejaVu (no platform font found)\n',
+            args.log.notice(
+                'warning: sans font fell back to bundled DejaVu (no platform font found)',
             );
         }
         if (result.monoFellBackToBundled) {
-            process.stderr.write(
-                'warning: mono font fell back to bundled DejaVu (no platform font found)\n',
+            args.log.notice(
+                'warning: mono font fell back to bundled DejaVu (no platform font found)',
             );
         }
     }
@@ -403,86 +450,99 @@ function jsonToNowlineText(contents: string, displayPath: string): string {
     return printNowlineFile(ast);
 }
 
-async function parseAndValidate(contents: string, args: ProduceArgs) {
-    const result = await parseSource(contents, args.displayPath, { validate: true });
-    if (result.hasErrors) {
-        emitDiagnostics(result.diagnostics, result.source, args.displayPath, args.operatorLocale);
-        throw new CliError(ExitCode.ValidationError, '');
-    }
-    if (args.verbose) {
-        const directive = readDirectiveLocale(result.ast);
-        const { tag, source } = describeContentLocaleSource(directive, args.resolvedLocale);
-        process.stderr.write(`nowline: locale=${tag} (${source})\n`);
-    }
-    return result;
+/** What `parseAndValidate` stages with, once the source validates. */
+interface StageRequest {
+    /** The layout inputs the export that follows will ask for. */
+    inputs: RenderInputs;
+    host: HostEnv;
+    /** Collects the text of each file the stage reads, for code frames. */
+    included: Map<string, string>;
 }
 
-async function loadConfigFor(
-    inputArg: string,
-    cwd: string,
-): Promise<{ defaultFormat?: string } | null> {
-    try {
-        if (inputArg === '-') {
-            const { config } = await loadConfig(cwd);
-            return config;
+/**
+ * Parse and validate; on errors, report them and throw. With `stage`, the
+ * validated document is also staged (include resolution, logo, layout) and a
+ * file that has includes reports the routed (wave-rule) diagnostics of that
+ * stage with the validator's, in the same report (specs/waves.md §6.1). The
+ * stage is returned for the export to reuse. Every other include error, and a
+ * stage that throws, is left for the caller to report where the kernel always
+ * did (exit 3).
+ */
+async function parseAndValidate(
+    contents: string,
+    args: ProduceArgs,
+    options: { stage?: StageRequest } = {},
+) {
+    const result = await parseSource(contents, args.displayPath, { validate: true });
+    const diagnostics = [...result.diagnostics];
+    const sources = new Map<string, DiagnosticSource>([[args.displayPath, result.source]]);
+    let failed = result.hasErrors;
+    let stage: StageResult | undefined;
+    let stageFailure: unknown;
+    if (!failed && options.stage) {
+        const { inputs, host, included } = options.stage;
+        try {
+            stage = await stageForExport(contents, inputs, host, {
+                document: result.document,
+                services: getServices(),
+            });
+        } catch (err) {
+            stageFailure = err;
+        }
+        if (stage && result.ast.includes.length > 0) {
+            for (const d of routedDiagnostics(stage)) {
+                const isRoot = d.sourcePath === args.absInputPath;
+                const file = isRoot ? args.displayPath : includeDisplayPath(d.sourcePath, args);
+                const text = isRoot ? result.source.contents : included.get(d.sourcePath);
+                if (text !== undefined) sources.set(file, { file, contents: text });
+                diagnostics.push(adaptResolveDiagnostic(d, file, text));
+                if (d.severity === 'error') failed = true;
+            }
         }
-        const abs = path.resolve(cwd, inputArg);
-        const dir = path.dirname(abs);
-        const { config } = await loadConfig(dir);
-        return config;
-    } catch {
-        return null;
     }
+    // Text mode prints only when the run fails. JSON mode prints one document
+    // whenever any diagnostic exists, warnings included, so a warnings-only
+    // run still exits 0 with the document on stderr.
+    if (failed || (args.diagnosticFormat === 'json' && diagnostics.length > 0)) {
+        emitDiagnostics(diagnostics, sources, args.operatorLocale, args.diagnosticFormat, args.log);
+    }
+    if (failed) {
+        throw new CliError(ExitCode.ValidationError, '');
+    }
+    const directive = readDirectiveLocale(result.ast);
+    const { tag, source } = describeContentLocaleSource(directive, args.resolvedLocale);
+    args.log.verbose(`nowline: locale=${tag} (${source})`);
+    return { ...result, stage, stageFailure };
 }
 
-function parseTheme(raw: string | undefined): ThemeName {
-    if (!raw) return 'light';
-    // `greyscale` (UK) is accepted and canonicalized to `grayscale` (US).
-    const theme = normalizeThemeName(raw);
-    if (!theme) {
-        throw new CliError(
-            ExitCode.InputError,
-            `nowline: invalid --theme "${raw}". Expected light, dark, or grayscale.`,
-        );
+/**
+ * The routed (wave-rule) diagnostics of a stage's include resolution. Empty
+ * when the resolver reports any other include error: that one is more
+ * fundamental, and the export reports it as before (exit 3).
+ */
+function routedDiagnostics(stage: StageResult): ResolveDiagnostic[] {
+    if (stage.kind === 'staged' || (stage.kind === 'include-error' && !stage.legacy)) {
+        return stage.routed;
     }
-    return theme;
+    return [];
 }
 
-// Resolve the now-line date from the CLI flags.
-//
-// Precedence:
-//   1. `--now -`                           → undefined (suppress now-line)
-//   2. `--now YYYY-MM-DD`                  → floating date; zone ignored
-//   3. `--now YYYY-MM-DDTHH:MM:SS[±HH:MM]` → civil date at embedded offset; --timezone ignored
-//   4. `--now YYYY-MM-DDTHH:MM:SSZ`        → civil date in UTC; --timezone ignored
-//   5. `--now YYYY-MM-DDTHH:MM:SS`         → floating; written date part; zone ignored
-//   6. flag omitted                        → civil date of today in --timezone (default: local)
-//
-// `--timezone` is only consulted for case 6. Authored dates in the roadmap
-// (bars, milestones, axis) are floating and are never affected.
-function resolveNowCli(args: { now?: string; timezone?: string }): Date | undefined {
-    let zone: NormalizedZone | undefined;
-    if (args.timezone) {
-        try {
-            zone = normalizeZone(args.timezone);
-        } catch (err) {
-            if (err instanceof TimezoneError) {
-                throw new CliError(ExitCode.InputError, err.message);
-            }
-            throw err;
-        }
-    }
-    const result = resolveToday({ now: args.now, zone });
-    // resolveToday returns undefined for unrecognised strings; surface that as
-    // an input error so the user gets a clear message instead of a silent no-line.
-    if (result === undefined && args.now !== undefined && args.now !== '-') {
+// Walk up from the input (or `cwd` for stdin) to the nearest `.nowlinerc`.
+// No rc file is not an error. One that exists but cannot be read or parsed is
+// a usage error (specs/cli.md, `.nowlinerc`): silently ignoring it would
+// render with settings the user believes they changed. The loader's reason
+// already names the file, so it is passed through. `--serve` shares this.
+export async function loadConfigFor(inputArg: string, cwd: string): Promise<LoadConfigResult> {
+    try {
+        if (inputArg === '-') return await loadConfig(cwd);
+        const abs = path.resolve(cwd, inputArg);
+        return await loadConfig(path.dirname(abs));
+    } catch (err) {
         throw new CliError(
             ExitCode.InputError,
-            `nowline: invalid --now "${args.now}". ` +
-                `Expected YYYY-MM-DD, YYYY-MM-DDTHH:MM:SS[Z|±HH:MM], or "-".`,
+            `nowline: invalid .nowlinerc: ${err instanceof Error ? err.message : String(err)}`,
         );
     }
-    return result;
 }
 
 function parseScale(raw: string | undefined): number | undefined {
@@ -497,68 +557,41 @@ function parseScale(raw: string | undefined): number | undefined {
     return value;
 }
 
-function parseOrientation(raw: string | undefined): 'portrait' | 'landscape' | 'auto' | undefined {
-    if (!raw) return undefined;
-    const lower = raw.toLowerCase();
-    if (lower === 'portrait' || lower === 'landscape' || lower === 'auto') return lower;
-    throw new CliError(
-        ExitCode.InputError,
-        `nowline: invalid --orientation "${raw}". Expected portrait, landscape, or auto.`,
-    );
-}
-
-function parseMargin(raw: string | undefined): number | undefined {
-    if (!raw) return undefined;
-    if (/^\d+(?:\.\d+)?$/.test(raw)) return Number(raw); // bare number → points
-    try {
-        return lengthToPoints(parseLength(raw));
-    } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        throw new CliError(ExitCode.InputError, `nowline: invalid --margin "${raw}": ${message}`);
-    }
-}
-
-function stringFromConfig(
-    config: { [key: string]: unknown } | null,
-    key: string,
-): string | undefined {
-    if (!config) return undefined;
-    const value = config[key];
-    return typeof value === 'string' ? value : undefined;
-}
-
-function boolFromConfig(config: { [key: string]: unknown } | null, key: string): boolean {
-    if (!config) return false;
-    const value = config[key];
-    return value === true;
-}
-
-function parseWidthArg(raw: string | undefined): number | undefined {
-    if (!raw) return undefined;
-    const value = parseInt(raw, 10);
-    if (!Number.isFinite(value) || value < 320) {
-        throw new CliError(
-            ExitCode.InputError,
-            `nowline: invalid --width "${raw}". Must be an integer ≥ 320.`,
-        );
-    }
-    return value;
+/**
+ * `--diagnostic-format` is the explicit switch. Left unset, a `--dry-run` that
+ * asks for `--format=json` gets JSON diagnostics (the machine-consumer shape
+ * in `specs/cli.md`); every other run keeps the text frames.
+ */
+function resolveDiagnosticFormat(args: ParsedArgs): DiagnosticFormat {
+    if (args.diagnosticFormat) return args.diagnosticFormat;
+    if (args.dryRun && args.format?.toLowerCase() === 'json') return 'json';
+    return 'text';
 }
 
 function emitDiagnostics(
-    diagnostics: Parameters<typeof formatDiagnostics>[0],
-    source: DiagnosticSource,
-    displayPath: string,
+    diagnostics: CliDiagnostic[],
+    sources: Map<string, DiagnosticSource>,
     operatorLocale: string,
+    format: DiagnosticFormat,
+    log: Log,
 ): void {
-    const sources = new Map<string, DiagnosticSource>([[displayPath, source]]);
-    const rendered = formatDiagnostics(diagnostics, 'text', sources, {
+    // JSON is machine output and always prints whole; text drops warnings under -q.
+    const shown = format === 'text' ? errorsOnlyWhenQuiet(diagnostics, log) : diagnostics;
+    const rendered = formatDiagnostics(shown, format, sources, {
         color: process.stderr.isTTY === true,
         operatorLocale,
     });
     if (rendered) process.stderr.write(`${rendered}\n`);
 }
 
+/** Under `-q`, text-mode diagnostics keep only errors. Shared with serve. */
+export function errorsOnlyWhenQuiet<T extends { severity: string }>(
+    diagnostics: T[],
+    log: Log,
+): T[] {
+    return log.quiet ? diagnostics.filter((d) => d.severity === 'error') : diagnostics;
+}
+
 // ---- Asset resolver (still used by serve.ts) --------------------------------
 
 export function createAssetResolver(assetRoot: string): AssetResolver {