articulate-parser/AGENTS.md

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

---

Go 1.24 & 1.25 New Features Reference

This project uses Go 1.24+. Below is a comprehensive summary of new features and changes in Go 1.24 and 1.25 that may be relevant for development and maintenance.

Go 1.24 Major Changes (Released February 2025)

Language Features

Generic Type Aliases

• Type aliases can now be parameterized with type parameters
• Example: type List[T any] = []T
• Can be disabled via GOEXPERIMENT=noaliastypeparams (removed in 1.25)

Tooling Enhancements

Module Tool Dependencies

• New tool directive in go.mod tracks executable dependencies
• Use go get -tool <package> to add tool dependencies
• Use go install tool and go get tool to manage them
• Eliminates need for blank imports in tools.go files

Build Output Formatting

• Both go build and go test support -json flag for structured JSON output
• New action types distinguish build output from test results

Authentication

• New GOAUTH environment variable provides flexible authentication for private modules

Automatic Version Tracking

• go build automatically sets main module version in binaries based on VCS tags
• Adds +dirty suffix for uncommitted changes

Cgo Performance Improvements

• New #cgo noescape annotation: Prevents escape analysis overhead for C function calls
• New #cgo nocallback annotation: Indicates C function won't call back to Go

Toolchain Tracing

• GODEBUG=toolchaintrace=1 enables tracing of toolchain selection

Runtime & Performance

Performance Improvements

• 2-3% CPU overhead reduction across benchmark suites
• New Swiss Tables-based map implementation (faster lookups)
  • Disable via GOEXPERIMENT=noswissmap
• More efficient small object allocation
• Redesigned runtime-internal mutexes
  • Disable via GOEXPERIMENT=nospinbitmutex

Compiler & Linker

Method Receiver Restrictions

• Methods on cgo-generated types now prevented (both directly and through aliases)

Build IDs

• Linkers generate GNU build IDs (ELF) and UUIDs (macOS) by default
• Disable via -B none flag

Standard Library Additions

File System Safety - os.Root

• New os.Root type enables directory-limited operations
• Prevents path escape and symlink breakouts
• Essential for sandboxed file operations

Cryptography Expansion

• crypto/mlkem: ML-KEM-768/1024 post-quantum key exchange (FIPS 203)
• crypto/hkdf: HMAC-based Extract-and-Expand KDF (RFC 5869)
• crypto/pbkdf2: Password-based key derivation (RFC 8018)
• crypto/sha3: SHA-3 and SHAKE functions (FIPS 202)

FIPS 140-3 Support

• New GOFIPS140 environment variable enables FIPS mode
• New fips140 GODEBUG setting for cryptographic module compliance

Weak References - weak Package

• New weak package provides low-level weak pointers
• Enables memory-efficient structures like weak maps and caches
• Useful for preventing memory leaks in cache implementations

Testing Improvements

• testing.B.Loop(): Cleaner syntax replacing manual b.N iteration
• Prevents compiler from optimizing away benchmarked code
• New testing/synctest package (experimental) for testing concurrent code with fake clocks

Iterator Support

• Multiple packages now offer iterator-returning variants:
  • bytes: Iterator-based functions
  • strings: Iterator-based functions
  • go/types: Iterator support

Security Enhancements

TLS Post-Quantum Cryptography

• X25519MLKEM768 hybrid key exchange enabled by default in TLS
• Provides quantum-resistant security

Encrypted Client Hello (ECH)

• TLS servers can enable ECH via Config.EncryptedClientHelloKeys
• Protects client identity during TLS handshake

RSA Key Validation

• Keys smaller than 1024 bits now rejected by default
• Use GODEBUG=rsa1024min=0 to revert (testing only)

Constant-Time Execution

• New crypto/subtle.WithDataIndependentTiming() enables architecture-specific timing guarantees
• Helps prevent timing attacks

Deprecations & Removals

• runtime.GOROOT(): Deprecated; use system path instead
• crypto/cipher OFB/CFB modes: Deprecated (unauthenticated encryption)
• x509sha1 GODEBUG: Removed; SHA-1 certificates no longer verified
• Experimental X25519Kyber768Draft00: Removed

Platform Changes

• Linux: Now requires kernel 3.2+ (enforced)
• macOS: Go 1.24 is final release supporting Big Sur
• Windows/ARM 32-bit: Marked broken
• WebAssembly:
  • New go:wasmexport directive
  • Reactor/library builds supported via -buildmode=c-shared

Bootstrap Requirements

• Go 1.24 requires Go 1.22.6+ for bootstrapping
• Go 1.26 will require Go 1.24+

---

Go 1.25 Major Changes (Released August 2025)

Language Changes

• No breaking language changes
• "Core types" concept removed from specification (replaced with clearer prose)

Tooling Improvements

Go Command Enhancements

• go build -asan: Now defaults to leak detection at program exit
• New go.mod ignore directive: Specify directories for go command to ignore
• go doc -http: Starts documentation server and opens in browser
• go version -m -json: Prints JSON-encoded BuildInfo structures
• Module path resolution now supports subdirectories using <meta> syntax
• New work package pattern matches all packages in work/workspace modules
• Removed automatic toolchain line additions when updating go version

Vet Analyzers

• "waitgroup": Detects misplaced sync.WaitGroup.Add calls
• "hostport": Warns against using fmt.Sprintf for constructing addresses
  • Recommends net.JoinHostPort instead

