setup

Documentation

Overview

Package setup provides project documentation generation and management.

Index

• Variables
• func AnalyzeConventions(dir string, langs []Language) map[string]ConventionSample
• func SaveMeta(docsDir string, meta *Meta) error
• func Update(projectDir string, outputDir string) ([]string, error)
• type ApplyResult
  • func ApplyChangePlan(plan *ChangePlan) (*ApplyResult, error)
• type BuildFile
• type ChangeAction
• type ChangeClass
• type ChangePlan
  • func BuildGeneratePlan(projectDir string, opts *GenerateOptions) (*ChangePlan, error)
  • func BuildUpdatePlan(projectDir string, outputDir string) (*ChangePlan, error)
• type ChangePlanMode
• type ConventionSample
• type DirEntry
• type DocSet
  • func Generate(projectDir string, opts *GenerateOptions) (*DocSet, error)
  • func Render(info *ProjectInfo, opts *RenderOptions) *DocSet
• type EntryPoint
• type FileMeta
• type FileStatus
• type Framework
• type GenerateOptions
• type Language
• type Meta
  • func LoadMeta(docsDir string) (*Meta, error)
  • func NewMeta(projectDir string) *Meta
  • func NewMetaAt(projectDir string, generatedAt time.Time) *Meta
  • func (m *Meta) HasContentChanged(docName, content string) bool
  • func (m *Meta) HasSourceChanged(docName, projectDir string) bool
  • func (m *Meta) SetFileMeta(docName, content string, sourceFiles []string, projectDir string)
• type MultiRepoInfo
  • func DetectMultiRepo(dir string) *MultiRepoInfo
• type PlannedChange
• type ProjectInfo
  • func Scan(projectDir string) (*ProjectInfo, error)
• type RenderOptions
• type RepoComponent
  • func ScanRepoComponent(dir string) (*RepoComponent, error)
• type RepoDependency
  • func MapCrossRepoDeps(components []RepoComponent) []RepoDependency
• type SetupConfig
• type Status
  • func GetStatus(projectDir string, outputDir string) (*Status, error)
• type TestConfiguration
• type ValidationReport
  • func Validate(docsDir, projectDir string) (*ValidationReport, error)
• type ValidationWarning
  • func ValidateCommands(docsDir, projectDir string) []ValidationWarning
• type Workspace
  • func DetectWorkspaces(dir string) []Workspace
• type WorkspaceHint
• type WorkspaceHintKind

Variables

var DocFiles = map[string]string{
	"index":        "index.md",
	"commands":     "commands.md",
	"structure":    "structure.md",
	"conventions":  "conventions.md",
	"boundaries":   "boundaries.md",
	"architecture": "architecture.md",
	"testing":      "testing.md",
}

DocFiles maps document names to file paths.

var ErrStaleChangePlan = errors.New("stale change plan")

ErrStaleChangePlan reports that the filesystem no longer matches the preview.

Functions

func AnalyzeConventions

func AnalyzeConventions(dir string, langs []Language) map[string]ConventionSample

AnalyzeConventions scans project source files to detect actual coding conventions.

func SaveMeta

func SaveMeta(docsDir string, meta *Meta) error

SaveMeta writes .meta.yaml to the docs directory.

func Update

func Update(projectDir string, outputDir string) ([]string, error)

Update regenerates only documents whose source data has changed.

Types

type ApplyResult

type ApplyResult struct {
	ChangedPaths []string
	DocSet       *DocSet
}

ApplyResult reports the files written by ApplyChangePlan.

func ApplyChangePlan

func ApplyChangePlan(plan *ChangePlan) (*ApplyResult, error)

ApplyChangePlan revalidates and writes the files described by a preview plan.

type BuildFile

type BuildFile struct {
	Path     string            // File path relative to project root
	Type     string            // Type: makefile, package.json, cargo.toml, go.mod, pyproject.toml, docker-compose
	Commands map[string]string // Extracted commands: name -> command string
}

BuildFile represents a build configuration file.

type ChangeAction

type ChangeAction string

ChangeAction describes how apply would treat a target file.

const (
	ChangeActionCreate   ChangeAction = "create"
	ChangeActionUpdate   ChangeAction = "update"
	ChangeActionPreserve ChangeAction = "preserve"
	ChangeActionSkip     ChangeAction = "skip"
)

type ChangeClass

type ChangeClass string

ChangeClass groups changes by ownership/runtime expectations.

const (
	ChangeClassTrackedDocs      ChangeClass = "tracked_docs"
	ChangeClassGeneratedSurface ChangeClass = "generated_surface"
	ChangeClassRuntimeState     ChangeClass = "runtime_state"
	ChangeClassConfig           ChangeClass = "config"
)

type ChangePlan

