docToolchain / docToolchain/dacli
False positive: duplicate_path warnings for files included with leveloffset
- Dominant language
- Python
- Stars
- 21
- Forks
- 3
- Avg merge
- 1m
- Merged PRs (30d)
- 1
Description
## Description
`dacli validate` reports `duplicate_path` warnings for AsciiDoc files that are included into a parent document via `include::...adoc[leveloffset=+1]`. This is a standard Docs-as-Code pattern where files work both standalone and as includes.
## Steps to Reproduce
Given this structure:
**`arc42.adoc`** (parent):
```asciidoc
= arc42 Architekturdokumentation
// ...
include::chapters/09_architecture_decisions.adoc[leveloffset=+1]
```
**`chapters/09_architecture_decisions.adoc`**:
```asciidoc
== Architekturentscheidungen
include::../../adr/0001-email-anbieter.adoc[leveloffset=+1]
include::../../adr/0002-programmiersprache.adoc[leveloffset=+1]
```
**`adr/0001-email-anbieter.adoc`**:
```asciidoc
= ADR-0001: E-Mail-Anbieter
:status: Akzeptiert
== Kontext
...
```
**`adr/0002-programmiersprache.adoc`**:
```asciidoc
= ADR-0002: Programmiersprache
:status: Akzeptiert
== Kontext
...
```
Running `dacli --docs-root docs validate` reports:
```
warnings:
type: duplicate_path
path: arc42/arc42
message: Duplicate section path 'arc42/arc42' (first at arc42.adoc:12, duplicate at adr/0001-email-anbieter.adoc:1)
type: duplicate_path
path: arc42/arc42
message: Duplicate section path 'arc42/arc42' (first at arc42.adoc:12, duplicate at adr/0002-programmiersprache.adoc:1)
```
In my project, this produces **26 duplicate_path warnings** — 9 ADRs, 10 Use Cases, 7 EPICs — all included via `leveloffset`.
## Expected Behavior
Files that are included into a parent document via `include::...[leveloffset=+N]` should not generate `duplicate_path` warnings, because:
1. The `leveloffset` shifts their heading levels, so they become subsections of the parent
2. This is a standard AsciiDoc pattern for modular documentation (used by arc42, Docs-as-Code)
3. The included files intentionally have their own `= Title` so they work both standalone and as includes
## Possible Solutions
- Detect `include::` directives and resolve `leveloffset` when building the section path tree
- Only flag `duplicate_path` for files that are NOT referenced by any `include::` directive
- Add a configuration option to suppress `duplicate_path` for included files
## Environment
- dacli (latest via `uv tool install dacli`)
- Documentation structure: arc42 template with ADRs, Use Cases, and EPICs included via leveloffset
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.