@shortlink-org/portolan 0.1.0 → 0.2.0

package/catalog/roundtrip_test.go

@@ -1,185 +0,0 @@
-package catalog
-
-import (
-	"encoding/json"
-	"fmt"
-	"os"
-	"path/filepath"
-	"sort"
-	"testing"
-)
-
-// TestRoundTrip is what holds this package to src/catalog.ts.
-//
-// Every real catalog in the repository is unmarshalled into these structs and
-// marshalled straight back out. Anything the mirror does not know about is
-// dropped on the way in and missing on the way out, so a field added to the
-// TypeScript and forgotten here fails as a named path rather than as a blank
-// section in somebody's generated documentation.
-//
-// The comparison is semantic: key order differs by construction, and an
-// optional list that was written as [] is the same fact as one left out.
-func TestRoundTrip(t *testing.T) {
-	files, err := filepath.Glob("../data/*.json")
-	if err != nil {
-		t.Fatal(err)
-	}
-	if len(files) == 0 {
-		t.Fatal("no catalogs under ../data - this test proves nothing without one")
-	}
-
-	for _, path := range files {
-		t.Run(filepath.Base(path), func(t *testing.T) {
-			raw, err := os.ReadFile(path)
-			if err != nil {
-				t.Fatal(err)
-			}
-
-			var before any
-			if err := json.Unmarshal(raw, &before); err != nil {
-				t.Fatalf("source is not JSON: %v", err)
-			}
-
-			var parsed Catalog
-			if err := json.Unmarshal(raw, &parsed); err != nil {
-				t.Fatalf("catalog does not fit the mirror: %v", err)
-			}
-
-			out, err := json.Marshal(&parsed)
-			if err != nil {
-				t.Fatalf("mirror does not marshal: %v", err)
-			}
-
-			var after any
-			if err := json.Unmarshal(out, &after); err != nil {
-				t.Fatal(err)
-			}
-
-			diffs := compare("catalog", normalize(before), normalize(after))
-			if len(diffs) == 0 {
-				return
-			}
-
-			shown := diffs
-			if len(shown) > 20 {
-				shown = shown[:20]
-			}
-			for _, d := range shown {
-				t.Error(d)
-			}
-			if len(diffs) > len(shown) {
-				t.Errorf("... and %d more", len(diffs)-len(shown))
-			}
-		})
-	}
-}
-
-// normalize drops keys whose value carries no information. An optional list
-// written as [] and one left out entirely say the same thing, and holding the
-// mirror to which of the two it produces would test encoding/json rather than
-// the shape.
-func normalize(v any) any {
-	switch t := v.(type) {
-	case map[string]any:
-		out := make(map[string]any, len(t))
-		for k, item := range t {
-			switch inner := item.(type) {
-			case []any:
-				if len(inner) == 0 {
-					continue
-				}
-			case map[string]any:
-				if len(inner) == 0 {
-					continue
-				}
-			}
-			out[k] = normalize(item)
-		}
-
-		return out
-	case []any:
-		out := make([]any, len(t))
-		for i, item := range t {
-			out[i] = normalize(item)
-		}
-
-		return out
-	default:
-		return v
-	}
-}
-
-// compare walks both trees together and names every place they part, as a path
-// a reader can find in the file.
-func compare(path string, before, after any) []string {
-	switch b := before.(type) {
-	case map[string]any:
-		a, ok := after.(map[string]any)
-		if !ok {
-			return []string{fmt.Sprintf("%s: object in the source, %T after the round trip", path, after)}
-		}
-
-		var diffs []string
-		for _, key := range sortedKeys(b, a) {
-			bv, inSource := b[key]
-			av, inMirror := a[key]
-			switch {
-			case inSource && !inMirror:
-				diffs = append(diffs, fmt.Sprintf("%s.%s: dropped by the mirror (%s)", path, key, brief(bv)))
-			case !inSource && inMirror:
-				diffs = append(diffs, fmt.Sprintf("%s.%s: invented by the mirror (%s)", path, key, brief(av)))
-			default:
-				diffs = append(diffs, compare(path+"."+key, bv, av)...)
-			}
-		}
-
-		return diffs
-	case []any:
-		a, ok := after.([]any)
-		if !ok {
-			return []string{fmt.Sprintf("%s: list in the source, %T after the round trip", path, after)}
-		}
-		if len(b) != len(a) {
-			return []string{fmt.Sprintf("%s: %d entries in the source, %d after the round trip", path, len(b), len(a))}
-		}
-
-		var diffs []string
-		for i := range b {
-			diffs = append(diffs, compare(fmt.Sprintf("%s[%d]", path, i), b[i], a[i])...)
-		}
-
-		return diffs
-	default:
-		if before != after {
-			return []string{fmt.Sprintf("%s: %s became %s", path, brief(before), brief(after))}
-		}
-
-		return nil
-	}
-}
-
-func sortedKeys(maps ...map[string]any) []string {
-	seen := map[string]bool{}
-	for _, m := range maps {
-		for k := range m {
-			seen[k] = true
-		}
-	}
-
-	keys := make([]string, 0, len(seen))
-	for k := range seen {
-		keys = append(keys, k)
-	}
-	sort.Strings(keys)
-
-	return keys
-}
-
-func brief(v any) string {
-	s := fmt.Sprintf("%v", v)
-	if len(s) > 60 {
-		return s[:57] + "..."
-	}
-
-	return s
-}

