parser

Documentation

Index

• func FormatReport(report *MigrationReport, format string) (string, error)
• func ListAdapters() []string
• func ParseMarkdownFile(path string) (*models.Artifact, string, error)
• func ParseSections(content string) (map[string]string, error)
• func RegisterAdapter(adapter MigrationAdapter) error
• func ResetRegistry()
• func WriteSection(content string, name string, value string) (string, error)
• func WriteSections(content string, updates map[string]string) (string, error)
• type BacklogMdAdapter
  • func (a *BacklogMdAdapter) Detect(path string) bool
  • func (a *BacklogMdAdapter) Name() string
  • func (a *BacklogMdAdapter) Parse(ctx context.Context, path string) ([]MigrationItem, error)
• type ClassificationResult
• type Classifier
  • func NewClassifier() *Classifier
  • func (c *Classifier) Classify(path string) (ClassificationResult, error)
  • func (c *Classifier) ClassifyDir(dirPath string) ([]ClassificationResult, error)
• type DocumentClass
• type LegacyItem
  • func Migrate(ctx context.Context, legacyPath string) ([]LegacyItem, error)
  • func ParseLegacy(content string) ([]LegacyItem, error)
  • func ParseLegacyEnhanced(content string) ([]LegacyItem, error)
• type MigrateOptions
• type MigrationAdapter
  • func DetectAdapter(path string) (MigrationAdapter, error)
  • func GetAdapter(name string) (MigrationAdapter, error)
• type MigrationItem
• type MigrationReport
  • func MigrateWithOptions(ctx context.Context, sourcePath string, opts MigrateOptions) (*MigrationReport, error)

Functions

func FormatReport

func FormatReport(report *MigrationReport, format string) (string, error)

FormatReport formats a MigrationReport as text or JSON.

When format is "json", the report is marshalled to indented JSON. For all other values (including ""), a human-readable text summary is produced.

func ListAdapters

func ListAdapters() []string

ListAdapters returns the names of all registered adapters.

Worker: Return a sorted slice of adapter names from the registry.

func ParseMarkdownFile

func ParseMarkdownFile(path string) (*models.Artifact, string, error)

ParseMarkdownFile reads a Markdown file and extracts the artifact and body.

func ParseSections

func ParseSections(content string) (map[string]string, error)

ParseSections extracts named sections from markdown content between <!-- BEGIN:{name} --> and <!-- END:{name} --> tags. Leading and trailing newlines are trimmed from each section's content, but internal whitespace (indentation, blank lines) is preserved. Returns an error if a BEGIN tag has no matching END tag.

func RegisterAdapter

func RegisterAdapter(adapter MigrationAdapter) error

RegisterAdapter adds a migration adapter to the global registry.

Worker: Store the adapter in the adapters map under adapter.Name(). Return an error if an adapter with the same name is already registered.

func ResetRegistry

func ResetRegistry()

ResetRegistry clears all registered adapters. Used for testing.

func WriteSection

func WriteSection(content string, name string, value string) (string, error)

WriteSection replaces a single section's content in the document. It is a convenience wrapper around WriteSections.

func WriteSections

func WriteSections(content string, updates map[string]string) (string, error)

WriteSections replaces multiple section contents while preserving the rest of the document. For each entry in updates the content between the matching BEGIN/END tags is replaced with the provided value. Returns an error if a named section is absent from content.

Types

type BacklogMdAdapter

type BacklogMdAdapter struct{}

BacklogMdAdapter implements MigrationAdapter for Backlog.md files.

func (*BacklogMdAdapter) Detect

func (a *BacklogMdAdapter) Detect(path string) bool

Detect reports whether the path contains a Backlog.md-compatible file.

Worker: Check if path points to a .md file that contains checklist items (regex match for `- [ ]` or `- [x]` patterns) indicating a legacy backlog format.

func (*BacklogMdAdapter) Name

func (a *BacklogMdAdapter) Name() string

Name returns the adapter identifier.

func (*BacklogMdAdapter) Parse

func (a *BacklogMdAdapter) Parse(ctx context.Context, path string) ([]MigrationItem, error)

Parse extracts migration items from a Backlog.md file.

Worker: Use the enhanced ParseLegacy to parse the file, then convert each LegacyItem to a MigrationItem with appropriate field mapping.

type ClassificationResult

type ClassificationResult struct {
	Class      DocumentClass `json:"class"`
	Confidence float64       `json:"confidence"`
	Path       string        `json:"path"`
}

ClassificationResult holds the output of document classification.

type Classifier

type Classifier struct{}

Classifier analyzes markdown documents to detect their type for migration routing.

func NewClassifier

func NewClassifier() *Classifier

NewClassifier creates a new document classifier.

func (*Classifier) Classify

func (c *Classifier) Classify(path string) (ClassificationResult, error)

Classify analyzes a single markdown file and returns its detected class with confidence score.

