documentation/reverse-spec by redcatbear · Pull Request #50 · exasol/error-reporting-java

redcatbear · 2026-10-01T07:50:04Z

Reverse-enginieered the specification with the OpenFastTrace reverse-spec-skill.

Please note that this PR also contains a bigger project keeper version jump, so many files (especially CI) are touched even though this does not directly have anything to do with the reverse specification.

Contains open issues.

…s with GitHub issues.

redcatbear

1st self-review done

kaklakariada · 2026-10-01T12:58:47Z

+
+Rationale:
+
+The README presents the builder as a fluent API and the implementation accumulates message fragments.


Suggested change

The README presents the builder as a fluent API and the implementation accumulates message fragments.

A fluent API is easy to use and the resulting code is easy to read.

kaklakariada · 2026-10-01T12:59:51Z

+
+Rationale:
+
+This convenience API was introduced in version 0.3.0.


Suggested change

This convenience API was introduced in version 0.3.0.

This makes the API more convenient to use.

kaklakariada · 2026-10-01T13:01:30Z

+
+Rationale:
+
+The behavior is asserted for named and unnamed placeholders and avoids silently producing an incomplete error message.


Suggested change

The behavior is asserted for named and unnamed placeholders and avoids silently producing an incomplete error message.

* The behavior is asserted for named and unnamed placeholders and avoids silently producing an incomplete error message.

* Throwing an exception at runtime may suppress a more helpful error and make debugging harder.

kaklakariada · 2026-10-01T13:09:59Z

+
+Rationale:
+
+Visualizing null values is better in an error reporting library than rising `NullPointerExceptions`.


Suggested change

Visualizing null values is better in an error reporting library than rising `NullPointerExceptions`.

* Visualizing null values is better in an error reporting library than rising `NullPointerExceptions`.

* Null can be a valid value and should be distinguishable from other values.

kaklakariada · 2026-10-01T13:10:00Z

+
+Rationale:
+
+The README defines automatic quoting as the default and lists the supported types.


Suggested change

The README defines automatic quoting as the default and lists the supported types.

This allows distinguishing values in error messages.

(or something similar)

kaklakariada · 2026-10-01T13:12:19Z

+### Render Collections Recursively
+`req~render-collections-recursively~1`
+
+When a parameter is a collection, rendering encloses the elements in brackets, separates them with comma-space, and applies the selected quoting mode to each element.


No change: What about recursive collections? ;)

kaklakariada · 2026-10-01T13:15:21Z

+### Preserve Parameter Metadata
+`req~preserve-parameter-metadata~1`
+
+The parameter model exposes a name, value, and optional description so catalog tooling can inspect parameter descriptions independently of rendered output.


The catalog tooling does not read the model directly, but reconstructs it by parsing the source code. Not sure if this requirement is necessary.

kaklakariada · 2026-10-01T13:17:19Z

+### Expose The Library As A Java Module
+`req~expose-java-module~1`
+
+The published library exposes the `com.exasol.errorreporting` package from the `error.reporting.java` module.


error.reporting.java is not a good module name. com.exasol.errorreporting would be better.

Should we rename it?

kaklakariada · 2026-10-01T13:20:30Z

+### Render Multiple Mitigations
+`scn~render-multiple-mitigations~1`
+
+**Given** mitigations `Fix it.` and `Contact support.` in that order
+**When** the builder is rendered
+**Then** the result contains `Known mitigations:` and two ordered `* ` list items


Add a scenario where mitigations are added to the builder before the message. The result must be the same.

kaklakariada · 2026-10-01T13:45:09Z

+* `ParameterDefinitionList` intentionally returns the first duplicate definition; this fault-tolerance detail is documented in code and tests but is not currently a separate user-level requirement.
+* `PlaceholderMatcher` is a public iterable API beyond the primary builder workflow; its iterator contract is tested but only indirectly represented in the system requirements.


These open issues could be fixed easily. Please create a ticket to do that.

kaklakariada · 2026-10-01T13:46:04Z

+* README output examples contain stray backticks and inconsistent sample values, while tests define the exact implementation output.
+* README lifecycle guidance mentions `error_code_config.yml`, but that file and enforcement logic are outside this repository.


Create a ticket to update the README

kaklakariada · 2026-10-01T13:47:35Z

+* Confirm whether crawler integration and module resolution need dedicated integration tests.
+* OFT implementation and unit-test markers are now present for the covered design items; the module export item still lacks a modular runtime test.


We could decide here:

integration tests are located in the crawler

no tests required for the Java module.

kaklakariada · 2026-10-01T13:51:12Z

