mirror of
https://github.com/kjanat/articulate-parser.git
synced 2026-01-16 08:22:09 +01:00
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.
This commit is contained in:
56
AGENTS.md
Normal file
56
AGENTS.md
Normal file
@ -0,0 +1,56 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user