@shortlink-org/portolan 0.1.0

package/internal/commands/justfile.go

@@ -0,0 +1,82 @@
+package commands
+
+import (
+	"regexp"
+	"strings"
+
+	"github.com/shortlink-org/portolan/catalog"
+)
+
+var justRecipe = regexp.MustCompile(`^(@?)([A-Za-z_][A-Za-z0-9_-]*)((?:\s+[+*$]?[A-Za-z_][A-Za-z0-9_-]*(?:=[^\s]+)?)*)\s*:(?:\s|$)`)
+var justDocAttribute = regexp.MustCompile(`\[doc\((['"])(.*?)['"]\)\]`)
+
+// readJustfile lists the recipes of a justfile.
+//
+// A recipe is a name at column 0 followed by its parameters and a colon; the
+// lines indented under it are the body. `#` lines directly over the recipe
+// are its doc, which is what `just --list` shows too, and a `[doc("...")]`
+// attribute beats them. `[private]`, `_`-prefixed and aliased names are left
+// out, as `--list` leaves them out.
+func readJustfile(file, src string) []catalog.Command {
+	lines := strings.Split(src, "\n")
+	var out []catalog.Command
+	for i := 0; i < len(lines); i++ {
+		line := lines[i]
+		match := justRecipe.FindStringSubmatch(line)
+		if match == nil || strings.HasPrefix(line, "alias ") || strings.HasPrefix(line, "set ") || strings.HasPrefix(line, "mod ") || strings.HasPrefix(line, "import ") {
+			continue
+		}
+		name := match[2]
+
+		// Attributes sit on their own lines above the recipe, above the
+		// comment or between it and the recipe; read up through both.
+		private := !typeable(name)
+		doc := ""
+		top := i
+		for j := i - 1; j >= 0; j-- {
+			text := strings.TrimSpace(lines[j])
+			if !strings.HasPrefix(text, "[") {
+				break
+			}
+			if strings.Contains(text, "[private]") {
+				private = true
+			}
+			if m := justDocAttribute.FindStringSubmatch(text); m != nil {
+				doc = m[2]
+			}
+			top = j
+		}
+		if doc == "" {
+			doc = commentAbove(lines, top, "#")
+		}
+		if private {
+			continue
+		}
+
+		var body []string
+		for j := i + 1; j < len(lines); j++ {
+			next := lines[j]
+			if strings.HasPrefix(next, " ") || strings.HasPrefix(next, "\t") {
+				body = append(body, strings.TrimSpace(next))
+
+				continue
+			}
+			if strings.TrimSpace(next) == "" {
+				continue
+			}
+
+			break
+		}
+
+		out = append(out, catalog.Command{
+			Runner: "just",
+			Name:   name,
+			Run:    "just " + name,
+			Doc:    doc,
+			Body:   strings.Join(body, "\n"),
+			Source: at(file, i+1),
+		})
+	}
+
+	return out
+}

package/internal/commands/makefile.go

