dbc/changelog.md

# Changelog

This changelog summarizes release and development history. Entries are listed
newest first. Historical dates follow the commit author dates. `v1.0` is the
existing Git tag; subsequent changes are listed as unreleased.

## Unreleased

### 2026-10-20

#### Maintenance

- Share attribute number conversion, skip unrelated default scopes, simplify CAN
  ID normalization, and remove duplicate signal length checks. Keep explicit
  return types, lambda-free code, and the existing TypeFactory dispatch.
- Add numeric boundary/locale and malformed-attribute regressions, including
  diagnostics for invalid definitions, defaults, assignments, and CAN references.
- Fill empty Doxygen file summaries, correct TypeFactory template parameter
  documentation, and document public metadata, parser state, and Qt model methods.
  Reword escape examples that caused a Doxygen Markdown warning.


#### Added

- Parse typed `BA_DEF_`, `BA_DEF_DEF_`, and `BA_` attributes with deferred
  definitions/references, validated ranges, defaults, and explicit overrides.
  Preserve definitions and assignments plus effective database/frame/signal values.
- Expose optional frame format and cycle time metadata in parsed frames, runtime
  snapshots, and tree payloads. Preserve unknown frame format labels with source
  warnings, and report format/ID conflicts without changing ID or J1939 behavior.
- Add attribute syntax, scope, reference, numeric, override, diagnostics, and
  metadata propagation regressions; document supported forms and limitations.
  Verified the qmake build, all six QtTest suites, the qmake tree target, and
  the standalone C++17 tree test. The existing named C locale test skipped
  because the required locale is not installed.


#### Changed

- J1939 interpretation now requires `DbcParserOptions::enableJ1939` (default off)
  or explicit per-frame `hasPgn` metadata. Extended CAN alone no longer derives
  PGN metadata. Runtime construction validates opted-in PGNs against frame IDs.
- Add indexed PGN lookup with PDU1 destination exclusion, PDU2 group extension,
  and both data-page bits. Decoder exact-ID matches take precedence; otherwise
  one J1939 PGN candidate is accepted and multiple candidates return
  `AmbiguousFrame`. Result and selection keys identify the DBC definition.
- Add opt-in, PDU1/PDU2, address/priority changes, ambiguity, exact precedence,
  metadata validation, selected decode, and snapshot-lifetime regressions.
  Verified with `qmake6 ../dbc.pro`, `make -j4`, and `make check` in `build/`:
  all six QtTest suites and the Qt-free tree target passed; the existing named
  comma-decimal C locale test skipped because that locale is not installed.

#### Added

- Expose stable frame and signal keys from Qt-free tree nodes using the existing
  runtime identifier types. Document missing-key cases and identity rules.
- Expand standalone navigation tests and add a Qt-free qmake test target covering
  ownership transfer, vector growth, bounds, key identity, and cycle rejection.

#### Fixed

- Reject self/ancestor insertion before consuming child ownership, preventing
  cycles while preserving parent links. Keep node copying and movement disabled.

### 2026-10-14

#### Fixed

- Issue #19: parse signal factor, offset, minimum, and maximum independently of
  C/C++ application locales with `std::from_chars`, retaining signed decimals,
  scientific notation, complete-token validation, and range/finite checks.
- Added custom C++ and named C comma-decimal locale regressions for valid physical
  values and invalid syntax, grouping, overflow/underflow, and reversed ranges.
  Documented portable test coverage and Linux locale generation. Verified with
  `qmake6`, `make -j4`, and `LOCPATH=/tmp/dbc-issue19-locales make check`: all six
  suites passed without skips. The named C locale regression fails with the old
  `std::stod` converter.

- Issue #18: frame/signal comments share frame-definition CAN ID validation and
  resolve after definitions are read. Support tabs, escaped quotes/backslashes,
  and multiline text while preserving whitespace and starting source locations.
- Report malformed comments and missing references as `InvalidStatement` errors;
  keep statement-order overwrites, including empty comments. Added regression
  coverage and updated parser/test documentation. Verified with `qmake6`,
  `make -j4`, and `make check`: all six regression suites passed.

#### Changed

