@shortlink-org/portolan 0.1.0

package/internal/commands/cargo.go

@@ -0,0 +1,154 @@
+package commands
+
+import (
+	"os"
+	"path/filepath"
+	"regexp"
+	"slices"
+	"strings"
+
+	"github.com/shortlink-org/portolan/catalog"
+)
+
+var cargoAliasTable = regexp.MustCompile(`(?m)^\[alias\]\s*$`)
+var xtaskArm = regexp.MustCompile(`(?m)^[ \t]*(?:Some\()?"[a-z][a-z0-9-]*"\)?[ \t]*(?:\|[ \t]*(?:Some\()?"[a-z][a-z0-9-]*"\)?[ \t]*)*=>`)
+var xtaskLiteral = regexp.MustCompile(`"([a-z][a-z0-9-]*)"`)
+var xtaskVariant = regexp.MustCompile(`^[ \t]*([A-Z][A-Za-z0-9]*)\s*(?:\{[^}]*\}|\([^)]*\))?\s*,?\s*$`)
+var xtaskEnum = regexp.MustCompile(`(?s)#\[derive\([^)]*Subcommand[^)]*\)\][^{]*\benum\s+\w+\s*\{(.*?)\n\}`)
+
+// readCargoAliases lists the aliases a checkout gives cargo in
+// `.cargo/config.toml`. An alias is the one place a Cargo project declares a
+// command of its own - `cargo xtask`, `cargo gen` - and its expansion is the
+// body. When an alias runs the `xtask` package, that package's subcommands
+// are listed under it as well, because `cargo xtask` on its own does nothing.
+func readCargoAliases(root, file, src string) []catalog.Command {
+	loc := cargoAliasTable.FindStringIndex(src)
+	if loc == nil {
+		return nil
+	}
+	lines := strings.Split(src, "\n")
+	start := strings.Count(src[:loc[0]], "\n") + 1
+
+	var out []catalog.Command
+	for i := start; i < len(lines); i++ {
+		text := strings.TrimSpace(lines[i])
+		if tomlHeader.MatchString(text) {
+			break
+		}
+		m := tomlKey.FindStringSubmatch(text)
+		if m == nil {
+			continue
+		}
+		name := strings.Trim(m[1], `"`)
+		if !typeable(name) {
+			continue
+		}
+		body, _ := tomlTask(strings.TrimSpace(m[2]))
+		out = append(out, catalog.Command{Runner: "cargo", Name: name, Run: "cargo " + name, Body: body, Source: at(file, i+1)})
+
+		if pkg := runsPackage(body); pkg != "" {
+			out = append(out, readXtask(root, name, pkg)...)
+		}
+	}
+
+	return out
+}
+
+// runsPackage is the package an alias expansion runs, when it is `run
+// --package <name>` or `run -p <name>` - the xtask convention - and the
+// alias leaves the subcommand to the caller. `gen = "run -p xtask -- gen"`
+// names one subcommand already, and is listed as the one command it is.
+func runsPackage(expansion string) string {
+	fields := strings.Fields(expansion)
+	if len(fields) == 0 || fields[0] != "run" {
+		return ""
+	}
+	if i := slices.Index(fields, "--"); i >= 0 && i+1 < len(fields) {
+		return ""
+	}
+	for i, f := range fields {
+		if (f == "--package" || f == "-p") && i+1 < len(fields) {
+			return fields[i+1]
+		}
+		if rest, ok := strings.CutPrefix(f, "--package="); ok {
+			return rest
+		}
+	}
+
+	return ""
+}
+
+// readXtask lists the subcommands of an xtask-style package by reading its
+// main.rs for the two shapes they are written in: a match on the first
+// argument (`"dist" => ...`, `Some("dist") => ...`), and a clap enum
+// deriving Subcommand, whose variants are the commands in kebab-case. A
+// `///` comment over a variant, or its `about`, is the doc.
+func readXtask(root, alias, pkg string) []catalog.Command {
+	for _, candidate := range []string{filepath.Join(pkg, "src", "main.rs"), filepath.Join("xtask", "src", "main.rs")} {
+		raw, err := os.ReadFile(filepath.Join(root, candidate))
+		if err != nil {
+			continue
+		}
+		src := string(raw)
+		file := filepath.ToSlash(filepath.Join(root, candidate))
+		var out []catalog.Command
+		seen := map[string]bool{}
+		add := func(name, doc string, line int) {
+			if seen[name] || !typeable(name) {
+				return
+			}
+			seen[name] = true
+			out = append(out, catalog.Command{Runner: "cargo", Name: alias + " " + name, Run: "cargo " + alias + " " + name, Doc: doc, Source: at(file, line)})
+		}
+
+		if e := xtaskEnum.FindStringSubmatchIndex(src); e != nil {
+			body := src[e[2]:e[3]]
+			lines := strings.Split(body, "\n")
+			base := strings.Count(src[:e[2]], "\n") + 1
+			for i, line := range lines {
+				m := xtaskVariant.FindStringSubmatch(line)
+				if m == nil {
+					continue
+				}
+				doc := commentAbove(lines, i, "///")
+				if doc == "" {
+					if a := regexp.MustCompile(`about\s*=\s*"([^"]*)"`).FindStringSubmatch(strings.Join(lines[max(0, i-3):i], "\n")); a != nil {
+						doc = a[1]
+					}
+				}
+				add(kebab(m[1]), doc, base+i)
+			}
+		}
+		lines := strings.Split(src, "\n")
+		for _, m := range xtaskArm.FindAllStringIndex(src, -1) {
+			// `Some("bench") | Some("perf") =>` is one arm and two names, and
+			// the `//` comment over the arm is what both are for.
+			line := strings.Count(src[:m[0]], "\n")
+			doc := commentAbove(lines, line, "//")
+			for _, literal := range xtaskLiteral.FindAllStringSubmatch(src[m[0]:m[1]], -1) {
+				add(literal[1], doc, line+1)
+			}
+		}
+
+		return out
+	}
+
+	return nil
+}
+
+func kebab(name string) string {
+	var b strings.Builder
+	for i, r := range name {
+		if r >= 'A' && r <= 'Z' {
+			if i > 0 {
+				b.WriteByte('-')
+			}
+			b.WriteRune(r + 'a' - 'A')
+
+			continue
+		}
+		b.WriteRune(r)
+	}
+
+	return b.String()
+}