type ChangePlan struct {
	Mode                 ChangePlanMode
	ProjectDir           string
	DocsDir              string
	BuiltAt              time.Time
	Reason               string
	FullRegeneration     bool
	FullRegenerationNote string
	Fingerprint          string
	Changes              []PlannedChange
	WorkspaceHints       []WorkspaceHint
	// contains filtered or unexported fields
}

ChangePlan is a reusable no-write preview for setup generate/update flows.

func BuildGeneratePlan

func BuildGeneratePlan(projectDir string, opts *GenerateOptions) (*ChangePlan, error)

BuildGeneratePlan computes a no-write plan for setup generate.

func BuildUpdatePlan

func BuildUpdatePlan(projectDir string, outputDir string) (*ChangePlan, error)

BuildUpdatePlan computes a no-write plan for setup update.

type ChangePlanMode

type ChangePlanMode string

ChangePlanMode identifies the setup flow that produced a plan.

const (
	ChangePlanModeGenerate ChangePlanMode = "generate"
	ChangePlanModeUpdate   ChangePlanMode = "update"
)

type ConventionSample

type ConventionSample struct {
	FileNaming    string   // Detected file naming pattern: snake_case, kebab-case, camelCase, PascalCase
	ErrorPatterns []string // Sampled error handling patterns from real code
	ImportStyle   string   // Grouped, ungrouped, aliased
	HasLinter     bool     // Whether a linter config exists
	LinterName    string   // Detected linter name
	HasFormatter  bool     // Whether a formatter config exists
	FormatterName string   // Detected formatter name
	ExampleFiles  []string // Paths of representative source files
}

ConventionSample holds detected code conventions from actual project files.

type DirEntry

type DirEntry struct {
	Name        string     // Directory name
	Path        string     // Relative path
	Description string     // Role description
	Children    []DirEntry // Subdirectories (max 3 levels)
}

DirEntry represents a directory in the project tree.

type DocSet

type DocSet struct {
	Index        string
	Commands     string
	Structure    string
	Conventions  string
	Boundaries   string
	Architecture string
	Testing      string
	Meta         Meta
}

DocSet holds all rendered documentation content.

func Generate

func Generate(projectDir string, opts *GenerateOptions) (*DocSet, error)

Generate creates all documentation files for the project.

func Render

func Render(info *ProjectInfo, opts *RenderOptions) *DocSet

Render generates all documentation files from ProjectInfo.

type EntryPoint

type EntryPoint struct {
	Path        string // File path relative to project root
	Description string // Brief description
}

EntryPoint represents a main entry point of the project.

type FileMeta

type FileMeta struct {
	ContentHash  string   `yaml:"content_hash"`
	SourceHashes []string `yaml:"source_hashes"`
}

FileMeta holds per-file metadata.

type FileStatus

type FileStatus struct {
	Exists  bool
	Fresh   bool
	ModTime time.Time
}

FileStatus represents the status of a single documentation file.

type Framework

type Framework struct {
	Name    string // Framework name (React, Gin, Django, etc.)
	Version string // Detected version
}

Framework represents a detected framework or toolkit.

type GenerateOptions

type GenerateOptions struct {
	OutputDir string
	Force     bool
	Render    *RenderOptions
	Config    *config.HarnessConfig // optional; controls sigmap generation
}

GenerateOptions holds options for document generation.

type Language

type Language struct {
	Name       string   // Language name (Go, TypeScript, Python, etc.)
	Version    string   // Detected version (from go.mod, package.json, etc.)
	BuildFiles []string // Associated build files
}

Language represents a detected programming language.

type Meta

type Meta struct {
	GeneratedAt    time.Time           `yaml:"generated_at"`
	AutopusVersion string              `yaml:"autopus_version"`
	ProjectHash    string              `yaml:"project_hash"`
	Files          map[string]FileMeta `yaml:"files"`
}

Meta holds generation metadata for .meta.yaml.

func LoadMeta

func LoadMeta(docsDir string) (*Meta, error)

LoadMeta loads .meta.yaml from the docs directory.

func NewMeta

func NewMeta(projectDir string) *Meta

NewMeta creates a Meta with current timestamp and version.

func NewMetaAt

func NewMetaAt(projectDir string, generatedAt time.Time) *Meta

NewMetaAt creates a Meta with a fixed timestamp for preview/apply reuse.

func (*Meta) HasContentChanged

func (m *Meta) HasContentChanged(docName, content string) bool

HasContentChanged checks if a document's content has changed.

func (*Meta) HasSourceChanged

func (m *Meta) HasSourceChanged(docName, projectDir string) bool

HasSourceChanged checks if any source files for a document have changed.

func (*Meta) SetFileMeta

func (m *Meta) SetFileMeta(docName, content string, sourceFiles []string, projectDir string)

SetFileMeta records content and source hashes for a document.

type MultiRepoInfo

