fconvert 0.1.0

package/src/handlers/registry.ts

@@ -0,0 +1,68 @@
+import type { BundleResolver } from "../bundle/resolve.ts";
+import type { Logger } from "../core/logger.ts";
+import type { Workspace } from "../executor/workspace.ts";
+import type { ConversionHandler, HandlerContext } from "./base.ts";
+import { BinaryBridgeHandler } from "./bridges/binary.ts";
+import { TextBridgeHandler } from "./bridges/text.ts";
+import { FfmpegHandler } from "./native/ffmpeg.ts";
+import { ImageMagickHandler } from "./native/imagemagick.ts";
+import { PandocHandler } from "./native/pandoc.ts";
+import { SevenZipHandler } from "./native/sevenzip.ts";
+
+export class HandlerRegistry {
+  private readonly handlers: ConversionHandler[];
+  private readonly availability = new Map<string, boolean>();
+
+  constructor(handlers?: ConversionHandler[]) {
+    this.handlers =
+      handlers ??
+      [
+        new FfmpegHandler(),
+        new ImageMagickHandler(),
+        new PandocHandler(),
+        new SevenZipHandler(),
+        new TextBridgeHandler(),
+        new BinaryBridgeHandler(),
+      ];
+  }
+
+  async init(ctx: {
+    workspace: Workspace;
+    bundle: BundleResolver;
+    logger: Logger;
+    timeoutMs?: number;
+  }): Promise<void> {
+    const handlerContext: HandlerContext = {
+      workspace: ctx.workspace,
+      bundle: ctx.bundle,
+      logger: ctx.logger,
+      timeoutMs: ctx.timeoutMs,
+    };
+
+    for (const handler of this.handlers) {
+      if (handler.init) {
+        await handler.init(handlerContext);
+      }
+      if (handler.isAvailable) {
+        this.availability.set(handler.name, await handler.isAvailable(handlerContext));
+      } else {
+        this.availability.set(handler.name, true);
+      }
+    }
+  }
+
+  all(): ConversionHandler[] {
+    return [...this.handlers];
+  }
+
+  availableHandlers(): ConversionHandler[] {
+    return this.handlers.filter((handler) => this.availability.get(handler.name) ?? true);
+  }
+
+  status(): Array<{ name: string; available: boolean }> {
+    return this.handlers.map((handler) => ({
+      name: handler.name,
+      available: this.availability.get(handler.name) ?? true,
+    }));
+  }
+}

package/src/planner/costs.ts

@@ -0,0 +1,111 @@
+import type { FileFormat } from "../core/types.ts";
+import type { ConversionHandler, HandlerRule } from "../handlers/base.ts";
+
+const BASE_STEP_COST = 100;
+const LOSSY_PENALTY = 80;
+const ANY_INPUT_PENALTY = 140;
+const BINARY_PENALTY = 140;
+
+const CATEGORY_MATRIX = new Map<string, number>([
+  ["text|document", 20],
+  ["document|text", 20],
+  ["image|vector", 35],
+  ["vector|image", 35],
+  ["image|document", 40],
+  ["document|image", 40],
+  ["audio|video", 30],
+  ["video|audio", 30],
+  ["data|text", 25],
+  ["text|data", 25],
+  ["data|code", 35],
+  ["code|data", 35],
+  ["document|presentation", 30],
+  ["presentation|document", 30],
+  ["document|spreadsheet", 35],
+  ["spreadsheet|document", 35],
+  ["font|binary", 40],
+  ["binary|font", 40],
+]);
+
+function sameCategory(from: FileFormat, to: FileFormat): boolean {
+  return from.category.some((category) => to.category.includes(category));
+}
+
+function minCategoryTransition(from: FileFormat, to: FileFormat): number {
+  let min = Number.POSITIVE_INFINITY;
+  for (const source of from.category) {
+    for (const target of to.category) {
+      if (source === target) {
+        return 0;
+      }
+      const matrix = CATEGORY_MATRIX.get(`${source}|${target}`);
+      if (typeof matrix === "number") {
+        min = Math.min(min, matrix);
+      }
+    }
+  }
+
+  if (Number.isFinite(min)) {
+    return min;
+  }
+
+  if (from.category.includes("archive") || to.category.includes("archive")) {
+    return 90;
+  }
+  if (from.category.includes("binary") || to.category.includes("binary")) {
+    return BINARY_PENALTY;
+  }
+  return 120;
+}
+
+export function categoriesCompatibleStrict(from: FileFormat, to: FileFormat): boolean {
+  if (sameCategory(from, to)) {
+    return true;
+  }
+
+  const compatibleClusters: string[][] = [
+    ["text", "document", "data", "code"],
+    ["image", "vector", "document"],
+    ["audio", "video"],
+  ];
+
+  for (const cluster of compatibleClusters) {
+    const hasFrom = from.category.some((value) => cluster.includes(value));
+    const hasTo = to.category.some((value) => cluster.includes(value));
+    if (hasFrom && hasTo) {
+      return true;
+    }
+  }
+
+  if (to.category.includes("archive") || from.category.includes("archive")) {
+    return true;
+  }
+
+  return false;
+}
+
+export function edgeCost(
+  handler: ConversionHandler,
+  rule: HandlerRule,
+  from: FileFormat,
+  to: FileFormat,
+): number {
+  let cost = BASE_STEP_COST;
+  cost += rule.cost ?? 0;
+  cost += handler.capabilities.startupCost ?? 0;
+  cost += minCategoryTransition(from, to);
+
+  if (rule.from === "*" || handler.capabilities.supportsAnyInput) {
+    cost += ANY_INPUT_PENALTY;
+  }
+  if (rule.lossless === false) {
+    cost += LOSSY_PENALTY;
+  }
+  if (to.category.includes("binary")) {
+    cost += BINARY_PENALTY;
+  }
+
+  const priority = handler.capabilities.priority ?? 0;
+  cost += Math.max(0, 100 - priority);
+  return Math.max(1, cost);
+}