@@ -0,0 +1,106 @@
+package commands
+
+import (
+	"strings"
+
+	"github.com/shortlink-org/portolan/catalog"
+)
+
+// readMakefile lists the targets of a Makefile a person would type.
+//
+// A target is a line at column 0 with a colon that is not an assignment. Left
+// out: special targets (`.PHONY`), pattern and variable-spelled ones (`%.o`,
+// `$(BIN)`), and the `_`-prefixed ones a Makefile keeps for itself. The
+// description is the `## comment` on the target's own line - the convention
+// every `make help` recipe on the internet greps for - or, failing that, the
+// comment block sat directly over it. The recipe is the body.
+func readMakefile(file, src string) []catalog.Command {
+	lines := strings.Split(src, "\n")
+	var out []catalog.Command
+	for i := 0; i < len(lines); i++ {
+		line := lines[i]
+		names, rest, ok := makeTargets(line)
+		if !ok {
+			continue
+		}
+
+		doc := ""
+		if _, help, found := strings.Cut(rest, "##"); found {
+			doc = strings.TrimSpace(help)
+		} else {
+			doc = commentAbove(lines, i, "#")
+		}
+
+		var recipe []string
+		for j := i + 1; j < len(lines); j++ {
+			next := lines[j]
+			if strings.HasPrefix(next, "\t") {
+				recipe = append(recipe, strings.TrimSpace(strings.TrimPrefix(next, "\t")))
+
+				continue
+			}
+			if strings.TrimSpace(next) == "" || strings.HasPrefix(strings.TrimSpace(next), "#") {
+				continue
+			}
+
+			break
+		}
+		body := strings.Join(recipe, "\n")
+
+		for _, name := range names {
+			if !typeable(name) {
+				continue
+			}
+			out = append(out, catalog.Command{
+				Runner: "make",
+				Name:   name,
+				Run:    "make " + name,
+				Doc:    doc,
+				Body:   body,
+				Source: at(file, i+1),
+			})
+		}
+	}
+
+	return out
+}
+
+// makeTargets reads `a b: deps ## help` into its names and the rest of the
+// line, and refuses anything that is not a rule: assignments, directives,
+// recipes, comments.
+func makeTargets(line string) ([]string, string, bool) {
+	if line == "" || line[0] == '\t' || line[0] == '#' || line[0] == ' ' {
+		return nil, "", false
+	}
+	colon := strings.IndexByte(line, ':')
+	if colon <= 0 {
+		return nil, "", false
+	}
+	head := line[:colon]
+	tail := line[colon+1:]
+	// `X := 1`, `X ::= 1`, and `X = 1` (no colon at all) are assignments.
+	if strings.HasPrefix(tail, "=") || strings.HasPrefix(tail, ":=") || strings.ContainsAny(head, "=#") {
+		return nil, "", false
+	}
+	tail = strings.TrimPrefix(tail, ":")
+	names := strings.Fields(head)
+	if len(names) == 0 {
+		return nil, "", false
+	}
+	for _, name := range names {
+		switch {
+		case strings.HasPrefix(name, "."), strings.ContainsAny(name, "%$()"):
+			return nil, "", false
+		}
+	}
+	switch names[0] {
+	case "ifeq", "ifneq", "ifdef", "ifndef", "else", "endif", "include", "-include", "define", "endef", "export", "unexport", "override", "vpath":
+		return nil, "", false
+	}
+
+	return names, tail, true
+}
+
+func typeable(name string) bool {
+	return name != "" && !strings.HasPrefix(name, "_")
+}

package/internal/commands/maven.go

@@ -0,0 +1,93 @@
+package commands
+
+import (
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+
+	"github.com/shortlink-org/portolan/catalog"
+)
+
+// mavenGoals are the goals a person types, by the plugin that declares them.
+// Maven has no task list of its own: the pom declares plugins, and a plugin's
+// goals are either bound to a lifecycle phase - run by `mvn package`, never
+// typed - or offered to be typed, and only the plugin's documentation says
+// which. This is that documentation, for the plugins an estate meets.
+var mavenGoals = map[string][]struct{ goal, doc string }{
+	"spring-boot-maven-plugin":       {{"spring-boot:run", "Run the application"}},
+	"quarkus-maven-plugin":           {{"quarkus:dev", "Run the application in dev mode, reloading on change"}},
+	"flyway-maven-plugin":            {{"flyway:migrate", "Apply pending migrations"}},
+	"liquibase-maven-plugin":         {{"liquibase:update", "Apply pending changesets"}},
+	"exec-maven-plugin":              {{"exec:java", "Run the main class"}},
+	"jib-maven-plugin":               {{"jib:dockerBuild", "Build the container image into the local Docker daemon"}},
+	"docker-maven-plugin":            {{"docker:build", "Build the container image"}},
+	"openapi-generator-maven-plugin": {{"openapi-generator:generate", "Regenerate code from the OpenAPI document"}},
+}
+
+var pomArtifact = regexp.MustCompile(`<artifactId>\s*([^<\s]+)\s*</artifactId>`)
+
+// readPom lists what a Maven project answers to: the two lifecycle phases
+// every pom accepts, and the goals of the plugins it declares under
+// `<build><plugins>`. The line is typed at the wrapper when the checkout
+// keeps one, because that is the Maven the project was built with.
+func readPom(root, file, src string) []catalog.Command {
+	runner, prefix := "mvn", "mvn "
+	if _, err := os.Stat(filepath.Join(root, "mvnw")); err == nil {
+		runner, prefix = "./mvnw", "./mvnw "
+	}
+
+	lines := strings.Split(src, "\n")
+	self := 1
+	for i, line := range lines {
+		if strings.Contains(line, "<packaging>") {
+			self = i + 1
+
+			break
+		}
+	}
+
+	out := []catalog.Command{
+		{Runner: runner, Name: "test", Run: prefix + "test", Doc: "Run the tests (lifecycle phase)", Source: at(file, self)},
+		{Runner: runner, Name: "package", Run: prefix + "package", Doc: "Build the artifact (lifecycle phase)", Source: at(file, self)},
+	}
+
+	// Only the build's own plugins, not the ones a dependency's pom names
+	// or the ones under <pluginManagement>, which pin a version without
+	// running anything.
+	build := section(src, "build")
+	if build == "" {
+		return out
+	}
+	plugins := section(strings.Replace(build, section(build, "pluginManagement"), "", 1), "plugins")
+	offset := strings.Index(src, plugins)
+	seen := map[string]bool{}
+	for _, m := range pomArtifact.FindAllStringSubmatchIndex(plugins, -1) {
+		artifact := plugins[m[2]:m[3]]
+		goals, known := mavenGoals[artifact]
+		if !known || seen[artifact] {
+			continue
+		}
+		seen[artifact] = true
+		line := 1 + strings.Count(src[:offset+m[2]], "\n")
+		for _, g := range goals {
+			out = append(out, catalog.Command{Runner: runner, Name: g.goal, Run: prefix + g.goal, Doc: g.doc, Source: at(file, line)})
+		}
+	}
+
+	return out
+}
+
+// section is the text of the first `<name>...</name>` element, or "".
+func section(src, name string) string {
+	open := strings.Index(src, "<"+name+">")
+	if open < 0 {
+		return ""
+	}
+	close := strings.Index(src[open:], "</"+name+">")
+	if close < 0 {
+		return ""
+	}
+
+	return src[open : open+close+len(name)+3]
+}