package/internal/commands/commands.go

@@ -0,0 +1,143 @@
+// Package commands reads what a developer types against a checkout - the make
+// targets, npm scripts, just recipes and task-runner tasks a repository
+// declares - into catalog.Command values.
+//
+// It reads the runner files and nothing else. A README that says "run make
+// test" is a claim; a Makefile with a test target is the fact, and the two
+// drift apart exactly when the README stops being read. Every parser here is
+// deliberately shallow: it knows the file well enough to list its entries and
+// their descriptions, and it does not evaluate anything. A make target hidden
+// behind an `ifeq` is listed; a target spelled through a variable is not,
+// because the name it would have depends on a value nobody here can know.
+package commands
+
+import (
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+
+	"github.com/shortlink-org/portolan/catalog"
+)
+
+// Read lists the commands declared at root, in a fixed order of files - make,
+// just, Taskfile, the package manifest, pyproject, pom, the Gradle script,
+// cargo's aliases - and in file order inside each. Source is spelled root-relative with the line, the way the rest of the
+// catalog spells one.
+//
+// Warnings name what was seen and not read: a Taskfile that is not YAML, a
+// package.json whose scripts are not an object.
+func Read(root string) ([]catalog.Command, []string) {
+	var out []catalog.Command
+	var warnings []string
+
+	add := func(cmds []catalog.Command, warns []string) {
+		out = append(out, cmds...)
+		warnings = append(warnings, warns...)
+	}
+
+	if file, src, ok := first(root, "Makefile", "makefile", "GNUmakefile"); ok {
+		add(readMakefile(file, src), nil)
+	}
+	if file, src, ok := first(root, "justfile", "Justfile", ".justfile"); ok {
+		add(readJustfile(file, src), nil)
+	}
+	if file, src, ok := first(root, "Taskfile.yml", "Taskfile.yaml", "taskfile.yml", "taskfile.yaml", "Taskfile.dist.yml", "Taskfile.dist.yaml"); ok {
+		add(readTaskfile(file, src))
+	}
+	if file, src, ok := first(root, "package.json"); ok {
+		add(readPackageJSON(file, src, nodeRunner(root)))
+	}
+	if file, src, ok := first(root, "pyproject.toml"); ok {
+		add(readPyproject(file, src), nil)
+	}
+	if file, src, ok := first(root, "pom.xml"); ok {
+		add(readPom(root, file, src), nil)
+	}
+	if file, src, ok := first(root, "build.gradle.kts", "build.gradle"); ok {
+		add(readGradle(root, file, src), nil)
+	}
+	if file, src, ok := first(root, ".cargo/config.toml", ".cargo/config"); ok {
+		add(readCargoAliases(root, file, src), nil)
+	}
+
+	return out, warnings
+}
+
+// first opens the first of names that exists under root, answering its
+// root-relative path and contents.
+func first(root string, names ...string) (string, string, bool) {
+	for _, name := range names {
+		raw, err := os.ReadFile(filepath.Join(root, name))
+		if err != nil {
+			continue
+		}
+
+		return filepath.ToSlash(filepath.Join(root, name)), string(raw), true
+	}
+
+	return "", "", false
+}
+
+// nodeRunner is the package manager a checkout is set up for, read off the
+// lockfile it keeps - the one file that says which tool the last person used.
+func nodeRunner(root string) string {
+	for _, lock := range []struct{ file, runner string }{
+		{"pnpm-lock.yaml", "pnpm"},
+		{"yarn.lock", "yarn"},
+		{"bun.lockb", "bun"},
+		{"bun.lock", "bun"},
+	} {
+		if _, err := os.Stat(filepath.Join(root, lock.file)); err == nil {
+			return lock.runner
+		}
+	}
+
+	return "npm"
+}
+
+func at(file string, line int) string {
+	return file + ":" + strconv.Itoa(line)
+}
+
+// hooks drops the pre/post entries of a name that is itself listed, the way
+// npm and pdm run them: `pretest` is part of `test`, not a second command.
+func hooks(cmds []catalog.Command, prefixes ...string) []catalog.Command {
+	named := map[string]bool{}
+	for _, cmd := range cmds {
+		named[cmd.Name] = true
+	}
+	kept := cmds[:0]
+	for _, cmd := range cmds {
+		hook := false
+		for _, prefix := range prefixes {
+			if rest, ok := strings.CutPrefix(cmd.Name, prefix); ok && rest != "" && named[rest] {
+				hook = true
+			}
+		}
+		if !hook {
+			kept = append(kept, cmd)
+		}
+	}
+
+	return kept
+}
+
+// commentAbove is the contiguous block of `#` lines ending at line i-1, as one
+// paragraph, or "" when the line above is not a comment. A blank line breaks
+// the block: a comment two lines up is about something else.
+func commentAbove(lines []string, i int, marker string) string {
+	var block []string
+	for j := i - 1; j >= 0; j-- {
+		text := strings.TrimSpace(lines[j])
+		if !strings.HasPrefix(text, marker) {
+			break
+		}
+		text = strings.TrimSpace(strings.TrimPrefix(text, marker))
+		// A `## help` line in a block is help; a `##` divider is not a word.
+		text = strings.TrimSpace(strings.TrimLeft(text, "#"))
+		block = append([]string{text}, block...)
+	}
+
+	return strings.TrimSpace(strings.Join(block, " "))
+}