package/src/planner/deadends.ts

@@ -0,0 +1,31 @@
+import type { PlannedEdge, PlannedRoute } from "../handlers/base.ts";
+
+function edgeSignature(edge: PlannedEdge): string {
+  return `${edge.handler.name}:${edge.from.id}->${edge.to.id}`;
+}
+
+function prefixSignature(edges: PlannedEdge[]): string {
+  return edges.map((edge) => edgeSignature(edge)).join("|");
+}
+
+export class DeadEndTracker {
+  private readonly deadPrefixes = new Set<string>();
+
+  markDeadPrefix(edges: PlannedEdge[]): void {
+    if (edges.length === 0) {
+      return;
+    }
+    this.deadPrefixes.add(prefixSignature(edges));
+  }
+
+  routeBlocked(route: PlannedRoute): boolean {
+    for (let index = 0; index < route.edges.length; index += 1) {
+      const prefix = route.edges.slice(0, index + 1);
+      const signature = prefixSignature(prefix);
+      if (this.deadPrefixes.has(signature)) {
+        return true;
+      }
+    }
+    return false;
+  }
+}

package/src/planner/explain.ts

@@ -0,0 +1,12 @@
+import type { PlannedRoute } from "../handlers/base.ts";
+
+export function explainRoute(route: PlannedRoute): string[] {
+  return route.edges.map((edge) => `${edge.handler.name}:${edge.from.id}->${edge.to.id}`);
+}
+
+export function describeRoutes(routes: PlannedRoute[], limit = 5): string[] {
+  return routes.slice(0, limit).map((route, index) => {
+    const path = explainRoute(route).join(" | ");
+    return `${index + 1}. cost=${route.totalCost} ${path}`;
+  });
+}

package/src/planner/graph.ts

