docToolchain / docToolchain/dacli

False positive: duplicate_path warnings for files included with leveloffset

Open
#291 0 comments 0 reactions 0 assignees View on GitHub
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.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.