@shortlink-org/portolan 0.1.0

package/plugins/extract-adr/describe.go

@@ -0,0 +1,19 @@
+package main
+
+import (
+	_ "embed"
+
+	"github.com/shortlink-org/portolan/plugin"
+)
+
+//go:embed options.schema.json
+var optionsSchema []byte
+
+func descriptor() plugin.Descriptor {
+	return plugin.Descriptor{
+		Name:    "extract-adr",
+		Summary: "Reads decision records written by hand - MADR markdown with a title, meta bullets and the record itself, or the numbered records adr-tools writes - into a catalog fragment.",
+		Phases:  []string{plugin.PhaseExtract},
+		Options: optionsSchema,
+	}
+}

package/plugins/extract-adr/describe_test.go

@@ -0,0 +1,11 @@
+package main
+
+import (
+	"testing"
+
+	"github.com/shortlink-org/portolan/plugin/schematest"
+)
+
+func TestOptionsSchemaMatchesStruct(t *testing.T) {
+	schematest.Check(t, optionsSchema, Options{})
+}

package/plugins/extract-adr/extract.go

@@ -0,0 +1,153 @@
+package main
+
+import (
+	"encoding/json"
+	"errors"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+
+	"github.com/shortlink-org/portolan/catalog"
+	"github.com/shortlink-org/portolan/plugin"
+)
+
+// extract reads every record the options name and answers with one fragment
+// holding them.
+//
+// A file that does not parse, or that declares a record another file already
+// declared, is left out of the fragment with a warning that names it and the
+// line, and the rest of the tree is read: one record written differently is
+// not a reason to document nothing. What is refused whole is a supersession
+// with only one half recorded, because `src/catalog.ts` refuses to load a
+// catalog that says it, and either record alone would say something untrue.
+func extract(in plugin.Input, opts Options) (plugin.Response, error) {
+	b := &plugin.Builder{}
+
+	patterns := opts.Files
+	if len(patterns) == 0 {
+		patterns = []string{"docs/adr/*.md"}
+	}
+	var files []string
+	seen := map[string]bool{}
+	for _, pattern := range patterns {
+		matches, err := filepath.Glob(filepath.Join(in.Root, pattern))
+		if err != nil {
+			return plugin.Response{}, err
+		}
+		for _, match := range matches {
+			// A README in a directory of records is its index - written by
+			// hand or generated elsewhere - and is not itself a decision.
+			if strings.EqualFold(filepath.Base(match), "README.md") {
+				continue
+			}
+			if !seen[match] {
+				seen[match] = true
+				files = append(files, match)
+			}
+		}
+	}
+	sort.Strings(files)
+	if len(files) == 0 {
+		b.Warn(in.Root, "no decision records matched "+strings.Join(patterns, ", ")+"; the fragment holds none")
+	}
+
+	history := newHistory(in.Root, opts.History, b)
+
+	adrs := []catalog.Adr{}
+	ids := map[string]string{}
+	slugs := map[string]string{}
+	for _, file := range files {
+		src, err := os.ReadFile(file)
+		if err != nil {
+			return plugin.Response{}, err
+		}
+		rel := filepath.ToSlash(file)
+		adr, errs := parseAdr(rel, string(src), defaults{Scope: opts.Scope})
+		if len(errs) > 0 {
+			b.Warn(rel, "left out of the fragment: "+strings.Join(errs, "; "))
+
+			continue
+		}
+		if other, taken := ids[adr.ID]; taken {
+			b.Warn(rel, "left out of the fragment: "+adr.ID+" is already declared in "+other)
+
+			continue
+		}
+		if other, taken := slugs[adr.Slug]; taken {
+			b.Warn(rel, "left out of the fragment: the slug "+adr.Slug+" is already taken by "+other)
+
+			continue
+		}
+		ids[adr.ID] = rel
+		slugs[adr.Slug] = rel
+		adr.Created, adr.Revised = history.of(file)
+		adrs = append(adrs, adr)
+	}
+	if problems := supersessions(adrs, ids); len(problems) > 0 {
+		return plugin.Response{}, errors.New(strings.Join(problems, "\n"))
+	}
+
+	fragment := catalog.Catalog{
+		GeneratedAt: in.GeneratedAt,
+		Commit:      in.Commit,
+		Contexts:    []catalog.BoundedContext{},
+		Defs:        map[string]catalog.TypeDef{},
+		Flows:       []catalog.Flow{},
+		Adrs:        adrs,
+	}
+	encoded, err := json.MarshalIndent(fragment, "", "  ")
+	if err != nil {
+		return plugin.Response{}, err
+	}
+	out := opts.Out
+	if out == "" {
+		out = "adr.json"
+	}
+	b.File(out, string(encoded)+"\n")
+
+	return b.Response(), nil
+}
+
+// supersessions holds the two halves of a supersession against each other.
+//
+// Only the halves that are both here can be checked: a record superseded by
+// one in another service's tree is a claim this step has no way to look up,
+// and the validator, which sees the merged catalog, reports that one. What
+// this catches is the common case - a record superseded by its neighbour,
+// with only one of the two files edited.
+func supersessions(adrs []catalog.Adr, ids map[string]string) []string {
+	var problems []string
+
+	by := map[string]*catalog.Adr{}
+	for i := range adrs {
+		by[adrs[i].ID] = &adrs[i]
+	}
+	names := func(list []string, id string) bool {
+		for _, entry := range list {
+			if entry == id {
+				return true
+			}
+		}
+
+		return false
+	}
+
+	for i := range adrs {
+		adr := &adrs[i]
+		where := ids[adr.ID] + ": "
+		if successor, here := by[adr.SupersededBy]; here && !names(successor.Supersedes, adr.ID) {
+			problems = append(problems, where+adr.ID+" is superseded by "+successor.ID+", which does not say it supersedes it")
+		}
+		for _, id := range adr.Supersedes {
+			if predecessor, here := by[id]; here && predecessor.SupersededBy != adr.ID {
+				problems = append(problems, where+adr.ID+" supersedes "+id+", which is not marked superseded by it")
+			}
+		}
+		if adr.SupersededBy == adr.ID {
+			problems = append(problems, where+adr.ID+" supersedes itself")
+		}
+	}
+
+	return problems
+}