@@ -0,0 +1,68 @@
+import type { FileFormat } from "../core/types.ts";
+import { FormatRegistry } from "../formats/registry.ts";
+import type { ConversionHandler, PlannedEdge } from "../handlers/base.ts";
+import { categoriesCompatibleStrict, edgeCost } from "./costs.ts";
+
+export class ConversionGraph {
+  private readonly adjacency = new Map<string, PlannedEdge[]>();
+
+  constructor(
+    private readonly registry: FormatRegistry,
+    handlers: ConversionHandler[],
+    strict: boolean,
+  ) {
+    this.build(handlers, strict);
+  }
+
+  private addEdge(edge: PlannedEdge): void {
+    const list = this.adjacency.get(edge.from.id) ?? [];
+    list.push(edge);
+    this.adjacency.set(edge.from.id, list);
+  }
+
+  private resolveRuleTargets(ruleValue: string | "*", allFormats: FileFormat[]): FileFormat[] {
+    if (ruleValue === "*") {
+      return allFormats;
+    }
+
+    const format = this.registry.getById(ruleValue);
+    if (!format) {
+      return [];
+    }
+    return [format];
+  }
+
+  private build(handlers: ConversionHandler[], strict: boolean): void {
+    const allFormats = this.registry.all();
+
+    for (const handler of handlers) {
+      for (const rule of handler.rules) {
+        const fromCandidates = this.resolveRuleTargets(rule.from, allFormats);
+        const toCandidates = this.resolveRuleTargets(rule.to, allFormats);
+
+        for (const from of fromCandidates) {
+          for (const to of toCandidates) {
+            if (from.id === to.id) {
+              continue;
+            }
+            if (strict && !categoriesCompatibleStrict(from, to)) {
+              continue;
+            }
+
+            this.addEdge({
+              handler,
+              from,
+              to,
+              rule,
+              cost: edgeCost(handler, rule, from, to),
+            });
+          }
+        }
+      }
+    }
+  }
+
+  outgoing(formatId: string): PlannedEdge[] {
+    return this.adjacency.get(formatId) ?? [];
+  }
+}

package/src/planner/search.ts

@@ -0,0 +1,77 @@
+import type { PlanOptions } from "../core/types.ts";
+import type { PlannedRoute } from "../handlers/base.ts";
+import { ConversionGraph } from "./graph.ts";
+
+interface SearchState {
+  node: string;
+  cost: number;
+  edges: PlannedRoute["edges"];
+  visited: Set<string>;
+}
+
+function routeSignature(route: PlannedRoute): string {
+  return route.edges
+    .map((edge) => `${edge.handler.name}:${edge.from.id}->${edge.to.id}`)
+    .join("|");
+}
+
+export function findRoutes(
+  graph: ConversionGraph,
+  fromId: string,
+  toId: string,
+  options: PlanOptions,
+): PlannedRoute[] {
+  const queue: SearchState[] = [
+    {
+      node: fromId,
+      cost: 0,
+      edges: [],
+      visited: new Set([fromId]),
+    },
+  ];
+  const routes: PlannedRoute[] = [];
+  const seen = new Set<string>();
+
+  while (queue.length > 0 && routes.length < options.maxCandidates) {
+    queue.sort((a, b) => a.cost - b.cost);
+    const current = queue.shift();
+    if (!current) {
+      break;
+    }
+
+    if (current.node === toId && current.edges.length > 0) {
+      const route: PlannedRoute = {
+        edges: current.edges,
+        totalCost: current.cost,
+      };
+      const signature = routeSignature(route);
+      if (!seen.has(signature)) {
+        routes.push(route);
+        seen.add(signature);
+      }
+      continue;
+    }
+
+    if (current.edges.length >= options.maxSteps) {
+      continue;
+    }
+
+    for (const edge of graph.outgoing(current.node)) {
+      if (current.visited.has(edge.to.id)) {
+        continue;
+      }
+
+      const nextVisited = new Set(current.visited);
+      nextVisited.add(edge.to.id);
+
+      queue.push({
+        node: edge.to.id,
+        cost: current.cost + edge.cost,
+        edges: [...current.edges, edge],
+        visited: nextVisited,
+      });
+    }
+  }
+
+  return routes.sort((a, b) => a.totalCost - b.totalCost);
+}

package/test/e2e/engine-bridge.test.ts