- Validate duplicate frame keys before building the runtime lookup index, alongside
  CAN IDs, signal layouts, numeric parameters, and multiplexing metadata.

#### Added

- Root `AGENTS.md` with project coding rules, build/test commands, and
  documentation requirements, based on the existing `.project_rules`.
- End-to-end DBC fixture tests for parsed metadata, runtime frame/signal lookup,
  raw and physical decoding, value descriptions, and tree nodes. Both builders
  preserve supported metadata across same-numeric standard/extended IDs, comments,
  empty databases, and database replacement.

- Exhaustive layout checks for both byte orders at representative payload sizes
  (0, 1, 8, 64, and 255 bytes), including invalid lengths and uint32 overflow inputs.
- Regression coverage for builder input mutation/destruction and failed replacement
  with duplicate frame or signal keys, preserving existing lookups.

### 2026-10-13

#### Added

- Issue #16: construction-time validation for both manual runtime definitions and
  `DbcDecodeBuilder` input: normalized CAN IDs, duplicate keys, signal lengths and
  positions, enums, finite numeric parameters, ordered ranges, selectors, branch
  ranges, and overlaps.
- Regression tests for both construction paths, numeric and bit boundaries,
  mixed byte orders, exclusive overlaps, mutable input aliases, and failed reloads.

- `FrameDecodeStatus` distinguishes unknown frames, insufficient payloads,
  signal errors, and successful decoding; frame `valid` still means matched.
- `SignalDecodeStatus::PhysicalConversionFailed` reports NaN/Inf results,
  retaining exact raw values and the non-finite physical result.
- Regression tests for payload-length policy, partial results, invalid runtime
  metadata, physical overflow/non-finite parameters, and raw branch selection
  when selector physical conversion fails.

#### Changed

- Runtime construction rejects invalid definitions with `std::invalid_argument`
  before publishing a snapshot. Decoder tests now expect construction failures
  for malformed definitions; finite arithmetic overflow remains a decode status.
- Shared overflow-safe layout validation across parsing, construction, and
  decoding. Intel extraction also widens bit coordinates before arithmetic.
- `DecodeDatabase` now accepts definitions by const reference and copies them,
  even for rvalues, preventing retained
  mutable aliases from modifying the frozen snapshot or invalidating its index.

- Short payloads decode available signals without padding; longer payloads
  ignore bytes beyond the declared DLC. Short frame status takes precedence
  over signal errors, with per-signal causes retained in definition order.
- Runtime signal validation checks enum values and bit layouts against declared
  DLC using overflow-safe coordinates. Extra bytes cannot rescue invalid layouts.
- Documented frame/signal status meanings, value availability, and payload policy.

### 2026-10-11

#### Added

- Stable application identifiers: `FrameKey` (normalized CAN ID and frame type)
  and `SignalKey` (frame key and signal name), with equality and hashers.
- Runtime `FindSignal`, frame `GetKey`, and keys on decoded frame/signal results.
- Reload/lifetime tests for retained frames and independent signals, lookup
  handles, copies/moves, snapshot release, stable keys, removed/renamed definitions,
  failed/empty reloads, duplicate keys, and insufficient payloads.

- `ParseFileWithDiagnostics` and `DbcParseResult` with severity, stable error
  code, supplied file path, physical line number, and message for each diagnostic.
- Warnings for unregistered statements, including floating-point signal types,
  attributes, signal type references, environment variables, and vendor extensions.
- Quiet common DBC header handlers registered through TypeFactory; `NS_` symbol
  declarations do not produce unsupported-statement warnings.
- Regression tests for warning locations, header handling, immediate/deferred
  errors, file errors, empty results on failure, and legacy exception compatibility.

#### Changed

- **API change:** `DecodeDatabase` is an immutable shared snapshot. Use
  `GetFrames()` for reads or construct a new snapshot from a vector; its frame
  index is private and built automatically, with duplicate-key validation.
- **API change:** decoded `definition` fields and `DbcDecoder::FindFrame` return
  `shared_ptr<const ...>` ownership. Stored results retain old definitions across
  reload/clear/destruction, including separately copied signals and `VAL_` strings.
  Decoding shares metadata without per-result definition copies.
