@notedge/panduck 0.0.0 → 0.0.1

package/src/cli/commands/plan-cmd.ts

@@ -1,188 +1,188 @@
-import type { Cli, ParsedOptions } from "@vmz/commander";
-
-import {
-    assertReadableInput,
-    buildBlockedReport,
-    createContext,
-    resolveFormats,
-    validateIoPaths,
-} from "../context.js";
-import { emitReport } from "../diagnostics.js";
-import { ExitCode } from "../exit-codes.js";
-import { findFormat, isOperationReady } from "../format-registry.js";
-import { CliOptionError, readSharedOptions, readString } from "../options.js";
-import { hasPipeline } from "../pipeline.js";
-import { configureConsoleBackend } from "../console-backend.js";
-import { createReport } from "../report.js";
-
-export function registerPlanCommand(cli: Cli): void {
-    cli.command("plan", "cli.cmd.plan")
-        .option("--to <format>", "cli.opt.to")
-        .option("--from <format>", "cli.opt.from")
-        .option("--profile <name>", "cli.opt.profile")
-        .option("--config <file>", "cli.opt.config")
-        .option("--budget <limit>", "cli.opt.budget")
-        .option("--json", "cli.opt.json")
-        .action((options: ParsedOptions) => runPlan(options));
-}
-
-async function runPlan(options: ParsedOptions): Promise<number> {
-    try {
-        const shared = readSharedOptions(options);
-        const inputPath = options._[0] ?? readString(options, "input");
-        if (!inputPath) {
-            return ExitCode.InvalidArgs;
-        }
-        const ctx = createContext();
-        configureConsoleBackend(ctx.bindings, shared.logFile);
-        const resolved = resolveFormats(inputPath, undefined, shared);
-
-        if (resolved.ambiguous) {
-            const report = buildBlockedReport(
-                ctx,
-                "plan",
-                inputPath,
-                resolved,
-                "ambiguous input format",
-                ExitCode.InputUnsupported,
-                shared,
-            );
-            emitReport(report, shared.diagnostics, shared.json);
-            return ExitCode.InputUnsupported;
-        }
-
-        if (!resolved.to) {
-            const report = buildBlockedReport(
-                ctx,
-                "plan",
-                inputPath,
-                resolved,
-                "target format is required for plan",
-                ExitCode.InvalidArgs,
-                shared,
-            );
-            emitReport(report, shared.diagnostics, shared.json);
-            return ExitCode.InvalidArgs;
-        }
-
-        try {
-            await assertReadableInput(inputPath);
-        } catch {
-            const report = buildBlockedReport(
-                ctx,
-                "plan",
-                inputPath,
-                resolved,
-                "input is not readable",
-                ExitCode.InputUnsupported,
-                shared,
-            );
-            emitReport(report, shared.diagnostics, shared.json);
-            return ExitCode.InputUnsupported;
-        }
-
-        const source = resolved.from ? findFormat(ctx.registry, resolved.from) : undefined;
-        const target = findFormat(ctx.registry, resolved.to);
-        if (!target) {
-            const report = buildBlockedReport(
-                ctx,
-                "plan",
-                inputPath,
-                resolved,
-                `unknown target format ${resolved.to}`,
-                ExitCode.InputUnsupported,
-                shared,
-            );
-            emitReport(report, shared.diagnostics, shared.json);
-            return ExitCode.InputUnsupported;
-        }
-
-        const routeReady = hasPipeline(ctx.bindings, resolved.from, resolved.to);
-
-        if (!routeReady) {
-            if (source && !isOperationReady(source, "read")) {
-                const report = createReport({
-                    operation: "plan",
-                    toolVersion: ctx.toolVersion,
-                    status: "blocked",
-                    inputs: [{ path: inputPath, format: source.format }],
-                    detection: { format: source.format, confidence: "hint", hints: resolved.hints },
-                    pipeline: {
-                        reader: source.format,
-                        writer: target.format,
-                        stages: ["detect", "read", "ir", "write", "publish"],
-                        blocked_reason: `reader state is ${source.reader.state}`,
-                    },
-                    coverage: target.coverage,
-                    diagnostics: [
-                        {
-                            owner: "panduck",
-                            severity: "error",
-                            message: `source format ${source.format} is not ready for read`,
-                            code: "panduck.reader.not_ready",
-                        },
-                    ],
-                    determinism: { profile: shared.profile ?? "default", config: shared.config ?? null },
-                    statusPolicy: { loss: shared.loss, strict: shared.strict, exit_code: ExitCode.InputUnsupported },
-                });
-                emitReport(report, shared.diagnostics, shared.json);
-                return ExitCode.InputUnsupported;
-            }
-
-            if (!isOperationReady(target, "write")) {
-                const report = createReport({
-                    operation: "plan",
-                    toolVersion: ctx.toolVersion,
-                    status: "blocked",
-                    inputs: [{ path: inputPath, format: resolved.from }],
-                    detection: { format: resolved.from, confidence: "hint", hints: resolved.hints },
-                    pipeline: {
-                        reader: source?.format,
-                        writer: target.format,
-                        stages: ["detect", "read", "ir", "write", "publish"],
-                        blocked_reason: `writer state is ${target.writer.state}`,
-                    },
-                    coverage: target.coverage,
-                    diagnostics: [
-                        {
-                            owner: "panduck",
-                            severity: "error",
-                            message: `target format ${target.format} is not ready for write`,
-                            code: "panduck.writer.not_ready",
-                        },
-                    ],
-                    determinism: { profile: shared.profile ?? "default", config: shared.config ?? null },
-                    statusPolicy: { loss: shared.loss, strict: shared.strict, exit_code: ExitCode.InputUnsupported },
-                });
-                emitReport(report, shared.diagnostics, shared.json);
-                return ExitCode.InputUnsupported;
-            }
-        }
-
-        const report = createReport({
-            operation: "plan",
-            toolVersion: ctx.toolVersion,
-            status: routeReady ? "success" : "success_with_loss",
-            inputs: [{ path: inputPath, format: resolved.from }],
-            detection: { format: resolved.from, confidence: resolved.from ? "hint" : undefined, hints: resolved.hints },
-            pipeline: {
-                reader: source?.format ?? resolved.from,
-                writer: target.format,
-                stages: ["detect", "read", "ir", "write", "publish"],
-            },
-            coverage: source?.coverage ?? target.coverage,
-            budgets: shared.budgets,
-            determinism: { profile: shared.profile ?? "default", config: shared.config ?? null },
-            statusPolicy: { loss: shared.loss, strict: shared.strict, exit_code: ExitCode.Success },
-        });
-        emitReport(report, shared.diagnostics, shared.json);
-        return ExitCode.Success;
-    } catch (error) {
-        if (error instanceof CliOptionError) {
-            console.error(error.message);
-            return error.exitCode;
-        }
-        console.error(error instanceof Error ? error.message : String(error));
-        return ExitCode.InvalidArgs;
-    }
-}
+import type { Cli, ParsedOptions } from "@vmz/commander";
+
+import {
+    assertReadableInput,
+    buildBlockedReport,
+    createContext,
+    resolveFormats,
+    validateIoPaths,
+} from "../context.js";
+import { emitReport } from "../diagnostics.js";
+import { ExitCode } from "../exit-codes.js";
+import { findFormat, isOperationReady } from "../format-registry.js";
+import { CliOptionError, readSharedOptions, readString } from "../options.js";
+import { hasPipeline } from "../pipeline.js";
+import { configureConsoleBackend } from "../console-backend.js";
+import { createReport } from "../report.js";
+
+export function registerPlanCommand(cli: Cli): void {
+    cli.command("plan", "cli.cmd.plan")
+        .option("--to <format>", "cli.opt.to")
+        .option("--from <format>", "cli.opt.from")
+        .option("--profile <name>", "cli.opt.profile")
+        .option("--config <file>", "cli.opt.config")
+        .option("--budget <limit>", "cli.opt.budget")
+        .option("--json", "cli.opt.json")
+        .action((options: ParsedOptions) => runPlan(options));
+}
+
+async function runPlan(options: ParsedOptions): Promise<number> {
+    try {
+        const shared = readSharedOptions(options);
+        const inputPath = options._[0] ?? readString(options, "input");
+        if (!inputPath) {
+            return ExitCode.InvalidArgs;
+        }
+        const ctx = createContext();
+        configureConsoleBackend(ctx.bindings, shared.logFile);
+        const resolved = resolveFormats(inputPath, undefined, shared);
+
+        if (resolved.ambiguous) {
+            const report = buildBlockedReport(
+                ctx,
+                "plan",
+                inputPath,
+                resolved,
+                "ambiguous input format",
+                ExitCode.InputUnsupported,
+                shared,
+            );
+            emitReport(report, shared.diagnostics, shared.json);
+            return ExitCode.InputUnsupported;
+        }
+
+        if (!resolved.to) {
+            const report = buildBlockedReport(
+                ctx,
+                "plan",
+                inputPath,
+                resolved,
+                "target format is required for plan",
+                ExitCode.InvalidArgs,
+                shared,
+            );
+            emitReport(report, shared.diagnostics, shared.json);
+            return ExitCode.InvalidArgs;
+        }
+
+        try {
+            await assertReadableInput(inputPath);
+        } catch {
+            const report = buildBlockedReport(
+                ctx,
+                "plan",
+                inputPath,
+                resolved,
+                "input is not readable",
+                ExitCode.InputUnsupported,
+                shared,
+            );
+            emitReport(report, shared.diagnostics, shared.json);
+            return ExitCode.InputUnsupported;
+        }
+
+        const source = resolved.from ? findFormat(ctx.registry, resolved.from) : undefined;
+        const target = findFormat(ctx.registry, resolved.to);
+        if (!target) {
+            const report = buildBlockedReport(
+                ctx,
+                "plan",
+                inputPath,
+                resolved,
+                `unknown target format ${resolved.to}`,
+                ExitCode.InputUnsupported,
+                shared,
+            );
+            emitReport(report, shared.diagnostics, shared.json);
+            return ExitCode.InputUnsupported;
+        }
+
+        const routeReady = hasPipeline(ctx.bindings, resolved.from, resolved.to);
+
+        if (!routeReady) {
+            if (source && !isOperationReady(source, "read")) {
+                const report = createReport({
+                    operation: "plan",
+                    toolVersion: ctx.toolVersion,
+                    status: "blocked",
+                    inputs: [{ path: inputPath, format: source.format }],
+                    detection: { format: source.format, confidence: "hint", hints: resolved.hints },
+                    pipeline: {
+                        reader: source.format,
+                        writer: target.format,
+                        stages: ["detect", "read", "ir", "write", "publish"],
+                        blocked_reason: `reader state is ${source.reader.state}`,
+                    },
+                    coverage: target.coverage,
+                    diagnostics: [
+                        {
+                            owner: "panduck",
+                            severity: "error",
+                            message: `source format ${source.format} is not ready for read`,
+                            code: "panduck.reader.not_ready",
+                        },
+                    ],
+                    determinism: { profile: shared.profile ?? "default", config: shared.config ?? null },
+                    statusPolicy: { loss: shared.loss, strict: shared.strict, exit_code: ExitCode.InputUnsupported },
+                });
+                emitReport(report, shared.diagnostics, shared.json);
+                return ExitCode.InputUnsupported;
+            }
+
+            if (!isOperationReady(target, "write")) {
+                const report = createReport({
+                    operation: "plan",
+                    toolVersion: ctx.toolVersion,
+                    status: "blocked",
+                    inputs: [{ path: inputPath, format: resolved.from }],
+                    detection: { format: resolved.from, confidence: "hint", hints: resolved.hints },
+                    pipeline: {
+                        reader: source?.format,
+                        writer: target.format,
+                        stages: ["detect", "read", "ir", "write", "publish"],
+                        blocked_reason: `writer state is ${target.writer.state}`,
+                    },
+                    coverage: target.coverage,
+                    diagnostics: [
+                        {
+                            owner: "panduck",
+                            severity: "error",
+                            message: `target format ${target.format} is not ready for write`,
+                            code: "panduck.writer.not_ready",
+                        },
+                    ],
+                    determinism: { profile: shared.profile ?? "default", config: shared.config ?? null },
+                    statusPolicy: { loss: shared.loss, strict: shared.strict, exit_code: ExitCode.InputUnsupported },
+                });
+                emitReport(report, shared.diagnostics, shared.json);
+                return ExitCode.InputUnsupported;
+            }
+        }
+
+        const report = createReport({
+            operation: "plan",
+            toolVersion: ctx.toolVersion,
+            status: routeReady ? "success" : "success_with_loss",
+            inputs: [{ path: inputPath, format: resolved.from }],
+            detection: { format: resolved.from, confidence: resolved.from ? "hint" : undefined, hints: resolved.hints },
+            pipeline: {
+                reader: source?.format ?? resolved.from,
+                writer: target.format,
+                stages: ["detect", "read", "ir", "write", "publish"],
+            },
+            coverage: source?.coverage ?? target.coverage,
+            budgets: shared.budgets,
+            determinism: { profile: shared.profile ?? "default", config: shared.config ?? null },
+            statusPolicy: { loss: shared.loss, strict: shared.strict, exit_code: ExitCode.Success },
+        });
+        emitReport(report, shared.diagnostics, shared.json);
+        return ExitCode.Success;
+    } catch (error) {
+        if (error instanceof CliOptionError) {
+            console.error(error.message);
+            return error.exitCode;
+        }
+        console.error(error instanceof Error ? error.message : String(error));
+        return ExitCode.InvalidArgs;
+    }
+}