package/plugins/extract-adr/extract_test.go

@@ -0,0 +1,350 @@
+package main
+
+// The mapping: records in a tree, a catalog fragment out.
+//
+// Shaped like plugins/extract-proto/extract_test.go, which is the house style
+// for an extractor test - one behaviour per test, and a whole-fragment golden
+// underneath so an unintended field change is a diff rather than an assertion
+// nobody thought to write.
+
+import (
+	"encoding/json"
+	"flag"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"testing"
+
+	"github.com/shortlink-org/portolan/catalog"
+	"github.com/shortlink-org/portolan/plugin"
+)
+
+var update = flag.Bool("update", false, "rewrite the golden fragment instead of comparing against it")
+
+const goldenPath = "testdata/golden/adr.json"
+
+func input(root string) plugin.Input {
+	// The stamp comes from the host, which derives it from git. A plugin that
+	// read a clock would write a different file every run.
+	return plugin.Input{
+		Root:        root,
+		Commit:      "abc1234",
+		GeneratedAt: "2024-01-01T00:00:00Z",
+	}
+}
+
+func response(t *testing.T) plugin.Response {
+	t.Helper()
+
+	resp, err := extract(input("testdata/estate"), Options{History: "none"})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	return resp
+}
+
+func fragment(t *testing.T) catalog.Catalog {
+	t.Helper()
+
+	var cat catalog.Catalog
+	if err := json.Unmarshal([]byte(response(t).Files[0].Contents), &cat); err != nil {
+		t.Fatal(err)
+	}
+
+	return cat
+}
+
+func TestEveryRecordInTheTreeIsRead(t *testing.T) {
+	var ids []string
+	for _, adr := range fragment(t).Adrs {
+		ids = append(ids, adr.ID)
+	}
+	if strings.Join(ids, " ") != "acme.0001 payments.0002 acme.0003 org.0004" {
+		t.Errorf("ids = %v", ids)
+	}
+}
+
+// A README in a directory of records is its index, not a decision. Reading it
+// as one would put a table of contents on the site as a record with no status.
+func TestAnIndexIsNotARecord(t *testing.T) {
+	for _, adr := range fragment(t).Adrs {
+		if strings.HasSuffix(adr.Source, "README.md") {
+			t.Errorf("%q was read as a record", adr.Source)
+		}
+	}
+}
+
+// The fragment is one source among several, so it carries the empty lists of
+// everything it says nothing about rather than leaving the merge to guess.
+func TestTheFragmentSaysNothingItDidNotRead(t *testing.T) {
+	cat := fragment(t)
+	if len(cat.Contexts) != 0 || len(cat.Flows) != 0 || len(cat.Defs) != 0 {
+		t.Errorf("the fragment claims more than its records: %+v", cat)
+	}
+	if cat.Commit != "abc1234" || cat.GeneratedAt != "2024-01-01T00:00:00Z" {
+		t.Errorf("stamp = %q %q", cat.Commit, cat.GeneratedAt)
+	}
+}
+
+func TestTheFileIsNamedByTheOptions(t *testing.T) {
+	resp, err := extract(input("testdata/estate"), Options{History: "none", Out: "decisions.json"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if resp.Files[0].Name != "decisions.json" {
+		t.Errorf("name = %q", resp.Files[0].Name)
+	}
+	if response(t).Files[0].Name != "adr.json" {
+		t.Errorf("the default is not adr.json")
+	}
+}
+
+// A root with no records is worth saying out loud. A step pointed at the wrong
+// directory answers with an empty fragment either way, and the warning is the
+// only thing that tells the two apart.
+func TestARootWithNoRecordsWarns(t *testing.T) {
+	resp, err := extract(input("testdata"), Options{History: "none"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !warned(resp, "no decision records matched") {
+		t.Errorf("diagnostics = %+v", resp.Warnings())
+	}
+}
+
+// A supersession with one half recorded is refused whole: src/catalog.ts
+// fails the app on it, and either record alone would say something untrue.
+func TestAHalfRecordedSupersessionIsRefusedWhole(t *testing.T) {
+	resp, err := extract(input("testdata/broken"), Options{History: "none"})
+	if err == nil {
+		t.Fatal("the broken tree produced a fragment")
+	}
+	if len(resp.Files) != 0 {
+		t.Errorf("files were named anyway: %+v", resp.Files)
+	}
+	if want := "acme.0001 is superseded by acme.0002, which does not say it supersedes it"; !strings.Contains(err.Error(), want) {
+		t.Errorf("no %q in:\n%s", want, err)
+	}
+}
+
+// A tree kept with adr-tools, with the mistakes such a tree collects: two
+// records numbered the same by two branches, and a file of notes among them.
+// Each is left out with a warning that names it, and the rest is read.
+func TestATreeOfAdrToolsRecordsIsReadAndItsMistakesAreLeftOut(t *testing.T) {
+	resp, err := extract(input("testdata/lenient"), Options{Scope: "avia.aviasupp", Files: []string{"docs/adr/*.md"}, History: "none"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	var cat catalog.Catalog
+	if err := json.Unmarshal([]byte(resp.Files[0].Contents), &cat); err != nil {
+		t.Fatal(err)
+	}
+
+	var ids []string
+	for _, adr := range cat.Adrs {
+		ids = append(ids, adr.ID)
+	}
+	if strings.Join(ids, " ") != "aviasupp.0001 aviasupp.0003 aviasupp.0004 aviasupp.0005 acme.0007" {
+		t.Errorf("ids = %v", ids)
+	}
+
+	for _, want := range []string{
+		"0004-use-river.md: left out of the fragment: aviasupp.0004 is already declared in",
+		"0006-a-note-that-is-not-a-record.md: left out of the fragment: ",
+		"0007-declared-once.md: left out of the fragment: acme.0007 is already declared in",
+	} {
+		if !warnedAt(resp, want) {
+			t.Errorf("no warning %q among %+v", want, resp.Warnings())
+		}
+	}
+
+	by := map[string]catalog.Adr{}
+	for _, adr := range cat.Adrs {
+		by[adr.ID] = adr
+	}
+	if dto := by["aviasupp.0003"]; dto.Status != catalog.AdrSuperseded || dto.SupersededBy != "aviasupp.0005" {
+		t.Errorf("aviasupp.0003 = %+v", dto)
+	}
+	if schemas := by["aviasupp.0005"]; strings.Join(schemas.Supersedes, " ") != "aviasupp.0003" {
+		t.Errorf("aviasupp.0005 supersedes %v", schemas.Supersedes)
+	}
+	if action := by["aviasupp.0004"]; action.Status != catalog.AdrProposed || action.Title != "Call action" {
+		t.Errorf("aviasupp.0004 = %+v", action)
+	}
+}
+
+func warnedAt(resp plugin.Response, substring string) bool {
+	for _, d := range resp.Warnings() {
+		if strings.Contains(d.Ref+": "+d.Message, substring) {
+			return true
+		}
+	}
+
+	return false
+}
+
+// The fragment is committed and compared by gen:check. A map iterated in Go's
+// order would rewrite the file every run and turn every build into a diff.
+func TestOutputIsByteIdentical(t *testing.T) {
+	first, err := extract(input("testdata/estate"), Options{History: "none"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	for i := 0; i < 5; i++ {
+		again, err := extract(input("testdata/estate"), Options{History: "none"})
+		if err != nil {
+			t.Fatal(err)
+		}
+		if again.Files[0].Contents != first.Files[0].Contents {
+			t.Fatal("two runs over the same tree produced different fragments")
+		}
+	}
+}
+
+// The whole fragment, so a field that changes shape shows up as a diff rather
+// than slipping past every assertion above.
+func TestGoldenFragment(t *testing.T) {
+	got := response(t).Files[0].Contents
+
+	if *update {
+		if err := os.WriteFile(goldenPath, []byte(got), 0o644); err != nil {
+			t.Fatal(err)
+		}
+		t.Log("golden fragment rewritten")
+
+		return
+	}
+
+	want, err := os.ReadFile(goldenPath)
+	if err != nil {
+		t.Fatalf("reading the golden fragment: %v (run `go test ./plugins/extract-adr -update`)", err)
+	}
+	if string(want) != got {
+		t.Errorf("the fragment differs from the golden file\n%s", firstDifference(string(want), got))
+	}
+}
+
+func warned(resp plugin.Response, substring string) bool {
+	for _, d := range resp.Warnings() {
+		if strings.Contains(d.Message, substring) {
+			return true
+		}
+	}
+
+	return false
+}
+
+func firstDifference(want, got string) string {
+	a := strings.Split(want, "\n")
+	b := strings.Split(got, "\n")
+	for i := 0; i < len(a) && i < len(b); i++ {
+		if a[i] != b[i] {
+			return "line " + strconv.Itoa(i+1) + ":\n  want: " + a[i] + "\n  got:  " + b[i]
+		}
+	}
+
+	return "want " + strconv.Itoa(len(a)) + " lines, got " + strconv.Itoa(len(b))
+}
+
+// Who wrote a record down and when comes from the file's own commits: the
+// first commit is when it was created, the last when it was revised, and a
+// file committed once has no revision. A tree that is not a checkout says
+// nothing, once.
+func TestWhoCommittedARecordComesFromGit(t *testing.T) {
+	root := t.TempDir()
+	run := func(args ...string) {
+		t.Helper()
+		cmd := exec.Command("git", append([]string{"-C", root}, args...)...)
+		cmd.Env = append(os.Environ(),
+			"GIT_AUTHOR_NAME=Ada Lovelace", "GIT_AUTHOR_EMAIL=ada@example.com",
+			"GIT_COMMITTER_NAME=Ada Lovelace", "GIT_COMMITTER_EMAIL=ada@example.com",
+			"GIT_COMMITTER_DATE=2026-01-01T09:00:00Z", "GIT_AUTHOR_DATE=2026-01-01T09:00:00Z",
+		)
+		if out, err := cmd.CombinedOutput(); err != nil {
+			t.Fatalf("git %v: %v\n%s", args, err, out)
+		}
+	}
+	write := func(name, contents string) {
+		t.Helper()
+		if err := os.MkdirAll(filepath.Join(root, "docs", "adr"), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(filepath.Join(root, "docs", "adr", name), []byte(contents), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	record := func(title, body string) string {
+		return "# " + title + "\n\nDate: 2026-01-01\n\n## Status\n\nAccepted\n\n## Context\n\n" + body + "\n"
+	}
+
+	run("init", "-q")
+	write("0001-first.md", record("1. First", "As written."))
+	write("0002-second.md", record("2. Second", "As written."))
+	run("add", ".")
+	run("commit", "-q", "-m", "two records")
+
+	write("0002-second.md", record("2. Second", "Reworded."))
+	cmd := exec.Command("git", "-C", root, "commit", "-q", "-am", "reword")
+	cmd.Env = append(os.Environ(),
+		"GIT_AUTHOR_NAME=Grace Hopper", "GIT_AUTHOR_EMAIL=grace@example.com",
+		"GIT_COMMITTER_NAME=Grace Hopper", "GIT_COMMITTER_EMAIL=grace@example.com",
+		"GIT_COMMITTER_DATE=2026-01-03T17:30:00Z", "GIT_AUTHOR_DATE=2026-01-03T17:30:00Z",
+	)
+	if out, err := cmd.CombinedOutput(); err != nil {
+		t.Fatalf("git commit: %v\n%s", err, out)
+	}
+
+	resp, err := extract(input(root), Options{Scope: "org"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	var cat catalog.Catalog
+	if err := json.Unmarshal([]byte(resp.Files[0].Contents), &cat); err != nil {
+		t.Fatal(err)
+	}
+	if len(cat.Adrs) != 2 {
+		t.Fatalf("adrs = %+v", cat.Adrs)
+	}
+
+	first, second := cat.Adrs[0], cat.Adrs[1]
+	if first.Created == nil || first.Created.Author != "Ada Lovelace" || first.Created.Date != "2026-01-01T09:00:00Z" || len(first.Created.Commit) != 40 {
+		t.Errorf("first created = %+v", first.Created)
+	}
+	if first.Revised != nil {
+		t.Errorf("a file committed once was revised: %+v", first.Revised)
+	}
+	if second.Created == nil || second.Created.Author != "Ada Lovelace" {
+		t.Errorf("second created = %+v", second.Created)
+	}
+	if second.Revised == nil || second.Revised.Author != "Grace Hopper" || second.Revised.Date != "2026-01-03T17:30:00Z" || second.Revised.Commit == second.Created.Commit {
+		t.Errorf("second revised = %+v", second.Revised)
+	}
+
+	// Told not to look, the extractor does not.
+	resp, err = extract(input(root), Options{Scope: "org", History: "none"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if strings.Contains(resp.Files[0].Contents, "\"created\"") {
+		t.Error("history \"none\" still read git")
+	}
+
+	// A tree with no checkout around it says so once and carries on.
+	bare := t.TempDir()
+	if err := os.MkdirAll(filepath.Join(bare, "docs", "adr"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(bare, "docs", "adr", "0001-first.md"), []byte(record("1. First", "As written.")), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	resp, err = extract(input(bare), Options{Scope: "org"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !warned(resp, "not inside a git checkout") {
+		t.Errorf("warnings = %+v", resp.Warnings())
+	}
+}

package/plugins/extract-adr/history.go

@@ -0,0 +1,99 @@
+package main
+
+import (
+	"os/exec"
+	"path/filepath"
+	"strings"
+
+	"github.com/shortlink-org/portolan/catalog"
+	"github.com/shortlink-org/portolan/plugin"
+)
+
+// The markdown says when a decision was taken. Git says when it was written
+// down and by whom, and when it was last changed - the other half of "who
+// decided this", and one the author never has to type. Read from the file's
+// own commits, following renames, so a record moved into docs/adr keeps the
+// day it was first committed.
+//
+// This is the one place an extractor reads history rather than the tree. It
+// is still a function of the checkout: the same commit gives the same answer
+// on every machine, which is what lets the fragment be committed and checked.
+
+type history struct {
+	root string
+	// repo is the working tree the root belongs to, or "" when there is none
+	// and every record is answered with nothing.
+	repo string
+}
+
+func newHistory(root, mode string, b *plugin.Builder) *history {
+	h := &history{root: root}
+	if mode == "none" {
+		return h
+	}
+
+	top, err := git(root, "rev-parse", "--show-toplevel")
+	if err != nil || top == "" {
+		b.Warn(root, "not inside a git checkout, so the records say nothing about who committed them; set `history` to \"none\" to stop hearing this")
+
+		return h
+	}
+	h.repo = top
+
+	return h
+}
+
+// of answers with the commit that first added the file and the one that last
+// touched it, or nothing when the file has no history - it is new, or the
+// root is not a checkout.
+func (h *history) of(file string) (created, revised *catalog.AdrCommit) {
+	if h.repo == "" {
+		return nil, nil
+	}
+
+	// The file is named from where the extractor runs; git is asked from the
+	// top of the checkout, so the path is made absolute rather than left to
+	// be read against a directory it was not written for.
+	abs, err := filepath.Abs(file)
+	if err != nil {
+		return nil, nil
+	}
+	out, err := git(h.repo, "log", "--follow", "--format=%H%x1f%an%x1f%cI", "--", abs)
+	if err != nil || out == "" {
+		return nil, nil
+	}
+
+	lines := strings.Split(out, "\n")
+	first := commitOf(lines[len(lines)-1])
+	last := commitOf(lines[0])
+	if first == nil {
+		return nil, nil
+	}
+	if last != nil && last.Commit != first.Commit {
+		return first, last
+	}
+
+	return first, nil
+}
+
+func commitOf(line string) *catalog.AdrCommit {
+	parts := strings.Split(line, "\x1f")
+	if len(parts) != 3 || parts[0] == "" {
+		return nil
+	}
+
+	return &catalog.AdrCommit{Commit: parts[0], Author: parts[1], Date: parts[2]}
+}
+
+// git runs one command in the directory and answers with its trimmed output.
+// Its stderr is not this run's diagnostics: a directory that is not a
+// checkout is a fact newHistory reports once, in its own words.
+func git(dir string, args ...string) (string, error) {
+	cmd := exec.Command("git", append([]string{"-C", filepath.Clean(dir)}, args...)...)
+	out, err := cmd.Output()
+	if err != nil {
+		return "", err
+	}
+
+	return strings.TrimSpace(string(out)), nil
+}

package/plugins/extract-adr/main.go

@@ -0,0 +1,65 @@
+// Command extract-adr reads decision records written by hand, as the MADR
+// markdown they already are, and answers with a catalog fragment.
+//
+// A decision is written down once, in a file beside the code it constrains,
+// and it is read there by whoever changed that code. Typing it a second time
+// into the catalog's JSON - as an id, a slug, a number, a scope and a body
+// with every newline escaped - makes the JSON the source and the markdown a
+// copy, which is the arrow pointing the wrong way: the copy is the one that
+// goes stale, and the three records that lived in `data/catalog.json` before
+// this plugin existed all pointed at files that were never there.
+//
+// So the markdown is the source and the fragment is the output. What the
+// format cannot say - which service a record belongs to, whether the record
+// is still in force - it says in bullets under the title, and everything from
+// the first `##` onward is the record itself, carried through untouched. The
+// format is described in plugins/README.md and held to by parse_test.go.
+package main
+
+import (
+	"fmt"
+	"io"
+	"os"
+
+	"github.com/shortlink-org/portolan/plugin"
+)
+
+// Options are what the manifest tells the extractor.
+type Options struct {
+	// Files are the record files to read, as globs relative to the input
+	// root. Left out, every `docs/adr/*.md`, which is where a service keeps
+	// them; an estate-wide step points its own glob somewhere else.
+	Files []string `json:"files,omitempty"`
+
+	// Scope is what a record is about when it does not say so itself: a
+	// service, `avia.aviasupp`, a context, or the organisation. A record
+	// written by adr-tools has no such field, and its id takes its prefix
+	// from here. A MADR record with a Scope bullet keeps its own.
+	Scope string `json:"scope,omitempty"`
+
+	// History says where a record's author and dates come from: "git", the
+	// default, reads the file's commits - who first added it and who last
+	// touched it; "none" reads nothing, for a tree that is not a checkout
+	// or a fragment that must not change when the history does.
+	History string `json:"history,omitempty"`
+
+	// Out names the fragment file.
+	Out string `json:"out,omitempty"`
+}
+
+func main() {
+	if err := run(os.Stdin, os.Stdout); err != nil {
+		fmt.Fprintln(os.Stderr, "portolan-extract-adr:", err)
+		os.Exit(1)
+	}
+}
+
+func run(stdin io.Reader, stdout io.Writer) error {
+	return plugin.Serve(stdin, stdout, descriptor(), func(req plugin.Request, opts Options) (plugin.Response, error) {
+		if req.Input.Root == "" {
+			return plugin.Response{}, fmt.Errorf("no input root: an extractor has nothing to read")
+		}
+
+		return extract(req.Input, opts)
+	})
+}