@@ -0,0 +1,52 @@
+import { expect, test } from "bun:test";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { BundleResolver } from "../../src/bundle/resolve.ts";
+import { buildPlanOptions } from "../../src/core/config.ts";
+import { ConsoleLogger } from "../../src/core/logger.ts";
+import { ConversionEngine } from "../../src/executor/executor.ts";
+import { FormatRegistry } from "../../src/formats/registry.ts";
+import { BinaryBridgeHandler } from "../../src/handlers/bridges/binary.ts";
+import { TextBridgeHandler } from "../../src/handlers/bridges/text.ts";
+import { HandlerRegistry } from "../../src/handlers/registry.ts";
+
+test("engine converts txt to json via text bridge", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "convert-e2e-"));
+  const inputPath = join(dir, "input.txt");
+  const outputPath = join(dir, "output.json");
+
+  await writeFile(inputPath, "hello");
+
+  const formats = new FormatRegistry();
+  const handlers = new HandlerRegistry([new TextBridgeHandler(), new BinaryBridgeHandler()]);
+  const bundle = new BundleResolver();
+  const logger = new ConsoleLogger(false, true);
+  const engine = new ConversionEngine(formats, handlers, bundle, logger);
+
+  const inputFormat = formats.getById("txt");
+  const outputFormat = formats.getById("json");
+  if (!inputFormat || !outputFormat) {
+    throw new Error("Required test formats missing");
+  }
+
+  const result = await engine.execute({
+    inputPath,
+    outputPath,
+    inputFormat,
+    outputFormat,
+    strict: false,
+    keepTemp: false,
+    plan: buildPlanOptions({
+      strict: false,
+      maxSteps: 4,
+      maxCandidates: 5,
+    }),
+  });
+
+  const output = await readFile(outputPath, "utf8");
+  expect(result.route.edges.length).toBeGreaterThan(0);
+  expect(output.includes('"data": "hello"')).toBeTrue();
+
+  await rm(dir, { recursive: true, force: true });
+});

package/test/unit/detect.test.ts

@@ -0,0 +1,15 @@
+import { expect, test } from "bun:test";
+import { detectInputFormat, resolveOutputFormat } from "../../src/formats/detect.ts";
+import { FormatRegistry } from "../../src/formats/registry.ts";
+
+test("detects input format from extension", () => {
+  const registry = new FormatRegistry();
+  const format = detectInputFormat("/tmp/photo.jpg", undefined, registry);
+  expect(format.id).toBe("jpeg");
+});
+
+test("resolves output format from --to", () => {
+  const registry = new FormatRegistry();
+  const format = resolveOutputFormat(undefined, "pdf", registry);
+  expect(format.id).toBe("pdf");
+});

package/test/unit/planner.test.ts

@@ -0,0 +1,46 @@
+import { expect, test } from "bun:test";
+import { FormatRegistry } from "../../src/formats/registry.ts";
+import { ConversionGraph } from "../../src/planner/graph.ts";
+import { findRoutes } from "../../src/planner/search.ts";
+import type { ConversionHandler, ConvertRequest, HandlerContext, HandlerResult } from "../../src/handlers/base.ts";
+
+class MockHandler implements ConversionHandler {
+  readonly name: string;
+  readonly capabilities = { startupCost: 0, priority: 80, deterministic: true };
+  readonly rules;
+
+  constructor(name: string, rules: ConversionHandler["rules"]) {
+    this.name = name;
+    this.rules = rules;
+  }
+
+  async convert(_ctx: HandlerContext, request: ConvertRequest): Promise<HandlerResult> {
+    return {
+      output: {
+        kind: "file",
+        path: request.outputPath,
+      },
+    };
+  }
+}
+
+test("planner prefers meaningful route over wildcard", () => {
+  const registry = new FormatRegistry();
+
+  const handlers: ConversionHandler[] = [
+    new MockHandler("image-audio-bridge", [{ from: "png", to: "wav", cost: 10 }]),
+    new MockHandler("audio-encoder", [{ from: "wav", to: "mp3", cost: 10 }]),
+    new MockHandler("wildcard", [{ from: "*", to: "*", cost: 400 }]),
+  ];
+
+  const graph = new ConversionGraph(registry, handlers, false);
+  const routes = findRoutes(graph, "png", "mp3", {
+    strict: false,
+    maxSteps: 4,
+    maxCandidates: 5,
+  });
+
+  expect(routes.length).toBeGreaterThan(0);
+  const first = routes[0];
+  expect(first?.edges.map((edge) => edge.handler.name)).toEqual(["image-audio-bridge", "audio-encoder"]);
+});

package/tsconfig.json

@@ -0,0 +1,31 @@
+{
+  "compilerOptions": {
+    // Environment setup & latest features
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "types": ["bun"],
+    "allowJs": true,
+
+    // Bundler mode
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+
+    // Best practices
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+
+    // Some stricter flags (disabled by default)
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noPropertyAccessFromIndexSignature": false
+  },
+  "include": ["src/**/*.ts", "test/**/*.ts"]
+}