go

Instruction file imported from zenbase-ai/llml (.cursor/rules/go.mdc). Copyright stays with the author.

Go Coding Rules for LLML Project

Project Structure

The project follows a standard and clean structure for a Go library.

• go.mod, go.sum: Reside at the root of the Go project (go/). All dependency management should be handled here.
• pkg/: Contains the core library code. The main package is llml (go/pkg/llml/). Any new library code should be placed within the pkg/ directory.
• tests/: Contains the integration and unit tests. Tests are in a separate _test package (e.g., llml_test), which is a best practice for testing only the exported API of a package.
• README.md: A dedicated README for the Go implementation exists and should be updated with any new features, API changes, or usage instructions.

Dependencies

• Main Library: The core library in pkg/ has zero external dependencies and relies only on the Go standard library. This should be maintained to keep the library lightweight and easy to integrate.
• Testing: Tests use github.com/stretchr/testify/assert for assertions. This is the only development dependency and should be used for all new tests to maintain consistency.

Coding Style and Conventions

• Formatting: All code must be formatted with gofmt.
• Naming:
  • Packages should be named in lowercase (e.g., llml).
  • Exported identifiers (functions, types, variables) must start with a capital letter (e.g., LLML, Options).
  • Internal (private) identifiers must start with a lowercase letter (e.g., formatMap, toKebabCase).
  • Variable names should use camelCase (e.g., kebabKey, anyMap).
• Comments:
  • All exported functions and types must have a doc comment explaining their purpose, parameters, and return values.
  • Use comments to explain complex or non-obvious logic. Avoid comments that just restate what the code does.
• Imports: Imports should be organized into two blocks: standard library packages first, followed by third-party packages.

Patterns and Idioms

• Functional Options: The LLML function accepts optional configuration via opts ...Options. This is a clean pattern for optional parameters and should be used if new configuration options are added.
• Recursion for Data Structures: The core logic uses recursion to traverse nested maps and slices. This pattern should be continued for handling nested data.
• Type Handling:
  • The public API uses interface{} (or its modern alias any) to accept arbitrary data structures. This provides flexibility for the user.
  • Internally, the code uses type assertions (e.g., data.(map[string]any)) and type switches to handle different data types. This is the established pattern for working with the any type.
• Deterministic Output: To ensure consistent output, map keys are sorted before processing. This is a critical feature and must be maintained. Any processing of maps must be done in a deterministic order.
• Helper Functions: The logic is cleanly separated into smaller, private helper functions with specific responsibilities (e.g., formatMap, formatKeyValue, toKebabCase). Complex logic should continue to be broken down this way.

Type System Usage

• Public API: Continue to use any (interface{}) for the main data parameter to maintain flexibility.
• Internal Types: Use concrete types (string, int, bool, map[string]any, []any) internally after type assertion.
• Numeric Types: The implementation correctly handles a wide range of specific integer and float types. Any new numeric handling should also be comprehensive.
• Structs: The Options struct is a good example of how to group related configuration parameters.

Error Handling

The library currently does not return errors. For unsupported types, it falls back to a default string representation using fmt.Sprintf("%v", data).

• Guideline: This approach is acceptable for a formatting library where the goal is to always produce a string. Avoid introducing error return values unless a new feature can fail in a way that the caller must handle (e.g., I/O operations, invalid configuration that cannot be defaulted).

Testing

• Framework: All tests must use the standard testing package and github.com/stretchr/testify/assert.
• Test Naming: Test functions must follow the Test<Name> convention.
• Test Structure:
  • Each test function should focus on a specific feature or edge case.
  • For testing multiple variations of a feature, prefer creating separate, descriptively named tests (e.g., TestEmptySlice, TestSimpleListWithWrapper) as is the current convention. Table-driven tests are also an acceptable alternative for very similar inputs.
• Assertions:
  • Use functions from assert (e.g., assert.Equal, assert.Contains) for readable and expressive tests.
  • Since map keys are sorted, tests for map-based inputs should be deterministic. Use assert.Equal with the expected, correctly ordered string output. Avoid assert.Contains unless specifically testing for the presence of a substring in a larger, complex output.
• Coverage: All new code and features must be accompanied by comprehensive tests covering functionality, edge cases (e.g., nil, empty strings, zero values), and different data types.