- Documented borrowed views, owning handles, snapshot retention, identifier scope,
  reload behavior, application migration, and synchronization requirements.

- Kept `ParseFile` compatible while sharing parsing with the diagnostic API.
  Parsing stops at the first error and never returns a partial database.
- Deferred value-description and multiplexing errors carry structured source
  locations without extracting them from exception messages.
- Documented supported syntax, warning behavior, diagnostic codes, and limitations.
- Audited diagnostic coverage and added unsupported-statement variants, namespace
  termination, formatting/path handling, first-error stopping, deferred diagnostic
  order, duplicate/overlap errors, and supported decoding preservation tests.
  Linux file-read errors and legacy file-error messages are checked explicitly.

### 2026-10-07

#### Added

- Added regression coverage for signed bit-length boundaries, deterministic
  Intel/Motorola extraction, lookup failures, runtime validation, PGN, comments,
  file formatting, metadata copying/lifetime, and TypeFactory behavior.
- Added direct-handler and resolver tests for unsupported comments and ambiguous
  `VAL_` references in manually constructed databases.
- Documented GCC/gcov/LCOV instrumentation, Qt Creator setup, and HTML reports.
  Coverage after the added tests: 98.4% of lines and 71.4% of branches with
  GCC 14.2 and Qt 6.8.2, including the standalone tree test.
- Added a reusable post-build coverage report script and step-by-step Qt Creator
  configurations for model tests, strict warning checks, coverage, core-only,
  standalone tree tests, and the demo. Machine-specific `.user` settings stay
  outside version control.
- Basic `M` / `mN` multiplexing metadata in parsed, tree, and runtime definitions.
- Deferred selector and overlap validation with source locations: one unsigned
  selector, representable branch values, and overlaps only between exclusive branches.
- Selector-first decoding using exact raw values, preserving definition order and
  unconditional signals. Explicit statuses distinguish inactive branches, missing
  selector data, insufficient payloads, and malformed runtime metadata.
- Registered `SG_MUL_VAL_` rejection through TypeFactory; extended and nested
  multiplexing remain unsupported. Added parser/decoder regression coverage and
  documented supported syntax and consumer behavior.

#### Changed

- Qt-dependent targets now require the installed Qt 6.8.2 through a shared qmake
  version check; removed Qt 5 compatibility instructions. Core remains Qt-free.
- Used explicit local types in the additional coverage and model tests. Functions
  retain explicit return types, and runtime handler selection uses TypeFactory
  without lambdas or extra factory layers for concrete objects.
- Coverage documentation now describes the selected open GCC/LCOV toolchain.
- Overlapping unconditional signals are now rejected during parsing.

#### Fixed

- Linked QtGui only in the optional model tests and used QGuiApplication with an
  offscreen default, resolving the QAbstractItemModelTester invalid QPixmap
  metatype warning without adding QtGui to the adapter library.
- Accepted tabs after `CM_` by using the comment parser's keyword extraction
  instead of requiring a literal-space prefix.
- Removed test compiler warnings by using `QVERIFY_THROWS_EXCEPTION` and
  explicitly discarding `nodiscard` return values in exception checks.
- Reject duplicate frames by normalized CAN ID and frame type, including
  equivalent extended ID encodings, and duplicate signal names within a frame.
  Errors report the file path and line of the repeated definition. Standard and
  extended frames may share a numeric ID; separate frames may reuse signal names.
  Added regression coverage and updated parser documentation.

### 2026-10-06

#### Added

- Added non-owning TreeNode parent navigation and stable sibling positions;
  disabled node moves to preserve links while retaining unique_ptr ownership.
- Added optional read-only Qt Core DbcTreeModel with documented columns and
  metadata roles, exact VAL_ entries, exclusive tree ownership, and reset-based
  reload/clear support. Core remains independent of Qt.
- Added QAbstractItemModelTester coverage, navigation/metadata/reset tests,
  a standalone Qt-free tree test, and adapter build and usage documentation.

- Added `VAL_` signal value descriptions through the statement dispatcher and
  factory, with complete syntax validation, exact signed/unsigned 64-bit keys,
  deferred reference resolution, duplicate detection, and source error locations.
  Distinct keys from multiple statements merge; standard and extended frames
  remain distinct under existing CAN ID normalization.
