arch-fix: move Flavor and convention types to internal/convention (#280)

* refactor(arch): relocate convention types from markdownflavor to internal/convention

Hoist Convention, RulePreset, and Flavor data shapes plus
ParseFlavor / Lookup / Names out of the markdownflavor rule
into a new internal/convention package. internal/config now
imports internal/convention instead of reaching into a rule
package, restoring the layering direction recorded in the
architecture hub.

The markdownflavor rule keeps its rule.Rule impl and the
Feature/support table that maps flavor → which features it
accepts; r.Flavor is now convention.Flavor and Supports is a
free function in the rule package taking a convention.Flavor.

Adds TestConfigDoesNotImportRules to guard the new direction:
it parses every non-test file under internal/config/ and fails
if any import path contains internal/rules/.

Closes plan/155.

https://claude.ai/code/session_01SEJY8ZzkXWkinVyUYMiiKB

* fix(convention): tighten Flavor.IsValid to reject unknown values

Flavor.IsValid previously returned true for any non-zero
value, so an out-of-range cast like Flavor(999) would slip
past the check and reach the markdownflavor rule, which would
then treat every feature as unsupported. The docstring already
promised "reports whether f names a recognised flavor", so the
fix is to delegate to String — every recognised flavor has a
name, every other value returns "".

Adds a Flavor(999) case to TestFlavorIsValid.

https://claude.ai/code/session_01SEJY8ZzkXWkinVyUYMiiKB

* fix(plan): use numeric:id sort to keep PLAN.md in plan-id order

The catalog directive header reverted to `sort: id` after the
rebase, which sorts lexicographically — so plan 155 lands above
plan 52 in the rendered table. The `numeric:id` prefix was
added in 8d37e44 specifically for this case; restore it and
regenerate.

https://claude.ai/code/session_01SEJY8ZzkXWkinVyUYMiiKB

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: jeduden

PLAN.md

@@ -83,5 +83,5 @@ footer: |
 | 153 | ✅     | sonnet | [Catalog directive — accept `..` globs within project root](plan/153_catalog-dotdot-globs.md)                             |
 | 153 | ✅     | opus   | [Unify linkgraph and the LSP symbol index](plan/153_unify-linkgraph-and-lsp-index.md)                                     |
 | 154 | 🔲     | sonnet | [arch-fix: extract cross-rule helpers](plan/154_arch-fix-rule-helper-extraction.md)                                       |
-| 155 | 🔲     | sonnet | [arch-fix: relocate convention types out of markdownflavor](plan/155_arch-fix-convention-config-ownership.md)             |
+| 155 | ✅     | sonnet | [arch-fix: relocate convention types out of markdownflavor](plan/155_arch-fix-convention-config-ownership.md)             |
 <?/catalog?>

docs/development/architecture-audit.md

@@ -58,33 +58,29 @@ helper packages (e.g.
 donor and consumer rules. Scheduled by
 [plan/154](../../plan/154_arch-fix-rule-helper-extraction.md).
 
+### resolved by plan/155
+
 Config imports a rule package.
 
 [`internal/config/convention.go`](../../internal/config/convention.go)
-imports `internal/rules/markdownflavor`.
-
-The imported symbols are:
-
-- `Convention`
-- `RulePreset`
-- `ParseFlavor`
-- `Lookup`
-- `ConventionNames`
-
-This violates dependency direction. The
-[layering map](architecture/index.md)
-puts rules at the lowest layer. Config
-is a mid-layer.
-
-Severity: blocker.
-
-Fix by hoisting the convention and flavor
-data shapes into a layer config can own.
-A new `internal/convention` package
-works. The markdownflavor rule then
-consumes those types instead of defining
-them. Scheduled by
-[plan/155](../../plan/155_arch-fix-convention-config-ownership.md).
+imported `internal/rules/markdownflavor`
+to use `Convention`, `RulePreset`,
+`ParseFlavor`, `Lookup`, and
+`ConventionNames`.
+
+[plan/155](../../plan/155_arch-fix-convention-config-ownership.md)
+hoisted those shapes into a new
+[internal/convention package](../../internal/convention/convention.go).
+The markdownflavor rule now imports
+`internal/convention` for the `Flavor`
+type. The config package depends on
+`internal/convention`, not on a rule.
+
+`TestConfigDoesNotImportRules` guards
+the new direction. It parses every
+non-test file under `internal/config/`.
+It fails if any import path contains
+`internal/rules/`.
 
 ### tax
 

internal/config/config.go

@@ -53,8 +53,8 @@ type Config struct {
 	// values: "portable", "github", "plain". User-defined
 	// conventions may also be referenced here after being declared
 	// under the top-level `conventions:` key. Empty means no
-	// convention. See internal/rules/markdownflavor/conventions.go
-	// and docs/reference/conventions.md.
+	// convention. See internal/convention/convention.go and
+	// docs/reference/conventions.md.
 	Convention string `yaml:"convention,omitempty"`
 
 	// Conventions holds user-defined convention bundles declared

internal/config/convention.go

@@ -6,8 +6,8 @@ import (
 
 	"gopkg.in/yaml.v3"
 
+	"github.com/jeduden/mdsmith/internal/convention"
 	"github.com/jeduden/mdsmith/internal/rule"
-	"github.com/jeduden/mdsmith/internal/rules/markdownflavor"
 )
 
 // applyConvention reads the top-level Convention selector from the
@@ -42,7 +42,7 @@ func applyConvention(cfg *Config) error {
 	if cfg.Convention == "" {
 		return nil
 	}
-	convention, err := markdownflavor.Lookup(cfg.Convention, userMap)
+	conv, err := convention.Lookup(cfg.Convention, userMap)
 	if err != nil {
 		return fmt.Errorf("convention: %w", err)
 	}
@@ -53,16 +53,16 @@ func applyConvention(cfg *Config) error {
 		if err != nil {
 			return err
 		}
-		if userFlavor != "" && userFlavor != convention.Flavor.String() {
+		if userFlavor != "" && userFlavor != conv.Flavor.String() {
 			return fmt.Errorf(
 				"rules.markdown-flavor: convention %q requires flavor %q, but flavor is set to %q",
-				convention.Name, convention.Flavor, userFlavor,
+				conv.Name, conv.Flavor, userFlavor,
 			)
 		}
 	}
 
-	preset := make(map[string]RuleCfg, len(convention.Rules))
-	for ruleName, p := range convention.Rules {
+	preset := make(map[string]RuleCfg, len(conv.Rules))
+	for ruleName, p := range conv.Rules {
 		preset[ruleName] = RuleCfg{
 			Enabled:  p.Enabled,
 			Settings: cloneSettings(p.Settings),
@@ -103,7 +103,7 @@ func copyConventionPreset(p map[string]RuleCfg) map[string]RuleCfg {
 }
 
 // buildUserConventionMap validates every entry in cfg.Conventions and
-// returns them as a map[string]markdownflavor.Convention ready for
+// returns them as a map[string]convention.Convention ready for
 // Lookup. Validation checks:
 //   - The name must not be a reserved built-in name.
 //   - The flavor must be a recognised flavor string.
@@ -112,17 +112,17 @@ func copyConventionPreset(p map[string]RuleCfg) map[string]RuleCfg {
 //     check (called on a cloned instance so the registry is unaffected).
 //
 // Returns nil when cfg.Conventions is empty.
-func buildUserConventionMap(cfg *Config) (map[string]markdownflavor.Convention, error) {
+func buildUserConventionMap(cfg *Config) (map[string]convention.Convention, error) {
 	if len(cfg.Conventions) == 0 {
 		return nil, nil
 	}
 
-	reserved := make(map[string]bool, len(markdownflavor.ConventionNames()))
-	for _, name := range markdownflavor.ConventionNames() {
+	reserved := make(map[string]bool, len(convention.Names()))
+	for _, name := range convention.Names() {
 		reserved[name] = true
 	}
 
-	result := make(map[string]markdownflavor.Convention, len(cfg.Conventions))
+	result := make(map[string]convention.Convention, len(cfg.Conventions))
 	for name, uc := range cfg.Conventions {
 		if reserved[name] {
 			return nil, fmt.Errorf(
@@ -131,15 +131,15 @@ func buildUserConventionMap(cfg *Config) (map[string]markdownflavor.Convention,
 			)
 		}
 
-		fl, ok := markdownflavor.ParseFlavor(uc.Flavor)
+		fl, ok := convention.ParseFlavor(uc.Flavor)
 		if !ok {
 			return nil, fmt.Errorf(
 				"convention %q: unknown flavor %q",
 				name, uc.Flavor,
 			)
 		}
 
-		rules := make(map[string]markdownflavor.RulePreset, len(uc.Rules))
+		rules := make(map[string]convention.RulePreset, len(uc.Rules))
 		for ruleName, rc := range uc.Rules {
 			r := rule.ByName(ruleName)
 			if r == nil {
@@ -153,13 +153,13 @@ func buildUserConventionMap(cfg *Config) (map[string]markdownflavor.Convention,
 					return nil, err
 				}
 			}
-			rules[ruleName] = markdownflavor.RulePreset{
+			rules[ruleName] = convention.RulePreset{
 				Enabled:  rc.Enabled,
 				Settings: cloneSettings(rc.Settings),
 			}
 		}
 
-		result[name] = markdownflavor.Convention{
+		result[name] = convention.Convention{
 			Name:   name,
 			Flavor: fl,
 			Rules:  rules,

internal/config/convention_test.go

@@ -1,6 +1,9 @@
 package config
 
 import (
+	"go/parser"
+	"go/token"
+	"io/fs"
 	"os"
 	"path/filepath"
 	"strings"
@@ -16,6 +19,30 @@ import (
 	_ "github.com/jeduden/mdsmith/internal/rules/nohardtabs"
 )
 
+// TestConfigDoesNotImportRules guards the dependency direction
+// recorded in docs/development/architecture/index.md: rules sit at
+// the lowest layer, config sits above them, so config must not
+// import any rule package. The convention and flavor data types
+// live in internal/convention so this constraint can be enforced.
+// Test files are exempt because they need to register rules to
+// exercise rule.ByName lookups.
+func TestConfigDoesNotImportRules(t *testing.T) {
+	fset := token.NewFileSet()
+	pkgs, err := parser.ParseDir(fset, ".", func(fi fs.FileInfo) bool {
+		return !strings.HasSuffix(fi.Name(), "_test.go")
+	}, parser.ImportsOnly)
+	require.NoError(t, err)
+	for _, pkg := range pkgs {
+		for fname, file := range pkg.Files {
+			for _, imp := range file.Imports {
+				path := strings.Trim(imp.Path.Value, `"`)
+				assert.NotContains(t, path, "internal/rules/",
+					"%s imports a rule package: %s", fname, path)
+			}
+		}
+	}
+}
+
 func TestApplyConvention_NoConventionSet_NoOp(t *testing.T) {
 	cfg := &Config{
 		Rules: map[string]RuleCfg{

…rnal/rules/markdownflavor/conventions.go internal/convention/convention.gointernal/rules/markdownflavor/conventions.go renamed to internal/convention/convention.go internal/rules/markdownflavor/conventions.go renamed to internal/convention/convention.go

@@ -1,4 +1,4 @@
-package markdownflavor
+package convention
 
 import (
 	"fmt"
@@ -32,8 +32,8 @@ type Convention struct {
 
 // RulePreset is a convention's preset for a single rule. It mirrors
 // the shape of config.RuleCfg without depending on the config
-// package, so the markdownflavor package can declare convention
-// tables without the import cycle that would otherwise result.
+// package, so this package can declare convention tables without the
+// import cycle that would otherwise result.
 type RulePreset struct {
 	Enabled  bool
 	Settings map[string]any
@@ -176,7 +176,7 @@ func Lookup(name string, userConventions map[string]Convention) (Convention, err
 	}
 	c, ok := conventions[name]
 	if !ok {
-		names := conventionNamesWithUser(userConventions)
+		names := namesWithUser(userConventions)
 		return Convention{}, fmt.Errorf(
 			"unknown convention %q (valid: %s)",
 			name, strings.Join(names, ", "),
@@ -185,10 +185,10 @@ func Lookup(name string, userConventions map[string]Convention) (Convention, err
 	return cloneConvention(c), nil
 }
 
-// conventionNamesWithUser returns a sorted list of all available
-// convention names — built-in names plus user-defined names.
-func conventionNamesWithUser(userConventions map[string]Convention) []string {
-	names := ConventionNames()
+// namesWithUser returns a sorted list of all available convention
+// names — built-in names plus user-defined names.
+func namesWithUser(userConventions map[string]Convention) []string {
+	names := Names()
 	for name := range userConventions {
 		names = append(names, name)
 	}
@@ -259,9 +259,8 @@ func cloneValue(v any) any {
 	}
 }
 
-// ConventionNames returns the sorted list of built-in convention
-// names.
-func ConventionNames() []string {
+// Names returns the sorted list of built-in convention names.
+func Names() []string {
 	names := make([]string, 0, len(conventions))
 	for k := range conventions {
 		names = append(names, k)

…rules/markdownflavor/conventions_test.go internal/convention/convention_test.gointernal/rules/markdownflavor/conventions_test.go renamed to internal/convention/convention_test.go internal/rules/markdownflavor/conventions_test.go renamed to internal/convention/convention_test.go

@@ -1,4 +1,4 @@
-package markdownflavor
+package convention
 
 import (
 	"sort"
@@ -177,9 +177,9 @@ func TestLookup_UnknownListsUserAndBuiltin(t *testing.T) {
 	assert.Contains(t, err.Error(), "portable", "error must list built-in name")
 }
 
-func TestConventionNamesSorted(t *testing.T) {
-	names := ConventionNames()
+func TestNamesSorted(t *testing.T) {
+	names := Names()
 	assert.True(t, sort.StringsAreSorted(names),
-		"ConventionNames should return a sorted slice; got %v", names)
+		"Names should return a sorted slice; got %v", names)
 	assert.ElementsMatch(t, []string{"github", "plain", "portable"}, names)
 }

internal/convention/flavor.go

@@ -0,0 +1,101 @@
+// Package convention owns the convention and flavor data shapes
+// independent of any rule. A convention pairs a Markdown flavor with
+// a table of rule presets; the config loader consults this package
+// at load time so a top-level `convention:` selection becomes a base
+// layer beneath the user's own rule config. Rule packages (notably
+// internal/rules/markdownflavor) consume these data shapes — they do
+// not own them — which keeps internal/config from importing a rule.
+package convention
+
+// Flavor identifies a target Markdown flavor.
+type Flavor int
+
+// Flavor constants. The zero value is intentionally invalid so that
+// unparsed settings are caught.
+const (
+	flavorInvalid Flavor = iota
+	FlavorCommonMark
+	FlavorGFM
+	FlavorGoldmark
+	// FlavorAny accepts every tracked feature. Useful when the
+	// document is destined for an unknown or permissive renderer and
+	// the user wants to disable flavor reporting without disabling
+	// the rule.
+	FlavorAny
+	// FlavorPandoc is Pandoc's default markdown dialect. Accepts
+	// GFM's four features plus footnotes, definition lists, heading
+	// IDs, superscript, subscript, math block, and inline math;
+	// rejects abbreviations (a non-default Pandoc extension).
+	FlavorPandoc
+	// FlavorPHPExtra is PHP Markdown Extra. Accepts tables,
+	// footnotes, definition lists, heading IDs, and abbreviations;
+	// rejects GFM's task lists, strikethrough, bare-URL autolinks,
+	// and every math / sub/superscript feature.
+	FlavorPHPExtra
+	// FlavorMultiMarkdown extends PHP Markdown Extra with math
+	// block and inline math. Like PHP Extra, rejects GFM task lists,
+	// strikethrough, bare-URL autolinks, and sub/superscript.
+	FlavorMultiMarkdown
+	// FlavorMyST is the MyST flavor used by the Sphinx documentation
+	// toolchain. Accepts tables, strikethrough, footnotes,
+	// definition lists, heading IDs, math block, and inline math;
+	// rejects GFM task lists, bare-URL autolinks, sub/superscript,
+	// and abbreviations.
+	FlavorMyST
+)
+
+// IsValid reports whether f names a recognised flavor. The zero
+// value (reserved for "unparsed/unset") and any out-of-range integer
+// cast to Flavor both return false. Implemented in terms of String
+// so the two stay in lock-step: every recognised flavor has a name,
+// and adding a new constant only requires updating the switch in
+// String.
+func (f Flavor) IsValid() bool { return f.String() != "" }
+
+// String returns the canonical lowercase name of the flavor.
+func (f Flavor) String() string {
+	switch f {
+	case FlavorCommonMark:
+		return "commonmark"
+	case FlavorGFM:
+		return "gfm"
+	case FlavorGoldmark:
+		return "goldmark"
+	case FlavorAny:
+		return "any"
+	case FlavorPandoc:
+		return "pandoc"
+	case FlavorPHPExtra:
+		return "phpextra"
+	case FlavorMultiMarkdown:
+		return "multimarkdown"
+	case FlavorMyST:
+		return "myst"
+	}
+	return ""
+}
+
+// ParseFlavor converts a config string into a Flavor. The match is
+// case-sensitive to reject typos like "GFM" that would otherwise
+// silently validate against the wrong flavor.
+func ParseFlavor(s string) (Flavor, bool) {
+	switch s {
+	case "commonmark":
+		return FlavorCommonMark, true
+	case "gfm":
+		return FlavorGFM, true
+	case "goldmark":
+		return FlavorGoldmark, true
+	case "any":
+		return FlavorAny, true
+	case "pandoc":
+		return FlavorPandoc, true
+	case "phpextra":
+		return FlavorPHPExtra, true
+	case "multimarkdown":
+		return FlavorMultiMarkdown, true
+	case "myst":
+		return FlavorMyST, true
+	}
+	return 0, false
+}