+
+Missing placeholders become visible diagnostic text rather than exceptions. Null values become `<null>`. The builder does not validate error-code syntax.
+
+An important design rule in this project is that it is always better to have incomplete error output than missing output. Especially, if the missing part is highlighted.


Also don't throw runtime exceptions to avoid suppressing more important application errors.

kaklakariada · 2026-10-01T13:53:02Z

+
+## Security and Privacy
+
+The library has no authentication, authorization, storage, or network boundary. Parameter values are inserted into returned strings; callers remain responsible for avoiding secrets or sensitive data in error messages.


We should add a spec item saying that callers are responsible for censoring sensitive data and cover this by documentation.

sonarqubecloud · 2026-10-01T14:30:39Z

Quality Gate passed

Issues
0 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

redcatbear added 4 commits September 30, 2026 08:38

Prepared changelog for extracting specs.

a44a567

Reverse-engineered specs with Codex.

4233fe9

Contains open issues.

First review of the generated specification. Resolved some open issue…

00584c2

…s with GitHub issues.

Reverse-engineered coverage tags.

be0d882

redcatbear self-assigned this Oct 1, 2026

redcatbear added the documentation User guides, turorials, specifications label Oct 1, 2026

redcatbear added 12 commits October 1, 2026 09:54

Updated Project Keeper.

b2f944c

Updated Project Keeper.

1958207

Added OFT Maven plugin.

f2205f1

Updated dependency list.

f3741eb

Terms and roles are now H6.

2b9ce26

Updated dependencies and plugins.

527815f

#50: Building with Java 17 (binary 11).

9aec8ae

#50: Marked zizmor.yml as generated.

9d2cf9b

#50: Set release date.

7edda20

#50: Removed draft markers and open issues.

f116935

#50: Improved building block view.

ade15b2

#50: Open issue in user-requirements to ticket.

24a309d

redcatbear commented Oct 1, 2026

View reviewed changes

kaklakariada requested changes Oct 1, 2026

View reviewed changes

#50: Apply findings from code review.

d209196


		Rationale:

		The README presents the builder as a fluent API and the implementation accumulates message fragments.

	The README presents the builder as a fluent API and the implementation accumulates message fragments.
	A fluent API is easy to use and the resulting code is easy to read.


		Rationale:

		This convenience API was introduced in version 0.3.0.

	This convenience API was introduced in version 0.3.0.
	This makes the API more convenient to use.


		Rationale:

		The behavior is asserted for named and unnamed placeholders and avoids silently producing an incomplete error message.

	The behavior is asserted for named and unnamed placeholders and avoids silently producing an incomplete error message.
	* The behavior is asserted for named and unnamed placeholders and avoids silently producing an incomplete error message.
	* Throwing an exception at runtime may suppress a more helpful error and make debugging harder.


		Rationale:

		Visualizing null values is better in an error reporting library than rising `NullPointerExceptions`.

	Visualizing null values is better in an error reporting library than rising `NullPointerExceptions`.
	* Visualizing null values is better in an error reporting library than rising `NullPointerExceptions`.
	* Null can be a valid value and should be distinguishable from other values.


		Rationale:

		The README defines automatic quoting as the default and lists the supported types.

	The README defines automatic quoting as the default and lists the supported types.
	This allows distinguishing values in error messages.

		* `ParameterDefinitionList` intentionally returns the first duplicate definition; this fault-tolerance detail is documented in code and tests but is not currently a separate user-level requirement.
		* `PlaceholderMatcher` is a public iterable API beyond the primary builder workflow; its iterator contract is tested but only indirectly represented in the system requirements.

		* README output examples contain stray backticks and inconsistent sample values, while tests define the exact implementation output.
		* README lifecycle guidance mentions `error_code_config.yml`, but that file and enforcement logic are outside this repository.

		* Confirm whether crawler integration and module resolution need dedicated integration tests.
		* OFT implementation and unit-test markers are now present for the covered design items; the module export item still lacks a modular runtime test.


		Missing placeholders become visible diagnostic text rather than exceptions. Null values become `<null>`. The builder does not validate error-code syntax.

		An important design rule in this project is that it is always better to have incomplete error output than missing output. Especially, if the missing part is highlighted.


		## Security and Privacy

		The library has no authentication, authorization, storage, or network boundary. Parameter values are inserted into returned strings; callers remain responsible for avoiding secrets or sensitive data in error messages.

Conversation

redcatbear commented Oct 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

redcatbear left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sonarqubecloud Bot commented Oct 1, 2026

Quality Gate passed

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

redcatbear commented Oct 1, 2026 •

edited

Loading