- Preserved descriptions in parsed metadata, runtime decode definitions, and UI
  tree metadata. Added `DecodedSignalValue::GetValueDescription()` and
  `FindValueDescription()` for raw integer lookup before physical scaling.
  Unknown values retain normal numeric decoding.
- Added regression coverage for syntax, quoting, whitespace, integer boundaries,
  declaration order, invalid references, duplicates, scaling, and both builders;
  documented syntax, lookup behavior, and limitations in README.

### 2026-10-05

#### Changed

- Split the qmake project into a reusable static library in `core/`, a demo in
  `examples/`, and a combined regression test executable in `tests/`. Added
  shared `.pri` files and updated build instructions. (`f17ddb6`, #11)
- Added `.clang-format` and applied consistent formatting to the source code
  and tests. (`b91cf4a`, #7)
- Replaced lambdas with explicit functions and simpler code in statement
  handlers, the decoder, the demo, and regression tests. (`03dc8f2`)

#### Fixed

- Added complete validation of `SG_` signal statements, including syntax,
  receivers, numeric fields, lengths of 1–64 bits, physical ranges, and signal
  bounds within the declared frame payload for Intel and Motorola bit order.
  Invalid definitions report the file path and line number. Multiplexing
  markers are explicitly rejected. Added regression tests and documentation.
  (`8d82b13`, #6)

#### Documentation and maintenance

- Regenerated Doxygen documentation after code changes and the project
  restructuring. (`6cd9976`, `0067cb4`, `f17ddb6`)
- Removed the temporary signal-validation issue document. (`1163277`)

### 2026-10-01

#### Changed

- Moved DBC statement parsing into `TypeFactory`-registered handlers for
  `BO_`, `SG_`, and `CM_`, with a shared parse context and keyword dispatcher.
  Added tests for dispatch and handler replacement, and documented how to
  register additional handlers. (`88b5883`, #4)
- **API change:** `DecodedSignalValue::rawValue` now uses
  `std::variant<std::int64_t, std::uint64_t>` instead of `int64_t`. Consumers
  must handle the appropriate variant alternative. Physical values remain
  `double` and may lose precision for large integers. (`69074e3`, #2)

#### Fixed

- Corrected Motorola signal extraction within bytes and across byte
  boundaries using DBC sawtooth bit numbering. Added decoder regression
  tests and build instructions; introduced the `TypeFactory` utility.
  (`2c057b6`)
- Preserved the full unsigned 64-bit raw-value range, including values above
  `INT64_MAX`, and updated physical conversion and demo output. Added tests
  for signed and unsigned boundaries and numeric output. (`69074e3`, #2)
- Validated `BO_` frame syntax, CAN identifiers, payload lengths, numeric
  overflow, and unexpected trailing fields. Parsing errors now include the
  file path and physical line number. Added parser regression tests.
  (`3bd9339`, #3)

## v1.0 — 2026-06-14

Tag `v1.0` points to `38ce043` and includes the initial implementation below.

### Documentation

- Added source-file headers with author information and MIT license
  references. (`e2ffa97`)
- Added and subsequently simplified the Doxygen configuration.
  (`e2c07dd`, `4c8af9f`)
- Generated API documentation and refreshed the generated documentation.
  (`dfec39d`, `38ce043`)

### Initial implementation — 2026-03-13

#### Added

- Initialized the repository with a README and MIT license. (`4270459`)
- Added the DBC parser, frame and signal metadata, a tree representation and
  builder, a demonstration program, and a qmake project. (`2a90b2d`)
- Added runtime decoding through `DbcDecodeBuilder`, `DecodeDatabase`, and
  `DbcDecoder`, including CAN-frame lookup, Intel and Motorola extraction,
  signed and unsigned signals, and factor/offset conversion. Updated parser
  metadata and the demo to support decoding. (`a53a5df`)

#### Documentation and maintenance

- Added `.gitignore` and expanded the README with architecture, data
  structures, parsing behavior, decoding examples, and usage documentation.
  (`efc57d6`, `f2aa10c`, `cb20f5f`, `f0e7065`)