ai-docs-toolkit 0.4.0__tar.gz → 0.4.1__tar.gz

{ai_docs_toolkit-0.4.0 → ai_docs_toolkit-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ai-docs-toolkit
-Version: 0.4.0
+Version: 0.4.1
 Summary: AI-oriented documentation toolkit.
 Requires-Python: >=3.14
 Description-Content-Type: text/markdown
@@ -30,7 +30,7 @@ The core idea is that documentation should not be a secondary artifact created a
 
 ## Current Status
 
-Version 0.4.0 includes:
+Version 0.4.1 includes:
 
 - schema and structure validation for Markdown documents with YAML front matter;
 - document graph output;
@@ -48,26 +48,39 @@ Version 0.4.0 includes:
 Install this version with Python 3.14 or newer once it is available on PyPI:
 
 ```bash
-python -m pip install ai-docs-toolkit==0.4.0
+python -m pip install ai-docs-toolkit==0.4.1
 ai-docs --version
 ```
 
 For ephemeral execution with `uvx`:
 
 ```bash
-uvx --python 3.14 --from ai-docs-toolkit==0.4.0 ai-docs --version
+uvx --python 3.14 --from ai-docs-toolkit==0.4.1 ai-docs --version
 ```
 
 For the optional local MCP runtime:
 
 ```bash
-python -m pip install "ai-docs-toolkit[mcp]==0.4.0"
+python -m pip install "ai-docs-toolkit[mcp]==0.4.1"
 ai-docs-mcp --project-root .
 ```
 
 For the latest stable release, use `python -m pip install --upgrade ai-docs-toolkit`
 without an exact version pin.
 
+## Release 0.4.1
+
+Impact now includes test cases explicitly linked to a module, including modules
+selected from changed code through `cascade.module_ownership`. Both incoming
+`related.modules` and outgoing `related.test_cases` links work. Test cases remain
+terminal review candidates; output fields and exit codes are unchanged.
+
+No schema, configuration or managed-template content migration is required from
+0.4.0. Upgrade the package, reconnect MCP clients, rerun impact discovery and
+review newly included candidates before reusing saved evidence. Preserve project
+files, IDs, local rules and historical review rounds. See “Migration 0.4.0 To 0.4.1”
+in `ai_docs_toolkit/docs/agent-installation.md` for commands and rollback.
+
 ## Release 0.4.0
 
 `ai-docs code-links-check FILE... --format json` checks documentation paths and

{ai_docs_toolkit-0.4.0 → ai_docs_toolkit-0.4.1}/README.md

@@ -2,7 +2,7 @@
 
 AI Docs Toolkit is a documentation toolkit for AI-assisted software development.
 
-It treats documentation as an engineering interface between humans, AI agents, code, tests and change management. Version 0.4.0 adds an optional checker for documentation IDs and paths in Python comments, alongside test-evidence review, rollback guidance, linked test cases, changed-path coverage and optional review evidence checks. Python 3.14 or newer is required.
+It treats documentation as an engineering interface between humans, AI agents, code, tests and change management. The source tree prepares 0.4.1, extending impact to module-linked test cases, alongside optional code-link checks, test-evidence review, rollback guidance and changed-path coverage. Python 3.14 or newer is required.
 
 ## Purpose
 
@@ -83,7 +83,12 @@ pipx install ai-docs-toolkit
 uvx --from ai-docs-toolkit ai-docs validate
 ```
 
-For upgrades from 0.3.3 to 0.4.0, follow the [consumer migration guide](src/ai_docs_toolkit/docs/agent-installation.md#migration-033-to-040).
+Version 0.4.1 is prepared in source and has not been published yet. After publication,
+follow the [0.4.0 → 0.4.1 migration guide](src/ai_docs_toolkit/docs/agent-installation.md#migration-040-to-041).
+This patch requires no schema, configuration or managed-template content migration;
+repeat impact discovery and review any newly included module-linked test cases.
+Consumers on 0.3.3 must also apply the
+[0.4.0 migration](src/ai_docs_toolkit/docs/agent-installation.md#migration-033-to-040).
 Consumers on 0.3.1 must also read the
 [0.3.2 migration](src/ai_docs_toolkit/docs/agent-installation.md#migration-031-to-032).
 Consumers on 0.3.0 must also read the
@@ -96,7 +101,7 @@ Use Python 3.14+, review managed-file changes and preserve existing project rule
 and task records before refreshing. Completed standalone tasks are archived;
 tasks in a plan remain in place until the whole plan is archived.
 
-Version 0.4.0 is prepared for publication; [0.3.3 remains available on Public PyPI](https://pypi.org/project/ai-docs-toolkit/0.3.3/). The
+[Version 0.4.0 is available on Public PyPI](https://pypi.org/project/ai-docs-toolkit/0.4.0/). The
 [test-evidence review rule](.ai-docs/reference/documentation-change-review-skill.md#test-evidence-review)
 connects material requirements to test setup and assertions. A concrete risk of
 masked violations calls for a proportionate check within existing authority.

{ai_docs_toolkit-0.4.0 → ai_docs_toolkit-0.4.1}/packaging/pypi/README.md

@@ -16,7 +16,7 @@ The core idea is that documentation should not be a secondary artifact created a
 
 ## Current Status
 
-Version 0.4.0 includes:
+Version 0.4.1 includes:
 
 - schema and structure validation for Markdown documents with YAML front matter;
 - document graph output;
@@ -34,26 +34,39 @@ Version 0.4.0 includes:
 Install this version with Python 3.14 or newer once it is available on PyPI:
 
 ```bash
-python -m pip install ai-docs-toolkit==0.4.0
+python -m pip install ai-docs-toolkit==0.4.1
 ai-docs --version
 ```
 
 For ephemeral execution with `uvx`:
 
 ```bash
-uvx --python 3.14 --from ai-docs-toolkit==0.4.0 ai-docs --version
+uvx --python 3.14 --from ai-docs-toolkit==0.4.1 ai-docs --version
 ```
 
 For the optional local MCP runtime:
 
 ```bash
-python -m pip install "ai-docs-toolkit[mcp]==0.4.0"
+python -m pip install "ai-docs-toolkit[mcp]==0.4.1"
 ai-docs-mcp --project-root .
 ```
 
 For the latest stable release, use `python -m pip install --upgrade ai-docs-toolkit`
 without an exact version pin.
 
+## Release 0.4.1
+
+Impact now includes test cases explicitly linked to a module, including modules
+selected from changed code through `cascade.module_ownership`. Both incoming
+`related.modules` and outgoing `related.test_cases` links work. Test cases remain
+terminal review candidates; output fields and exit codes are unchanged.
+
+No schema, configuration or managed-template content migration is required from
+0.4.0. Upgrade the package, reconnect MCP clients, rerun impact discovery and
+review newly included candidates before reusing saved evidence. Preserve project
+files, IDs, local rules and historical review rounds. See “Migration 0.4.0 To 0.4.1”
+in `ai_docs_toolkit/docs/agent-installation.md` for commands and rollback.
+
 ## Release 0.4.0
 
 `ai-docs code-links-check FILE... --format json` checks documentation paths and

{ai_docs_toolkit-0.4.0 → ai_docs_toolkit-0.4.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ai-docs-toolkit"
-version = "0.4.0"
+version = "0.4.1"
 description = "AI-oriented documentation toolkit."
 readme = "packaging/pypi/README.md"
 requires-python = ">=3.14"

{ai_docs_toolkit-0.4.0 → ai_docs_toolkit-0.4.1}/src/ai_docs_toolkit/__init__.py

@@ -1,3 +1,3 @@
 """AI Docs Toolkit package baseline."""
 
-__version__ = "0.4.0"
+__version__ = "0.4.1"

{ai_docs_toolkit-0.4.0 → ai_docs_toolkit-0.4.1}/src/ai_docs_toolkit/core/impact.py

@@ -7,6 +7,8 @@ from ai_docs_toolkit.core.graph import DocumentGraph, DocumentGraphEdge, Documen
 
 RULE_DOCUMENT_IMPACT_UNKNOWN_ID = "document.impact.unknown_id"
 
+# Select review candidates through explicit links; test cases remain terminal.
+# Docs: MOD-IMPACT-TRAVERSAL-001 | ai-docs/product/modules/impact-analysis/modules/traversal/module.md
 IMPACT_TRANSITIONS: dict[str, frozenset[str]] = {
     "business_rule": frozenset(
         {
@@ -36,7 +38,7 @@ IMPACT_TRANSITIONS: dict[str, frozenset[str]] = {
         {"module", "scenario", "acceptance", "guide", "operation", "runbook"}
     ),
     "module": frozenset(
-        {"contract", "scenario", "acceptance", "guide", "operation", "runbook"}
+        {"contract", "scenario", "acceptance", "test_case", "guide", "operation", "runbook"}
     ),
     "scenario": frozenset({"acceptance", "test_case", "guide", "operation", "runbook"}),
     "acceptance": frozenset({"test_case", "operation", "runbook"}),

{ai_docs_toolkit-0.4.0 → ai_docs_toolkit-0.4.1}/src/ai_docs_toolkit/docs/agent-installation.md

@@ -47,7 +47,7 @@ ai-docs --version
 Pinned install:
 
 ```bash
-python -m pip install "ai-docs-toolkit==0.4.0"
+python -m pip install "ai-docs-toolkit==0.4.1"
 ai-docs --version
 ```
 
@@ -89,6 +89,68 @@ bulk task deletion is required. Detailed migration and rollback guidance is in
 the installed `.ai-docs/reference/planning-document-model.md`, under
 “Consumer Migration: Proportionate Workflow”.
 
+## Migration 0.4.0 To 0.4.1
+
+From: `0.4.0`. To: `0.4.1`. Install the target only after it is available on
+Public PyPI. Python 3.14+ remains required.
+
+This patch includes test cases explicitly linked to a module in `impact`
+results, including modules selected through `cascade.module_ownership`.
+Use `related.modules` on the test case or `related.test_cases` on the module.
+Test cases remain terminal review candidates; inclusion does not run tests or
+prove coverage. Parent/child module links alone do not expand traversal.
+Output fields and exit codes are unchanged.
+
+Record the current version, Git state, independent project checks and saved
+review evidence before upgrading:
+
+```bash
+ai-docs --version
+ai-docs validate --json
+ai-docs doctor --format json
+ai-docs init --check
+```
+
+Install in the project's approved environment and update its version pin:
+
+```bash
+python -m pip install --upgrade "ai-docs-toolkit==0.4.1"
+# MCP users install the complete extra instead:
+python -m pip install --upgrade "ai-docs-toolkit[mcp]==0.4.1"
+# Isolated CLI alternatives:
+pipx install --force --python python3.14 "ai-docs-toolkit==0.4.1"
+uvx --python 3.14 --from ai-docs-toolkit==0.4.1 ai-docs --version
+```
+
+Reconnect long-lived MCP clients to load the new traversal behavior. No schema,
+configuration, document-layout or init-managed content migration is required
+from 0.4.0. `init` is not needed to activate this fix. If run, it updates managed
+manifest version provenance while preserving unchanged managed content. Preserve
+project documents, IDs, aliases, AGENTS.md, local rules and historical reviews.
+
+After upgrading:
+
+```bash
+ai-docs --version
+ai-docs validate --json
+ai-docs doctor --format json
+ai-docs init --check
+# Substitute an actual module ID, or use the original changed/base review scope:
+ai-docs impact --id MOD-YOUR-MODULE-001 --format json
+```
+
+Expect version 0.4.1 and no unexpected validation/doctor/init findings. Review
+newly included test cases, their selectors and assertions. Repeat the original
+impact discovery before reusing saved evidence; a new tool identity or candidate
+set requires a new reviewed round, without rewriting historical records. Keep
+independent project gates. Stop for unresolved policy drift, unexplained impact
+changes or project rewrites outside this migration.
+
+For rollback, preserve current evidence, revert only this upgrade's committed
+pin/provenance changes and reinstall 0.4.0. Verify the restored version and
+project gates. Module-linked test cases will again require manual discovery.
+See “Rollback Verification” for dependency-restoration and reproducibility limits.
+
 ## Migration 0.3.3 To 0.4.0
 
 From: `0.3.3`. To: `0.4.0`. Install the target only after it is available on

{ai_docs_toolkit-0.4.0 → ai_docs_toolkit-0.4.1}/src/ai_docs_toolkit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ai-docs-toolkit
-Version: 0.4.0
+Version: 0.4.1
 Summary: AI-oriented documentation toolkit.
 Requires-Python: >=3.14
 Description-Content-Type: text/markdown
@@ -30,7 +30,7 @@ The core idea is that documentation should not be a secondary artifact created a
 
 ## Current Status
 
-Version 0.4.0 includes:
+Version 0.4.1 includes:
 
 - schema and structure validation for Markdown documents with YAML front matter;
 - document graph output;
@@ -48,26 +48,39 @@ Version 0.4.0 includes:
 Install this version with Python 3.14 or newer once it is available on PyPI:
 
 ```bash
-python -m pip install ai-docs-toolkit==0.4.0
+python -m pip install ai-docs-toolkit==0.4.1
 ai-docs --version
 ```
 
 For ephemeral execution with `uvx`:
 
 ```bash
-uvx --python 3.14 --from ai-docs-toolkit==0.4.0 ai-docs --version
+uvx --python 3.14 --from ai-docs-toolkit==0.4.1 ai-docs --version
 ```
 
 For the optional local MCP runtime:
 
 ```bash
-python -m pip install "ai-docs-toolkit[mcp]==0.4.0"
+python -m pip install "ai-docs-toolkit[mcp]==0.4.1"
 ai-docs-mcp --project-root .
 ```
 
 For the latest stable release, use `python -m pip install --upgrade ai-docs-toolkit`
 without an exact version pin.
 
+## Release 0.4.1
+
+Impact now includes test cases explicitly linked to a module, including modules
+selected from changed code through `cascade.module_ownership`. Both incoming
+`related.modules` and outgoing `related.test_cases` links work. Test cases remain
+terminal review candidates; output fields and exit codes are unchanged.
+
+No schema, configuration or managed-template content migration is required from
+0.4.0. Upgrade the package, reconnect MCP clients, rerun impact discovery and
+review newly included candidates before reusing saved evidence. Preserve project
+files, IDs, local rules and historical review rounds. See “Migration 0.4.0 To 0.4.1”
+in `ai_docs_toolkit/docs/agent-installation.md` for commands and rollback.
+
 ## Release 0.4.0
 
 `ai-docs code-links-check FILE... --format json` checks documentation paths and

{ai_docs_toolkit-0.4.0 → ai_docs_toolkit-0.4.1}/tests/test_cli_baseline.py

@@ -10,7 +10,7 @@ def test_cli_help(capsys):
     assert main(["--help"]) == 0
 
     output = capsys.readouterr()
-    assert "ai-docs 0.4.0" in output.out
+    assert "ai-docs 0.4.1" in output.out
     assert "ai-docs doctor" in output.out
     assert "ai-docs validate" in output.out
     assert "ai-docs validate --json" in output.out
@@ -24,7 +24,7 @@ def test_cli_version(capsys):
     assert main(["--version"]) == 0
 
     output = capsys.readouterr()
-    assert output.out.strip() == "0.4.0"
+    assert output.out.strip() == "0.4.1"
     assert output.err == ""
 
 

{ai_docs_toolkit-0.4.0 → ai_docs_toolkit-0.4.1}/tests/test_impact_analysis.py

@@ -91,6 +91,7 @@ def test_impact_analyzer_reports_direct_impact():
     ("source_id", "source_type", "relationship"),
     [
         ("BR-TEST-001", "business_rule", "business_rules"),
+        ("MOD-TEST-001", "module", "modules"),
         ("SCN-TEST-001", "scenario", "scenarios"),
         ("ACC-TEST-001", "acceptance", "acceptance"),
     ],
@@ -118,6 +119,76 @@ def test_test_case_direct_impact_from_supported_sources(source_id, source_type,
     )
 
 
+def test_module_test_case_outgoing_link():
+    document_graph = graph(
+        nodes=(node("MOD-TEST-001", "module"), node("TC-TEST-001", "test_case")),
+        edges=(edge("MOD-TEST-001", "TC-TEST-001", "test_cases"),),
+    )
+
+    result = analyze_document_impact(document_graph, ["MOD-TEST-001"])
+
+    assert result.ok
+    assert [(item.document_id, item.distance) for item in result.impacted] == [
+        ("TC-TEST-001", 1)
+    ]
+    assert result.impacted[0].reasons == (
+        ImpactReason(
+            source="MOD-TEST-001",
+            via=None,
+            relationship="test_cases",
+            direction="outgoing",
+            message="MOD-TEST-001 references TC-TEST-001 through related.test_cases.",
+        ),
+    )
+
+
+def test_module_test_case_transitive_path_preserves_boundaries():
+    document_graph = graph(
+        nodes=(
+            node("CON-TEST-001", "contract"),
+            node("MOD-TEST-001", "module"),
+            node("TC-TEST-001", "test_case"),
+            node("MOD-OTHER-001", "module"),
+            node("MOD-PARENT-001", "module"),
+            node("MOD-CHILD-001", "module"),
+            node("TC-OTHER-001", "test_case"),
+            node("TC-PARENT-001", "test_case"),
+            node("TC-CHILD-001", "test_case"),
+            node("TC-UNLINKED-001", "test_case"),
+        ),
+        edges=(
+            edge("CON-TEST-001", "MOD-TEST-001", "modules"),
+            edge("TC-TEST-001", "MOD-TEST-001", "modules"),
+            # A shared test must not bridge to another module and its tests.
+            edge("TC-TEST-001", "MOD-OTHER-001", "modules"),
+            edge("TC-OTHER-001", "MOD-OTHER-001", "modules"),
+            # The module tree itself is navigation, not an accepted impact path.
+            edge("MOD-PARENT-001", "MOD-TEST-001", "modules"),
+            edge("MOD-TEST-001", "MOD-CHILD-001", "modules"),
+            edge("TC-PARENT-001", "MOD-PARENT-001", "modules"),
+            edge("TC-CHILD-001", "MOD-CHILD-001", "modules"),
+        ),
+    )
+
+    result = analyze_document_impact(document_graph, ["CON-TEST-001"])
+
+    assert result.ok
+    assert [(item.document_id, item.impact, item.distance) for item in result.impacted] == [
+        ("MOD-TEST-001", "direct", 1),
+        ("TC-TEST-001", "transitive", 2),
+    ]
+    assert result.impacted[1].reasons == (
+        ImpactReason(
+            source="CON-TEST-001",
+            via="MOD-TEST-001",
+            relationship="modules",
+            direction="incoming",
+            message="TC-TEST-001 references MOD-TEST-001 through related.modules.",
+        ),
+    )
+    assert analyze_document_impact(document_graph, ["TC-TEST-001"]).impacted == ()
+
+
 def test_test_case_transitive_impact_is_terminal_and_requires_links():
     document_graph = graph(
         nodes=(
@@ -183,7 +254,7 @@ def test_test_case_shortest_path_is_unique_and_deterministic():
 
 @pytest.mark.parametrize(
     ("source_type", "relationship"),
-    [("module", "modules"), ("contract", "contracts"),
+    [("contract", "contracts"),
      ("architecture_decision", "architecture_decisions"), ("operation", "operations")],
 )
 def test_test_case_direct_impact_excludes_other_source_types(source_type, relationship):

{ai_docs_toolkit-0.4.0 → ai_docs_toolkit-0.4.1}/tests/test_impact_cli_json.py

@@ -225,7 +225,8 @@ def test_impact_changed_warns_for_non_document_files(monkeypatch, capsys, tmp_pa
     ]
 
 
-def test_impact_changed_maps_code_file_to_owning_module(monkeypatch, capsys, tmp_path):
+@pytest.mark.parametrize("committed", [False, True])
+def test_impact_changed_maps_code_file_to_owning_module(monkeypatch, capsys, tmp_path, committed):
     _write_impact_project(tmp_path)
     (tmp_path / "src").mkdir()
     (tmp_path / "src" / "service.py").write_text("VALUE = 1\n", encoding="utf-8")
@@ -240,6 +241,12 @@ def test_impact_changed_maps_code_file_to_owning_module(monkeypatch, capsys, tmp
         document_id="ACC-TEST-001",
         document_type="acceptance",
     )
+    _write_document(
+        tmp_path / "ai-docs" / "test-case.md",
+        document_id="TC-TEST-001",
+        document_type="test_case",
+        related={"modules": ["MOD-TEST-001"]},
+    )
     (tmp_path / "ai-docs.config.yaml").write_text(
         """version: 1
 project:
@@ -255,9 +262,13 @@ cascade:
     )
     _commit_all(tmp_path)
     (tmp_path / "src" / "service.py").write_text("VALUE = 2\n", encoding="utf-8")
+    base_args = []
+    if committed:
+        _commit_all(tmp_path)
+        base_args = ["--base", "HEAD^"]
     monkeypatch.chdir(tmp_path)
 
-    assert main(["impact", "--changed", "--format", "json"]) == 0
+    assert main(["impact", "--changed", *base_args, "--format", "json"]) == 0
 
     payload = json.loads(capsys.readouterr().out)
     assert payload["sources"] == [
@@ -270,10 +281,37 @@ cascade:
         }
     ]
     assert [item["document_id"] for item in payload["impacted"]] == [
-        "ACC-TEST-001"
+        "ACC-TEST-001", "TC-TEST-001"
     ]
+    test_case = payload["impacted"][1]
+    assert (test_case["impact"], test_case["distance"]) == ("direct", 1)
+    assert test_case["reasons"] == [{
+        "source": "MOD-TEST-001",
+        "via": None,
+        "relationship": "modules",
+        "direction": "incoming",
+        "message": "TC-TEST-001 references MOD-TEST-001 through related.modules.",
+    }]
+    assert payload["coverage"] == {
+        "status": "available",
+        "changed_paths": 1,
+        "document_paths": 0,
+        "owned_paths": 1,
+        "unmapped_paths": 0,
+        "unique_source_documents": 1,
+        "unmapped": [],
+    }
     assert payload["warnings"] == []
 
+    assert main(["impact", "--changed", *base_args]) == 0
+    human = capsys.readouterr()
+    assert (
+        "- TC-TEST-001 (test_case) distance=1 ai-docs/test-case.md\n"
+        "  reason: MOD-TEST-001 incoming related.modules: "
+        "TC-TEST-001 references MOD-TEST-001 through related.modules.\n"
+    ) in human.out
+    assert human.err == ""
+
 
 @pytest.mark.parametrize("owner_type", [None, "business_rule"])
 def test_impact_changed_fails_for_unknown_owning_module(monkeypatch, capsys, tmp_path, owner_type):