workspace

Documentation

Overview

Package workspace provides configuration resolution utilities for docmgr.

Configuration management functions in this package handle the resolution of documentation workspace roots using a multi-level fallback chain:

1. --root flag (explicit command-line argument)
2. .ttmp.yaml in current directory
3. .ttmp.yaml in parent directories (walk up tree)
4. DOCMGR_ROOT environment variable
5. Git repository root: <git-root>/ttmp
6. Default: ttmp in current directory

See ResolveRoot() for the complete fallback logic.

Index

• func CollectTicketScaffoldsWithoutIndex(root string, skipDir func(relPath, baseName string) bool) ([]string, error)
• func DetectMultipleTTMPRoots() ([]string, error)
• func FindGitRoot() (string, error)
• func FindRepositoryRoot() (string, error)
• func FindTTMPConfigPath() (string, error)
• func ResolveRoot(root string) string
• func ResolveVocabularyPath() (string, error)
• func VerboseLog(format string, args ...interface{})
• type TTMPConfig
  • func LoadTTMPConfig() (*TTMPConfig, error)
• type TicketWorkspace
  • func CollectTicketWorkspaces(root string, skipDir func(relPath, baseName string) bool) ([]TicketWorkspace, error)
• type WorkspaceConfig
  • func LoadWorkspaceConfig() (*WorkspaceConfig, error)

Functions

func CollectTicketScaffoldsWithoutIndex

func CollectTicketScaffoldsWithoutIndex(root string, skipDir func(relPath, baseName string) bool) ([]string, error)

CollectTicketScaffoldsWithoutIndex finds directories that look like a ticket workspace (they contain scaffold subdirectories such as design/ or .meta/) but are missing index.md. The same skipDir predicate used in collectTicketWorkspaces can be provided to omit ignored paths.

func DetectMultipleTTMPRoots

func DetectMultipleTTMPRoots() ([]string, error)

DetectMultipleTTMPRoots walks up from CWD and records directories containing a 'ttmp' folder

func FindGitRoot

func FindGitRoot() (string, error)

FindGitRoot walks up from the current working directory to find the nearest .git directory

func FindRepositoryRoot

func FindRepositoryRoot() (string, error)

FindRepositoryRoot returns the best-effort repository root by preferring the git root, then falling back to markers like go.mod or doc/ as anchors.

func FindTTMPConfigPath

func FindTTMPConfigPath() (string, error)

FindTTMPConfigPath walks up from cwd to find .ttmp.yaml

func ResolveRoot

func ResolveRoot(root string) string

ResolveRoot applies config.Root if available and the provided root is the default ("ttmp").

The function uses a multi-level fallback chain to resolve the workspace root:

1. --root flag (if non-default and provided)
2. .ttmp.yaml config file (if found)
3. Git repository root: <git-root>/ttmp
4. Current working directory: <cwd>/ttmp

If DOCMGR_DEBUG is set, the function logs each step of the resolution process.

func ResolveVocabularyPath

func ResolveVocabularyPath() (string, error)

ResolveVocabularyPath returns the absolute path to the vocabulary file. Priority: 1) If .ttmp.yaml defines 'vocabulary', use it (relative to the config file if not absolute) 2) Else, use '<root>/vocabulary.yaml' where root comes from .ttmp.yaml (default 'ttmp' relative to config) 3) Else, search upwards for 'ttmp/vocabulary.yaml' 4) Finally, as a legacy fallback, search for 'doc/vocabulary.yaml'

func VerboseLog

func VerboseLog(format string, args ...interface{})

VerboseLog exposes verbose logging for other packages that need to honor DOCMGR_DEBUG.

Types

type TTMPConfig

type TTMPConfig = WorkspaceConfig

TTMPConfig is a deprecated alias for WorkspaceConfig. Use WorkspaceConfig instead.

Deprecated: Use WorkspaceConfig instead. This alias is maintained for backward compatibility and will be removed in a future version.

func LoadTTMPConfig

func LoadTTMPConfig() (*TTMPConfig, error)

LoadTTMPConfig is a deprecated alias for LoadWorkspaceConfig.

Deprecated: Use LoadWorkspaceConfig instead. This function is maintained for backward compatibility and will be removed in a future version.

type TicketWorkspace

type TicketWorkspace struct {
	Path           string
	Doc            *models.Document
	FrontmatterErr error
}

TicketWorkspace represents a discovered workspace directory and its metadata.

func CollectTicketWorkspaces

func CollectTicketWorkspaces(root string, skipDir func(relPath, baseName string) bool) ([]TicketWorkspace, error)

CollectTicketWorkspaces walks the docs root and returns directories that contain an index.md file with valid frontmatter. Directories whose base name starts with an underscore are ignored (for example, _templates, _guidelines). The optional skipDir predicate can be used to skip additional directories by relative path or base name.

type WorkspaceConfig

type WorkspaceConfig struct {
	Root     string `yaml:"root"`
	Defaults struct {
		Owners []string `yaml:"owners"`
		Intent string   `yaml:"intent"`
	} `yaml:"defaults"`
	FilenamePrefixPolicy string `yaml:"filenamePrefixPolicy"`
	Vocabulary           string `yaml:"vocabulary"`
}

WorkspaceConfig defines repository-level configuration for docmgr.

WorkspaceConfig holds settings for the documentation workspace, including the root directory path, default metadata values, vocabulary file location, and filename prefix policies.

Example config file (.ttmp.yaml):

root: ~/projects/myapp/docs
defaults:
  owners: [alice, bob]
  intent: long-term
vocabulary: ~/projects/myapp/docs/vocabulary.yaml
filenamePrefixPolicy: numeric

The root directory contains ticket workspaces organized by date:

root/
  2025/
    11/
      18/
        MEN-3475-add-feature/
          analysis/
          design-doc/
          playbook/

func LoadWorkspaceConfig

func LoadWorkspaceConfig() (*WorkspaceConfig, error)

LoadWorkspaceConfig loads the nearest .ttmp.yaml configuration file. Returns nil if no config file is found (not an error condition).

The function searches for .ttmp.yaml starting from the current directory and walking up the directory tree. Relative paths in the config are resolved relative to the config file's directory.

If DOCMGR_DEBUG is set, the function logs the config resolution path. If a config file exists but is malformed, a warning is printed to stderr.