package/internal/commands/packagejson.go

@@ -0,0 +1,159 @@
+package commands
+
+import (
+	"encoding/json"
+	"strings"
+
+	"github.com/shortlink-org/portolan/catalog"
+)
+
+// readPackageJSON lists the scripts of a package manifest, in the order the
+// file lists them, because the author put `build` before `deploy` for a
+// reason and a sorted list would lose it. `pre` and `post` hooks of a listed
+// script are folded into it, the way the runner runs them. The line to type
+// is the runner's: npm keeps `start`, `test`, `stop` and `restart` as
+// commands of their own, and a checkout with a pnpm or yarn lockfile is
+// typed at that tool instead.
+func readPackageJSON(file, src, runner string) ([]catalog.Command, []string) {
+	scripts, lines, err := packageScripts(src)
+	if err != nil {
+		return nil, []string{file + ": " + err.Error()}
+	}
+
+	out := make([]catalog.Command, 0, len(scripts))
+	for _, script := range scripts {
+		out = append(out, catalog.Command{
+			Runner: runner,
+			Name:   script.name,
+			Run:    runLine(runner, script.name),
+			Body:   script.body,
+			Source: at(file, lines[script.name]),
+		})
+	}
+
+	return hooks(out, "pre", "post"), nil
+}
+
+type script struct{ name, body string }
+
+// packageScripts walks the document token by token, which is the one way
+// encoding/json will give back an object's keys in file order.
+func packageScripts(src string) ([]script, map[string]int, error) {
+	dec := json.NewDecoder(strings.NewReader(src))
+	tok, err := dec.Token()
+	if err != nil || tok != json.Delim('{') {
+		return nil, nil, wrap("not a JSON object", err)
+	}
+	for dec.More() {
+		keyTok, err := dec.Token()
+		if err != nil {
+			return nil, nil, wrap("not a JSON object", err)
+		}
+		key, _ := keyTok.(string)
+		if key != "scripts" {
+			var skip json.RawMessage
+			if err := dec.Decode(&skip); err != nil {
+				return nil, nil, wrap("not a JSON object", err)
+			}
+
+			continue
+		}
+
+		offset := int(dec.InputOffset())
+		var raw json.RawMessage
+		if err := dec.Decode(&raw); err != nil {
+			return nil, nil, wrap("scripts could not be read", err)
+		}
+		var byName map[string]string
+		if err := json.Unmarshal(raw, &byName); err != nil {
+			return nil, nil, wrap("scripts is not an object of strings", err)
+		}
+		order := keyOrder(raw)
+		scripts := make([]script, 0, len(order))
+		for _, name := range order {
+			scripts = append(scripts, script{name: name, body: byName[name]})
+		}
+
+		return scripts, keyLines(src, offset, raw), nil
+	}
+
+	return nil, nil, nil
+}
+
+func wrap(what string, err error) error {
+	if err == nil {
+		return errString(what)
+	}
+
+	return errString(what + ": " + err.Error())
+}
+
+type errString string
+
+func (e errString) Error() string { return string(e) }
+
+// keyOrder reads the keys of a JSON object in the order they are written.
+func keyOrder(raw json.RawMessage) []string {
+	dec := json.NewDecoder(strings.NewReader(string(raw)))
+	if tok, err := dec.Token(); err != nil || tok != json.Delim('{') {
+		return nil
+	}
+	var keys []string
+	for dec.More() {
+		tok, err := dec.Token()
+		if err != nil {
+			return keys
+		}
+		if key, ok := tok.(string); ok {
+			keys = append(keys, key)
+		}
+		var skip json.RawMessage
+		if err := dec.Decode(&skip); err != nil {
+			return keys
+		}
+	}
+
+	return keys
+}
+
+// keyLines finds the line each script's key sits on. The decoder says where
+// the `scripts` key ended, the object opens at the next brace, and each key's
+// position inside the object is then a position in the file.
+func keyLines(src string, offset int, raw json.RawMessage) map[string]int {
+	lines := map[string]int{}
+	brace := strings.Index(src[offset:], "{")
+	if brace < 0 {
+		return lines
+	}
+	start := offset + brace
+	object := string(raw)
+	for _, key := range keyOrder(raw) {
+		quoted := `"` + key + `"`
+		at := strings.Index(object, quoted)
+		if at < 0 {
+			continue
+		}
+		lines[key] = 1 + strings.Count(src[:start+at], "\n")
+		// Blank the key so a second script whose name contains this one
+		// (`build` inside `build:watch`) is not found at the first.
+		object = object[:at] + strings.Repeat(" ", len(quoted)) + object[at+len(quoted):]
+	}
+
+	return lines
+}
+
+func runLine(runner, name string) string {
+	switch runner {
+	case "npm":
+		switch name {
+		case "start", "test", "stop", "restart":
+			return "npm " + name
+		}
+
+		return "npm run " + name
+	case "bun":
+		return "bun run " + name
+	}
+
+	return runner + " " + name
+}

