fix: Allow negative numbers as arguments in sections-at-level

Fixes #199

Changes:
- Add ignore_unknown_options and allow_interspersed_args to command settings
  to allow Click to parse negative numbers like -1 as arguments instead of options
- Add validation to reject negative levels with clear error message explaining
  that document hierarchies start at level 0
- Add comprehensive tests covering negative number parsing, validation, and
  regression tests for positive numbers
- Update CLI specification to document valid level range (non-negative integers)
- Bump version to 0.4.5

Technical details:
Click's argument parser treats tokens starting with '-' as option flags before
type conversion. The combination of ignore_unknown_options=True and
allow_interspersed_args=False tells Click to treat unknown options as potential
arguments, allowing negative numbers to be parsed correctly.

Since document hierarchies don't have semantic meaning for negative levels, the
implementation validates and rejects negative numbers with a helpful error message.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: 2 people

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "dacli"
-version = "0.4.4"
+version = "0.4.5"
 description = "Documentation Access CLI - Navigate and query large documentation projects"
 readme = "README.md"
 license = { text = "MIT" }

src/dacli/__init__.py

@@ -4,4 +4,4 @@
 through hierarchical, content-aware access via the Model Context Protocol (MCP).
 """
 
-__version__ = "0.4.4"
+__version__ = "0.4.5"

src/dacli/cli.py

@@ -467,7 +467,7 @@ def section(ctx: CliContext, path: str):
         sys.exit(EXIT_ERROR)
 
 
-@cli.command("sections-at-level", epilog="""
+@cli.command("sections-at-level", context_settings={"ignore_unknown_options": True, "allow_interspersed_args": False}, epilog="""
 Examples:
   dacli sections-at-level 1        # All top-level chapters
   dacli sections-at-level 2        # All second-level sections
@@ -476,7 +476,18 @@ def section(ctx: CliContext, path: str):
 @click.argument("level", type=int)
 @pass_context
 def sections_at_level(ctx: CliContext, level: int):
-    """Get all sections at a specific nesting level."""
+    """Get all sections at a specific nesting level.
+
+    LEVEL must be a non-negative integer (0, 1, 2, ...).
+    """
+    # Validate level is non-negative (Issue #199)
+    if level < 0:
+        raise click.BadParameter(
+            f"Level must be non-negative, got {level}. "
+            "Document hierarchies start at level 0 (document root).",
+            param_hint="level"
+        )
+
     sections = ctx.index.get_sections_at_level(level)
     result = {
         "level": level,

src/docs/spec/06_cli_specification.adoc

@@ -177,6 +177,29 @@ Shows all sections at a specific level.
 dacli sections-at-level <LEVEL>
 ----
 
+**Arguments:**
+
+* `LEVEL`: Non-negative integer (0, 1, 2, ...) representing the nesting level
+  - Level 0: Document root
+  - Level 1: Top-level chapters/sections
+  - Level 2: Subsections
+  - Level 3 and higher: Deeper nested sections
+
+**Examples:**
+[source,bash]
+----
+# Get all top-level chapters (Level 1)
+$ dacli sections-at-level 1
+
+# Get all second-level sections (Level 2)
+$ dacli sections-at-level 2
+
+# Error: Negative levels are not valid (Issue #199)
+$ dacli sections-at-level -1
+Error: Invalid value for 'level': Level must be non-negative, got -1.
+Document hierarchies start at level 0 (document root).
+----
+
 == Search & Elements Commands
 
 === search

tests/test_negative_numbers_fix_199.py

@@ -0,0 +1,243 @@
+"""Tests for Issue #199: sections-at-level cannot handle negative numbers.
+
+These tests verify that:
+1. Negative numbers can be parsed (not treated as options)
+2. Negative numbers are rejected with clear error message
+3. Zero and positive numbers continue to work correctly
+"""
+
+from pathlib import Path
+
+import pytest
+from click.testing import CliRunner
+
+from dacli.cli import cli
+
+
+@pytest.fixture
+def temp_doc_dir(tmp_path: Path) -> Path:
+    """Create a temporary directory with test documents."""
+    doc_file = tmp_path / "test.adoc"
+    doc_file.write_text(
+        """= Test Document
+
+== Level 1 Section A
+
+Content here.
+
+=== Level 2 Section A.1
+
+Nested content.
+
+== Level 1 Section B
+
+More content.
+
+=== Level 2 Section B.1
+
+More nested content.
+
+=== Level 2 Section B.2
+
+Even more nested.
+""",
+        encoding="utf-8",
+    )
+    return tmp_path
+
+
+class TestNegativeNumberParsing:
+    """Test that negative numbers are parsed correctly."""
+
+    def test_negative_one_is_parsed_not_treated_as_option(self, temp_doc_dir: Path):
+        """Negative number -1 should be parsed as argument, not option (Issue #199)."""
+        runner = CliRunner()
+        result = runner.invoke(
+            cli,
+            [
+                "--docs-root",
+                str(temp_doc_dir),
+                "sections-at-level",
+                "-1",
+            ],
+        )
+
+        # Should NOT fail with "No such option: -1"
+        assert "No such option: -1" not in result.output
+
+        # Should fail with validation error instead
+        assert result.exit_code != 0
+        assert "Level must be non-negative" in result.output
+
+    def test_negative_ten_is_parsed(self, temp_doc_dir: Path):
+        """Larger negative number -10 should be parsed as argument."""
+        runner = CliRunner()
+        result = runner.invoke(
+            cli,
+            [
+                "--docs-root",
+                str(temp_doc_dir),
+                "sections-at-level",
+                "-10",
+            ],
+        )
+
+        # Should NOT fail with "No such option: -10"
+        assert "No such option: -10" not in result.output
+
+        # Should fail with validation error
+        assert result.exit_code != 0
+        assert "Level must be non-negative" in result.output
+
+
+class TestNegativeNumberValidation:
+    """Test validation of negative levels."""
+
+    def test_negative_level_rejected_with_clear_message(self, temp_doc_dir: Path):
+        """Negative level should be rejected with helpful error message."""
+        runner = CliRunner()
+        result = runner.invoke(
+            cli,
+            [
+                "--docs-root",
+                str(temp_doc_dir),
+                "sections-at-level",
+                "-1",
+            ],
+        )
+
+        assert result.exit_code != 0
+        assert "Level must be non-negative" in result.output
+        assert "got -1" in result.output
+        assert "Document hierarchies start at level 0" in result.output
+
+    def test_negative_level_error_includes_level_value(self, temp_doc_dir: Path):
+        """Error message should include the actual negative value provided."""
+        runner = CliRunner()
+        result = runner.invoke(
+            cli,
+            [
+                "--docs-root",
+                str(temp_doc_dir),
+                "sections-at-level",
+                "-5",
+            ],
+        )
+
+        assert result.exit_code != 0
+        assert "got -5" in result.output
+
+
+class TestPositiveNumbersStillWork:
+    """Test that zero and positive numbers continue to work correctly."""
+
+    def test_level_zero_works(self, temp_doc_dir: Path):
+        """Level 0 (document root) should work."""
+        runner = CliRunner()
+        result = runner.invoke(
+            cli,
+            [
+                "--docs-root",
+                str(temp_doc_dir),
+                "sections-at-level",
+                "0",
+            ],
+        )
+
+        assert result.exit_code == 0
+        # Should return the document root
+        assert "test" in result.output or "count" in result.output
+
+    def test_level_one_works(self, temp_doc_dir: Path):
+        """Level 1 (top-level sections) should work."""
+        runner = CliRunner()
+        result = runner.invoke(
+            cli,
+            [
+                "--docs-root",
+                str(temp_doc_dir),
+                "sections-at-level",
+                "1",
+            ],
+        )
+
+        assert result.exit_code == 0
+        # Should return both Level 1 sections
+        assert "Level 1 Section A" in result.output or "level-1-section-a" in result.output
+        assert "Level 1 Section B" in result.output or "level-1-section-b" in result.output
+
+    def test_level_two_works(self, temp_doc_dir: Path):
+        """Level 2 (nested sections) should work."""
+        runner = CliRunner()
+        result = runner.invoke(
+            cli,
+            [
+                "--docs-root",
+                str(temp_doc_dir),
+                "sections-at-level",
+                "2",
+            ],
+        )
+
+        assert result.exit_code == 0
+        # Should return level 2 sections
+        assert (
+            "Level 2 Section A.1" in result.output
+            or "level-2-section-a-1" in result.output
+        )
+
+    def test_level_one_json_format(self, temp_doc_dir: Path):
+        """Level 1 with JSON format should work."""
+        runner = CliRunner()
+        result = runner.invoke(
+            cli,
+            [
+                "--docs-root",
+                str(temp_doc_dir),
+                "--format",
+                "json",
+                "sections-at-level",
+                "1",
+            ],
+        )
+
+        assert result.exit_code == 0
+        assert '"level": 1' in result.output
+        assert '"count":' in result.output
+        assert '"sections":' in result.output
+
+
+class TestAliasStillWorks:
+    """Test that the 'lv' alias still works correctly."""
+
+    def test_lv_alias_with_positive_number(self, temp_doc_dir: Path):
+        """The 'lv' alias should work with positive numbers."""
+        runner = CliRunner()
+        result = runner.invoke(
+            cli,
+            [
+                "--docs-root",
+                str(temp_doc_dir),
+                "lv",  # Using alias
+                "1",
+            ],
+        )
+
+        assert result.exit_code == 0
+        assert "Level 1 Section" in result.output or "level-1-section" in result.output
+
+    def test_lv_alias_rejects_negative(self, temp_doc_dir: Path):
+        """The 'lv' alias should also reject negative numbers."""
+        runner = CliRunner()
+        result = runner.invoke(
+            cli,
+            [
+                "--docs-root",
+                str(temp_doc_dir),
+                "lv",  # Using alias
+                "-1",
+            ],
+        )
+
+        assert result.exit_code != 0
+        assert "Level must be non-negative" in result.output