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_test.go b/report/artifact_test.go new file mode 100644 index 0000000..de304eb --- /dev/null +++ b/report/artifact_test.go @@ -0,0 +1,139 @@ +package report + +import ( + "bytes" + "fmt" + "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", "**Producers:**\n\n- clang\n- rustc", + "**Needed:**\n\n- libc.so.6\n- libm.so.6", + "**Go:** go1.27.3", "**Go path:** example.org/tool", "**Go main:** example.org/main v1.0.0", + "**Go dependencies:**\n\n- 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"}) + for _, unwanted := range []string{"**Entries:**", "## Object:", "**SHA256:**", "**Go:"} { + if strings.Contains(out.String(), unwanted) { + t.Errorf("unexpected optional field %q: %s", unwanted, out.String()) + } + } +} + +func TestArtifactMarkdownBareObject(t *testing.T) { + var out bytes.Buffer + ArtifactMarkdown(&out, &brief.Artifact{ + Path: "build/tool", Format: "elf", + NativeObjects: []binary.Object{{Path: "build/tool", Format: "elf", Arch: "amd64"}}, + }) + if strings.Contains(out.String(), "**Entries:**") { + t.Errorf("bare binary reports archive entries: %s", out.String()) + } + if !strings.Contains(out.String(), "## Object: build/tool") { + t.Errorf("bare binary is missing its object metadata: %s", out.String()) + } +} + +func TestArtifactMarkdownLists(t *testing.T) { + for _, count := range []int{0, 1, maxDisplayItems, maxDisplayItems + 3} { + t.Run(fmt.Sprint(count), func(t *testing.T) { + values := make([]string, count) + for i := range values { + values[i] = fmt.Sprintf("item-%02d", i) + } + var out bytes.Buffer + ArtifactMarkdown(&out, &brief.Artifact{NativeObjects: []binary.Object{{ + Producer: values, Needed: values, Go: &binary.GoBuild{Deps: values}, + }}}) + for _, header := range []string{"Producers", "Needed", "Go dependencies"} { + if got := strings.Contains(out.String(), "**"+header+":**\n\n- item-00"); got != (count > 0) { + t.Errorf("%s list presence = %v for %d values:\n%s", header, got, count, out.String()) + } + } + for i, value := range values { + want := 3 + if i >= maxDisplayItems { + want = 0 + } + if got := strings.Count(out.String(), "- "+value+"\n"); got != want { + t.Errorf("%s occurs %d times, want %d", value, got, want) + } + } + wantTruncated := 0 + if count > maxDisplayItems { + wantTruncated = 3 + } + if got := strings.Count(out.String(), "- ... and 3 more\n"); got != wantTruncated { + t.Errorf("truncation summaries = %d, want %d:\n%s", got, wantTruncated, out.String()) + } + }) + } +} + +func TestArtifactMarkdownEscapesMetadata(t *testing.T) { + value := "[link](url)|`*_