package/internal/commands/pyproject.go

@@ -0,0 +1,169 @@
+package commands
+
+import (
+	"regexp"
+	"strings"
+
+	"github.com/shortlink-org/portolan/catalog"
+)
+
+var tomlHeader = regexp.MustCompile(`^\[([^\]]+)\]\s*$`)
+var tomlKey = regexp.MustCompile(`^([A-Za-z0-9_.-]+|"[^"]+")\s*=\s*(.*)$`)
+var tomlString = regexp.MustCompile(`^(?:"((?:[^"\\]|\\.)*)"|'([^']*)')`)
+var tomlInlineField = regexp.MustCompile(`(\w+)\s*=\s*(?:"((?:[^"\\]|\\.)*)"|'([^']*)'|\[([^\]]*)\])`)
+
+// readPyproject lists the tasks of the two task runners that live in
+// pyproject.toml: poe (`[tool.poe.tasks]`) and pdm (`[tool.pdm.scripts]`).
+// Python has no runner of its own, and uv has no task section, so a
+// pyproject without one of these tables declares no commands.
+//
+// The reader is a line scanner, not a TOML parser: it follows table headers
+// and reads `name = "cmd"`, `name = ["cmd", "arg"]`, `name = { cmd = "...",
+// help = "..." }` and `[tool.poe.tasks.name]` subtables. That is the whole of
+// what either runner's documentation shows, and a full parser would be a
+// dependency for the sake of shapes nobody writes.
+func readPyproject(file, src string) []catalog.Command {
+	runners := []struct {
+		table  string
+		runner string
+		run    string
+	}{
+		{"tool.poe.tasks", "poe", "poe "},
+		{"tool.pdm.scripts", "pdm", "pdm run "},
+	}
+
+	lines := strings.Split(src, "\n")
+	var out []catalog.Command
+	for _, r := range runners {
+		var cmds []catalog.Command
+		byName := map[string]int{}
+		upsert := func(cmd catalog.Command) {
+			if i, ok := byName[cmd.Name]; ok {
+				if cmd.Doc != "" {
+					cmds[i].Doc = cmd.Doc
+				}
+				if cmd.Body != "" {
+					cmds[i].Body = cmd.Body
+				}
+
+				return
+			}
+			byName[cmd.Name] = len(cmds)
+			cmds = append(cmds, cmd)
+		}
+
+		table := ""
+		for i, line := range lines {
+			text := strings.TrimSpace(line)
+			if m := tomlHeader.FindStringSubmatch(text); m != nil {
+				table = strings.TrimSpace(m[1])
+
+				continue
+			}
+			if text == "" || strings.HasPrefix(text, "#") {
+				continue
+			}
+			m := tomlKey.FindStringSubmatch(text)
+			if m == nil {
+				continue
+			}
+			key, value := strings.Trim(m[1], `"`), strings.TrimSpace(m[2])
+
+			switch {
+			case table == r.table:
+				// `name = ...` in the tasks table itself.
+				cmd := catalog.Command{Runner: r.runner, Name: key, Run: r.run + key, Source: at(file, i+1)}
+				cmd.Body, cmd.Doc = tomlTask(value)
+				upsert(cmd)
+			case strings.HasPrefix(table, r.table+"."):
+				// `[tool.poe.tasks.name]` and its fields.
+				name := strings.Trim(strings.TrimPrefix(table, r.table+"."), `"`)
+				cmd := catalog.Command{Runner: r.runner, Name: name, Run: r.run + name}
+				if _, known := byName[name]; !known {
+					cmd.Source = at(file, i+1)
+					for j := i - 1; j >= 0; j-- {
+						if tomlHeader.MatchString(strings.TrimSpace(lines[j])) {
+							cmd.Source = at(file, j+1)
+
+							break
+						}
+					}
+				}
+				switch key {
+				case "cmd", "script", "shell", "call", "expr", "ref":
+					cmd.Body = tomlScalar(value)
+				case "sequence", "composite":
+					cmd.Body = strings.Join(tomlList(value), "\n")
+				case "help":
+					cmd.Doc = tomlScalar(value)
+				}
+				upsert(cmd)
+			}
+		}
+		out = append(out, cmds...)
+	}
+
+	return hooks(filterTypeable(out), "pre_", "post_")
+}
+
+func filterTypeable(cmds []catalog.Command) []catalog.Command {
+	kept := cmds[:0]
+	for _, cmd := range cmds {
+		if typeable(cmd.Name) {
+			kept = append(kept, cmd)
+		}
+	}
+
+	return kept
+}
+
+// tomlTask reads the value of a task entry: a string, a list, or an inline
+// table with a cmd and a help.
+func tomlTask(value string) (body, doc string) {
+	switch {
+	case strings.HasPrefix(value, "{"):
+		for _, m := range tomlInlineField.FindAllStringSubmatch(value, -1) {
+			field := m[1]
+			text := unescape(m[2] + m[3])
+			switch field {
+			case "cmd", "script", "shell", "call", "expr", "ref":
+				body = text
+			case "sequence", "composite":
+				body = strings.Join(tomlList("["+m[4]+"]"), "\n")
+			case "help":
+				doc = text
+			}
+		}
+
+		return body, doc
+	case strings.HasPrefix(value, "["):
+		return strings.Join(tomlList(value), " "), ""
+	}
+
+	return tomlScalar(value), ""
+}
+
+func tomlScalar(value string) string {
+	if m := tomlString.FindStringSubmatch(value); m != nil {
+		return unescape(m[1] + m[2])
+	}
+	if strings.HasPrefix(value, `"""`) {
+		return strings.TrimSpace(strings.Trim(value, `"`))
+	}
+
+	return strings.TrimSpace(value)
+}
+
+func tomlList(value string) []string {
+	inner := strings.TrimSuffix(strings.TrimPrefix(strings.TrimSpace(value), "["), "]")
+	var items []string
+	for _, m := range regexp.MustCompile(`"((?:[^"\\]|\\.)*)"|'([^']*)'`).FindAllStringSubmatch(inner, -1) {
+		items = append(items, unescape(m[1]+m[2]))
+	}
+
+	return items
+}
+
+func unescape(s string) string {
+	return strings.NewReplacer(`\"`, `"`, `\\`, `\`, `\n`, "\n", `\t`, "\t").Replace(s)
+}