package/catalog/via_test.go

@@ -1,38 +0,0 @@
-package catalog
-
-import (
-	"encoding/json"
-	"testing"
-)
-
-// TestEdgeViaRoundTrip pins the one field no committed catalog carries: `via`
-// is written by the host after the merge, so the roundtrip over data/*.json
-// never sees it, and the mirror would drop it silently on the way to a
-// generator.
-func TestEdgeViaRoundTrip(t *testing.T) {
-	in := `{"service":"payments.ledger","status":"declared","via":{"flow":"order-accepted","step":"a3"}}`
-
-	var c EventConsumer
-	if err := json.Unmarshal([]byte(in), &c); err != nil {
-		t.Fatal(err)
-	}
-	if c.Via == nil || c.Via.Flow != "order-accepted" || c.Via.Step != "a3" {
-		t.Fatalf("via not read: %+v", c.Via)
-	}
-
-	out, err := json.Marshal(&c)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if string(out) != in {
-		t.Fatalf("round trip changed the consumer:\n got %s\nwant %s", out, in)
-	}
-
-	var call RpcCall
-	if err := json.Unmarshal([]byte(`{"id":"x/Y","peer":"p","status":"declared","source":"s"}`), &call); err != nil {
-		t.Fatal(err)
-	}
-	if call.Via != nil {
-		t.Fatalf("a call without via must round-trip without one: %+v", call.Via)
-	}
-}

package/go.mod

@@ -1,14 +0,0 @@
-module github.com/shortlink-org/portolan
-
-go 1.27.0
-
-require (
-	github.com/pgplex/pgparser v0.2.0
-	golang.org/x/tools v0.49.0
-	gopkg.in/yaml.v3 v3.0.1
-)
-
-require (
-	golang.org/x/mod v0.39.0 // indirect
-	golang.org/x/sync v0.22.0 // indirect
-)

package/go.sum

@@ -1,14 +0,0 @@
-github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=
-github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
-github.com/pgplex/pgparser v0.2.0 h1:BB7I/Mrwetiw07PTq/AlXcKfajlCwoJfwB7KZ7V9irI=
-github.com/pgplex/pgparser v0.2.0/go.mod h1:DWhK7oZJn/16KTFeOQ+mk78+sRnEYya1XPghIoP9NFU=
-golang.org/x/mod v0.39.0 h1:UF5zwQdCRRUpHfyPwr7d4UrGiVeldIsogtzWVnczL74=
-golang.org/x/mod v0.39.0/go.mod h1:bvIbwjQ0HUFFf5AKukeeYQG4ZBUG9yxQbR9aEweIwYY=
-golang.org/x/sync v0.22.0 h1:SZjpbeLmrCk4xhRSZFNZW5gFUeCeFgjekvI/+gfScek=
-golang.org/x/sync v0.22.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
-golang.org/x/tools v0.49.0 h1:3NI7VXzL9+1WZD52Dx2ttoPwD5DWrFGpl9mFZDlmisI=
-golang.org/x/tools v0.49.0/go.mod h1:SJNXV9DBKT0UbdttsQjbfJlAE/q+y36++zo3uL3N0Oo=
-gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
-gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
-gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
-gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

package/internal/commands/cargo.go

@@ -1,154 +0,0 @@
-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

@@ -1,143 +0,0 @@
-// 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, " "))
-}