[PR #74] [MERGED] Improve parser/dumper safety, determinism, and API hardening #74

New issue

Closed

opened 2026-02-28 01:20:47 +03:00 by kerem · 0 comments

kerem commented

2026-02-28 01:20:47 +03:00

Owner

📋 Pull Request Information

Original PR: https://github.com/tufanbarisyildirim/gonginx/pull/74
Author: @tufanbarisyildirim
Created: 2/19/2026
Status: ✅ Merged
Merged: 2/20/2026
Merged by: @tufanbarisyildirim

Base: master ← Head: codex/enhancement-plan-implementation

📝 Commits (3)

947d273 harden parser and config error handling
0aaba8b make dumper deterministic and Lua-safe
0c5b6ba document behavior changes and completed enhancement plan

📊 Changes

18 files changed (+1221 additions, -68 deletions)

View changed files

📝 CONTRIBUTING.md (+4 -1)
📝 GUIDE.md (+37 -0)
📝 README.md (+16 -0)
📝 config/config.go (+37 -2)
➕ config/constructor_validation_test.go (+109 -0)
📝 config/include.go (+13 -6)
📝 config/location.go (+1 -1)
📝 config/upstream.go (+4 -0)
📝 dumper/dumper.go (+7 -5)
📝 dumper/dumper_test.go (+54 -0)
📝 dumper/lua.go (+280 -24)
➕ dumper/lua_test.go (+71 -0)
➕ parser/fuzz_test.go (+31 -0)
📝 parser/lexer.go (+19 -2)
📝 parser/lexer_test.go (+7 -8)
📝 parser/parser.go (+86 -17)
📝 parser/parser_test.go (+268 -2)
➕ todo/enhancement-plan.md (+177 -0)

📄 Description

Summary

This PR implements the completed enhancement plan to improve reliability and maintainability across parser, config, and dumper components.

It removes panic-prone runtime paths, makes include handling safe under cycles, hardens extension-point type assertions, preserves dumper determinism, and documents behavior/migration changes.

Commit Structure

harden parser and config error handling
- Replace panic-prone malformed-input paths with explicit errors.
- Add include cycle protection using canonical paths and include cache.
- Add optional strict cycle mode via WithIncludeCycleErr().
- Ensure parser file lifecycle is closed safely on all parse paths.
- Add constructor validations and strict upstream lookup (FindUpstreamsStrict).
- Add parser regression tests and fuzz target.
make dumper deterministic and Lua-safe
- Stop in-place sorting mutation in DumpBlock by sorting a copied slice.
- Replace panic in include write path with typed error return.
- Rework Lua formatting to avoid global #/-- corruption:
  - convert only comment markers outside literals,
  - restore converted comments reversibly,
  - fallback to original Lua source when formatter fails.
- Add regression tests for non-mutating sort and Lua literal/comment safety.
document behavior changes and completed enhancement plan
- Update README.md and GUIDE.md with behavior notes and migration guidance.
- Document include cycle policy, parent semantics, sort non-mutation, strict upstream mode.
- Update CONTRIBUTING.md with race/fuzz guidance for parser/dumper safety changes.
- Add todo/enhancement-plan.md with completed checklist.

Key Behavior Changes

Parser malformed input now returns errors instead of panicking in key lexer paths.
Include parsing now:
- canonicalizes paths,
- skips cyclic branches by default,
- can return explicit cycle errors with WithIncludeCycleErr(),
- caches parsed include files by canonical path.
Root-level leaf directive parent pointers are nil (no self-parent cycle).
FindUpstreams() is permissive; FindUpstreamsStrict() provides typed strict errors.
Sorted dump styles no longer mutate in-memory AST directive order.
Lua dump preserves string literal semantics and safely handles formatter failures.

Validation

go test ./... ✅
go vet ./... ✅

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/tufanbarisyildirim/gonginx/pull/74 **Author:** [@tufanbarisyildirim](https://github.com/tufanbarisyildirim) **Created:** 2/19/2026 **Status:** ✅ Merged **Merged:** 2/20/2026 **Merged by:** [@tufanbarisyildirim](https://github.com/tufanbarisyildirim) **Base:** `master` ← **Head:** `codex/enhancement-plan-implementation` --- ### 📝 Commits (3) - [`947d273`](https://github.com/tufanbarisyildirim/gonginx/commit/947d273b3ff570d0a7b5a5a47556e59d7c88f996) harden parser and config error handling - [`0aaba8b`](https://github.com/tufanbarisyildirim/gonginx/commit/0aaba8ba9f84ea10f9690ed83b5d0013506659d6) make dumper deterministic and Lua-safe - [`0c5b6ba`](https://github.com/tufanbarisyildirim/gonginx/commit/0c5b6ba040c2acf3bbf23fb76f2c13b74a0474a9) document behavior changes and completed enhancement plan ### 📊 Changes **18 files changed** (+1221 additions, -68 deletions) <details> <summary>View changed files</summary> 📝 `CONTRIBUTING.md` (+4 -1) 📝 `GUIDE.md` (+37 -0) 📝 `README.md` (+16 -0) 📝 `config/config.go` (+37 -2) ➕ `config/constructor_validation_test.go` (+109 -0) 📝 `config/include.go` (+13 -6) 📝 `config/location.go` (+1 -1) 📝 `config/upstream.go` (+4 -0) 📝 `dumper/dumper.go` (+7 -5) 📝 `dumper/dumper_test.go` (+54 -0) 📝 `dumper/lua.go` (+280 -24) ➕ `dumper/lua_test.go` (+71 -0) ➕ `parser/fuzz_test.go` (+31 -0) 📝 `parser/lexer.go` (+19 -2) 📝 `parser/lexer_test.go` (+7 -8) 📝 `parser/parser.go` (+86 -17) 📝 `parser/parser_test.go` (+268 -2) ➕ `todo/enhancement-plan.md` (+177 -0) </details> ### 📄 Description ## Summary This PR implements the completed enhancement plan to improve reliability and maintainability across parser, config, and dumper components. It removes panic-prone runtime paths, makes include handling safe under cycles, hardens extension-point type assertions, preserves dumper determinism, and documents behavior/migration changes. ## Commit Structure 1. **harden parser and config error handling** - Replace panic-prone malformed-input paths with explicit errors. - Add include cycle protection using canonical paths and include cache. - Add optional strict cycle mode via `WithIncludeCycleErr()`. - Ensure parser file lifecycle is closed safely on all parse paths. - Add constructor validations and strict upstream lookup (`FindUpstreamsStrict`). - Add parser regression tests and fuzz target. 2. **make dumper deterministic and Lua-safe** - Stop in-place sorting mutation in `DumpBlock` by sorting a copied slice. - Replace panic in include write path with typed error return. - Rework Lua formatting to avoid global `#`/`--` corruption: - convert only comment markers outside literals, - restore converted comments reversibly, - fallback to original Lua source when formatter fails. - Add regression tests for non-mutating sort and Lua literal/comment safety. 3. **document behavior changes and completed enhancement plan** - Update `README.md` and `GUIDE.md` with behavior notes and migration guidance. - Document include cycle policy, parent semantics, sort non-mutation, strict upstream mode. - Update `CONTRIBUTING.md` with race/fuzz guidance for parser/dumper safety changes. - Add `todo/enhancement-plan.md` with completed checklist. ## Key Behavior Changes - Parser malformed input now returns errors instead of panicking in key lexer paths. - Include parsing now: - canonicalizes paths, - skips cyclic branches by default, - can return explicit cycle errors with `WithIncludeCycleErr()`, - caches parsed include files by canonical path. - Root-level leaf directive parent pointers are `nil` (no self-parent cycle). - `FindUpstreams()` is permissive; `FindUpstreamsStrict()` provides typed strict errors. - Sorted dump styles no longer mutate in-memory AST directive order. - Lua dump preserves string literal semantics and safely handles formatter failures. ## Validation - `go test ./...` ✅ - `go vet ./...` ✅ --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>