It uses path hints, YAML frontmatter fields, content keywords, and checklist density to determine the document class. The highest-confidence signal wins.

func (*Classifier) ClassifyDir

func (c *Classifier) ClassifyDir(dirPath string) ([]ClassificationResult, error)

ClassifyDir scans a directory and classifies all markdown files found. Non-markdown files are skipped.

type DocumentClass

type DocumentClass string

DocumentClass represents the type of a markdown document detected by classification.

const (
	// ClassSpec indicates a requirements or specification document.
	ClassSpec DocumentClass = "spec"
	// ClassPlan indicates an implementation or execution plan.
	ClassPlan DocumentClass = "plan"
	// ClassWorkItem indicates a task, bug, or user story.
	ClassWorkItem DocumentClass = "work_item"
	// ClassDecision indicates an architecture decision record.
	ClassDecision DocumentClass = "decision"
	// ClassNote indicates a general note or documentation.
	ClassNote DocumentClass = "note"
	// ClassUnknown indicates the document type could not be determined.
	ClassUnknown DocumentClass = "unknown"
)

type LegacyItem

type LegacyItem struct {
	Title       string
	Status      string
	ParentTitle string
	Depth       int
	Description string
}

LegacyItem represents a parsed item from a legacy backlog.md file.

func Migrate

func Migrate(ctx context.Context, legacyPath string) ([]LegacyItem, error)

Migrate parses a legacy backlog.md and returns the extracted items. The caller is responsible for creating artifacts in the workspace.

func ParseLegacy

func ParseLegacy(content string) ([]LegacyItem, error)

ParseLegacy parses a monolithic backlog.md using heading and checklist heuristics.

func ParseLegacyEnhanced

func ParseLegacyEnhanced(content string) ([]LegacyItem, error)

ParseLegacyEnhanced extends ParseLegacy with broader format coverage.

It parses checklist items and enriches each LegacyItem with:

• Depth set from the heading level (H1=1 … H4=4) of the containing heading
• ParentTitle from the immediate heading title
• Title with priority markers ([P0]-[P4], !high), @mentions, dates (YYYY-MM-DD) and tag annotations ([tag, tag]) stripped
• Description populated from paragraph text immediately following the item

Status mapping and backwards compatibility are identical to ParseLegacy.

type MigrateOptions

type MigrateOptions struct {
	DryRun     bool
	Validate   bool
	Adapter    string
	ConfigPath string
	Format     string
}

MigrateOptions configures migration behavior.

type MigrationAdapter

type MigrationAdapter interface {
	// Name returns the adapter's unique identifier.
	Name() string
	// Detect reports whether the given path contains content this adapter can migrate.
	Detect(path string) bool
	// Parse reads the source at path and returns extracted migration items.
	Parse(ctx context.Context, path string) ([]MigrationItem, error)
}

MigrationAdapter defines the contract for pluggable migration sources.

func DetectAdapter

func DetectAdapter(path string) (MigrationAdapter, error)

DetectAdapter finds the first registered adapter that can handle the given path.

Worker: Iterate through all registered adapters, call Detect(path) on each. Return the first adapter that returns true. If none match, return an error.

func GetAdapter

func GetAdapter(name string) (MigrationAdapter, error)

GetAdapter retrieves a registered adapter by name.

Worker: Look up the adapter in the adapters map. Return (adapter, nil) if found, (nil, error) if not found.

type MigrationItem

type MigrationItem struct {
	Title        string            `json:"title"`
	Body         string            `json:"body"`
	Status       string            `json:"status"`
	Metadata     map[string]string `json:"metadata"`
	Fields       map[string]any    `json:"fields,omitempty"`
	SourceType   DocumentClass     `json:"source_type"`
	ParentRef    string            `json:"parent_ref"`
	SourcePath   string            `json:"source_path"`
	SourceID     string            `json:"source_id,omitempty"`
	ArtifactType string            `json:"artifact_type,omitempty"`
	Depth        int               `json:"depth"`
	Priority     string            `json:"priority"`
	AssignedTo   string            `json:"assigned_to"`
	DateRef      string            `json:"date_ref"`
	Tags         []string          `json:"tags"`
	Dependencies []string          `json:"dependencies,omitempty"`
	References   []string          `json:"references,omitempty"`
	SprintGroup  string            `json:"sprint_group"`
}

MigrationItem is a generalized intermediate representation produced by adapters.

type MigrationReport

type MigrationReport struct {
	ItemsMigrated int
	ItemsSkipped  int
	ItemsFailed   int
	Errors        []string
	Items         []MigrationItem
}

MigrationReport holds the results of a migration operation.

func MigrateWithOptions

func MigrateWithOptions(ctx context.Context, sourcePath string, opts MigrateOptions) (*MigrationReport, error)

MigrateWithOptions performs migration with configurable behavior.

It resolves an adapter (by name or auto-detect), parses the source file, and returns a MigrationReport with counts and any errors encountered. When DryRun is true, items are counted but no files are written.