package/src/cli/console-backend.ts

@@ -1,16 +1,16 @@
-import type { PanduckBindings } from "../types.js";
-
-/** Install a native JSON lines log sink when bindings expose the hook. */
-export function configureConsoleBackend(
-    bindings: PanduckBindings | null,
-    logFile?: string,
-): void {
-    if (!logFile) {
-        return;
-    }
-    const install = bindings?.installLoggerLogFile ?? bindings?.installConsoleLogFile;
-    if (!install) {
-        return;
-    }
-    install(logFile);
-}
+import type { PanduckBindings } from "../types.js";
+
+/** Install a native JSON lines log sink when bindings expose the hook. */
+export function configureConsoleBackend(
+    bindings: PanduckBindings | null,
+    logFile?: string,
+): void {
+    if (!logFile) {
+        return;
+    }
+    const install = bindings?.installLoggerLogFile ?? bindings?.installConsoleLogFile;
+    if (!install) {
+        return;
+    }
+    install(logFile);
+}

package/src/cli/context.ts

@@ -1,98 +1,98 @@
-import { access } from "node:fs/promises";
-import { constants } from "node:fs";
-
-import type { PanduckBindings } from "../types.js";
-import { loadPanduckNode } from "../node/load.js";
-import { getFormatRegistry, findFormat, type FormatRecord } from "./format-registry.js";
-import { extensionHints, inferTargetFromPath, isStdinPath, normalizeFormatId, pathsOverlap } from "./paths.js";
-import { ExitCode } from "./exit-codes.js";
-import type { SharedCliOptions } from "./options.js";
-import { createReport, type PanduckReport } from "./report.js";
-
-export type CliContext = {
-    bindings: PanduckBindings | null;
-    toolVersion: string;
-    registry: FormatRecord[];
-};
-
-export function loadBindings(): PanduckBindings | null {
-    try {
-        return loadPanduckNode();
-    } catch {
-        return null;
-    }
-}
-
-export function createContext(): CliContext {
-    const bindings = loadBindings();
-    return {
-        bindings,
-        toolVersion: bindings?.panduckVersion() ?? "0.0.0",
-        registry: getFormatRegistry(bindings),
-    };
-}
-
-/** Resolved source/target format ids for a CLI invocation. */
-export type ResolvedFormats = {
-    from?: string;
-    to?: string;
-    ambiguous: boolean;
-    hints: string[];
-};
-
-export function resolveFormats(
-    inputPath: string,
-    outputPath: string | undefined,
-    shared: SharedCliOptions,
-): ResolvedFormats {
-    const hints = extensionHints(inputPath);
-    const from = shared.from ? normalizeFormatId(shared.from) : hints.length === 1 ? hints[0] : undefined;
-    const to =
-        shared.to
-            ? normalizeFormatId(shared.to)
-            : outputPath && outputPath !== "-"
-              ? inferTargetFromPath(outputPath)
-              : undefined;
-    const ambiguous = !shared.from && hints.length > 1;
-    return { from, to, ambiguous, hints };
-}
-
-export async function assertReadableInput(path: string): Promise<void> {
-    if (isStdinPath(path)) {
-        return;
-    }
-    await access(path, constants.R_OK);
-}
-
-export function buildBlockedReport(
-    ctx: CliContext,
-    operation: string,
-    inputPath: string,
-    resolved: ResolvedFormats,
-    reason: string,
-    exitCode: number,
-    shared: SharedCliOptions,
-): PanduckReport {
-    return createReport({
-        operation,
-        toolVersion: ctx.toolVersion,
-        status: "blocked",
-        inputs: [{ path: inputPath, format: resolved.from }],
-        detection: {
-            format: resolved.from,
-            confidence: resolved.ambiguous ? "ambiguous" : resolved.from ? "hint" : undefined,
-            hints: resolved.hints,
-        },
-        pipeline: { blocked_reason: reason },
-        diagnostics: [{ owner: "panduck", severity: "error", message: reason }],
-        determinism: { profile: shared.profile ?? "default", config: shared.config ?? null },
-        statusPolicy: { loss: shared.loss, strict: shared.strict, exit_code: exitCode },
-    });
-}
-
-export function validateIoPaths(inputPath: string, outputPath: string | undefined): number | null {
-    if (outputPath && pathsOverlap(inputPath, outputPath)) {
-        return ExitCode.InvalidArgs;
-    }
-    return null;
-}
+import { access } from "node:fs/promises";
+import { constants } from "node:fs";
+
+import type { PanduckBindings } from "../types.js";
+import { loadPanduckNode } from "../node/load.js";
+import { getFormatRegistry, findFormat, type FormatRecord } from "./format-registry.js";
+import { extensionHints, inferTargetFromPath, isStdinPath, normalizeFormatId, pathsOverlap } from "./paths.js";
+import { ExitCode } from "./exit-codes.js";
+import type { SharedCliOptions } from "./options.js";
+import { createReport, type PanduckReport } from "./report.js";
+
+export type CliContext = {
+    bindings: PanduckBindings | null;
+    toolVersion: string;
+    registry: FormatRecord[];
+};
+
+export function loadBindings(): PanduckBindings | null {
+    try {
+        return loadPanduckNode();
+    } catch {
+        return null;
+    }
+}
+
+export function createContext(): CliContext {
+    const bindings = loadBindings();
+    return {
+        bindings,
+        toolVersion: bindings?.panduckVersion() ?? "0.0.0",
+        registry: getFormatRegistry(bindings),
+    };
+}
+
+/** Resolved source/target format ids for a CLI invocation. */
+export type ResolvedFormats = {
+    from?: string;
+    to?: string;
+    ambiguous: boolean;
+    hints: string[];
+};
+
+export function resolveFormats(
+    inputPath: string,
+    outputPath: string | undefined,
+    shared: SharedCliOptions,
+): ResolvedFormats {
+    const hints = extensionHints(inputPath);
+    const from = shared.from ? normalizeFormatId(shared.from) : hints.length === 1 ? hints[0] : undefined;
+    const to =
+        shared.to
+            ? normalizeFormatId(shared.to)
+            : outputPath && outputPath !== "-"
+              ? inferTargetFromPath(outputPath)
+              : undefined;
+    const ambiguous = !shared.from && hints.length > 1;
+    return { from, to, ambiguous, hints };
+}
+
+export async function assertReadableInput(path: string): Promise<void> {
+    if (isStdinPath(path)) {
+        return;
+    }
+    await access(path, constants.R_OK);
+}
+
+export function buildBlockedReport(
+    ctx: CliContext,
+    operation: string,
+    inputPath: string,
+    resolved: ResolvedFormats,
+    reason: string,
+    exitCode: number,
+    shared: SharedCliOptions,
+): PanduckReport {
+    return createReport({
+        operation,
+        toolVersion: ctx.toolVersion,
+        status: "blocked",
+        inputs: [{ path: inputPath, format: resolved.from }],
+        detection: {
+            format: resolved.from,
+            confidence: resolved.ambiguous ? "ambiguous" : resolved.from ? "hint" : undefined,
+            hints: resolved.hints,
+        },
+        pipeline: { blocked_reason: reason },
+        diagnostics: [{ owner: "panduck", severity: "error", message: reason }],
+        determinism: { profile: shared.profile ?? "default", config: shared.config ?? null },
+        statusPolicy: { loss: shared.loss, strict: shared.strict, exit_code: exitCode },
+    });
+}
+
+export function validateIoPaths(inputPath: string, outputPath: string | undefined): number | null {
+    if (outputPath && pathsOverlap(inputPath, outputPath)) {
+        return ExitCode.InvalidArgs;
+    }
+    return null;
+}

