kjanat/articulate-parser
1
0
Fork 0
mirror of https://github.com/kjanat/articulate-parser.git synced 2026-01-16 08:22:09 +01:00
Code Issues Packages Projects Releases Wiki Activity
Files
e7de5d044a6ca6c17abd2127410db6e31be4eaf1
articulate-parser/AGENTS.md
Kaj Kowalski bd308e4dfc refactor(exporter): rewrite HTML exporter to use Go templates 
Replaces the manual string-building implementation of the HTML exporter with a more robust and maintainable solution using Go's `html/template` package. This improves readability, security, and separation of concerns.

- HTML structure and CSS styles are moved into their own files and embedded into the binary using `go:embed`.
- A new data preparation layer adapts the course model for the template, simplifying rendering logic.
- Tests are updated to reflect the new implementation, removing obsolete test cases for the old string-building methods.

Additionally, this commit:
- Adds an `AGENTS.md` file with development and contribution guidelines.
- Updates `.golangci.yml` to allow standard Go patterns for interface package naming.
2025-11-07 06:33:38 +01:00

2.2 KiB
Raw Blame History

Agent Guidelines for articulate-parser

Build/Test Commands

  • Build: task build or go build -o bin/articulate-parser main.go
  • Run tests: task test or go test -race -timeout 5m ./...
  • Run single test: go test -v -race -run ^TestName$ ./path/to/package
  • Test with coverage:
    • task test:coverage or
    • go test -race -coverprofile=coverage/coverage.out -covermode=atomic ./...
  • Lint: task lint (runs vet, fmt check, staticcheck, golangci-lint)
  • Format: task fmt or gofmt -s -w .
  • CI checks: task ci (deps, lint, test with coverage, build)

Code Style Guidelines

Imports

  • Use goimports with local prefix: github.com/kjanat/articulate-parser
  • Order: stdlib, external, internal packages
  • Group related imports together

Formatting

  • Use gofmt -s (simplify) and gofumpt with extra rules
  • Function length: max 100 lines, 50 statements
  • Cyclomatic complexity: max 15
  • Cognitive complexity: max 20

Types & Naming

  • Use interface-based design (see internal/interfaces/)
  • Export types/functions with clear godoc comments ending with period
  • Use descriptive names: ArticulateParser, MarkdownExporter
  • Receiver names: short (1-2 chars), consistent per type

Error Handling

  • Always wrap errors with context: fmt.Errorf("operation failed: %w", err)
  • Use %w verb for error wrapping to preserve error chain
  • Check all error returns (enforced by errcheck)
  • Document error handling rationale in defer blocks when ignoring close errors

Comments

  • All exported types/functions require godoc comments
  • End sentences with periods (godot linter enforced)
  • Mark known issues with TODO/FIXME/HACK/BUG/XXX

Security

  • Use #nosec with justification for deliberate security exceptions (G304 for CLI file paths, G306 for export file permissions)
  • Run gosec and govulncheck for security audits

Testing

  • Enable race detection: -race flag
  • Use table-driven tests where applicable
  • Mark test helpers with t.Helper()
  • Benchmarks in *_bench_test.go, examples in *_example_test.go

Dependencies

  • Minimal external dependencies (currently: go-docx, golang.org/x/net, golang.org/x/text)
  • Run task deps:tidy after adding/removing dependencies