Runtime Enhancements

Container-Aware GOMAXPROCS

• Linux now respects cgroup CPU bandwidth limits
• All OSes periodically update GOMAXPROCS if CPU availability changes
• Disable via environment variables or GODEBUG settings
• Critical for containerized applications

New Garbage Collector - "Green Tea GC"

• Experimental GOEXPERIMENT=greenteagc enables new GC
• 10-40% reduction in garbage collection overhead
• Significant for GC-sensitive applications

Trace Flight Recorder

• New runtime/trace.FlightRecorder API
• Captures execution traces in in-memory ring buffer
• Essential for debugging rare events and production issues

Other Runtime Changes

• Simplified unhandled panic output
• VMA names on Linux identify memory purpose (debugging aid)
• New SetDefaultGOMAXPROCS function resets GOMAXPROCS to defaults

Compiler Fixes & Improvements

Critical Nil Pointer Bug Fix

• Fixed Go 1.21 regression where nil pointer checks were incorrectly delayed
• ⚠️ May cause previously passing code to now panic (correct behavior)
• Review code for assumptions about delayed nil checks

DWARF5 Support

• Debug information now uses DWARF version 5
• Reduces binary size and linking time
• Better debugging experience

Faster Slices

• Expanded stack allocation for slice backing stores
• Improved slice performance

Linker

• New -funcalign=N option specifies function entry alignment

Standard Library Highlights

New Packages

1. testing/synctest (Promoted from Experimental)

   • Concurrent code testing with virtualized time
   • Control time progression in tests
   • Essential for testing time-dependent concurrent code

2. encoding/json/v2 (Experimental)

   • Substantially better decoding performance
   • Improved API design
   • Backward compatible with v1

Major Package Updates

Package	Key Changes
crypto	New MessageSigner interface and SignMessage function
crypto/ecdsa	New raw key parsing/serialization functions
crypto/rsa	Key generation now 3x faster
crypto/sha1	Hashing 2x faster on amd64 with SHA-NI
crypto/tls	New CurveID field; SHA-1 algorithms disallowed in TLS 1.2
net	Windows now supports file-to-connection conversion; IPv6 multicast improvements
net/http	New CrossOriginProtection middleware for CSRF defense
os	Windows async I/O support; Root type expanded with 12 new methods
sync	New WaitGroup.Go method for convenient goroutine creation
testing	New Attr, Output methods; AllocsPerRun panics with parallel tests
unique	More eager and parallel reclamation of interned values

Performance Notes

Performance Improvements

• ECDSA and Ed25519 signing 4x faster in FIPS 140-3 mode
• SHA3 hashing 2x faster on Apple M processors
• AMD64 fused multiply-add instructions in v3+ mode
  • ⚠️ Changes floating-point results (within IEEE 754 spec)

Performance Regressions

• SHA-1, SHA-256, SHA-512 slower without AVX2
  • Most servers post-2015 support AVX2

Platform Changes

• macOS: Requires version 12 Monterey or later
• Windows: 32-bit windows/arm port marked for removal in Go 1.26
• Loong64: Race detector now supported
• RISC-V:
  • Plugin build mode support
  • New GORISCV64=rva23u64 environment variable value

Deprecations

• go/ast functions: FilterPackage, PackageExports, MergePackageFiles
• go/parser.ParseDir function
• Old testing/synctest API (when GOEXPERIMENT=synctest set)

---

Actionable Recommendations for This Project

Immediate Opportunities

1. Replace sync.WaitGroup patterns with WaitGroup.Go() (Go 1.25)

   // Old pattern
   wg.Add(1)
   go func() {
       defer wg.Done()
       // work
   }()
   
   // New pattern (Go 1.25)
   wg.Go(func() {
       // work
   })
   

2. Use testing.B.Loop() in benchmarks (Go 1.24)

   // Old pattern
   for i := 0; i < b.N; i++ {
       // benchmark code
   }
   
   // New pattern (Go 1.24)
   for b.Loop() {
       // benchmark code
   }
   

3. Consider os.Root for file operations (Go 1.24)

   • Prevents path traversal vulnerabilities
   • Safer for user-provided file paths

4. Enable Green Tea GC for testing (Go 1.25)

   • Test with GOEXPERIMENT=greenteagc
   • May reduce GC overhead by 10-40%

5. Leverage container-aware GOMAXPROCS (Go 1.25)

   • No changes needed; automatic in containers
   • Improves resource utilization

6. Review floating-point operations (Go 1.25)

   • AMD64 v3+ uses FMA instructions
   • May change floating-point results (within spec)

7. Watch nil pointer checks (Go 1.25)

   • Compiler bug fix may expose latent nil pointer bugs
   • Review crash reports carefully

Future Considerations

1. Evaluate encoding/json/v2 when stable

   • Better performance for JSON operations
   • Currently experimental in Go 1.25

2. Adopt tool directives in go.mod

   • Cleaner dependency management for build tools
   • Remove tools.go if present

3. Enable FIPS mode if required

   • Use GOFIPS140=1 for compliance
   • Performance improvements in Go 1.25 (4x faster signing)

4. Use runtime/trace.FlightRecorder for production debugging

   • Capture traces of rare events
   • Minimal overhead when not triggered