package/internal/commands/commands_test.go

@@ -0,0 +1,323 @@
+package commands
+
+import (
+	"encoding/json"
+	"flag"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/shortlink-org/portolan/catalog"
+)
+
+var update = flag.Bool("update", false, "rewrite the golden list instead of comparing against it")
+
+const goldenPath = "testdata/golden/commands.json"
+
+func read(t *testing.T) []catalog.Command {
+	t.Helper()
+	cmds, warnings := Read("testdata/estate")
+	if len(warnings) != 0 {
+		t.Fatalf("warnings: %v", warnings)
+	}
+
+	return cmds
+}
+
+func find(t *testing.T, cmds []catalog.Command, run string) catalog.Command {
+	t.Helper()
+	for _, cmd := range cmds {
+		if cmd.Run == run {
+			return cmd
+		}
+	}
+	t.Fatalf("no command %q in %s", run, names(cmds))
+
+	return catalog.Command{}
+}
+
+func names(cmds []catalog.Command) string {
+	out := make([]string, 0, len(cmds))
+	for _, cmd := range cmds {
+		out = append(out, cmd.Run)
+	}
+
+	return strings.Join(out, ", ")
+}
+
+func absent(t *testing.T, cmds []catalog.Command, run string) {
+	t.Helper()
+	for _, cmd := range cmds {
+		if cmd.Run == run {
+			t.Errorf("%q is listed and should not be", run)
+		}
+	}
+}
+
+func TestMakefileTargetsAndDocs(t *testing.T) {
+	cmds := read(t)
+
+	gen := find(t, cmds, "make gen")
+	if gen.Doc != "Regenerate the gRPC stubs" {
+		t.Errorf("gen doc = %q", gen.Doc)
+	}
+	if !strings.HasPrefix(gen.Body, "buf generate $(GRPC)/quote/proto") || strings.Count(gen.Body, "\n") != 1 {
+		t.Errorf("gen body = %q", gen.Body)
+	}
+	if gen.Source != "testdata/estate/Makefile:10" {
+		t.Errorf("gen source = %q", gen.Source)
+	}
+
+	build := find(t, cmds, "make build")
+	if build.Doc != "Compiles every package. Nothing is installed." {
+		t.Errorf("comment over a target is its doc; got %q", build.Doc)
+	}
+
+	// Two targets on one rule are two commands.
+	find(t, cmds, "make test")
+	find(t, cmds, "make lint")
+	// Inside a conditional is still a target.
+	find(t, cmds, "make ci")
+
+	for _, hidden := range []string{"make .PHONY", "make _internal", "make $(BIN)", "make %.pb.go", "make GRPC", "make BIN", "make ifeq"} {
+		absent(t, cmds, hidden)
+	}
+}
+
+func TestJustfileRecipes(t *testing.T) {
+	cmds := read(t)
+
+	dev := find(t, cmds, "just dev")
+	if dev.Doc != "Run the service against the compose stack" || dev.Body != "docker compose up -d\ncargo run" {
+		t.Errorf("dev = %+v", dev)
+	}
+	test := find(t, cmds, "just test")
+	if test.Doc != "Run the tests, unit and integration" {
+		t.Errorf("doc attribute beats the comment; got %q", test.Doc)
+	}
+	for _, hidden := range []string{"just release", "just _setup", "just alias", "just set", "just port"} {
+		absent(t, cmds, hidden)
+	}
+}
+
+func TestTaskfileTasks(t *testing.T) {
+	cmds := read(t)
+
+	build := find(t, cmds, "task build")
+	if build.Doc != "Compile the binary" || build.Body != "go build -o bin/svc ./cmd/svc" {
+		t.Errorf("build = %+v", build)
+	}
+	if migrate := find(t, cmds, "task migrate"); migrate.Doc != "Apply pending migrations" || migrate.Body != "goose up" {
+		t.Errorf("migrate = %+v", migrate)
+	}
+	if def := find(t, cmds, "task default"); def.Body != "task build" {
+		t.Errorf("default = %+v", def)
+	}
+	if fmt := find(t, cmds, "task fmt"); fmt.Body != "gofmt -w ." {
+		t.Errorf("fmt = %+v", fmt)
+	}
+	absent(t, cmds, "task lint")
+	absent(t, cmds, "task _shared")
+}
+
+func TestPackageScriptsInFileOrder(t *testing.T) {
+	cmds := read(t)
+
+	var npm []string
+	for _, cmd := range cmds {
+		if cmd.Runner == "npm" {
+			npm = append(npm, cmd.Run)
+		}
+	}
+	want := "npm run build, npm start, npm test, npm run build:watch, npm run generate, npm run generate:api"
+	if got := strings.Join(npm, ", "); got != want {
+		t.Errorf("scripts = %s\n     want %s", got, want)
+	}
+	if build := find(t, cmds, "npm run build"); build.Body != "tsc -p tsconfig.build.json" || build.Source != "testdata/estate/package.json:4" {
+		t.Errorf("build = %+v", build)
+	}
+	if watch := find(t, cmds, "npm run build:watch"); watch.Source != "testdata/estate/package.json:8" {
+		t.Errorf("a name containing another name has its own line; got %q", watch.Source)
+	}
+}
+
+func TestPackageRunnerFollowsTheLockfile(t *testing.T) {
+	root := t.TempDir()
+	if err := os.WriteFile(filepath.Join(root, "package.json"), []byte(`{"scripts":{"test":"vitest"}}`), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(root, "pnpm-lock.yaml"), nil, 0o644); err != nil {
+		t.Fatal(err)
+	}
+	cmds, _ := Read(root)
+	if len(cmds) != 1 || cmds[0].Run != "pnpm test" || cmds[0].Runner != "pnpm" {
+		t.Errorf("commands = %+v", cmds)
+	}
+}
+
+func TestPyprojectTasks(t *testing.T) {
+	cmds := read(t)
+
+	if test := find(t, cmds, "poe test"); test.Body != "pytest" {
+		t.Errorf("test = %+v", test)
+	}
+	if lint := find(t, cmds, "poe lint"); lint.Body != "ruff check ." {
+		t.Errorf("lint = %+v", lint)
+	}
+	if serve := find(t, cmds, "poe serve"); serve.Doc != "Run the dev server" || serve.Body != "python manage.py runserver" {
+		t.Errorf("serve = %+v", serve)
+	}
+	migrate := find(t, cmds, "poe migrate")
+	if migrate.Doc != "Apply pending migrations" || migrate.Body != "python manage.py migrate" || migrate.Source != "testdata/estate/pyproject.toml:14" {
+		t.Errorf("migrate = %+v", migrate)
+	}
+	if check := find(t, cmds, "poe check"); check.Body != "lint\ntest" {
+		t.Errorf("check = %+v", check)
+	}
+	if worker := find(t, cmds, "pdm run worker"); worker.Doc != "Run the celery worker" || worker.Body != "celery -A billing worker" {
+		t.Errorf("worker = %+v", worker)
+	}
+	find(t, cmds, "pdm run test")
+	absent(t, cmds, "pdm run pre_test")
+	absent(t, cmds, "poe _hidden")
+	// Entry points are programs the package installs, not tasks.
+	absent(t, cmds, "poe billing")
+}
+
+func TestPomPhasesAndPluginGoals(t *testing.T) {
+	cmds := read(t)
+
+	if test := find(t, cmds, "mvn test"); test.Source != "testdata/estate/pom.xml:5" || test.Doc == "" {
+		t.Errorf("test = %+v", test)
+	}
+	find(t, cmds, "mvn package")
+	if run := find(t, cmds, "mvn spring-boot:run"); run.Doc != "Run the application" || run.Source != "testdata/estate/pom.xml:22" {
+		t.Errorf("spring-boot:run = %+v", run)
+	}
+	// A plugin bound to a phase is run by the phase, not typed; a plugin
+	// under pluginManagement or in dependencies is not part of the build.
+	for _, hidden := range []string{"mvn protobuf:compile", "mvn jib:dockerBuild", "mvn flyway:migrate"} {
+		absent(t, cmds, hidden)
+	}
+}
+
+func TestPomIsTypedAtTheWrapper(t *testing.T) {
+	root := t.TempDir()
+	if err := os.WriteFile(filepath.Join(root, "pom.xml"), []byte("<project><packaging>jar</packaging></project>"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(root, "mvnw"), []byte("#!/bin/sh\n"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	cmds, _ := Read(root)
+	if len(cmds) != 2 || cmds[0].Run != "./mvnw test" || cmds[0].Runner != "./mvnw" {
+		t.Errorf("commands = %+v", cmds)
+	}
+}
+
+func TestGradleTasks(t *testing.T) {
+	cmds := read(t)
+
+	find(t, cmds, "gradle build")
+	find(t, cmds, "gradle test")
+	if run := find(t, cmds, "gradle run"); run.Source != "testdata/estate/build.gradle.kts:3" {
+		t.Errorf("run = %+v", run)
+	}
+	if boot := find(t, cmds, "gradle bootRun"); boot.Source != "testdata/estate/build.gradle.kts:2" {
+		t.Errorf("bootRun = %+v", boot)
+	}
+	if gen := find(t, cmds, "gradle generateProto"); gen.Doc != "Regenerate the gRPC stubs" || gen.Source != "testdata/estate/build.gradle.kts:6" {
+		t.Errorf("generateProto = %+v", gen)
+	}
+	if smoke := find(t, cmds, "gradle smokeTest"); smoke.Doc != "Run the tests that need the compose stack" {
+		t.Errorf("smokeTest = %+v", smoke)
+	}
+	find(t, cmds, "gradle legacyTask")
+	absent(t, cmds, "gradle _shared")
+}
+
+func TestCargoAliasesAndXtask(t *testing.T) {
+	cmds := read(t)
+
+	if xtask := find(t, cmds, "cargo xtask"); xtask.Body != "run --package xtask --" || xtask.Source != "testdata/estate/.cargo/config.toml:5" {
+		t.Errorf("xtask = %+v", xtask)
+	}
+	if gen := find(t, cmds, "cargo gen"); gen.Body != "run --package xtask -- gen" {
+		t.Errorf("gen = %+v", gen)
+	}
+	absent(t, cmds, "cargo _secret")
+
+	if gen := find(t, cmds, "cargo xtask gen"); gen.Doc != "Regenerate the gRPC stubs from the vendored protos" || gen.Source != "testdata/estate/xtask/src/main.rs:12" {
+		t.Errorf("xtask gen = %+v", gen)
+	}
+	if ci := find(t, cmds, "cargo xtask ci"); ci.Doc != "Run fmt, clippy and the tests the way CI does" {
+		t.Errorf("xtask ci = %+v", ci)
+	}
+	if dist := find(t, cmds, "cargo xtask dist"); dist.Doc != "Build the release artefacts" {
+		t.Errorf("xtask dist = %+v", dist)
+	}
+	// Match arms add what the enum does not name, once each.
+	if bench := find(t, cmds, "cargo xtask bench"); bench.Doc != "Run the benchmarks against the compose stack" {
+		t.Errorf("bench = %+v", bench)
+	}
+	if perf := find(t, cmds, "cargo xtask perf"); perf.Doc != "Run the benchmarks against the compose stack" {
+		t.Errorf("perf = %+v", perf)
+	}
+	count := 0
+	for _, cmd := range cmds {
+		if cmd.Run == "cargo xtask gen" {
+			count++
+		}
+	}
+	if count != 1 {
+		t.Errorf("cargo xtask gen listed %d times", count)
+	}
+}
+
+func TestNothingToReadIsNothing(t *testing.T) {
+	cmds, warnings := Read(t.TempDir())
+	if len(cmds) != 0 || len(warnings) != 0 {
+		t.Errorf("commands = %+v, warnings = %v", cmds, warnings)
+	}
+}
+
+func TestBrokenFilesWarnRatherThanFail(t *testing.T) {
+	root := t.TempDir()
+	if err := os.WriteFile(filepath.Join(root, "Taskfile.yml"), []byte("tasks: [\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(root, "package.json"), []byte(`{"scripts": "nope"}`), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	cmds, warnings := Read(root)
+	if len(cmds) != 0 || len(warnings) != 2 {
+		t.Errorf("commands = %+v, warnings = %v", cmds, warnings)
+	}
+}
+
+func TestGolden(t *testing.T) {
+	cmds := read(t)
+	got, err := json.MarshalIndent(cmds, "", "  ")
+	if err != nil {
+		t.Fatal(err)
+	}
+	got = append(got, '\n')
+	if *update {
+		if err := os.MkdirAll(filepath.Dir(goldenPath), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(goldenPath, got, 0o644); err != nil {
+			t.Fatal(err)
+		}
+
+		return
+	}
+	want, err := os.ReadFile(goldenPath)
+	if err != nil {
+		t.Fatalf("%v (run with -update to write it)", err)
+	}
+	if string(want) != string(got) {
+		t.Errorf("golden differs from what is read now; run with -update and review the diff\n%s", got)
+	}
+}

package/internal/commands/gradle.go

@@ -0,0 +1,77 @@
+package commands
+
+import (
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+
+	"github.com/shortlink-org/portolan/catalog"
+)
+
+var gradleRegister = regexp.MustCompile(`(?m)^[ \t]*(?:tasks\.register(?:<[^>]+>)?\(\s*["']([A-Za-z][\w-]*)["']|task\s+([A-Za-z][\w-]*)\s*[({]|val\s+([A-Za-z][\w-]*)\s+by\s+tasks\.(?:registering|creating))`)
+var gradleDescription = regexp.MustCompile(`description\s*(?:=|\.set\()\s*["']([^"']*)["']`)
+var gradlePlugin = regexp.MustCompile(`(?m)^[ \t]*(?:id\s*\(?\s*["']([\w.-]+)["']\)?|apply\s+plugin:\s*["']([\w.-]+)["']|\b(application|java|java-library|kotlin)\b\s*$)`)
+
+// readGradle lists what a Gradle build answers to: `build` and `test`, which
+// every JVM build has; `run` when the application plugin is applied and
+// `bootRun` for Spring Boot; and the tasks the script registers itself, with
+// the description it sets on them. The line is typed at the wrapper when the
+// checkout keeps one.
+//
+// A build script is a program, and this reads it as text: a task registered
+// inside a loop or by a plugin the script does not name is not here.
+func readGradle(root, file, src string) []catalog.Command {
+	runner, prefix := "gradle", "gradle "
+	if _, err := os.Stat(filepath.Join(root, "gradlew")); err == nil {
+		runner, prefix = "./gradlew", "./gradlew "
+	}
+
+	out := []catalog.Command{
+		{Runner: runner, Name: "build", Run: prefix + "build", Doc: "Assemble and test the project", Source: file},
+		{Runner: runner, Name: "test", Run: prefix + "test", Doc: "Run the tests", Source: file},
+	}
+
+	plugins := map[string]int{}
+	for _, m := range gradlePlugin.FindAllStringSubmatchIndex(src, -1) {
+		for _, group := range [][2]int{{m[2], m[3]}, {m[4], m[5]}, {m[6], m[7]}} {
+			if group[0] >= 0 {
+				plugins[src[group[0]:group[1]]] = 1 + strings.Count(src[:group[0]], "\n")
+			}
+		}
+	}
+	if line, ok := plugins["application"]; ok {
+		out = append(out, catalog.Command{Runner: runner, Name: "run", Run: prefix + "run", Doc: "Run the application", Source: at(file, line)})
+	}
+	if line, ok := plugins["org.springframework.boot"]; ok {
+		out = append(out, catalog.Command{Runner: runner, Name: "bootRun", Run: prefix + "bootRun", Doc: "Run the Spring Boot application", Source: at(file, line)})
+	}
+
+	matches := gradleRegister.FindAllStringSubmatchIndex(src, -1)
+	for i, m := range matches {
+		name := ""
+		for _, group := range [][2]int{{m[2], m[3]}, {m[4], m[5]}, {m[6], m[7]}} {
+			if group[0] >= 0 {
+				name = src[group[0]:group[1]]
+			}
+		}
+		if !typeable(name) {
+			continue
+		}
+		// The description is read from the task's own block: from its
+		// registration up to the next one. A script that sets one task's
+		// description after registering the next is read wrong, and that
+		// is the price of not running Gradle.
+		end := len(src)
+		if i+1 < len(matches) {
+			end = matches[i+1][0]
+		}
+		doc := ""
+		if d := gradleDescription.FindStringSubmatch(src[m[0]:end]); d != nil {
+			doc = d[1]
+		}
+		out = append(out, catalog.Command{Runner: runner, Name: name, Run: prefix + name, Doc: doc, Source: at(file, 1+strings.Count(src[:m[0]], "\n"))})
+	}
+
+	return out
+}