chore: modernize workflows, security scanning, and linting configuration (#50)

* build: update Go 1.25, CI workflows, and build tooling - Upgrade to Go 1.25 - Add benchmark targets to Makefile - Implement parallel gosec execution - Lock tool versions for reproducibility - Add shellcheck directives to scripts - Update CI workflows with improved caching * refactor: migrate from golangci-lint to revive - Replace golangci-lint with revive for linting - Configure comprehensive revive rules - Fix all EditorConfig violations - Add yamllint and yamlfmt support - Remove deprecated .golangci.yml * refactor: rename utils to shared and deduplicate code - Rename utils package to shared - Add shared constants package - Deduplicate constants across packages - Address CodeRabbit review feedback * fix: resolve SonarQube issues and add safety guards - Fix all 73 SonarQube OPEN issues - Add nil guards for resourceMonitor, backpressure, metricsCollector - Implement io.Closer for headerFileReader - Propagate errors from processing helpers - Add metrics and templates packages - Improve error handling across codebase * test: improve test infrastructure and coverage - Add benchmarks for cli, fileproc, metrics - Improve test coverage for cli, fileproc, config - Refactor tests with helper functions - Add shared test constants - Fix test function naming conventions - Reduce cognitive complexity in benchmark tests * docs: update documentation and configuration examples - Update CLAUDE.md with current project state - Refresh README with new features - Add usage and configuration examples - Add SonarQube project configuration - Consolidate config.example.yaml * fix: resolve shellcheck warnings in scripts - Use ./*.go instead of *.go to prevent dash-prefixed filenames from being interpreted as options (SC2035) - Remove unreachable return statement after exit (SC2317) - Remove obsolete gibidiutils/ directory reference * chore(deps): upgrade go dependencies * chore(lint): megalinter fixes * fix: improve test coverage and fix file descriptor leaks - Add defer r.Close() to fix pipe file descriptor leaks in benchmark tests - Refactor TestProcessorConfigureFileTypes with helper functions and assertions - Refactor TestProcessorLogFinalStats with output capture and keyword verification - Use shared constants instead of literal strings (TestFilePNG, FormatMarkdown, etc.) - Reduce cognitive complexity by extracting helper functions * fix: align test comments with function names Remove underscores from test comments to match actual function names: - benchmark/benchmark_test.go (2 fixes) - fileproc/filetypes_config_test.go (4 fixes) - fileproc/filetypes_registry_test.go (6 fixes) - fileproc/processor_test.go (6 fixes) - fileproc/resource_monitor_types_test.go (4 fixes) - fileproc/writer_test.go (3 fixes) * fix: various test improvements and bug fixes - Remove duplicate maxCacheSize check in filetypes_registry_test.go - Shorten long comment in processor_test.go to stay under 120 chars - Remove flaky time.Sleep in collector_test.go, use >= 0 assertion - Close pipe reader in benchmark_test.go to fix file descriptor leak - Use ContinueOnError in flags_test.go to match ResetFlags behavior - Add nil check for p.ui in processor_workers.go before UpdateProgress - Fix resource_monitor_validation_test.go by setting hardMemoryLimitBytes directly * chore(yaml): add missing document start markers Add --- document start to YAML files to satisfy yamllint: - .github/workflows/codeql.yml - .github/workflows/build-test-publish.yml - .github/workflows/security.yml - .github/actions/setup/action.yml * fix: guard nil resourceMonitor and fix test deadlock - Guard resourceMonitor before CreateFileProcessingContext call - Add ui.UpdateProgress on emergency stop and path error returns - Fix potential deadlock in TestProcessFile using wg.Go with defer close
2026-02-20 18:52:05 +00:00 · 2025-12-10 19:07:11 +02:00
parent ea4a39a360
commit 95b7ef6dd3
149 changed files with 22990 additions and 8976 deletions
--- a/templates/engine.go
+++ b/templates/engine.go
@@ -0,0 +1,389 @@
+// Package templates provides templating engine functionality for output formatting.
+package templates
+
+import (
+	"bytes"
+	"fmt"
+	"path/filepath"
+	"strings"
+	"text/template"
+	"time"
+
+	"golang.org/x/text/cases"
+	"golang.org/x/text/language"
+
+	"github.com/ivuorinen/gibidify/shared"
+)
+
+// bufferBuilder wraps bytes.Buffer with error accumulation for robust error handling.
+type bufferBuilder struct {
+	buf *bytes.Buffer
+	err error
+}
+
+// newBufferBuilder creates a new buffer builder.
+func newBufferBuilder() *bufferBuilder {
+	return &bufferBuilder{buf: &bytes.Buffer{}}
+}
+
+// writeString writes a string, accumulating any errors.
+func (bb *bufferBuilder) writeString(s string) {
+	if bb.err != nil {
+		return
+	}
+	_, bb.err = bb.buf.WriteString(s)
+}
+
+// String returns the accumulated string, or empty string if there was an error.
+func (bb *bufferBuilder) String() string {
+	if bb.err != nil {
+		return ""
+	}
+	return bb.buf.String()
+}
+
+// Engine handles template processing and output generation.
+type Engine struct {
+	template OutputTemplate
+	context  TemplateContext
+}
+
+// NewEngine creates a new template engine with the specified template.
+func NewEngine(templateName string, context TemplateContext) (*Engine, error) {
+	tmpl, exists := BuiltinTemplates[templateName]
+	if !exists {
+		return nil, fmt.Errorf("template '%s' not found", templateName)
+	}
+
+	// Apply custom variables to context
+	if context.Variables == nil {
+		context.Variables = make(map[string]string)
+	}
+
+	// Merge template variables with context variables
+	for k, v := range tmpl.Variables {
+		if _, exists := context.Variables[k]; !exists {
+			context.Variables[k] = v
+		}
+	}
+
+	return &Engine{
+		template: tmpl,
+		context:  context,
+	}, nil
+}
+
+// NewEngineWithCustomTemplate creates a new template engine with a custom template.
+func NewEngineWithCustomTemplate(customTemplate OutputTemplate, context TemplateContext) *Engine {
+	if context.Variables == nil {
+		context.Variables = make(map[string]string)
+	}
+
+	// Merge template variables with context variables
+	for k, v := range customTemplate.Variables {
+		if _, exists := context.Variables[k]; !exists {
+			context.Variables[k] = v
+		}
+	}
+
+	return &Engine{
+		template: customTemplate,
+		context:  context,
+	}
+}
+
+// RenderHeader renders the template header.
+func (e *Engine) RenderHeader() (string, error) {
+	return e.renderTemplate(e.template.Header, e.context)
+}
+
+// RenderFooter renders the template footer.
+func (e *Engine) RenderFooter() (string, error) {
+	return e.renderTemplate(e.template.Footer, e.context)
+}
+
+// RenderFileHeader renders the file header for a specific file.
+func (e *Engine) RenderFileHeader(fileCtx FileContext) (string, error) {
+	return e.renderTemplate(e.template.FileHeader, fileCtx)
+}
+
+// RenderFileFooter renders the file footer for a specific file.
+func (e *Engine) RenderFileFooter(fileCtx FileContext) (string, error) {
+	return e.renderTemplate(e.template.FileFooter, fileCtx)
+}
+
+// RenderFileContent renders file content according to template options.
+func (e *Engine) RenderFileContent(fileCtx FileContext) (string, error) {
+	content := fileCtx.Content
+
+	// Apply markdown-specific formatting if needed
+	if e.template.Format == shared.FormatMarkdown && e.template.Markdown.UseCodeBlocks {
+		// Content is wrapped in code blocks via FileHeader/FileFooter
+		return content, nil
+	}
+
+	// Apply line length limits if specified
+	if e.template.Markdown.MaxLineLength > 0 {
+		content = e.wrapLongLines(content, e.template.Markdown.MaxLineLength)
+	}
+
+	// Apply folding for long files if enabled
+	if e.template.Markdown.FoldLongFiles && len(strings.Split(content, "\n")) > 100 {
+		lines := strings.Split(content, "\n")
+		if len(lines) > 100 {
+			content = strings.Join(lines[:50], "\n") + "\n\n<!-- ... " +
+				fmt.Sprintf("%d lines truncated", len(lines)-100) + " ... -->\n\n" +
+				strings.Join(lines[len(lines)-50:], "\n")
+		}
+	}
+
+	return content, nil
+}
+
+// RenderMetadata renders metadata based on template options.
+func (e *Engine) RenderMetadata() (string, error) {
+	if !e.hasAnyMetadata() {
+		return "", nil
+	}
+
+	buf := newBufferBuilder()
+
+	if e.template.Format == shared.FormatMarkdown {
+		buf.writeString("## Metadata\n\n")
+	}
+
+	if e.template.Metadata.IncludeTimestamp {
+		buf.writeString(fmt.Sprintf("**Generated**: %s\n", e.context.Timestamp.Format(shared.TemplateFmtTimestamp)))
+	}
+
+	if e.template.Metadata.IncludeSourcePath {
+		buf.writeString(fmt.Sprintf("**Source**: %s\n", e.context.SourcePath))
+	}
+
+	if e.template.Metadata.IncludeFileCount {
+		buf.writeString(
+			fmt.Sprintf(
+				"**Files**: %d total (%d processed, %d skipped, %d errors)\n",
+				e.context.TotalFiles, e.context.ProcessedFiles, e.context.SkippedFiles, e.context.ErrorFiles,
+			),
+		)
+	}
+
+	if e.template.Metadata.IncludeTotalSize {
+		buf.writeString(fmt.Sprintf("**Total Size**: %d bytes\n", e.context.TotalSize))
+	}
+
+	if e.template.Metadata.IncludeProcessingTime {
+		buf.writeString(fmt.Sprintf("**Processing Time**: %s\n", e.context.ProcessingTime))
+	}
+
+	if e.template.Metadata.IncludeMetrics && e.context.FilesPerSecond > 0 {
+		buf.writeString(
+			fmt.Sprintf(
+				"**Performance**: %.1f files/sec, %.1f MB/sec\n",
+				e.context.FilesPerSecond, e.context.BytesPerSecond/float64(shared.BytesPerMB),
+			),
+		)
+	}
+
+	if e.template.Metadata.IncludeFileTypes && len(e.context.FileTypes) > 0 {
+		buf.writeString("**File Types**:\n")
+		for fileType, count := range e.context.FileTypes {
+			buf.writeString(fmt.Sprintf("- %s: %d files\n", fileType, count))
+		}
+	}
+
+	buf.writeString("\n")
+
+	return buf.String(), nil
+}
+
+// RenderTableOfContents renders a table of contents if enabled.
+func (e *Engine) RenderTableOfContents(files []FileContext) (string, error) {
+	if !e.template.Markdown.TableOfContents {
+		return "", nil
+	}
+
+	buf := newBufferBuilder()
+	buf.writeString("## Table of Contents\n\n")
+
+	for _, file := range files {
+		// Create markdown anchor from file path
+		anchor := strings.ToLower(strings.ReplaceAll(file.RelativePath, "/", "-"))
+		anchor = strings.ReplaceAll(anchor, ".", "")
+		anchor = strings.ReplaceAll(anchor, " ", "-")
+
+		buf.writeString(fmt.Sprintf("- [%s](#%s)\n", file.RelativePath, anchor))
+	}
+
+	buf.writeString("\n")
+
+	return buf.String(), nil
+}
+
+// Template returns the current template.
+func (e *Engine) Template() OutputTemplate {
+	return e.template
+}
+
+// Context returns the current context.
+func (e *Engine) Context() TemplateContext {
+	return e.context
+}
+
+// renderTemplate renders a template string with the given context.
+func (e *Engine) renderTemplate(templateStr string, data any) (string, error) {
+	if templateStr == "" {
+		return "", nil
+	}
+
+	tmpl, err := template.New("template").Funcs(e.getTemplateFunctions()).Parse(templateStr)
+	if err != nil {
+		return "", fmt.Errorf("failed to parse template: %w", err)
+	}
+
+	var buf bytes.Buffer
+	if err := tmpl.Execute(&buf, data); err != nil {
+		return "", fmt.Errorf("failed to execute template: %w", err)
+	}
+
+	return buf.String(), nil
+}
+
+// getTemplateFunctions returns custom functions available in templates.
+func (e *Engine) getTemplateFunctions() template.FuncMap {
+	return template.FuncMap{
+		"formatSize": func(size int64) string {
+			return e.formatBytes(size)
+		},
+		"formatTime": func(t time.Time) string {
+			return t.Format(shared.TemplateFmtTimestamp)
+		},
+		"basename": filepath.Base,
+		"ext":      filepath.Ext,
+		"dir":      filepath.Dir,
+		"upper":    strings.ToUpper,
+		"lower":    strings.ToLower,
+		"title": func(s string) string {
+			return cases.Title(language.English).String(s)
+		},
+		"trim": strings.TrimSpace,
+		"replace": func(old, replacement, str string) string {
+			return strings.ReplaceAll(str, old, replacement)
+		},
+		"join": strings.Join,
+		"split": func(sep, str string) []string {
+			return strings.Split(str, sep)
+		},
+	}
+}
+
+// formatBytes formats byte counts in human-readable format.
+func (e *Engine) formatBytes(byteCount int64) string {
+	if byteCount == 0 {
+		return "0B"
+	}
+
+	if byteCount < shared.BytesPerKB {
+		return fmt.Sprintf(shared.MetricsFmtBytesShort, byteCount)
+	}
+
+	exp := 0
+	for n := byteCount / shared.BytesPerKB; n >= shared.BytesPerKB; n /= shared.BytesPerKB {
+		exp++
+	}
+
+	divisor := int64(1)
+	for i := 0; i < exp+1; i++ {
+		divisor *= shared.BytesPerKB
+	}
+
+	return fmt.Sprintf(shared.MetricsFmtBytesHuman, float64(byteCount)/float64(divisor), "KMGTPE"[exp])
+}
+
+// wrapLongLines wraps lines that exceed the specified length.
+func (e *Engine) wrapLongLines(content string, maxLength int) string {
+	lines := strings.Split(content, "\n")
+	var wrappedLines []string
+
+	for _, line := range lines {
+		wrappedLines = append(wrappedLines, e.wrapSingleLine(line, maxLength)...)
+	}
+
+	return strings.Join(wrappedLines, "\n")
+}
+
+// wrapSingleLine wraps a single line if it exceeds maxLength.
+func (e *Engine) wrapSingleLine(line string, maxLength int) []string {
+	if len(line) <= maxLength {
+		return []string{line}
+	}
+
+	return e.wrapLongLineWithWords(line, maxLength)
+}
+
+// wrapLongLineWithWords wraps a long line by breaking it into words.
+func (e *Engine) wrapLongLineWithWords(line string, maxLength int) []string {
+	words := strings.Fields(line)
+	var wrappedLines []string
+	var currentLine strings.Builder
+
+	for _, word := range words {
+		if e.wouldExceedLength(&currentLine, word, maxLength) {
+			if currentLine.Len() > 0 {
+				wrappedLines = append(wrappedLines, currentLine.String())
+				currentLine.Reset()
+			}
+		}
+
+		e.addWordToLine(&currentLine, word)
+	}
+
+	if currentLine.Len() > 0 {
+		wrappedLines = append(wrappedLines, currentLine.String())
+	}
+
+	return wrappedLines
+}
+
+// wouldExceedLength checks if adding a word would exceed the maximum length.
+func (e *Engine) wouldExceedLength(currentLine *strings.Builder, word string, maxLength int) bool {
+	return currentLine.Len()+len(word)+1 > maxLength
+}
+
+// addWordToLine adds a word to the current line with appropriate spacing.
+func (e *Engine) addWordToLine(currentLine *strings.Builder, word string) {
+	if currentLine.Len() > 0 {
+		// These errors are highly unlikely and would only occur in extreme memory conditions
+		// We intentionally ignore them as recovering would be complex and the impact minimal
+		_ = currentLine.WriteByte(' ')
+	}
+	// Similar rationale - memory exhaustion is the only realistic failure case
+	_, _ = currentLine.WriteString(word)
+}
+
+// hasAnyMetadata checks if any metadata options are enabled.
+func (e *Engine) hasAnyMetadata() bool {
+	m := e.template.Metadata
+
+	return m.IncludeStats || m.IncludeTimestamp || m.IncludeFileCount ||
+		m.IncludeSourcePath || m.IncludeFileTypes || m.IncludeProcessingTime ||
+		m.IncludeTotalSize || m.IncludeMetrics
+}
+
+// ListBuiltinTemplates returns a list of available builtin templates.
+func ListBuiltinTemplates() []string {
+	names := make([]string, 0, len(BuiltinTemplates))
+	for name := range BuiltinTemplates {
+		names = append(names, name)
+	}
+
+	return names
+}
+
+// BuiltinTemplate returns a builtin template by name.
+func BuiltinTemplate(name string) (OutputTemplate, bool) {
+	tmpl, exists := BuiltinTemplates[name]
+
+	return tmpl, exists
+}
--- a/templates/engine_test.go
+++ b/templates/engine_test.go
@@ -0,0 +1,540 @@
+package templates
+
+import (
+	"fmt"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/ivuorinen/gibidify/shared"
+)
+
+func TestNewEngine(t *testing.T) {
+	context := TemplateContext{
+		Timestamp:  time.Now(),
+		SourcePath: "/test/source",
+		Format:     "markdown",
+	}
+
+	engine, err := NewEngine("default", context)
+	if err != nil {
+		t.Fatalf(shared.TestMsgNewEngineFailed, err)
+	}
+
+	if engine == nil {
+		t.Fatal("Engine is nil")
+	}
+
+	if engine.template.Name != "Default" {
+		t.Errorf("Expected template name 'Default', got '%s'", engine.template.Name)
+	}
+}
+
+func TestNewEngineUnknownTemplate(t *testing.T) {
+	context := TemplateContext{}
+
+	_, err := NewEngine("nonexistent", context)
+	if err == nil {
+		t.Error("Expected error for unknown template")
+	}
+
+	if !strings.Contains(err.Error(), "template 'nonexistent' not found") {
+		t.Errorf("Unexpected error message: %v", err)
+	}
+}
+
+func TestNewEngineWithCustomTemplate(t *testing.T) {
+	customTemplate := OutputTemplate{
+		Name:        "Custom",
+		Description: "Custom template",
+		Format:      "markdown",
+		Header:      "# Custom Header",
+		Footer:      "Custom Footer",
+	}
+
+	context := TemplateContext{
+		SourcePath: "/test",
+	}
+
+	engine := NewEngineWithCustomTemplate(customTemplate, context)
+
+	if engine == nil {
+		t.Fatal("Engine is nil")
+	}
+
+	if engine.template.Name != "Custom" {
+		t.Errorf("Expected template name 'Custom', got '%s'", engine.template.Name)
+	}
+}
+
+func TestRenderHeader(t *testing.T) {
+	context := TemplateContext{
+		Timestamp:  time.Date(2023, 12, 25, 10, 0, 0, 0, time.UTC),
+		SourcePath: shared.TestPathTestProject,
+		Format:     "markdown",
+	}
+
+	engine, err := NewEngine("default", context)
+	if err != nil {
+		t.Fatalf(shared.TestMsgNewEngineFailed, err)
+	}
+
+	header, err := engine.RenderHeader()
+	if err != nil {
+		t.Fatalf("RenderHeader failed: %v", err)
+	}
+
+	if !strings.Contains(header, shared.TestPathTestProject) {
+		t.Errorf("Header should contain source path, got: %s", header)
+	}
+
+	if !strings.Contains(header, "2023-12-25") {
+		t.Errorf("Header should contain timestamp, got: %s", header)
+	}
+}
+
+func TestRenderFooter(t *testing.T) {
+	engine, err := NewEngine("default", TemplateContext{})
+	if err != nil {
+		t.Fatalf(shared.TestMsgNewEngineFailed, err)
+	}
+
+	footer, err := engine.RenderFooter()
+	if err != nil {
+		t.Fatalf("RenderFooter failed: %v", err)
+	}
+
+	if !strings.Contains(footer, "gibidify") {
+		t.Errorf("Footer should contain 'gibidify', got: %s", footer)
+	}
+}
+
+func TestRenderFileHeader(t *testing.T) {
+	engine, err := NewEngine("default", TemplateContext{})
+	if err != nil {
+		t.Fatalf(shared.TestMsgNewEngineFailed, err)
+	}
+
+	fileCtx := FileContext{
+		Path:         shared.TestPathTestFileGo,
+		RelativePath: shared.TestFileGoExt,
+		Name:         shared.TestFileGoExt,
+		Language:     "go",
+		Size:         1024,
+	}
+
+	header, err := engine.RenderFileHeader(fileCtx)
+	if err != nil {
+		t.Fatalf("RenderFileHeader failed: %v", err)
+	}
+
+	if !strings.Contains(header, shared.TestFileGoExt) {
+		t.Errorf("File header should contain filename, got: %s", header)
+	}
+
+	if !strings.Contains(header, "```go") {
+		t.Errorf("File header should contain language code block, got: %s", header)
+	}
+}
+
+func TestRenderFileFooter(t *testing.T) {
+	engine, err := NewEngine("default", TemplateContext{})
+	if err != nil {
+		t.Fatalf(shared.TestMsgNewEngineFailed, err)
+	}
+
+	fileCtx := FileContext{
+		Path: shared.TestPathTestFileGo,
+	}
+
+	footer, err := engine.RenderFileFooter(fileCtx)
+	if err != nil {
+		t.Fatalf("RenderFileFooter failed: %v", err)
+	}
+
+	if !strings.Contains(footer, "```") {
+		t.Errorf("File footer should contain code block close, got: %s", footer)
+	}
+}
+
+func TestRenderFileContentBasic(t *testing.T) {
+	engine, err := NewEngine("default", TemplateContext{})
+	if err != nil {
+		t.Fatalf(shared.TestMsgNewEngineFailed, err)
+	}
+
+	fileCtx := FileContext{
+		Content: "package main\n\nfunc main() {\n    fmt.Println(\"hello\")\n}",
+	}
+
+	content, err := engine.RenderFileContent(fileCtx)
+	if err != nil {
+		t.Fatalf(shared.TestMsgRenderFileContentFailed, err)
+	}
+
+	if content != fileCtx.Content {
+		t.Errorf("Content should be unchanged for basic case, got: %s", content)
+	}
+}
+
+func TestRenderFileContentLongLines(t *testing.T) {
+	customTemplate := OutputTemplate{
+		Format: "markdown",
+		Markdown: MarkdownOptions{
+			MaxLineLength: 20,
+		},
+	}
+
+	engine := NewEngineWithCustomTemplate(customTemplate, TemplateContext{})
+
+	fileCtx := FileContext{
+		Content: "this is a very long line that should be wrapped",
+	}
+
+	content, err := engine.RenderFileContent(fileCtx)
+	if err != nil {
+		t.Fatalf(shared.TestMsgRenderFileContentFailed, err)
+	}
+
+	lines := strings.Split(content, "\n")
+	for _, line := range lines {
+		if len(line) > 20 {
+			t.Errorf("Line length should not exceed 20 characters, got line: %s (len=%d)", line, len(line))
+		}
+	}
+}
+
+func TestRenderFileContentFoldLongFiles(t *testing.T) {
+	customTemplate := OutputTemplate{
+		Format: "markdown",
+		Markdown: MarkdownOptions{
+			FoldLongFiles: true,
+		},
+	}
+
+	engine := NewEngineWithCustomTemplate(customTemplate, TemplateContext{})
+
+	// Create content with more than 100 lines
+	lines := make([]string, 150)
+	for i := range lines {
+		lines[i] = fmt.Sprintf("line %d", i+1)
+	}
+
+	fileCtx := FileContext{
+		Content: strings.Join(lines, "\n"),
+	}
+
+	content, err := engine.RenderFileContent(fileCtx)
+	if err != nil {
+		t.Fatalf(shared.TestMsgRenderFileContentFailed, err)
+	}
+
+	if !strings.Contains(content, "lines truncated") {
+		t.Error("Content should contain truncation message")
+	}
+}
+
+func TestRenderMetadata(t *testing.T) {
+	context := TemplateContext{
+		Timestamp:      time.Date(2023, 12, 25, 10, 0, 0, 0, time.UTC),
+		SourcePath:     shared.TestPathTestProject,
+		TotalFiles:     10,
+		ProcessedFiles: 8,
+		SkippedFiles:   1,
+		ErrorFiles:     1,
+		TotalSize:      1024000,
+		ProcessingTime: "2.5s",
+		FilesPerSecond: 3.2,
+		BytesPerSecond: 409600,
+		FileTypes: map[string]int{
+			"go":   5,
+			"js":   3,
+			"yaml": 2,
+		},
+	}
+
+	engine, err := NewEngine("detailed", context)
+	if err != nil {
+		t.Fatalf(shared.TestMsgNewEngineFailed, err)
+	}
+
+	metadata, err := engine.RenderMetadata()
+	if err != nil {
+		t.Fatalf("RenderMetadata failed: %v", err)
+	}
+
+	if !strings.Contains(metadata, "2023-12-25") {
+		t.Error("Metadata should contain timestamp")
+	}
+
+	if !strings.Contains(metadata, shared.TestPathTestProject) {
+		t.Error("Metadata should contain source path")
+	}
+
+	if !strings.Contains(metadata, "10 total") {
+		t.Error("Metadata should contain file count")
+	}
+
+	if !strings.Contains(metadata, "1024000 bytes") {
+		t.Error("Metadata should contain total size")
+	}
+
+	if !strings.Contains(metadata, "2.5s") {
+		t.Error("Metadata should contain processing time")
+	}
+
+	if !strings.Contains(metadata, "3.2 files/sec") {
+		t.Error("Metadata should contain performance metrics")
+	}
+
+	if !strings.Contains(metadata, "go: 5 files") {
+		t.Error("Metadata should contain file types")
+	}
+}
+
+func TestRenderTableOfContents(t *testing.T) {
+	engine, err := NewEngine("detailed", TemplateContext{})
+	if err != nil {
+		t.Fatalf(shared.TestMsgNewEngineFailed, err)
+	}
+
+	files := []FileContext{
+		{RelativePath: "main.go"},
+		{RelativePath: "utils/helper.go"},
+		{RelativePath: "config.yaml"},
+	}
+
+	toc, err := engine.RenderTableOfContents(files)
+	if err != nil {
+		t.Fatalf("RenderTableOfContents failed: %v", err)
+	}
+
+	if !strings.Contains(toc, "Table of Contents") {
+		t.Error("TOC should contain header")
+	}
+
+	if !strings.Contains(toc, "[main.go]") {
+		t.Error("TOC should contain main.go link")
+	}
+
+	if !strings.Contains(toc, "[utils/helper.go]") {
+		t.Error("TOC should contain utils/helper.go link")
+	}
+
+	if !strings.Contains(toc, "[config.yaml]") {
+		t.Error("TOC should contain config.yaml link")
+	}
+}
+
+func TestRenderTableOfContentsDisabled(t *testing.T) {
+	engine, err := NewEngine("default", TemplateContext{})
+	if err != nil {
+		t.Fatalf(shared.TestMsgNewEngineFailed, err)
+	}
+
+	files := []FileContext{{RelativePath: "test.go"}}
+
+	toc, err := engine.RenderTableOfContents(files)
+	if err != nil {
+		t.Fatalf("RenderTableOfContents failed: %v", err)
+	}
+
+	if toc != "" {
+		t.Errorf("TOC should be empty when disabled, got: %s", toc)
+	}
+}
+
+func TestTemplateFunctions(t *testing.T) {
+	engine, err := NewEngine("default", TemplateContext{})
+	if err != nil {
+		t.Fatalf(shared.TestMsgNewEngineFailed, err)
+	}
+
+	testCases := []struct {
+		name     string
+		template string
+		context  any
+		expected string
+	}{
+		{
+			name:     "formatSize",
+			template: "{{formatSize .Size}}",
+			context:  struct{ Size int64 }{Size: 1024},
+			expected: "1.0KB",
+		},
+		{
+			name:     "basename",
+			template: "{{basename .Path}}",
+			context:  struct{ Path string }{Path: shared.TestPathTestFileGo},
+			expected: shared.TestFileGoExt,
+		},
+		{
+			name:     "ext",
+			template: "{{ext .Path}}",
+			context:  struct{ Path string }{Path: shared.TestPathTestFileGo},
+			expected: ".go",
+		},
+		{
+			name:     "upper",
+			template: "{{upper .Text}}",
+			context:  struct{ Text string }{Text: "hello"},
+			expected: "HELLO",
+		},
+		{
+			name:     "lower",
+			template: "{{lower .Text}}",
+			context:  struct{ Text string }{Text: "HELLO"},
+			expected: "hello",
+		},
+	}
+
+	for _, tc := range testCases {
+		t.Run(
+			tc.name, func(t *testing.T) {
+				result, err := engine.renderTemplate(tc.template, tc.context)
+				if err != nil {
+					t.Fatalf("Template rendering failed: %v", err)
+				}
+
+				if result != tc.expected {
+					t.Errorf("Expected %q, got %q", tc.expected, result)
+				}
+			},
+		)
+	}
+}
+
+func TestListBuiltinTemplates(t *testing.T) {
+	templates := ListBuiltinTemplates()
+
+	if len(templates) == 0 {
+		t.Error("Should have builtin templates")
+	}
+
+	expectedTemplates := []string{"default", "minimal", "detailed", "compact"}
+	for _, expected := range expectedTemplates {
+		found := false
+		for _, tmpl := range templates {
+			if tmpl == expected {
+				found = true
+
+				break
+			}
+		}
+		if !found {
+			t.Errorf("Expected template %s not found in list", expected)
+		}
+	}
+}
+
+func TestBuiltinTemplate(t *testing.T) {
+	tmpl, exists := BuiltinTemplate("default")
+	if !exists {
+		t.Error("Default template should exist")
+	}
+
+	if tmpl.Name != "Default" {
+		t.Errorf("Expected name 'Default', got %s", tmpl.Name)
+	}
+
+	_, exists = BuiltinTemplate("nonexistent")
+	if exists {
+		t.Error("Nonexistent template should not exist")
+	}
+}
+
+func TestFormatBytes(t *testing.T) {
+	engine, err := NewEngine("default", TemplateContext{})
+	if err != nil {
+		t.Fatalf(shared.TestMsgNewEngineFailed, err)
+	}
+
+	testCases := []struct {
+		bytes    int64
+		expected string
+	}{
+		{0, "0B"},
+		{512, "512B"},
+		{1024, "1.0KB"},
+		{1536, "1.5KB"},
+		{1024 * 1024, "1.0MB"},
+		{5 * 1024 * 1024 * 1024, "5.0GB"},
+	}
+
+	for _, tc := range testCases {
+		t.Run(
+			tc.expected, func(t *testing.T) {
+				result := engine.formatBytes(tc.bytes)
+				if result != tc.expected {
+					t.Errorf("formatBytes(%d) = %s, want %s", tc.bytes, result, tc.expected)
+				}
+			},
+		)
+	}
+}
+
+// validateTemplateRendering validates all template rendering functions for a given engine.
+func validateTemplateRendering(t *testing.T, engine *Engine, name string) {
+	t.Helper()
+
+	// Test header rendering
+	_, err := engine.RenderHeader()
+	if err != nil {
+		t.Errorf("Failed to render header for template %s: %v", name, err)
+	}
+
+	// Test footer rendering
+	_, err = engine.RenderFooter()
+	if err != nil {
+		t.Errorf("Failed to render footer for template %s: %v", name, err)
+	}
+
+	// Test file rendering
+	validateFileRendering(t, engine, name)
+}
+
+// validateFileRendering validates file header and footer rendering for a given engine.
+func validateFileRendering(t *testing.T, engine *Engine, name string) {
+	t.Helper()
+
+	fileCtx := FileContext{
+		Path:         "/test.go",
+		RelativePath: "test.go",
+		Language:     "go",
+		Size:         100,
+	}
+
+	// Test file header rendering
+	_, err := engine.RenderFileHeader(fileCtx)
+	if err != nil {
+		t.Errorf("Failed to render file header for template %s: %v", name, err)
+	}
+
+	// Test file footer rendering
+	_, err = engine.RenderFileFooter(fileCtx)
+	if err != nil {
+		t.Errorf("Failed to render file footer for template %s: %v", name, err)
+	}
+}
+
+func TestBuiltinTemplatesIntegrity(t *testing.T) {
+	// Test that all builtin templates are valid and can be used
+	context := TemplateContext{
+		Timestamp:  time.Now(),
+		SourcePath: "/test",
+		Format:     "markdown",
+	}
+
+	for name := range BuiltinTemplates {
+		t.Run(
+			name, func(t *testing.T) {
+				engine, err := NewEngine(name, context)
+				if err != nil {
+					t.Fatalf("Failed to create engine for template %s: %v", name, err)
+				}
+
+				validateTemplateRendering(t, engine, name)
+			},
+		)
+	}
+}
--- a/templates/types.go
+++ b/templates/types.go
@@ -0,0 +1,222 @@
+// Package templates provides output formatting templates and customization options.
+package templates
+
+import (
+	"time"
+
+	"github.com/ivuorinen/gibidify/shared"
+)
+
+// OutputTemplate represents a customizable output template.
+type OutputTemplate struct {
+	Name        string            `json:"name"        yaml:"name"`
+	Description string            `json:"description" yaml:"description"`
+	Format      string            `json:"format"      yaml:"format"` // markdown, json, yaml
+	Header      string            `json:"header"      yaml:"header"`
+	Footer      string            `json:"footer"      yaml:"footer"`
+	FileHeader  string            `json:"file_header" yaml:"file_header"`
+	FileFooter  string            `json:"file_footer" yaml:"file_footer"`
+	Metadata    MetadataOptions   `json:"metadata"    yaml:"metadata"`
+	Markdown    MarkdownOptions   `json:"markdown"    yaml:"markdown"`
+	Variables   map[string]string `json:"variables"   yaml:"variables"`
+}
+
+// MetadataOptions controls what metadata to include in the output.
+type MetadataOptions struct {
+	IncludeStats          bool `json:"include_stats"           yaml:"include_stats"`
+	IncludeTimestamp      bool `json:"include_timestamp"       yaml:"include_timestamp"`
+	IncludeFileCount      bool `json:"include_file_count"      yaml:"include_file_count"`
+	IncludeSourcePath     bool `json:"include_source_path"     yaml:"include_source_path"`
+	IncludeFileTypes      bool `json:"include_file_types"      yaml:"include_file_types"`
+	IncludeProcessingTime bool `json:"include_processing_time" yaml:"include_processing_time"`
+	IncludeTotalSize      bool `json:"include_total_size"      yaml:"include_total_size"`
+	IncludeMetrics        bool `json:"include_metrics"         yaml:"include_metrics"`
+}
+
+// MarkdownOptions controls markdown-specific formatting.
+type MarkdownOptions struct {
+	UseCodeBlocks      bool   `json:"use_code_blocks"     yaml:"use_code_blocks"`
+	IncludeLanguage    bool   `json:"include_language"    yaml:"include_language"`
+	HeaderLevel        int    `json:"header_level"        yaml:"header_level"` // 1-6 for # levels
+	TableOfContents    bool   `json:"table_of_contents"   yaml:"table_of_contents"`
+	UseCollapsible     bool   `json:"use_collapsible"     yaml:"use_collapsible"`
+	SyntaxHighlighting bool   `json:"syntax_highlighting" yaml:"syntax_highlighting"`
+	LineNumbers        bool   `json:"line_numbers"        yaml:"line_numbers"`
+	FoldLongFiles      bool   `json:"fold_long_files"     yaml:"fold_long_files"`
+	MaxLineLength      int    `json:"max_line_length"     yaml:"max_line_length"`
+	CustomCSS          string `json:"custom_css"          yaml:"custom_css"`
+}
+
+// TemplateContext provides data available for template substitution.
+type TemplateContext struct {
+	// Basic information
+	Timestamp  time.Time `json:"timestamp"`
+	SourcePath string    `json:"source_path"`
+	Format     string    `json:"format"`
+
+	// File statistics
+	TotalFiles     int   `json:"total_files"`
+	ProcessedFiles int   `json:"processed_files"`
+	SkippedFiles   int   `json:"skipped_files"`
+	ErrorFiles     int   `json:"error_files"`
+	TotalSize      int64 `json:"total_size"`
+
+	// Processing metrics
+	ProcessingTime string         `json:"processing_time"`
+	FilesPerSecond float64        `json:"files_per_second"`
+	BytesPerSecond float64        `json:"bytes_per_second"`
+	FileTypes      map[string]int `json:"file_types"`
+
+	// Custom variables
+	Variables map[string]string `json:"variables"`
+}
+
+// FileContext provides data for individual file formatting.
+type FileContext struct {
+	Path         string    `json:"path"`
+	RelativePath string    `json:"relative_path"`
+	Name         string    `json:"name"`
+	Extension    string    `json:"extension"`
+	Language     string    `json:"language"`
+	Size         int64     `json:"size"`
+	ModTime      time.Time `json:"mod_time"`
+	Content      string    `json:"content"`
+	LineCount    int       `json:"line_count"`
+	IsLarge      bool      `json:"is_large"`
+	Truncated    bool      `json:"truncated"`
+}
+
+// BuiltinTemplates contains predefined templates.
+var BuiltinTemplates = map[string]OutputTemplate{
+	"default": {
+		Name:        "Default",
+		Description: "Standard output template",
+		Format:      shared.FormatMarkdown,
+		Header:      "# {{.SourcePath}}\n\nGenerated on {{.Timestamp.Format \"2006-01-02 15:04:05\"}}\n",
+		Footer:      "\n---\nGenerated by gibidify\n",
+		FileHeader:  "## {{.Path}}\n\n```{{.Language}}\n",
+		FileFooter:  "```\n\n",
+		Metadata: MetadataOptions{
+			IncludeStats:      true,
+			IncludeTimestamp:  true,
+			IncludeFileCount:  true,
+			IncludeSourcePath: true,
+		},
+		Markdown: MarkdownOptions{
+			UseCodeBlocks:      true,
+			IncludeLanguage:    true,
+			HeaderLevel:        2,
+			SyntaxHighlighting: true,
+		},
+	},
+	"minimal": {
+		Name:        "Minimal",
+		Description: "Minimal output with just file contents",
+		Format:      shared.FormatMarkdown,
+		Header:      "",
+		Footer:      "",
+		FileHeader:  "<!-- {{.Path}} -->\n",
+		FileFooter:  "\n",
+		Metadata: MetadataOptions{
+			IncludeStats:      false,
+			IncludeTimestamp:  false,
+			IncludeFileCount:  false,
+			IncludeSourcePath: false,
+		},
+		Markdown: MarkdownOptions{
+			UseCodeBlocks:   false,
+			IncludeLanguage: false,
+		},
+	},
+	"detailed": {
+		Name:        "Detailed",
+		Description: "Comprehensive output with full metadata",
+		Format:      shared.FormatMarkdown,
+		Header: `# Project Analysis: {{.SourcePath}}
+
+Generated on {{.Timestamp.Format "January 2, 2006 at 3:04 PM"}}
+
+## Summary
+
+- **Total Files**: {{.TotalFiles}}
+- **Processed Files**: {{.ProcessedFiles}}
+- **Total Size**: {{.TotalSize}} bytes
+- **Processing Time**: {{.ProcessingTime}}
+- **Rate**: {{.FilesPerSecond}} files/sec
+
+`,
+		Footer: "\n---\n*Generated by gibidify*\n",
+		FileHeader: "### {{.RelativePath}}\n\n**Language**: {{.Language}}  \n" +
+			"**Size**: {{.Size}} bytes  \n**Lines**: {{.LineCount}}  \n\n```{{.Language}}\n",
+		FileFooter: "```\n\n",
+		Metadata: MetadataOptions{
+			IncludeStats:          true,
+			IncludeTimestamp:      true,
+			IncludeFileCount:      true,
+			IncludeSourcePath:     true,
+			IncludeFileTypes:      true,
+			IncludeProcessingTime: true,
+			IncludeTotalSize:      true,
+			IncludeMetrics:        true,
+		},
+		Markdown: MarkdownOptions{
+			UseCodeBlocks:      true,
+			IncludeLanguage:    true,
+			HeaderLevel:        3,
+			TableOfContents:    true,
+			SyntaxHighlighting: true,
+			LineNumbers:        false,
+		},
+	},
+	"compact": {
+		Name:        "Compact",
+		Description: "Space-efficient output with collapsible sections",
+		Format:      shared.FormatMarkdown,
+		Header: "# {{.SourcePath}}\n\n<details><summary>📊 Stats ({{.TotalFiles}} files)</summary>\n\n" +
+			"- Processed: {{.ProcessedFiles}}\n- Size: {{.TotalSize}} bytes\n" +
+			"- Time: {{.ProcessingTime}}\n\n</details>\n\n",
+		Footer:     "\n---\n*Compressed with gibidify*\n",
+		FileHeader: "<details><summary>📄 {{.RelativePath}} ({{.Size}} bytes)</summary>\n\n```{{.Language}}\n",
+		FileFooter: "```\n\n</details>\n\n",
+		Metadata: MetadataOptions{
+			IncludeStats:     true,
+			IncludeFileCount: true,
+			IncludeTotalSize: true,
+		},
+		Markdown: MarkdownOptions{
+			UseCodeBlocks:      true,
+			IncludeLanguage:    true,
+			UseCollapsible:     true,
+			SyntaxHighlighting: true,
+		},
+	},
+}
+
+// DefaultMetadataOptions returns the default metadata options.
+func DefaultMetadataOptions() MetadataOptions {
+	return MetadataOptions{
+		IncludeStats:          true,
+		IncludeTimestamp:      true,
+		IncludeFileCount:      true,
+		IncludeSourcePath:     true,
+		IncludeFileTypes:      false,
+		IncludeProcessingTime: false,
+		IncludeTotalSize:      false,
+		IncludeMetrics:        false,
+	}
+}
+
+// DefaultMarkdownOptions returns the default markdown options.
+func DefaultMarkdownOptions() MarkdownOptions {
+	return MarkdownOptions{
+		UseCodeBlocks:      true,
+		IncludeLanguage:    true,
+		HeaderLevel:        2,
+		TableOfContents:    false,
+		UseCollapsible:     false,
+		SyntaxHighlighting: true,
+		LineNumbers:        false,
+		FoldLongFiles:      false,
+		MaxLineLength:      120,
+	}
+}