chore: unify [ERROR] prefixes to public-API-name.function form across common #37

New issue

Closed

opened 2026-07-19 20:03:58 +02:00 by michael · 1 comment

michael commented

2026-07-19 20:03:58 +02:00

Owner

Summary

daw-error-standard.md establishes a repo-wide error prefix contract:

[ERROR] modul.funktion: message

using the public API name the caller actually uses (not the internal
file/module structure). During today's cleanup pass this was applied
inconsistently -- some files already match (base64.lua, most of
crypto.lua), others use a colon-separated form without a dot
(decimal.lua, fs/query.lua, fs/dir.lua, fs/file.lua, fs/handle.lua,
fs/temp.lua), and two files omit the function name entirely
(config_parser.lua, uuid.lua).

Affected files

decimal.lua -- parse, tostring, round, add, sub, mul, div, cmp
fs/query.lua -- exists, is_dir, read_attrs, abspath
fs/dir.lua -- mkdir_p, list_dirs, list_files, find_recursive, remove_dir_recursive
fs/file.lua -- read_file, write_file, copy, copy_dir, remove, rename
fs/handle.lua -- open_append, write_line, open_read, read_bytes
fs/temp.lua -- tmpdir, tmpfile
config_parser.lua -- parse_file (currently no function name in prefix)
uuid.lua -- generate (currently no function name in prefix)
time.lua -- iso8601_to_epoch, epoch_to_iso8601 (colon form, not dot form)

base64.lua and crypto.lua already largely comply and are out of scope.

Open question to resolve first

config_parser.lua and uuid.lua each expose exactly one public function.
Does the standard apply uniformly (prefix always includes the function
name, even for single-function modules), or is a module-name-only
prefix acceptable when there is exactly one public entry point? The
standard document does not currently distinguish this case.

Also in scope

fs/handle.lua's open_read/read_line/read_bytes were re-exported on the
fs/init.lua facade (fs.open_read etc.) ahead of this issue, so the
"use the public facade name, not the internal module path" rule now
applies cleanly to all fs.handle functions without exception.

Acceptance criteria

All prefixes in the affected files above match [ERROR] public.name: message
Forwarded errors keep the inner prefix intact (no stripping)
Module-init errors (missing dependency) use [ERROR] module: message (no function name)
fragjan runs clean
make test passes under 5.1 and 5.4
Corresponding test files updated where error text is pattern-matched

Refs

DAW/daw-lua-common -- daw-error-standard.md

## Summary daw-error-standard.md establishes a repo-wide error prefix contract: [ERROR] modul.funktion: message using the public API name the caller actually uses (not the internal file/module structure). During today's cleanup pass this was applied inconsistently -- some files already match (base64.lua, most of crypto.lua), others use a colon-separated form without a dot (decimal.lua, fs/query.lua, fs/dir.lua, fs/file.lua, fs/handle.lua, fs/temp.lua), and two files omit the function name entirely (config_parser.lua, uuid.lua). ## Affected files - decimal.lua -- parse, tostring, round, add, sub, mul, div, cmp - fs/query.lua -- exists, is_dir, read_attrs, abspath - fs/dir.lua -- mkdir_p, list_dirs, list_files, find_recursive, remove_dir_recursive - fs/file.lua -- read_file, write_file, copy, copy_dir, remove, rename - fs/handle.lua -- open_append, write_line, open_read, read_bytes - fs/temp.lua -- tmpdir, tmpfile - config_parser.lua -- parse_file (currently no function name in prefix) - uuid.lua -- generate (currently no function name in prefix) - time.lua -- iso8601_to_epoch, epoch_to_iso8601 (colon form, not dot form) base64.lua and crypto.lua already largely comply and are out of scope. ## Open question to resolve first config_parser.lua and uuid.lua each expose exactly one public function. Does the standard apply uniformly (prefix always includes the function name, even for single-function modules), or is a module-name-only prefix acceptable when there is exactly one public entry point? The standard document does not currently distinguish this case. ## Also in scope fs/handle.lua's open_read/read_line/read_bytes were re-exported on the fs/init.lua facade (fs.open_read etc.) ahead of this issue, so the "use the public facade name, not the internal module path" rule now applies cleanly to all fs.handle functions without exception. ## Acceptance criteria - [ ] All prefixes in the affected files above match `[ERROR] public.name: message` - [ ] Forwarded errors keep the inner prefix intact (no stripping) - [ ] Module-init errors (missing dependency) use `[ERROR] module: message` (no function name) - [ ] fragjan runs clean - [ ] make test passes under 5.1 and 5.4 - [ ] Corresponding test files updated where error text is pattern-matched ## Refs DAW/daw-lua-common -- daw-error-standard.md

michael added the

labels

2026-07-19 20:03:58 +02:00

michael commented

2026-07-20 07:12:58 +02:00

Author

Owner

Beyond the pure renaming, this pass also surfaced and fixed three real bugs where a function forwarded another function's error unchanged instead of adding its own context:

uuid.generate() now wraps read_random_bytes()'s error instead of passing it through raw
crypto.hash_file()/hash_string() now wrap their internal helpers' errors instead of passing them through raw
yaml.load()/load_file()/dump() now wrap parse.lua/dump.lua's errors instead of passing them through raw

Also found: json/decode.lua and json/encode.lua were using json_decode:/json_encode: (underscore-joined) instead of the dot form -- a third, previously unnoticed variant. Fixed to json.decode:/json.encode:.

Side effect: crypto.lua grew past fragjan's 250-line limit during this pass and was split into crypto/init.lua (facade), crypto/hash.lua, and crypto/hmac.lua -- require("daw.common.crypto") is unchanged for callers. The hmac_sha256_hex/hmac_sha256_b64url duplication (near-identical temp-file plumbing) was also consolidated into a shared run_hmac() helper as part of the split.

make test: 391 tests passed under both Lua 5.1 and 5.4. fragjan: 34 files, 711 checks, all clear.

Refs: DAW/daw-lua-common#8 (crypto), DAW/daw-lua-common#30 (namespace migration this built on)

Done. All [ERROR] prefixes across the repo now use the public-API-name.function form (fs.read_file:, decimal.add:, etc.), except the documented module-init exception (bare module name when a whole submodule failed to load). Beyond the pure renaming, this pass also surfaced and fixed three real bugs where a function forwarded another function's error unchanged instead of adding its own context: - uuid.generate() now wraps read_random_bytes()'s error instead of passing it through raw - crypto.hash_file()/hash_string() now wrap their internal helpers' errors instead of passing them through raw - yaml.load()/load_file()/dump() now wrap parse.lua/dump.lua's errors instead of passing them through raw Also found: json/decode.lua and json/encode.lua were using json_decode:/json_encode: (underscore-joined) instead of the dot form -- a third, previously unnoticed variant. Fixed to json.decode:/json.encode:. Side effect: crypto.lua grew past fragjan's 250-line limit during this pass and was split into crypto/init.lua (facade), crypto/hash.lua, and crypto/hmac.lua -- require("daw.common.crypto") is unchanged for callers. The hmac_sha256_hex/hmac_sha256_b64url duplication (near-identical temp-file plumbing) was also consolidated into a shared run_hmac() helper as part of the split. make test: 391 tests passed under both Lua 5.1 and 5.4. fragjan: 34 files, 711 checks, all clear. Refs: DAW/daw-lua-common#8 (crypto), DAW/daw-lua-common#30 (namespace migration this built on)

michael

2026-07-20 07:12:59 +02:00