type MultiRepoInfo struct {
	IsMultiRepo   bool
	WorkspaceRoot string
	Components    []RepoComponent
	Dependencies  []RepoDependency
}

MultiRepoInfo describes a workspace composed of multiple Git repositories.

func DetectMultiRepo

func DetectMultiRepo(dir string) *MultiRepoInfo

DetectMultiRepo scans the workspace root and its immediate child directories for Git repositories. Deeper recursive discovery remains out of scope here.

type PlannedChange

type PlannedChange struct {
	Path   string
	Action ChangeAction
	Class  ChangeClass
	Reason string
}

PlannedChange is a single preview entry in a no-write change plan.

type ProjectInfo

type ProjectInfo struct {
	Name        string
	RootDir     string
	Languages   []Language
	Frameworks  []Framework
	EntryPoints []EntryPoint
	BuildFiles  []BuildFile
	TestConfig  TestConfiguration
	Structure   []DirEntry                  // Top-level directory tree (max 3 levels)
	Conventions map[string]ConventionSample // Per-language convention samples
	Workspaces  []Workspace                 // Detected monorepo workspaces
	MultiRepo   *MultiRepoInfo              // Detected multi-repo workspace metadata
}

ProjectInfo holds all scanned information about a project.

func Scan

func Scan(projectDir string) (*ProjectInfo, error)

Scan analyzes a project directory and returns ProjectInfo.

type RenderOptions

type RenderOptions struct {
	ArchMap   *arch.ArchitectureMap
	LoreItems []lore.LoreEntry
}

RenderOptions holds optional data for rendering.

type RepoComponent

type RepoComponent struct {
	Name            string
	Path            string
	AbsPath         string
	RemoteURL       string
	PrimaryLanguage string
	ModulePath      string
	PackageName     string
	Role            string
}

RepoComponent represents a repository inside a multi-repo workspace.

func ScanRepoComponent

func ScanRepoComponent(dir string) (*RepoComponent, error)

ScanRepoComponent inspects a single repository.

type RepoDependency

type RepoDependency struct {
	Source  string
	Target  string
	Type    string
	Version string
}

RepoDependency represents a directed dependency between repositories.

func MapCrossRepoDeps

func MapCrossRepoDeps(components []RepoComponent) []RepoDependency

MapCrossRepoDeps derives repository edges from Go and package manifests.

type SetupConfig

type SetupConfig struct {
	AutoGenerate bool   `yaml:"auto_generate"`
	OutputDir    string `yaml:"output_dir"`
}

SetupConfig holds setup-specific configuration from autopus.yaml.

type Status

type Status struct {
	Exists       bool
	GeneratedAt  time.Time
	FileStatuses map[string]FileStatus
	DriftScore   float64
}

Status returns the documentation status.

func GetStatus

func GetStatus(projectDir string, outputDir string) (*Status, error)

GetStatus returns the current documentation status.

type TestConfiguration

type TestConfiguration struct {
	Framework  string   // Test framework name
	Command    string   // Test execution command
	Dirs       []string // Test directories
	CoverageOn bool     // Whether coverage is configured
}

TestConfiguration holds test framework and configuration details.

type ValidationReport

type ValidationReport struct {
	Valid      bool
	Warnings   []ValidationWarning
	DriftScore float64 // 0.0 = no drift, 1.0 = fully drifted
}

ValidationReport holds the result of document-code validation.

func Validate

func Validate(docsDir, projectDir string) (*ValidationReport, error)

Validate checks documentation against current project state.

type ValidationWarning

type ValidationWarning struct {
	File    string // Document file
	Line    int    // Line number (0 if unknown)
	Message string // Warning message
	Type    string // stale_path, stale_command, line_limit, missing_lang_id
}

ValidationWarning represents a single validation issue.

func ValidateCommands

func ValidateCommands(docsDir, projectDir string) []ValidationWarning

ValidateCommands checks that documented commands are still valid.

type Workspace

type Workspace struct {
	Name string // Workspace name or path
	Path string // Relative path to workspace root
	Type string // go.work, npm, cargo, pnpm, yarn
}

Workspace represents a monorepo workspace/module.

func DetectWorkspaces

func DetectWorkspaces(dir string) []Workspace

DetectWorkspaces scans for monorepo workspace configurations.

type WorkspaceHint

type WorkspaceHint struct {
	Kind          WorkspaceHintKind
	Repo          string
	SourceOfTruth string
	Message       string
}

WorkspaceHint exposes repo-aware context for bootstrap previews.

type WorkspaceHintKind

type WorkspaceHintKind string

WorkspaceHintKind identifies repo-aware context for preview/apply.

const (
	WorkspaceHintKindSingleRepo WorkspaceHintKind = "single_repo"
	WorkspaceHintKindWorkspace  WorkspaceHintKind = "workspace"
	WorkspaceHintKindMultiRepo  WorkspaceHintKind = "multi_repo"
)