package/src/cli/diagnostics.ts

@@ -1,24 +1,24 @@
-import type { DiagnosticsMode } from "./options.js";
-import type { PanduckReport } from "./report.js";
-
-export function emitHuman(message: string): void {
-    console.error(message);
-}
-
-export function emitJson(value: unknown): void {
-    console.log(JSON.stringify(value, null, 2));
-}
-
-export function emitReport(report: PanduckReport, mode: DiagnosticsMode, jsonRequested: boolean): void {
-    if (jsonRequested || mode === "json") {
-        emitJson(report);
-        return;
-    }
-    if (mode === "silent") {
-        return;
-    }
-    emitHuman(`${report.operation}: ${report.status}`);
-    for (const item of report.diagnostics ?? []) {
-        emitHuman(`[${item.owner}] ${item.severity}: ${item.message}`);
-    }
-}
+import type { DiagnosticsMode } from "./options.js";
+import type { PanduckReport } from "./report.js";
+
+export function emitHuman(message: string): void {
+    console.error(message);
+}
+
+export function emitJson(value: unknown): void {
+    console.log(JSON.stringify(value, null, 2));
+}
+
+export function emitReport(report: PanduckReport, mode: DiagnosticsMode, jsonRequested: boolean): void {
+    if (jsonRequested || mode === "json") {
+        emitJson(report);
+        return;
+    }
+    if (mode === "silent") {
+        return;
+    }
+    emitHuman(`${report.operation}: ${report.status}`);
+    for (const item of report.diagnostics ?? []) {
+        emitHuman(`[${item.owner}] ${item.severity}: ${item.message}`);
+    }
+}