@shortlink-org/portolan 0.1.0

package/plugins/extract-adr/options.schema.json

@@ -0,0 +1,26 @@
+{
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "files": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "The record files to read, as globs relative to the input root. A README.md among them is an index rather than a record and is skipped. Left out, every docs/adr/*.md.",
+      "examples": [["docs/adr/*.md"], ["adr/*.md"]]
+    },
+    "scope": {
+      "type": "string",
+      "description": "What a record is about when it does not say so itself: \"org\", a context slug, or \"<context>.<service>\". A record written by adr-tools has no scope of its own and takes its id's prefix from here; a MADR record with a Scope bullet keeps its own.",
+      "examples": ["avia.aviasupp", "payments", "org"]
+    },
+    "history": {
+      "enum": ["git", "none"],
+      "description": "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.",
+      "default": "git"
+    },
+    "out": {
+      "type": "string",
+      "description": "Name of the fragment file, inside the step's output directory. Left out, adr.json."
+    }
+  }
+}

package/plugins/extract-adr/parse.go

@@ -0,0 +1,642 @@
+package main
+
+import (
+	"fmt"
+	"path"
+	"regexp"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/shortlink-org/portolan/catalog"
+)
+
+// The format, in one place.
+//
+//	# auth.0003 — Session expiry publishes no event
+//
+//	- **Status:** accepted
+//	- **Date:** 2026-08-22
+//	- **Scope:** auth.auth
+//	- **Superseded by:** auth.0007                      optional
+//	- **Supersedes:** auth.0001, auth.0002              optional
+//	- **Relates:** auth.auth.session.SessionEnded, shop.cart, checkout
+//	- **Note:** prose the catalog has no other field for
+//
+//	## Context and Problem Statement
+//	…
+//
+// The title carries the id and, after an em dash, the title itself. The id's
+// prefix is whatever the record is about - a service (`auth`), a context
+// (`payments`) or the organisation (`org`) - and the four digits after it are
+// the record's number, which the file's own name repeats.
+//
+// The bullets are everything the markdown knows that the prose does not say
+// in a form anything can read. Status, Date and Scope are required; the rest
+// are written when there is something to write. `Relates` names events,
+// services and flows in one list and they are told apart by their shape,
+// because a record's author should not have to remember which of three lists
+// a name belongs in.
+//
+// Everything from the first `##` onward is the record. It is frozen history:
+// it goes into the catalog exactly as written and comes out onto the page the
+// same way, and nothing in it is ever regenerated from the model as it stands
+// now.
+//
+// The other format read here is the one adr-tools writes, because a tree of
+// records kept that way for years should not have to be retyped to be read:
+//
+//	# 2. Integration with external suppliers
+//
+//	Date: 2024-09-04
+//
+//	## Status
+//
+//	Superseded by [5. Use schemas](0005-use-schemas.md)
+//
+//	## Context
+//	…
+//
+// The title carries the number and the title; the id's prefix, which the
+// format has no place for, comes from the step's scope option, as does the
+// scope itself. The date is a line of its own above the record, and the status
+// is the first section of the record, where adr-tools writes it - a word, or
+// "Superseded by" and a link to the record that replaced this one, and
+// "Supersedes" and a link the other way. The record is the same as above:
+// everything from the first `##`, the status section included.
+
+var (
+	titleLine  = regexp.MustCompile(`^#\s+(\S+)\s+—\s+(.+?)\s*$`)
+	toolsTitle = regexp.MustCompile(`^#\s+(\d+)\.\s+(.+?)\s*$`)
+	plainTitle = regexp.MustCompile(`^#\s+(.+?)\s*$`)
+	toolsDate  = regexp.MustCompile(`^Date:\s*(.+?)\s*$`)
+	toolsLink  = regexp.MustCompile(`\[\s*(\d+)\.[^\]]*\]\([^)]*\)`)
+	toolsBare  = regexp.MustCompile(`(?i)^(?:adr[-\s]?)?0*(\d+)$`)
+	statusHead = regexp.MustCompile(`^##\s+Status\s*$`)
+	sectionAny = regexp.MustCompile(`^#{1,2}\s`)
+	bulletLine = regexp.MustCompile(`^-\s+\*\*([^*:]+):\*\*\s*(.*?)\s*$`)
+	bodyStart  = regexp.MustCompile(`^##\s`)
+	fileName   = regexp.MustCompile(`^(\d{4})-([a-z0-9]+(?:-[a-z0-9]+)*)$`)
+	adrID      = regexp.MustCompile(`^([a-z][a-z0-9-]*(?:\.[a-z][a-z0-9-]*)*)\.(\d+)$`)
+	scopeValue = regexp.MustCompile(`^[a-z][a-z0-9-]*(?:\.[a-z][a-z0-9-]*)?$`)
+	flowSlug   = regexp.MustCompile(`^[a-z0-9]+(?:-[a-z0-9]+)*$`)
+	eventID    = regexp.MustCompile(`^[a-z][a-z0-9-]*\.[a-z][a-z0-9-]*\.[a-z][a-z0-9-]*\.[A-Za-z][A-Za-z0-9]*$`)
+	serviceID  = regexp.MustCompile(`^[a-z][a-z0-9-]*\.[a-z][a-z0-9-]*$`)
+)
+
+var statuses = map[string]catalog.AdrStatus{
+	"proposed":   catalog.AdrProposed,
+	"accepted":   catalog.AdrAccepted,
+	"superseded": catalog.AdrSuperseded,
+	"deprecated": catalog.AdrDeprecated,
+	"rejected":   catalog.AdrRejected,
+}
+
+// defaults are what the manifest says about a tree of records, for the
+// records that do not say it themselves.
+type defaults struct {
+	// Scope is what a record is about when it has no Scope of its own: "org",
+	// a context, or "<context>.<service>". It also lends an adr-tools record
+	// the prefix of its id, which is the last segment: the service, the
+	// context, or "org".
+	Scope string
+}
+
+type parser struct {
+	file  string
+	lines []string
+	errs  []string
+	d     defaults
+
+	// tools is set when the title is the one adr-tools writes, and picks the
+	// way the rest of the file is read.
+	tools bool
+
+	adr catalog.Adr
+}
+
+// parseAdr reads one record. Every mistake it can find is collected rather
+// than returned at the first one, because a file with two typos in its header
+// should be fixed once.
+func parseAdr(file, src string, d defaults) (catalog.Adr, []string) {
+	p := &parser{
+		file:  file,
+		lines: strings.Split(strings.ReplaceAll(src, "\r\n", "\n"), "\n"),
+		d:     d,
+	}
+	p.read()
+	if len(p.errs) > 0 {
+		return catalog.Adr{}, p.errs
+	}
+
+	return p.adr, nil
+}
+
+func (p *parser) fail(line int, msg string) {
+	p.errs = append(p.errs, p.file+":"+strconv.Itoa(line+1)+": "+msg)
+}
+
+func (p *parser) read() {
+	p.adr.Source = p.file
+	p.adr.Relates = catalog.AdrRelates{}
+
+	head := p.title()
+	if head < 0 {
+		return
+	}
+	p.checkFileName()
+
+	body := -1
+	if p.tools {
+		body = p.toolsMeta(head + 1)
+	} else {
+		body = p.meta(head + 1)
+	}
+	if body < 0 {
+		return
+	}
+	p.adr.Body = strings.TrimSpace(strings.Join(p.lines[body:], "\n")) + "\n"
+	if p.tools {
+		p.toolsStatus(body)
+		p.checkSupersession(head)
+	}
+}
+
+// title reads the one line the record has to open with and answers with its
+// index, or -1 when there is nothing to go on.
+func (p *parser) title() int {
+	for i, line := range p.lines {
+		if strings.TrimSpace(line) == "" {
+			continue
+		}
+
+		match := titleLine.FindStringSubmatch(line)
+		if match == nil {
+			if tools := toolsTitle.FindStringSubmatch(line); tools != nil {
+				return p.toolsTitleLine(i, tools)
+			}
+			// A title with no number at all is numbered by its file, unless
+			// it opens with something shaped like an id: that is a MADR
+			// title with the wrong dash, and reading it as a plain one would
+			// turn a typo into a record under another name.
+			if plain := plainTitle.FindStringSubmatch(line); plain != nil && !adrID.MatchString(strings.Fields(plain[1])[0]) {
+				return p.plainTitleLine(i, plain[1])
+			}
+			p.fail(i, `a record opens with "# <id> — <title>", an em dash between the two, or with "# <n>. <title>" as adr-tools writes it`)
+
+			return -1
+		}
+
+		id := adrID.FindStringSubmatch(match[1])
+		if id == nil {
+			p.fail(i, "the id "+strconv.Quote(match[1])+` is not a prefix and a number, as in "auth.0003"`)
+
+			return -1
+		}
+		number, err := strconv.Atoi(id[2])
+		if err != nil || fmt.Sprintf("%04d", number) != id[2] {
+			// The app fails the whole catalog on an id that does not end with
+			// its own number, so the digits are the number and are written
+			// the one way that round-trips.
+			p.fail(i, "the number in "+strconv.Quote(match[1])+" is not four padded digits")
+
+			return -1
+		}
+
+		p.adr.ID = match[1]
+		p.adr.Number = number
+		p.adr.Title = strings.TrimSpace(match[2])
+
+		return i
+	}
+
+	p.fail(0, "the file is empty")
+
+	return -1
+}
+
+// toolsTitleLine reads the title adr-tools writes: the record's number, a
+// full stop, the title. The id is built from the number and the prefix the
+// scope lends, because the format keeps no id of its own.
+func (p *parser) toolsTitleLine(i int, match []string) int {
+	number, err := strconv.Atoi(match[1])
+	if err != nil || number <= 0 {
+		p.fail(i, "the number "+strconv.Quote(match[1])+" is not a record's number")
+
+		return -1
+	}
+
+	p.tools = true
+	p.adr.ID = p.toolsID(number)
+	p.adr.Number = number
+	p.adr.Title = strings.TrimSpace(match[2])
+
+	return i
+}
+
+// plainTitleLine reads a title that carries no number, which adr-tools trees
+// collect when a record is written by hand: the file's own name numbers it,
+// and the heading is the title.
+func (p *parser) plainTitleLine(i int, title string) int {
+	match := fileName.FindStringSubmatch(strings.TrimSuffix(path.Base(p.file), ".md"))
+	if match == nil {
+		p.fail(i, `the title carries no number and the file is not named "NNNN-kebab-slug.md", so nothing numbers the record`)
+
+		return -1
+	}
+	number, _ := strconv.Atoi(match[1])
+	if number <= 0 {
+		p.fail(i, "the file is numbered "+match[1]+", which is not a record's number")
+
+		return -1
+	}
+
+	p.tools = true
+	p.adr.ID = p.toolsID(number)
+	p.adr.Number = number
+	p.adr.Title = strings.TrimSpace(title)
+
+	return i
+}
+
+// toolsID is the id an adr-tools record gets: the prefix the scope lends and
+// the number, padded the one way that round-trips.
+func (p *parser) toolsID(number int) string {
+	return p.prefix() + "." + fmt.Sprintf("%04d", number)
+}
+
+// prefix is what an id opens with, taken from the scope the way the MADR
+// records of the estate do it: the service for a service, the context for a
+// context, and "org" for the organisation.
+func (p *parser) prefix() string {
+	scope := strings.TrimSpace(p.d.Scope)
+	if scope == "" || scope == "org" {
+		return "org"
+	}
+	if _, service, ok := strings.Cut(scope, "."); ok {
+		return service
+	}
+
+	return scope
+}
+
+// toolsMeta reads what adr-tools keeps above the record - the date, on a line
+// of its own - and answers with the index the record starts at, or -1 when
+// there is none.
+func (p *parser) toolsMeta(from int) int {
+	for i := from; i < len(p.lines); i++ {
+		line := p.lines[i]
+		switch {
+		case bodyStart.MatchString(line):
+			if p.adr.Date == "" {
+				p.fail(from-1, `the record says no "Date:"`)
+			}
+			p.scope(from-1, p.d.Scope)
+
+			return i
+
+		case strings.TrimSpace(line) == "":
+
+		case toolsDate.MatchString(line):
+			value := toolsDate.FindStringSubmatch(line)[1]
+			if _, err := time.Parse("2006-01-02", value); err != nil {
+				p.fail(i, strconv.Quote(value)+" is not a date, as in 2026-08-22")
+
+				continue
+			}
+			p.adr.Date = value
+
+		default:
+			p.fail(i, "only \"Date:\" belongs between the title and the first `##`")
+
+			return -1
+		}
+	}
+
+	p.fail(len(p.lines)-1, "the record has no body: nothing here is under a `##`")
+
+	return -1
+}
+
+// toolsStatus reads the status from the record's own Status section, which is
+// where adr-tools keeps it. Each non-empty line there is one statement: a
+// status word, or "Superseded by" or "Supersedes" and the record it means. A
+// later statement wins over an earlier one, because a record that was accepted
+// and then superseded has both written down, in that order.
+func (p *parser) toolsStatus(body int) {
+	head := -1
+	for i := body; i < len(p.lines); i++ {
+		if statusHead.MatchString(p.lines[i]) {
+			head = i
+
+			break
+		}
+	}
+	if head < 0 {
+		p.fail(body, "the record has no `## Status` section")
+
+		return
+	}
+
+	statements := 0
+	for i := head + 1; i < len(p.lines) && !sectionAny.MatchString(p.lines[i]); i++ {
+		statement := strings.TrimSpace(p.lines[i])
+		if statement == "" {
+			continue
+		}
+		statements++
+		p.toolsStatement(i, statement)
+	}
+	if statements == 0 {
+		p.fail(head, "the Status section says nothing")
+	}
+	if p.adr.Status == "" && len(p.errs) == 0 {
+		p.fail(head, "the Status section names no status: proposed, accepted, superseded, deprecated or rejected")
+	}
+}
+
+func (p *parser) toolsStatement(at int, statement string) {
+	lower := strings.ToLower(strings.TrimRight(statement, ". "))
+	if status, ok := statuses[lower]; ok {
+		p.adr.Status = status
+
+		return
+	}
+
+	switch {
+	case strings.HasPrefix(lower, "superseded by"):
+		ids := p.toolsRecords(statement[len("superseded by"):])
+		if len(ids) != 1 {
+			p.fail(at, "the record is superseded and says by which one record")
+
+			return
+		}
+		p.adr.Status = catalog.AdrSuperseded
+		p.adr.SupersededBy = ids[0]
+
+	case strings.HasPrefix(lower, "supersedes"):
+		ids := p.toolsRecords(statement[len("supersedes"):])
+		if len(ids) == 0 {
+			p.fail(at, "the record supersedes something and says which record")
+
+			return
+		}
+		p.adr.Supersedes = append(p.adr.Supersedes, ids...)
+
+	case strings.HasPrefix(lower, "amends"), strings.HasPrefix(lower, "amended by"):
+		// An amendment is a fact the catalog has no field for. It stays in the
+		// body, which is on the page as written.
+
+	default:
+		p.fail(at, strconv.Quote(statement)+` is not a status: proposed, accepted, superseded, deprecated or rejected, or "Superseded by" a record`)
+	}
+}
+
+// toolsRecords finds the records a statement names, as the links adr-tools
+// writes - "[3. Use DTO](0003-use-dto.md)" - or as bare numbers.
+func (p *parser) toolsRecords(rest string) []string {
+	var ids []string
+	for _, match := range toolsLink.FindAllStringSubmatch(rest, -1) {
+		number, err := strconv.Atoi(match[1])
+		if err != nil {
+			continue
+		}
+		ids = append(ids, p.toolsID(number))
+	}
+	if len(ids) > 0 {
+		return ids
+	}
+	for _, word := range strings.Fields(strings.NewReplacer(",", " ", "and", " ").Replace(rest)) {
+		if match := toolsBare.FindStringSubmatch(word); match != nil {
+			number, _ := strconv.Atoi(match[1])
+			ids = append(ids, p.toolsID(number))
+		}
+	}
+
+	return ids
+}
+
+// checkFileName ties the record to the file it is in. The slug is built from
+// both - the id says which record this is, the file's name says what it was
+// about - so a file renamed away from its record would silently change the
+// URL of a decision somebody linked to.
+func (p *parser) checkFileName() {
+	base := strings.TrimSuffix(path.Base(p.file), ".md")
+
+	match := fileName.FindStringSubmatch(base)
+	if match == nil {
+		p.fail(0, "the file is named "+strconv.Quote(base+".md")+`, not "NNNN-kebab-slug.md"`)
+
+		return
+	}
+	if number, _ := strconv.Atoi(match[1]); number != p.adr.Number {
+		p.fail(0, "the file is numbered "+match[1]+" and the record inside it is "+p.adr.ID)
+
+		return
+	}
+
+	p.adr.Slug = strings.ReplaceAll(p.adr.ID, ".", "-") + "-" + match[2]
+}
+
+// meta reads the bullets between the title and the record, and answers with
+// the index the record starts at, or -1 when there is none.
+func (p *parser) meta(from int) int {
+	seen := map[string]bool{}
+	key, value, at := "", "", 0
+	flush := func() {
+		if key != "" {
+			p.bullet(at, key, value)
+		}
+		key, value = "", ""
+	}
+
+	for i := from; i < len(p.lines); i++ {
+		line := p.lines[i]
+		switch {
+		case bodyStart.MatchString(line):
+			flush()
+			p.require(from-1, seen)
+
+			return i
+
+		case strings.TrimSpace(line) == "":
+			flush()
+
+		case bulletLine.MatchString(line):
+			flush()
+			match := bulletLine.FindStringSubmatch(line)
+			key, value, at = strings.TrimSpace(match[1]), match[2], i
+			if seen[key] {
+				p.fail(i, strconv.Quote(key)+" is written twice")
+			}
+			seen[key] = true
+
+		case key != "" && (strings.HasPrefix(line, " ") || strings.HasPrefix(line, "\t")):
+			// A bullet wraps onto the next line, indented under itself. The
+			// break is the author's line width and means nothing, so it
+			// closes up into a space.
+			value = strings.TrimSpace(value + " " + strings.TrimSpace(line))
+
+		default:
+			p.fail(i, "only meta bullets belong between the title and the first `##`")
+
+			return -1
+		}
+	}
+
+	flush()
+	p.fail(len(p.lines)-1, "the record has no body: nothing here is under a `##`")
+
+	return -1
+}
+
+// require reports the three bullets a record cannot be read without. They are
+// reported against the title rather than against the missing line, because
+// there is no missing line to point at.
+func (p *parser) require(at int, seen map[string]bool) {
+	for _, key := range []string{"Status", "Date"} {
+		if !seen[key] {
+			p.fail(at, "the record says no "+strconv.Quote(key))
+		}
+	}
+	// A record that does not say what it is about is about what the step says
+	// its tree is about; only when the step says nothing either is that a
+	// mistake.
+	switch {
+	case seen["Scope"]:
+	case strings.TrimSpace(p.d.Scope) != "":
+		p.scope(at, p.d.Scope)
+	default:
+		p.fail(at, `the record says no "Scope"`)
+	}
+
+	p.checkSupersession(at)
+}
+
+// checkSupersession holds the two things a record says about being replaced
+// against each other. Supersession is a two-way fact and half of it recorded
+// is a bug. The other half - that the record named actually names this one
+// back - can only be checked once every record is read, so it is checked
+// there.
+func (p *parser) checkSupersession(at int) {
+	if p.adr.Status == catalog.AdrSuperseded && p.adr.SupersededBy == "" {
+		p.fail(at, "the record is superseded and says by what")
+	}
+	if p.adr.SupersededBy != "" && p.adr.Status != catalog.AdrSuperseded {
+		p.fail(at, "the record is superseded by "+p.adr.SupersededBy+` but its status is "`+string(p.adr.Status)+`"`)
+	}
+}
+
+func (p *parser) bullet(at int, key, value string) {
+	switch key {
+	case "Status":
+		status, ok := statuses[value]
+		if !ok {
+			p.fail(at, strconv.Quote(value)+" is not a status: proposed, accepted, superseded, deprecated or rejected")
+
+			return
+		}
+		p.adr.Status = status
+
+	case "Date":
+		if _, err := time.Parse("2006-01-02", value); err != nil {
+			p.fail(at, strconv.Quote(value)+" is not a date, as in 2026-08-22")
+
+			return
+		}
+		p.adr.Date = value
+
+	case "Scope":
+		p.scope(at, value)
+
+	case "Superseded by":
+		if ids := p.ids(at, key, value); len(ids) > 1 {
+			p.fail(at, "a record is superseded by one record, not "+strconv.Itoa(len(ids)))
+		} else if len(ids) == 1 {
+			p.adr.SupersededBy = ids[0]
+		}
+
+	case "Supersedes":
+		p.adr.Supersedes = p.ids(at, key, value)
+
+	case "Relates":
+		p.relates(at, value)
+
+	case "Note":
+		p.adr.Note = value
+
+	default:
+		p.fail(at, strconv.Quote(key)+" is not one of the bullets a record carries")
+	}
+}
+
+// scope says what the record is about, and the number of segments says which
+// of the three kinds it is: none for the organisation, one for a context, two
+// for a service. Whether the thing named exists is not a question this side
+// can answer - an extractor sees one service's tree - so it is left to the
+// validator, which sees the merged catalog.
+func (p *parser) scope(at int, value string) {
+	value = strings.TrimSpace(value)
+	if value == "" || value == "org" {
+		p.adr.Scope = catalog.AdrScope{Kind: "org"}
+
+		return
+	}
+	if !scopeValue.MatchString(value) {
+		p.fail(at, strconv.Quote(value)+` is not a scope: "org", a context, or "<context>.<service>"`)
+
+		return
+	}
+	if strings.Contains(value, ".") {
+		p.adr.Scope = catalog.AdrScope{Kind: "service", Service: value}
+
+		return
+	}
+	p.adr.Scope = catalog.AdrScope{Kind: "context", Context: value}
+}
+
+// relates names events, services and flows in one comma-separated list and
+// they are told apart by their shape: a flow by its slug, which has no dots; a
+// service by `<context>.<service>`; an event by the aggregate and Name after
+// that. A name matching none of the three is a typo, and reported here rather
+// than left to come back from the validator as a reference to something that
+// does not exist.
+func (p *parser) relates(at int, value string) {
+	for _, id := range split(value) {
+		switch {
+		case eventID.MatchString(id):
+			p.adr.Relates.Events = append(p.adr.Relates.Events, id)
+		case serviceID.MatchString(id):
+			p.adr.Relates.Services = append(p.adr.Relates.Services, id)
+		case flowSlug.MatchString(id):
+			p.adr.Relates.Flows = append(p.adr.Relates.Flows, id)
+		default:
+			p.fail(at, strconv.Quote(id)+" is not the shape of an event, a service or a flow")
+		}
+	}
+}
+
+func (p *parser) ids(at int, key, value string) []string {
+	var ids []string
+	for _, id := range split(value) {
+		if !adrID.MatchString(id) {
+			p.fail(at, strconv.Quote(id)+" in "+strconv.Quote(key)+" is not a record's id")
+
+			continue
+		}
+		ids = append(ids, id)
+	}
+
+	return ids
+}
+
+func split(value string) []string {
+	var out []string
+	for _, part := range strings.Split(value, ",") {
+		if part = strings.TrimSpace(part); part != "" {
+			out = append(out, part)
+		}
+	}
+
+	return out
+}