From 094569412fefa12d81640533342bcd969b120dee Mon Sep 17 00:00:00 2001 From: Alexandre Rodrigues Date: Sat, 14 Nov 2026 21:09:45 -0300 Subject: [PATCH 1/3] Add Markdown output for artifact inspection Render escaped artifact and native-object metadata in Markdown. Preserve the Markdown flag when automatically routing artifacts from the scan command, with the same output-format precedence as other commands. Fixes #180. Signed-off-by: Alexandre Rodrigues --- README.md | 2 + cmd/brief/inspect.go | 10 ++++- cmd/brief/inspect_test.go | 35 +++++++++++++++++ cmd/brief/main.go | 4 +- report/artifact.go | 52 +++++++++++++++++++++++++ report/artifact_test.go | 82 +++++++++++++++++++++++++++++++++++++++ 6 files changed, 181 insertions(+), 4 deletions(-) create mode 100644 report/artifact.go create mode 100644 report/artifact_test.go diff --git a/README.md b/README.md index 4b38d78..65535c8 100644 --- a/README.md +++ b/README.md @@ -129,6 +129,8 @@ Use `--verbose` to include homepage, docs, and repo links for each detected tool brief inspect build/tool brief inspect dist/package.whl brief inspect --json package.gem +brief inspect --markdown dist/package.whl +brief --markdown dist/package.whl ``` Passing a supported local artifact directly selects the same inspection path, so `brief dist/package.whl` works too. Archive inspection rejects more than 100,000 entries or 512 MiB of input or extracted content. diff --git a/cmd/brief/inspect.go b/cmd/brief/inspect.go index fb0e140..585de94 100644 --- a/cmd/brief/inspect.go +++ b/cmd/brief/inspect.go @@ -70,6 +70,7 @@ func cmdInspect(args []string) { fs := flag.NewFlagSet("brief inspect", flag.ExitOnError) jsonFlag := fs.Bool("json", false, "Force JSON output") humanFlag := fs.Bool("human", false, "Force human-readable output") + markdownFlag := fs.Bool("markdown", false, "Force markdown output") _ = fs.Parse(args) if fs.NArg() == 0 { @@ -83,7 +84,9 @@ func cmdInspect(args []string) { os.Exit(1) } - if *jsonFlag || (!*humanFlag && !isTTY()) { + if *markdownFlag { + report.ArtifactMarkdown(os.Stdout, art) + } else if *jsonFlag || (!*humanFlag && !isTTY()) { writeJSONOrExit(report.ArtifactJSON(os.Stdout, art)) } else { report.ArtifactHuman(os.Stdout, art) @@ -818,7 +821,7 @@ func isPEFile(f *os.File, size int64) bool { // inspectAutoArgs builds the argument slice for an auto-routed inspect call // from cmdScan's already-parsed shared flags. -func inspectAutoArgs(jsonFlag, humanFlag bool, path string) []string { +func inspectAutoArgs(jsonFlag, humanFlag, markdownFlag bool, path string) []string { var args []string if jsonFlag { args = append(args, "-json") @@ -826,6 +829,9 @@ func inspectAutoArgs(jsonFlag, humanFlag bool, path string) []string { if humanFlag { args = append(args, "-human") } + if markdownFlag { + args = append(args, "-markdown") + } return append(args, "--", path) } diff --git a/cmd/brief/inspect_test.go b/cmd/brief/inspect_test.go index f861f4e..1cc907a 100644 --- a/cmd/brief/inspect_test.go +++ b/cmd/brief/inspect_test.go @@ -32,6 +32,41 @@ import ( const inspectCondaHelperEnv = "BRIEF_INSPECT_CONDA_HELPER" +func TestInspectMarkdownCommand(t *testing.T) { + const helperEnv = "BRIEF_INSPECT_MARKDOWN_HELPER" + if mode := os.Getenv(helperEnv); mode != "" { + for i, arg := range os.Args { + if arg == "--" { + if mode == "auto" { + cmdScan(os.Args[i+1:]) + } else { + cmdInspect(os.Args[i+1:]) + } + os.Exit(0) + } + } + t.Fatal("missing helper arguments") + } + + path := writeZip(t, map[string]string{"README.txt": "example package\n"}) + for _, mode := range []string{"explicit", "auto"} { + for _, flags := range [][]string{{"--markdown"}, {"--markdown", "--json"}, {"--markdown", "--human"}} { + t.Run(mode+strings.Join(flags, ""), func(t *testing.T) { + args := append([]string{"-test.run=^TestInspectMarkdownCommand$", "--"}, flags...) + cmd := exec.Command(os.Args[0], append(args, path)...) + cmd.Env = append(os.Environ(), helperEnv+"="+mode) + out, err := cmd.CombinedOutput() + if err != nil { + t.Fatalf("inspect failed: %v\n%s", err, out) + } + if !bytes.HasPrefix(out, []byte("# brief ")) || !bytes.Contains(out, []byte("**Format:** zip")) { + t.Fatalf("expected Markdown artifact output, got:\n%s", out) + } + }) + } + } +} + func TestInspectPathBareObject(t *testing.T) { bin := buildHello(t, runtime.GOOS, runtime.GOARCH) diff --git a/cmd/brief/main.go b/cmd/brief/main.go index edc8c5d..437a1b2 100644 --- a/cmd/brief/main.go +++ b/cmd/brief/main.go @@ -99,11 +99,11 @@ func cmdScan(args []string) { // A regular-file argument that sniffs as a native object or archive is // routed to inspect so `brief foo.whl` and `brief foo.so` work without - // the subcommand. Only the shared -json/-human flags carry over; + // the subcommand. Only the shared -json/-human/-markdown flags carry over; // scan-specific flags are dropped rather than passed to a FlagSet that // would reject them. if shouldAutoInspect(path) { - cmdInspect(inspectAutoArgs(*jsonFlag, *humanFlag, path)) + cmdInspect(inspectAutoArgs(*jsonFlag, *humanFlag, *markdownFlag, path)) return } diff --git a/report/artifact.go b/report/artifact.go new file mode 100644 index 0000000..8f640b3 --- /dev/null +++ b/report/artifact.go @@ -0,0 +1,52 @@ +package report + +import ( + "fmt" + "io" + + "github.com/git-pkgs/brief" +) + +// ArtifactMarkdown writes the artifact report in Markdown format. +func ArtifactMarkdown(w io.Writer, a *brief.Artifact) { + text := func(value string) string { return escapeCitationMarkdown(sanitizeLine(value)) } + field := func(label, value string) { + if value != "" { + _, _ = fmt.Fprintf(w, "**%s:** %s\n\n", label, text(value)) + } + } + _, _ = fmt.Fprintf(w, "# brief %s — %s\n\n", text(a.Version), text(a.Path)) + field("Format", a.Format) + field("SHA256", a.SHA256) + _, _ = fmt.Fprintf(w, "**Entries:** %d files, %d native objects\n\n", a.Entries, len(a.NativeObjects)) + + for _, obj := range a.NativeObjects { + _, _ = fmt.Fprintf(w, "## Object: %s\n\n", text(obj.Path)) + field("Format", obj.Format) + field("Architecture", obj.Arch) + field("SOName", obj.SOName) + for _, producer := range obj.Producer { + field("Producer", producer) + } + for _, needed := range obj.Needed { + field("Needed", needed) + } + if obj.Go != nil { + field("Go", obj.Go.Version) + field("Go path", obj.Go.Path) + field("Go main", obj.Go.Main) + for _, dep := range obj.Go.Deps { + field("Go dependency", dep) + } + } + for _, hint := range obj.Static { + label := hint.Library + if hint.Version != "" { + label += " " + hint.Version + } + field("Static (low confidence)", label) + field("Matched text", hint.Match) + } + } + _, _ = fmt.Fprintf(w, "---\n\n%.1fms\n", a.DurationMS) +} diff --git a/report/artifact_test.go b/report/artifact_test.go new file mode 100644 index 0000000..0deca4f --- /dev/null +++ b/report/artifact_test.go @@ -0,0 +1,82 @@ +package report + +import ( + "bytes" + "strings" + "testing" + + "github.com/git-pkgs/brief" + "github.com/git-pkgs/brief/binary" +) + +func TestArtifactMarkdown(t *testing.T) { + art := &brief.Artifact{ + Version: "dev", Path: "package.whl", Format: "zip", SHA256: "abc123", Entries: 3, + DurationMS: 1.25, + NativeObjects: []binary.Object{ + { + Path: "lib/example.so", Format: "elf", Arch: "amd64", SOName: "example.so.1", + Producer: []string{"clang", "rustc"}, Needed: []string{"libc.so.6", "libm.so.6"}, + Go: &binary.GoBuild{ + Version: "go1.27.3", Path: "example.org/tool", Main: "example.org/main v1.0.0", + Deps: []string{"example.org/dep v2.0.0"}, + }, + Static: []binary.Hint{{Library: "zlib", Version: "1.3", Match: "zlib 1.3"}}, + }, + {Path: "bin/tool.exe", Format: "pe", Arch: "arm64"}, + }, + } + var out bytes.Buffer + ArtifactMarkdown(&out, art) + for _, want := range []string{ + "# brief dev — package.whl", "**Format:** zip", "**SHA256:** abc123", + "**Entries:** 3 files, 2 native objects", "## Object: lib/example.so", "**Format:** elf", + "**Architecture:** amd64", "**SOName:** example.so.1", "**Producer:** clang", + "**Producer:** rustc", "**Needed:** libc.so.6", "**Needed:** libm.so.6", + "**Go:** go1.27.3", "**Go path:** example.org/tool", "**Go main:** example.org/main v1.0.0", + "**Go dependency:** example.org/dep v2.0.0", "**Static (low confidence):** zlib 1.3", + "**Matched text:** zlib 1.3", "## Object: bin/tool.exe", "**Format:** pe", + "**Architecture:** arm64", "1.2ms", + } { + if !strings.Contains(out.String(), want) { + t.Errorf("missing %q in Markdown:\n%s", want, out.String()) + } + } +} + +func TestArtifactMarkdownEmpty(t *testing.T) { + var out bytes.Buffer + ArtifactMarkdown(&out, &brief.Artifact{Path: "empty.zip", Format: "zip"}) + if !strings.Contains(out.String(), "0 files, 0 native objects") { + t.Fatalf("missing empty artifact counts: %s", out.String()) + } + for _, unwanted := range []string{"## Object:", "**SHA256:**", "**Go:"} { + if strings.Contains(out.String(), unwanted) { + t.Errorf("unexpected optional field %q: %s", unwanted, out.String()) + } + } +} + +func TestArtifactMarkdownEscapesMetadata(t *testing.T) { + value := "[link](url)|`*_