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):

= arc42 Architekturdokumentation

// ...

include::chapters/09_architecture_decisions.adoc[leveloffset=+1]

chapters/09_architecture_decisions.adoc:

== Architekturentscheidungen

include::../../adr/0001-email-anbieter.adoc[leveloffset=+1]
include::../../adr/0002-programmiersprache.adoc[leveloffset=+1]

adr/0001-email-anbieter.adoc:

= ADR-0001: E-Mail-Anbieter
:status: Akzeptiert

== Kontext
...

adr/0002-programmiersprache.adoc:

= 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