Document Chronicle Values requirements and harden generator utilities

[peter-lawrey]

This PR refines contributor guidance for AI agents, restructures Chronicle Values documentation into src/main/docs, bumps the shared dependency BOM, and tightens several code generation utilities used by Chronicle Values. It also clarifies how to run builds and where to find system properties and decision records.

---

Functional changes

• Generated implementations now include toString()

  • Generators.generateValueCommons(...) now always adds toStringMethod(...) for both native and heap implementations.
  • Improves debuggability and logging of generated Values classes.
  • Behavioural change: existing code that prints or logs generated instances will now see a structured representation instead of the default Object.toString().

• Stronger null handling in array field model

  • ArrayFieldModel constructor now uses Objects.requireNonNull(elemModel).
  • Fails fast with a clear NullPointerException if an invalid configuration is passed, instead of leaking a null further into layout calculations.

• More precise exception types from reflection utilities

  • Enums.getUniverse(...) now throws IllegalStateException("Unable to access enum constants", e) rather than a generic RuntimeException.
  • MyJavaFileManager.classFileObject(...) now throws IllegalStateException("Unable to resolve class URI for " + c.getName(), e) instead of a bare RuntimeException.
  • Callers will now see more descriptive exception types/messages if reflection or class URI resolution fails.

• Deterministic encoding for generated source output

  • SimpleURIClassObject.openWriter() now uses new OutputStreamWriter(openOutputStream(), StandardCharsets.UTF_8).
  • Previously relied on the platform default charset; behaviour now fixed to UTF-8, avoiding platform-dependent differences when writing generated code.

• Locale-independent uppercasing

  • PrimitiveBackedHeapMemberGenerator now uses fieldType.getName().toUpperCase(Locale.ROOT) instead of toUpperCase() with the default locale.
  • Prevents subtle bugs in non-English locales (for example Turkish locale issues) when generating method names and constants for primitive fields.

• Dependency set updated via BOM

  • pom.xml updates net.openhft:third-party-bom from 3.27ea5 to 3.27ea7.
  • Pulls in the latest curated third-party dependency versions (including the newer logging stack from the central BOM), which may affect logging behaviour and runtime compatibility in downstream modules.

---

Non-functional changes

• Agent and contributor guidance (AGENTS.md)

  • Language and charset policy updated:

    • Move from strict ASCII-7 to ISO-8859-1 (code points 0-255) as the allowed character set.
    • Still discourages smart quotes, non-breaking spaces and accented characters to avoid toolchain surprises.
    • Adds explicit link to the University of Oxford style guide.
    • Updates symbol guidance to ISO-8859-1 context and keeps the recommendation to use textual forms for symbols not safely representable.

  • Adds a note on tools to check for non-ASCII characters, including iconv and IDE settings to catch stray Unicode before code review.

  • Expands Javadoc and inline comment guidelines with concrete examples:

    • Shows what constitutes a noisy vs useful inline comment.

  • Clarifies build instructions:

    • Recommends mvn -q clean verify from a clean checkout and notes that exit code 0 indicates success.

  • PR etiquette extended:

    • Subject line advice kept, but quotes removed from the example to keep subject wording copy-paste friendly.

    • New "When to open a PR" section emphasising:

      • Open PRs only after a green mvn -q clean verify.
      • Linking to issues or decision records.
      • Keeping PRs focused and rerunning the build after addressing review comments.

  • Adds a Security checklist section to review on every change:

    • Explicit instructions to scan diffs for validation, auth, encoding, overflow, resource exhaustion and timing-attack risks.
    • Strong guidance to never commit secrets or credentials and to use environment variables or secret managers.
    • Encourages documenting intentional security trade-offs (for example unchecked casts for performance) in Javadoc and .adoc files.

• Documentation structure and attributes

  • Moves requirement and decision documentation under src/main/docs:

    • src/main/adoc/project-requirements.adoc renamed to src/main/docs/project-requirements.adoc.

    • Old src/main/adoc/decision-log.adoc removed.

    • New src/main/docs/decision-log.adoc introduced with a structured Chronicle Values decision log:

      • Adds decision index and VAL-scoped decisions (for example VAL-FN-101, VAL-NFP-111, VAL-SPOT-301) with context, rationale, impact and links.

    • project-requirements.adoc now includes:

      • :toc:, :lang: en-GB, :sectnums: and :source-highlighter: rouge attributes.
      • Explicit links to both the legacy Chronicle Libraries decision log and the new Chronicle Values decision log.

  • New src/main/docs/functional-requirements.adoc:

    • Summarises CV-FN-001 .. CV-FN-008 and groups them into domains.
    • Provides a table with requirement summaries and references for verification and documentation.
    • Adds a traceability section tying tests and examples back to CV-FN-* tags.

  • New src/main/docs/systemProperties.adoc:

    • Documents Chronicle Values system properties, currently chronicle.values.dumpCode.
    • Clarifies how to set properties via -D and notes Chronicle Boolean parsing conventions (for example empty value, true or yes).
    • Describes that chronicle.values.dumpCode controls printing of generated Java source for native and heap implementations during code generation and is intended for debugging, not normal production use.

  • README header (README.adoc) updated:

    • Adds :lang: en-GB and :source-highlighter: rouge to align with the rest of the documentation set.

• AsciiDoc style and formatting clean-ups

  • AGENTS.md:

    • Tweaks wording to reference ISO-8859-1 instead of ASCII-7 in the AI content guidelines.

  • Decision template:

    • Normalises Decision Statement :: to be a single line entry.
    • Updates examples of list structure to avoid relying on indentation and clarifies how to write section labels (section :: ...).
    • Adds a section on automatic section numbering with a minimal example, recommending :sectnums: and avoiding manual numbering in headings.

• Test and comment clean-ups

  • VolatileTest:

    • Simplifies testGenerateJavaCode signature to no longer declare unused checked exceptions.
    • Removes large blocks of commented-out test code that asserted failures for bad interfaces.

  • PointerTest:

    • Removes commented-out System.setProperty("chronicle.values.dumpCode", "true"); line to reduce noise.

  • MyJavaFileManager:

    • Converts some redundant Javadoc blocks to simple block comments to keep surface area of public documentation cleaner without changing behaviour.

• Minor style and readability improvements

  • ValueModel:

    • Wraps CACHED_COMPILER.fileManagerOverride assignment over two lines for clarity.

  • BooleanFieldModel:

    • Normalises method signature formatting and extracts a dedicated BooleanHeapMemberGenerator inner class, making heap generator responsibilities more explicit while retaining the same behaviour.

  • FloatingFieldModel:

    • Uses "%n" rather than hardcoded "\n" in generated equality methods, ensuring platform-appropriate line separators in generated code.

  • Utils:

    • Adds java.util.Locale import for use in locale-safe helpers.

---

Impact and migration notes

• Generated Values classes now have a toString() implementation. This should mostly aid debugging and logging, but any tests asserting on the previous default Object.toString() format may need to be updated.
• Exception types for some internal utilities have changed from RuntimeException to IllegalStateException with richer messages. Callers that explicitly check exception types should be reviewed.
• Generated source writing now uses UTF-8 explicitly, which removes platform-sensitive differences but may change behaviour on non-UTF-8 default platforms.
• The BOM bump to third-party-bom:3.27ea7 aligns this module with the latest shared dependency set; downstream projects should be retested, especially where SLF4J / logging behaviour or other third-party versions are sensitive.
• Documentation consumers should now refer to src/main/docs for Chronicle Values requirements, decision logs and system property definitions; links from code and other docs have been updated accordingly.

[sonarqubecloud]

Quality Gate passed

Issues
2 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud