Skip to content

armgit / Filee

Public Imported from GitHub
0

Free, open-source file converter. Convert 263 formats offline by drag & drop — images, PDF, Word, Excel, PowerPoint, HWP/HWPX, video, audio, e-books and archives. No upload, no Office needed.

feat(cli): add presets --json and engine hints to failed convert --json files

SeoJCalive85cdc567001d
diff --git a/src/Filee.Cli/Cli.cs b/src/Filee.Cli/Cli.cs
index a0c8a06c..d9765ea1 100644
--- a/src/Filee.Cli/Cli.cs
+++ b/src/Filee.Cli/Cli.cs
@@ -9,6 +9,7 @@ using Filee.Core.Localization;
using Filee.Core.Platform;
using Filee.Core.Presets;
using Filee.Core.Watching;
+using Filee.Engines.Infrastructure;
namespace Filee.Cli;
@@ -46,7 +47,7 @@ internal static class Cli
"convert" => await ConvertAsync(options, host, output, errors, cancellationToken),
"watch" => await WatchAsync(options, host, output, errors, cancellationToken),
"formats" => ListFormats(options, host, output, errors),
- _ => ListPresets(host, output),
+ _ => ListPresets(options, host, output),
};
}
@@ -73,7 +74,7 @@ internal static class Cli
var done = job.Files.Count(f => f.State == FileState.Done);
var failed = job.Files.Count(f => f.State is FileState.Failed or FileState.Cancelled);
if (options.Json)
- WriteJson(job, host.Texts, output);
+ WriteJson(job, host.Texts, host.Catalog, output);
else if (!options.Quiet)
output.WriteLine(failed == 0
? $"Converted {done} of {job.Files.Count} file(s)."
@@ -179,8 +180,9 @@ internal static class Cli
return relative.StartsWith("..", StringComparison.Ordinal) || Path.IsPathRooted(relative) ? path : relative;
}
- private static void WriteJson(ConversionJob job, ILocalizer texts, TextWriter output)
+ private static void WriteJson(ConversionJob job, ILocalizer texts, ConverterCatalog catalog, TextWriter output)
{
+ var optional = new OptionalEngineRoutes(catalog);
using var stream = new MemoryStream();
using (var json = new Utf8JsonWriter(stream, new JsonWriterOptions { Indented = true }))
{
@@ -211,6 +213,11 @@ internal static class Cli
json.WriteStringValue(font);
json.WriteEndArray();
}
+ if (file.State is FileState.Failed or FileState.Cancelled && file.ErrorKey is not null)
+ json.WriteString("errorKey", file.ErrorKey);
+ if (file.State == FileState.Failed && file.ErrorKey == "error.no_route"
+ && file.FailedRoute is { } request && optional.MissingPackages(request) is { Count: > 0 } packages)
+ WriteStrings(json, "needsEngines", packages);
json.WriteEndObject();
}
json.WriteEndArray();
@@ -332,13 +339,11 @@ internal static class Cli
return UsageError;
}
var installed = host.Catalog.CreatePlanner();
- // Engines a download would add, not those this platform lacks (JPEG XR is read with Windows' own codec).
- var everything = host.Catalog.CreatePlanner(host.Catalog.All
- .Where(c => host.Catalog.StatusOf(c).ReasonKey != "engine.reason.unsupported_platform")
- .Select(c => c.Id).ToList());
+ var optional = new OptionalEngineRoutes(host.Catalog);
var targets = FormatRegistry.Known.Where(t => t.Writable && t.Id != from.Id).ToList();
var now = targets.Where(t => installed.CanConvert(from.Id, t.Id)).Select(t => t.Id).ToList();
- var later = targets.Where(t => !now.Contains(t.Id) && everything.CanConvert(from.Id, t.Id)).Select(t => t.Id).ToList();
+ var later = targets.Where(t => !now.Contains(t.Id)
+ && optional.MissingPackages(new RouteRequest(from.Id, t.Id)) is not null).Select(t => t.Id).ToList();
if (options.Json)
{
WriteJsonDocument(output, json =>
@@ -413,8 +418,27 @@ internal static class Cli
output.WriteLine(System.Text.Encoding.UTF8.GetString(stream.ToArray()));
}
- private static int ListPresets(CliHost host, TextWriter output)
+ private static int ListPresets(CliOptions options, CliHost host, TextWriter output)
{
+ if (options.Json)
+ {
+ WriteJsonDocument(output, json =>
+ {
+ json.WriteStartObject();
+ json.WriteStartArray("presets");
+ foreach (var preset in host.Store.Presets.Where(p => !p.IsGroup && !p.IsTool))
+ {
+ json.WriteStartObject();
+ json.WriteString("id", preset.Id);
+ json.WriteString("name", host.Texts.DisplayName(preset));
+ json.WriteString("target", preset.TargetFormat);
+ json.WriteEndObject();
+ }
+ json.WriteEndArray();
+ json.WriteEndObject();
+ });
+ return Success;
+ }
output.WriteLine($"{"ID",-24} {"NAME",-28} TARGET");
foreach (var preset in host.Store.Presets.Where(p => !p.IsGroup && !p.IsTool))
output.WriteLine($"{preset.Id,-24} {host.Texts.DisplayName(preset),-28} {preset.TargetFormat}");
@@ -422,4 +446,35 @@ internal static class Cli
output.WriteLine("Use one with: filee convert <files> --preset <id or name>");
return Success;
}
+
+ private sealed class OptionalEngineRoutes
+ {
+ private readonly ConverterCatalog _catalog;
+ private readonly RoutePlanner _installed;
+ private readonly RoutePlanner _optional;
+ private readonly Dictionary<string, IReadOnlyList<string>> _packages;
+
+ public OptionalEngineRoutes(ConverterCatalog catalog)
+ {
+ _catalog = catalog;
+ _packages = EngineDownloads.Packages.SelectMany(p => p.ConverterIds.Select(id => (Converter: id, Package: p.Id)))
+ .GroupBy(p => p.Converter).ToDictionary(g => g.Key, g => (IReadOnlyList<string>)g.Select(p => p.Package).ToList());
+ _installed = catalog.CreatePlanner();
+ _optional = catalog.CreatePlanner(catalog.All
+ .Where(c => _packages.ContainsKey(c.Id) && catalog.StatusOf(c).ReasonKey != "engine.reason.unsupported_platform")
+ .Select(c => c.Id).ToList());
+ }
+
+ public IReadOnlyList<string>? MissingPackages(RouteRequest request)
+ {
+ if (Plan(_installed) is not null || Plan(_optional) is not { } route)
+ return null;
+ var packages = route.Steps.Where(s => !_catalog.StatusOf(s.Converter).IsAvailable)
+ .SelectMany(s => _packages[s.Converter.Id]).Distinct().ToList();
+ return packages.Count > 0 ? packages : null;
+
+ Route? Plan(RoutePlanner planner) => planner.Plan(request.Source, request.Target, frames: request.Frames,
+ shaping: request.Shaping, motionPhoto: request.MotionPhoto, livePhoto: request.LivePhoto, ocr: request.Ocr);
+ }
+ }
}
diff --git a/src/Filee.Cli/CliHost.cs b/src/Filee.Cli/CliHost.cs
index c7bfa9e6..9e26eb38 100644
--- a/src/Filee.Cli/CliHost.cs
+++ b/src/Filee.Cli/CliHost.cs
@@ -12,7 +12,7 @@ namespace Filee.Cli;
internal sealed class CliHost : IAsyncDisposable
{
- private CliHost(UserDataStore store, ConverterCatalog catalog, JobQueue queue)
+ internal CliHost(UserDataStore store, ConverterCatalog catalog, JobQueue queue)
{
Store = store;
Catalog = catalog;
diff --git a/src/Filee.Cli/Help.cs b/src/Filee.Cli/Help.cs
index 5c508909..5108afcf 100644
--- a/src/Filee.Cli/Help.cs
+++ b/src/Filee.Cli/Help.cs
@@ -16,7 +16,8 @@ internal static class Help
"watch" => Watch,
"formats" => "Usage: filee formats [<format>] [--json]\n\nLists every format, or what one format converts to.\n" +
"With --json, prints the same as JSON (for scripts and other programs).\n",
- "presets" => "Usage: filee presets\n\nLists the presets saved in Filee (built-in and your own).\n",
+ "presets" => "Usage: filee presets [--json]\n\nLists the presets saved in Filee (built-in and your own).\n" +
+ "With --json, prints the same as JSON (for scripts and other programs).\n",
_ => General,
};
@@ -28,7 +29,7 @@ internal static class Help
filee convert <files or folders...> --preset <preset> [options]
filee watch <folder> --to <format> [options]
filee formats [<format>] [--json]
- filee presets
+ filee presets [--json]
filee help [<command>]
filee version
diff --git a/src/Filee.Core/Conversion/ConversionJob.cs b/src/Filee.Core/Conversion/ConversionJob.cs
index e1d4c91f..e2280ceb 100644
--- a/src/Filee.Core/Conversion/ConversionJob.cs
+++ b/src/Filee.Core/Conversion/ConversionJob.cs
@@ -39,6 +39,9 @@ public sealed class FileResult
/// <summary>Localization key of the error (e.g. <c>error.no_route</c>), if any.</summary>
public string? ErrorKey { get; set; }
+ /// <summary>The actual request whose initial route planning failed, or null for other failures.</summary>
+ public RouteRequest? FailedRoute { get; set; }
+
/// <summary>The job's fetcher saves this source first (a file from a browser).</summary>
public bool NeedsFetch { get; init; }
@@ -73,6 +76,10 @@ public sealed class FileResult
public IReadOnlyList<string> MissingFonts { get; set; } = [];
}
+/// <summary>The source, target and constraints of a route planning request.</summary>
+public sealed record RouteRequest(string Source, string Target, bool Frames = false, bool Shaping = false,
+ bool MotionPhoto = false, bool LivePhoto = false, bool Ocr = false);
+
/// <summary>A batch of files converted with one preset.</summary>
public sealed class ConversionJob
{
diff --git a/src/Filee.Core/Conversion/JobQueue.cs b/src/Filee.Core/Conversion/JobQueue.cs
index 53e9b84b..c9517bce 100644
--- a/src/Filee.Core/Conversion/JobQueue.cs
+++ b/src/Filee.Core/Conversion/JobQueue.cs
@@ -765,7 +765,8 @@ public sealed class JobQueue : IAsyncDisposable
var ocr = (finalOutput || target == "pdf") && runWith.RecognizesTextOf(source.Id);
var route = planner.Plan(source.Id, target, frames, motionPhoto: motionPhoto, livePhoto: livePhoto, ocr: ocr);
if (route is null)
- return Fail(file, "error.no_route", $"{source.Id} → {target}");
+ return Fail(file, "error.no_route", $"{source.Id} → {target}",
+ new RouteRequest(source.Id, target, Frames: frames, MotionPhoto: motionPhoto, LivePhoto: livePhoto, Ocr: ocr));
// A step that draws text without shaping (rhwp) would break Arabic, Hebrew, Indic or Thai text: such a file
// takes a route without it (LibreOffice), or is refused with the reason rather than written broken. One
@@ -952,11 +953,12 @@ public sealed class JobQueue : IAsyncDisposable
return copy;
}
- IReadOnlyList<string> Fail(FileResult f, string key, string? detail)
+ IReadOnlyList<string> Fail(FileResult f, string key, string? detail, RouteRequest? failedRoute = null)
{
f.State = FileState.Failed;
f.ErrorKey = key;
f.ErrorDetail = detail;
+ f.FailedRoute = failedRoute;
f.Progress = 1;
Notify(job);
return [];
diff --git a/tests/Filee.Cli.Tests/CliTests.cs b/tests/Filee.Cli.Tests/CliTests.cs
index 3ea02fc1..c11f5678 100644
--- a/tests/Filee.Cli.Tests/CliTests.cs
+++ b/tests/Filee.Cli.Tests/CliTests.cs
@@ -3,7 +3,12 @@
using System.Buffers.Binary;
using System.Text.Json;
using System.Xml.Linq;
+using Filee.Core.Conversion;
+using Filee.Core.Formats;
+using Filee.Core.Localization;
using Filee.Core.Presets;
+using Filee.Core.Settings;
+using Filee.Engines.Infrastructure;
using Filee.Engines.Tests;
namespace Filee.Cli.Tests;
@@ -319,11 +324,12 @@ public sealed class CliTests : IDisposable
[Fact]
public async Task Archives_list_folder_as_a_target()
{
- var (code, output, _) = await Run("formats", "zip");
+ var catalog = ArchiveCatalog();
+ var (code, output, _) = await RunWith(catalog, "formats", "zip");
Assert.Equal(Cli.Success, code);
Assert.Contains("folder", output);
- (code, output, _) = await Run("formats", "png");
+ (code, output, _) = await RunWith(catalog, "formats", "png");
Assert.Equal(Cli.Success, code);
Assert.DoesNotContain("folder", output);
}
@@ -346,9 +352,10 @@ public sealed class CliTests : IDisposable
[Fact]
public async Task Formats_json_of_one_format_matches_the_text()
{
- var (code, text, _) = await Run("formats", "zip");
+ var catalog = ArchiveCatalog();
+ var (code, text, _) = await RunWith(catalog, "formats", "zip");
Assert.Equal(Cli.Success, code);
- (code, var output, _) = await Run("formats", "zip", "--json");
+ (code, var output, _) = await RunWith(catalog, "formats", "zip", "--json");
Assert.Equal(Cli.Success, code);
using var json = JsonDocument.Parse(output);
@@ -623,4 +630,480 @@ public sealed class CliTests : IDisposable
Assert.Equal(Cli.UsageError, code);
Assert.Contains("is an interactive tool, not a conversion", errors);
}
+
+ private static ConverterCatalog ArchiveCatalog() =>
+ new([new ControlledConverter("archive", true, [new("zip", "folder")])]);
+
+ private CliHost ControlledHost(ConverterCatalog catalog)
+ {
+ var store = new UserDataStore(_settings);
+ store.Load();
+ var joins = new UnexpectedMerger();
+ return new CliHost(store, catalog, new JobQueue(catalog, joins, tiffMerger: joins, mediaJoiner: joins));
+ }
+
+ private async Task<(int Code, string Output, string Errors)> RunWith(ConverterCatalog catalog, params string[] args)
+ {
+ var output = new StringWriter();
+ var errors = new StringWriter();
+ var code = await Cli.RunAsync(args, output, errors, TestContext.Current.CancellationToken, () => ControlledHost(catalog));
+ return (code, output.ToString(), errors.ToString());
+ }
+
+ private string Input(string extension, string content = "input")
+ {
+ var path = Path.Combine(_folder, "input." + extension);
+ File.WriteAllText(path, content);
+ return path;
+ }
+
+ private static ControlledConverter Package(string package, bool available, params ConversionEdge[] edges) =>
+ new(EngineDownloads.Packages.Single(p => p.Id == package).ConverterIds[0], available, edges);
+
+ private static JsonElement Result(string output)
+ {
+ using var json = JsonDocument.Parse(output);
+ return json.RootElement.Clone();
+ }
+
+ private static JsonElement FileResultOf(string output) => Result(output).GetProperty("files")[0];
+
+ private static string[] Strings(JsonElement value) => value.EnumerateArray().Select(e => e.GetString()!).ToArray();
+
+ private static void Hints(JsonElement file, params string[] packages)
+ {
+ Assert.Equal("failed", file.GetProperty("state").GetString());
+ Assert.Equal("error.no_route", file.GetProperty("errorKey").GetString());
+ if (packages.Length == 0)
+ Assert.False(file.TryGetProperty("needsEngines", out _));
+ else
+ Assert.Equal(packages, Strings(file.GetProperty("needsEngines")));
+ }
+
+ [Fact]
+ public async Task Presets_json_has_one_envelope_and_explicit_fields()
+ {
+ var (code, output, errors) = await RunWith(new([]), "presets", "--json");
+ Assert.Equal(0, code);
+ Assert.Equal("", errors);
+ using var json = JsonDocument.Parse(output);
+ Assert.Equal(["presets"], json.RootElement.EnumerateObject().Select(p => p.Name));
+ Assert.NotEmpty(json.RootElement.GetProperty("presets").EnumerateArray());
+ foreach (var preset in json.RootElement.GetProperty("presets").EnumerateArray())
+ {
+ Assert.Equal(["id", "name", "target"], preset.EnumerateObject().Select(p => p.Name));
+ Assert.All(preset.EnumerateObject(), p => Assert.Equal(JsonValueKind.String, p.Value.ValueKind));
+ }
+ Assert.EndsWith(Environment.NewLine, output);
+ }
+
+ [Fact]
+ public async Task Presets_json_preserves_visible_presets_and_order()
+ {
+ AddPresets(
+ new() { Id = "z-custom", Name = "공백 \"quoted\" name", TargetFormat = "*" },
+ new() { Id = "a-key", NameKey = "preset.merge_pdf", TargetFormat = "folder" },
+ new() { Id = "unnamed", TargetFormat = "jpg" },
+ new() { Id = "hidden-group", Kind = PresetKind.Group },
+ new() { Id = "hidden-tool", Kind = PresetKind.Tool });
+ var store = new UserDataStore(_settings);
+ store.Load();
+ var texts = new EnglishTexts();
+ var expected = store.Presets.Where(p => !p.IsGroup && !p.IsTool).ToArray();
+ var (_, output, _) = await RunWith(new([]), "presets", "--json");
+ var actual = Result(output).GetProperty("presets").EnumerateArray().ToArray();
+ Assert.Equal(expected.Select(p => p.Id), actual.Select(p => p.GetProperty("id").GetString()));
+ Assert.Equal(expected.Select(p => texts.DisplayName(p)), actual.Select(p => p.GetProperty("name").GetString()));
+ Assert.Equal(expected.Select(p => p.TargetFormat), actual.Select(p => p.GetProperty("target").GetString()));
+ var (_, text, _) = await RunWith(new([]), "presets");
+ Assert.Equal(expected.Select(p => p.Id), text.Split('\n').Skip(1).Take(expected.Length)
+ .Select(line => line.Split(' ', StringSplitOptions.RemoveEmptyEntries)[0]));
+ }
+
+ [Fact]
+ public async Task Convert_json_keeps_existing_fields()
+ {
+ var converter = new ControlledConverter("built-in", true, [new("md", "html")])
+ {
+ Convert = (step, _) =>
+ {
+ step.Notice?.Invoke("notice.pdf_not_smaller");
+ step.MissingFonts?.Invoke(["Missing Family"]);
+ return ControlledConverter.Write(step);
+ },
+ };
+ var source = Input("md");
+ var catalog = new ConverterCatalog([converter]);
+ var (code, output, errors) = await RunWith(catalog, "convert", source, "--to", "html", "--json");
+ Assert.Equal(0, code);
+ Assert.Equal("", errors);
+ var root = Result(output);
+ Assert.Equal(["preset", "target", "converted", "skipped", "failed", "files"], root.EnumerateObject().Select(p => p.Name));
+ Assert.Equal("HTML", root.GetProperty("preset").GetString());
+ Assert.Equal("html", root.GetProperty("target").GetString());
+ Assert.Equal(1, root.GetProperty("converted").GetInt32());
+ Assert.Equal(0, root.GetProperty("skipped").GetInt32());
+ Assert.Equal(0, root.GetProperty("failed").GetInt32());
+ var done = FileResultOf(output);
+ Assert.Equal(["source", "state", "outputs", "notice", "missingFonts"], done.EnumerateObject().Select(p => p.Name));
+ Assert.Equal(source, done.GetProperty("source").GetString());
+ Assert.Equal("done", done.GetProperty("state").GetString());
+ Assert.Equal([Path.ChangeExtension(source, "html")], Strings(done.GetProperty("outputs")));
+ Assert.Equal(new EnglishTexts()["notice.pdf_not_smaller"], done.GetProperty("notice").GetString());
+ Assert.Equal(["Missing Family"], Strings(done.GetProperty("missingFonts")));
+
+ // An allocator skip returns no outputs, notice or fonts.
+ converter.Convert = null;
+ (_, output, _) = await RunWith(catalog, "convert", source, "--to", "html", "--skip", "--json");
+ var skipped = FileResultOf(output);
+ Assert.Equal(["source", "state", "outputs"], skipped.EnumerateObject().Select(p => p.Name));
+ Assert.Equal("skipped", skipped.GetProperty("state").GetString());
+ Assert.Empty(Strings(skipped.GetProperty("outputs")));
+ (_, output, _) = await RunWith(new([]), "convert", source, "--to", "mp3", "--json");
+ var failed = FileResultOf(output);
+ Assert.Equal(["source", "state", "outputs", "error", "errorKey"], failed.EnumerateObject().Select(p => p.Name));
+ Assert.Equal(new EnglishTexts()["error.no_route"] + " (md → mp3)", failed.GetProperty("error").GetString());
+ Assert.Empty(Strings(failed.GetProperty("outputs")));
+ // Cancellation's exact old fields and values are asserted by the event-driven cancellation test.
+ await Cancelled_files_do_not_invent_failure_metadata();
+ }
+
+ [Fact]
+ public async Task Convert_exit_codes_remain_compatible()
+ {
+ var source = Input("md");
+ var catalog = new ConverterCatalog([new ControlledConverter("built-in", true, [new("md", "html")])]);
+ var (code, output, _) = await RunWith(catalog, "convert", source, "--to", "html", "--json");
+ Assert.Equal(0, code);
+ Assert.Equal("done", FileResultOf(output).GetProperty("state").GetString());
+ (code, output, _) = await RunWith(catalog, "convert", source, "--to", "html", "--skip", "--json");
+ Assert.Equal(0, code);
+ Assert.Equal(1, Result(output).GetProperty("skipped").GetInt32());
+ Assert.Equal("skipped", FileResultOf(output).GetProperty("state").GetString());
+ (code, output, _) = await RunWith(catalog, "convert", source, "--to", "mp3", "--json");
+ Assert.Equal(1, code);
+ Assert.Equal("failed", FileResultOf(output).GetProperty("state").GetString());
+ Assert.Equal(2, (await RunWith(catalog, "convert", source + ".missing", "--to", "html")).Code);
+ Assert.Equal(2, (await RunWith(catalog, "convert", source, "--wrong")).Code);
+ var empty = Directory.CreateDirectory(Path.Combine(_folder, "empty")).FullName;
+ Assert.Equal(3, (await RunWith(catalog, "convert", empty, "--to", "html")).Code);
+ await Cancelled_files_do_not_invent_failure_metadata();
+ }
+
+ [Fact]
+ public async Task No_route_distinguishes_missing_packages_from_impossible_targets()
+ {
+ var catalog = new ConverterCatalog([Package("pandoc", false, new ConversionEdge("md", "pptx"))]);
+ var (code, output, errors) = await RunWith(catalog, "convert", Input("md"), "--to", "pptx", "--json");
+ Assert.Equal(1, code);
+ Assert.Equal("", errors);
+ Hints(FileResultOf(output), "pandoc");
+ (code, output, _) = await RunWith(catalog, "convert", Input("txt"), "--to", "mp3", "--json");
+ Assert.Equal(1, code);
+ Hints(FileResultOf(output));
+ }
+
+ [Fact]
+ public async Task Optional_targets_and_failure_hints_agree()
+ {
+ var catalog = new ConverterCatalog([
+ new ControlledConverter("built-in", true, [new("md", "html")]),
+ new ControlledConverter("rhwp", false, [new("md", "pptx", 1), new("md", "png")]),
+ Package("pandoc", false, new ConversionEdge("md", "pptx", 30)),
+ ])
+ { Priority = ["rhwp", "pandoc", "built-in"] };
+ var (_, output, _) = await RunWith(catalog, "formats", "md", "--json");
+ var formats = Result(output);
+ Assert.Equal(["html"], Strings(formats.GetProperty("targets")));
+ Assert.Equal(["pptx"], Strings(formats.GetProperty("withEngines")));
+ var optional = Strings(formats.GetProperty("withEngines"));
+ var source = Input("md");
+ foreach (var target in FormatRegistry.Known.Where(t => t.Writable && t.Id != "md"))
+ {
+ (_, output, _) = await RunWith(catalog, "convert", source, "--to", target.Id, "--json");
+ var file = FileResultOf(output);
+ var hasHints = file.TryGetProperty("needsEngines", out var hints);
+ Assert.Equal(optional.Contains(target.Id), hasHints);
+ if (hasHints)
+ {
+ Assert.NotEmpty(Strings(hints));
+ Hints(file, "pandoc");
+ }
+ }
+ }
+
+ [Fact]
+ public async Task Multi_step_failure_lists_all_missing_packages_once()
+ {
+ var pandoc = Package("pandoc", false, new("md", "html"), new("wav", "pptx"));
+ var ffmpeg = Package("ffmpeg", false, new ConversionEdge("html", "wav"));
+ var source = Input("md");
+ var (_, output, _) = await RunWith(new([pandoc, ffmpeg]), "convert", source, "--to", "pptx", "--json");
+ Hints(FileResultOf(output), "pandoc", "ffmpeg");
+ ffmpeg.Available = true;
+ (_, output, _) = await RunWith(new([pandoc, ffmpeg]), "convert", source, "--to", "pptx", "--json");
+ Hints(FileResultOf(output), "pandoc");
+
+ var direct = Package("libreoffice", false, new ConversionEdge("md", "pptx", 40));
+ var catalog = new ConverterCatalog([pandoc, ffmpeg, direct]) { Priority = ["pandoc", "ffmpeg", "libreoffice"] };
+ (_, output, _) = await RunWith(catalog, "convert", source, "--to", "pptx", "--json");
+ Hints(FileResultOf(output), "pandoc");
+ direct.Edges = [new("md", "pptx", 1)];
+ (_, output, _) = await RunWith(catalog, "convert", source, "--to", "pptx", "--json");
+ Hints(FileResultOf(output), "libreoffice");
+
+ var a = Package("pandoc", false, new ConversionEdge("md", "pptx"));
+ var b = Package("libreoffice", false, new ConversionEdge("md", "pptx"));
+ catalog = new([a, b]) { Priority = [b.Id, a.Id] };
+ (_, output, _) = await RunWith(catalog, "convert", source, "--to", "pptx", "--json");
+ Hints(FileResultOf(output), "libreoffice");
+ catalog.Priority = [a.Id, b.Id];
+ (_, output, _) = await RunWith(catalog, "convert", source, "--to", "pptx", "--json");
+ Hints(FileResultOf(output), "pandoc");
+ }
+
+ [Fact]
+ public async Task Engine_hints_exclude_unsupported_and_nonpackage_converters()
+ {
+ var source = Input("md");
+ foreach (var id in new[] { "archive", "rhwp", "wic", "vision", "7zip", "h2orestart", "jre", "vcruntime" })
+ {
+ var catalog = new ConverterCatalog([new ControlledConverter(id, false, [new("md", "pptx")])]);
+ var (_, formats, _) = await RunWith(catalog, "formats", "md", "--json");
+ Assert.Empty(Strings(Result(formats).GetProperty("withEngines")));
+ var (_, output, _) = await RunWith(catalog, "convert", source, "--to", "pptx", "--json");
+ Hints(FileResultOf(output));
+ }
+ var unsupported = Package("pandoc", false, new ConversionEdge("md", "pptx"));
+ unsupported.Reason = "engine.reason.unsupported_platform";
+ var (_, listing, _) = await RunWith(new([unsupported]), "formats", "md", "--json");
+ Assert.Empty(Strings(Result(listing).GetProperty("withEngines")));
+ var (_, failed, _) = await RunWith(new([unsupported]), "convert", source, "--to", "pptx", "--json");
+ Hints(FileResultOf(failed));
+
+ var bridge = new ControlledConverter("built-in", true, [new("md", "html")]);
+ var catalogWithBridge = new ConverterCatalog([bridge, Package("pandoc", false, new ConversionEdge("html", "pptx"))]);
+ (_, failed, _) = await RunWith(catalogWithBridge, "convert", source, "--to", "pptx", "--json");
+ Hints(FileResultOf(failed), "pandoc");
+ // A cheaper missing non-package alternative must be filtered before choosing the route.
+ await Optional_targets_and_failure_hints_agree();
+ }
+
+ [Fact]
+ public async Task Non_route_failures_do_not_suggest_packages()
+ {
+ var magick = new Filee.Engines.Magick.MagickImageConverter();
+ var catalog = new ConverterCatalog([magick, Package("pandoc", false, new ConversionEdge("png", "jpg"))]);
+ Assert.NotNull(catalog.CreatePlanner().Plan("png", "jpg"));
+ var (_, output, _) = await RunWith(catalog, "convert", Input("png", "not a png"), "--to", "jpg", "--json");
+ Assert.Equal("error.conversion_failed", FileResultOf(output).GetProperty("errorKey").GetString());
+ Assert.False(FileResultOf(output).TryGetProperty("needsEngines", out _));
+ foreach (var (extension, content, key) in new[] {
+ ("png", "", "error.empty_file"), ("unknown", "bytes", "error.unsupported_source") })
+ {
+ (_, output, _) = await RunWith(catalog, "convert", Input(extension, content), "--to", "jpg", "--json");
+ var file = FileResultOf(output);
+ Assert.Equal(key, file.GetProperty("errorKey").GetString());
+ Assert.False(file.TryGetProperty("needsEngines", out _));
+ }
+ foreach (var key in new[] { "error.no_route", "error.needs_shaping", "error.cannot_turn", "" })
+ {
+ var refusal = new ControlledConverter("built-in", true, [new("md", "pptx")])
+ {
+ Convert = (_, _) => throw new ConversionRefusedException(key, "not a route request"),
+ };
+ (_, output, _) = await RunWith(new([refusal]), "convert", Input("md"), "--to", "pptx", "--json");
+ Assert.Equal(key, FileResultOf(output).GetProperty("errorKey").GetString());
+ Assert.False(FileResultOf(output).TryGetProperty("needsEngines", out _));
+ }
+ var unshaped = new ControlledConverter("rhwp", true, [new("md", "pptx", Unshaped: true)]) { NeedsShaping = true };
+ (_, output, _) = await RunWith(new([unshaped]), "convert", Input("md"), "--to", "pptx", "--json");
+ Assert.Equal("error.needs_shaping", FileResultOf(output).GetProperty("errorKey").GetString());
+ Assert.False(FileResultOf(output).TryGetProperty("needsEngines", out _));
+ AddPresets(new Preset { Id = "turn", TargetFormat = "pptx", Image = { Rotation = ImageRotation.Right90 } });
+ (_, output, _) = await RunWith(new([new ControlledConverter("built-in", true, [new("md", "pptx")])]),
+ "convert", Input("md"), "--preset", "turn", "--json");
+ Assert.Equal("error.cannot_turn", FileResultOf(output).GetProperty("errorKey").GetString());
+ Assert.False(FileResultOf(output).TryGetProperty("needsEngines", out _));
+ }
+
+ [Fact]
+ public async Task Cancelled_files_do_not_invent_failure_metadata()
+ {
+ var started = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously);
+ var ended = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously);
+ var converter = new ControlledConverter("built-in", true, [new("md", "html")])
+ {
+ Convert = async (_, token) =>
+ {
+ var cancelled = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously);
+ using var registration = token.Register(() => cancelled.TrySetCanceled(token));
+ started.TrySetResult();
+ try { await cancelled.Task; }
+ finally { ended.TrySetResult(); }
+ return [];
+ },
+ };
+ using var stop = CancellationTokenSource.CreateLinkedTokenSource(TestContext.Current.CancellationToken);
+ var output = new StringWriter();
+ var errors = new StringWriter();
+ var running = Cli.RunAsync(["convert", Input("md"), "--to", "html", "--json"], output, errors, stop.Token,
+ () => ControlledHost(new([converter])));
+ try
+ {
+ await started.Task.WaitAsync(TimeSpan.FromSeconds(10), TestContext.Current.CancellationToken);
+ }
+ finally { stop.Cancel(); }
+ Assert.Equal(1, await running.WaitAsync(TimeSpan.FromSeconds(10), TestContext.Current.CancellationToken));
+ await ended.Task.WaitAsync(TimeSpan.FromSeconds(10), TestContext.Current.CancellationToken);
+ var root = Result(output.ToString());
+ Assert.Equal(1, root.GetProperty("failed").GetInt32());
+ Assert.Equal(0, root.GetProperty("converted").GetInt32());
+ Assert.Equal("", errors.ToString());
+ var file = root.GetProperty("files")[0];
+ Assert.Equal(["source", "state", "outputs", "error"], file.EnumerateObject().Select(p => p.Name));
+ Assert.Equal("cancelled", file.GetProperty("state").GetString());
+ Assert.Equal("conversion failed", file.GetProperty("error").GetString());
+ Assert.Empty(Strings(file.GetProperty("outputs")));
+ Assert.False(file.TryGetProperty("errorKey", out _));
+ Assert.False(file.TryGetProperty("needsEngines", out _));
+ }
+
+ [Fact]
+ public async Task Engine_hints_follow_the_failed_operation()
+ {
+ var mp3 = Input("mp3");
+ var catalog = new ConverterCatalog([Package("ffmpeg", false, new ConversionEdge("mp3", "mp3"))]);
+ var (_, output, _) = await RunWith(catalog, "convert", mp3, "--to", "mp3", "--json");
+ Hints(FileResultOf(output), "ffmpeg");
+ AddPresets(new Preset { Id = "same", TargetFormat = "*" });
+ (_, output, _) = await RunWith(catalog, "convert", mp3, "--preset", "same", "--json");
+ Hints(FileResultOf(output), "ffmpeg");
+ (_, output, _) = await RunWith(catalog, "formats", "mp3", "--json");
+ Assert.DoesNotContain("mp3", Strings(Result(output).GetProperty("withEngines")));
+
+ var cases = new (string Source, Preset Preset, ConversionEdge Edge, string Package)[] {
+ ("mp4", new() { TargetFormat = "png", Media = { SaveEveryFrame = true } }, new("mp4", "png", FrameSequence: true), "ffmpeg"),
+ ("jpg", new() { TargetFormat = "mp4", Media = { ExtractMotionPhoto = true } }, new("jpg", "mp4", MotionPhoto: true), "ffmpeg"),
+ ("mp4", new() { TargetFormat = "jpg", Media = { LivePhoto = LivePhotoKind.Android } }, new("mp4", "jpg", LivePhoto: true), "ffmpeg"),
+ ("png", new() { TargetFormat = "pdf", Pdf = { Ocr = true } }, new("png", "pdf", Ocr: true), "tesseract"),
+ };
+ foreach (var (source, preset, edge, package) in cases)
+ {
+ preset.Id = "special-" + Guid.NewGuid().ToString("N");
+ AddPresets(preset);
+ var specialCatalog = new ConverterCatalog([
+ new ControlledConverter("ordinary", true, [new(edge.From, edge.To)]),
+ Package(package, false, edge),
+ ]);
+ (_, output, _) = await RunWith(specialCatalog, "convert", Input(source), "--preset", preset.Id, "--json");
+ Hints(FileResultOf(output), package);
+ (_, output, _) = await RunWith(specialCatalog, "convert", Input(source), "--to", preset.TargetFormat, "--json");
+ Assert.Equal("done", FileResultOf(output).GetProperty("state").GetString());
+ Assert.False(FileResultOf(output).TryGetProperty("needsEngines", out _));
+ }
+
+ // Intermediate PDF, TIFF and slideshow PNG requests discard final-output-only flags.
+ var intermediateCases = new (Preset Preset, string Target)[] {
+ (new() { TargetFormat = "pdf", Pdf = { MergeIntoSingle = true, Ocr = true } }, "pdf"),
+ (new() { TargetFormat = "tiff", Image = { MultiPageTiff = true }, Media = { SaveEveryFrame = true } }, "tiff"),
+ (new() { TargetFormat = "mp4", Media = { Slideshow = true, ExtractMotionPhoto = true } }, "png"),
+ };
+ foreach (var (preset, target) in intermediateCases)
+ {
+ preset.Id = "intermediate-" + target;
+ AddPresets(preset);
+ var edge = new ConversionEdge("jpg", target, Ocr: preset.Pdf.Ocr);
+ var package = preset.Pdf.Ocr ? "tesseract" : "pandoc";
+ catalog = new([Package(package, false, edge)]);
+ var source = Input("jpg");
+ var second = Path.Combine(_folder, "second.jpg");
+ File.WriteAllText(second, "input");
+ (_, output, _) = await RunWith(catalog, "convert", source, second, "--preset", preset.Id, "--json");
+ Assert.All(Result(output).GetProperty("files").EnumerateArray(), file => Hints(file, package));
+ }
+
+ var imageJoiner = new ControlledConverter("joiner", true, []) { ReadsImages = false };
+ var merge = new Preset { Id = "plain-merge", TargetFormat = "jpg", Image = { JoinIntoOne = true }, Pdf = { Ocr = true } };
+ AddPresets(merge);
+ catalog = new([imageJoiner, Package("pandoc", false, new ConversionEdge("heic", "png")), Package("tesseract", false, new ConversionEdge("heic", "pdf", Ocr: true))]);
+ (_, output, _) = await RunWith(catalog, "convert", Input("heic"), "--preset", merge.Id, "--json");
+ Hints(FileResultOf(output), "pandoc");
+ // The image joiner cannot write the target. An ordinary package route is irrelevant.
+ imageJoiner.ReadsImages = true;
+ catalog = new([imageJoiner, Package("pandoc", false, new ConversionEdge("heic", "jpg"))]);
+ (_, output, _) = await RunWith(catalog, "convert", Input("heic"), "--preset", merge.Id, "--json");
+ Hints(FileResultOf(output));
+ }
+
+ [Fact]
+ public async Task Engine_less_cli_discovery_is_verified()
+ {
+ var packageIds = EngineDownloads.Packages.SelectMany(p => p.ConverterIds).ToHashSet();
+ if (Environment.GetEnvironmentVariable("FILEE_753_VERIFY_NO_ENGINES") == "1")
+ {
+ await using var host = CliHost.Create(_settings);
+ TestContext.Current.TestOutputHelper!.WriteLine($"BaseDirectory={AppContext.BaseDirectory}; Data={host.Store.Directory}; " +
+ $"DownloadRoot={EngineEnvironment.DownloadRoot}; SearchSystem={EngineEnvironment.SearchSystem}; " +
+ $"OwnCopies={string.Join(",", EngineEnvironment.OwnCopies)}; CWD={Environment.CurrentDirectory}");
+ var converters = host.Catalog.All.Where(c => packageIds.Contains(c.Id)).ToArray();
+ Assert.Equal(packageIds.Order(), converters.Select(c => c.Id).Order());
+ foreach (var converter in converters)
+ {
+ var status = host.Catalog.StatusOf(converter);
+ TestContext.Current.TestOutputHelper.WriteLine($"{converter.Id}: available={status.IsAvailable}, reason={status.ReasonKey}, detail={status.Detail}");
+ Assert.False(status.IsAvailable);
+ }
+ }
+ else
+ {
+ var catalog = new ConverterCatalog(EngineDownloads.Packages.Select(p => Package(p.Id, false)));
+ Assert.Equal(packageIds.Order(), catalog.All.Select(c => c.Id).Order());
+ Assert.All(catalog.All, c => Assert.False(catalog.StatusOf(c).IsAvailable));
+ var (code, output, errors) = await RunWith(catalog, "formats", "md", "--json");
+ Assert.Equal(0, code);
+ Assert.Equal("", errors);
+ Assert.Empty(Strings(Result(output).GetProperty("withEngines")));
+ }
+ }
+
+ private sealed class ControlledConverter(string id, bool available, IReadOnlyList<ConversionEdge> edges)
+ : IConverter, ITextShapingCheck, IImageJoiner
+ {
+ public string Id => id;
+ public string DisplayName => id;
+ public int MaxParallelism => 1;
+ public bool Available { get; set; } = available;
+ public string Reason { get; set; } = "engine.reason.not_installed";
+ public IReadOnlyList<ConversionEdge> Edges { get; set; } = edges;
+ public bool NeedsShaping { get; init; }
+ public bool ReadsImages { get; set; }
+ public Func<ConversionStep, CancellationToken, Task<IReadOnlyList<string>>>? Convert { get; set; }
+ public EngineStatus GetStatus() => Available ? EngineStatus.Available() : EngineStatus.Unavailable(Reason);
+ public Task<IReadOnlyList<string>> ConvertAsync(ConversionStep step, IProgress<double>? progress, CancellationToken cancellationToken) =>
+ Convert?.Invoke(step, cancellationToken) ?? Write(step);
+ public static Task<IReadOnlyList<string>> Write(ConversionStep step)
+ {
+ if (step.Output.Allocate(step.To) is not { } path)
+ return Task.FromResult<IReadOnlyList<string>>([]);
+ File.WriteAllText(path, "converted");
+ return Task.FromResult<IReadOnlyList<string>>([path]);
+ }
+ public TextScripts ScanScripts(string sourcePath, string sourceFormat) => new(NeedsShaping ? "Arabic" : null, null);
+ public bool CanRead(string format) => ReadsImages;
+ public bool CanWrite(string format) => false;
+ public Task JoinAsync(IReadOnlyList<(string Path, string Format)> inputs, string outputPath, string format, ImageOptions options,
+ IProgress<double>? progress, CancellationToken cancellationToken) => throw new InvalidOperationException("Unexpected image join");
+ }
+
+ private sealed class UnexpectedMerger : IPdfMerger, ITiffMerger, IMediaJoiner
+ {
+ public Task MergeAsync(IReadOnlyList<string> inputPaths, string outputPath, CancellationToken cancellationToken) =>
+ throw new InvalidOperationException("Unexpected PDF merge");
+ public Task MergeAsync(IReadOnlyList<string> inputPaths, string outputPath, ImageOptions options, CancellationToken cancellationToken) =>
+ throw new InvalidOperationException("Unexpected TIFF merge");
+ public Task JoinAsync(IReadOnlyList<string> inputPaths, string outputPath, string format, Preset preset,
+ string workDirectory, IProgress<double>? progress, CancellationToken cancellationToken) =>
+ throw new InvalidOperationException("Unexpected media join");
+ }
}