fix(docs): align DeadCode copy and verify its command syntax

Author: Coding-Dev-Tools

.github/workflows/ci.yml

@@ -65,13 +65,14 @@ jobs:
       - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
         with:
           python-version: '3.12'
-      - name: Install the four documented CLI tools
+      - name: Install the documented CLI tools
         run: >-
           pip install pytest pyyaml
           git+https://github.com/Coding-Dev-Tools/api-contract-guardian.git
           git+https://github.com/Coding-Dev-Tools/json2sql.git
           git+https://github.com/Coding-Dev-Tools/deploydiff.git
           git+https://github.com/Coding-Dev-Tools/configdrift.git
+          git+https://github.com/Coding-Dev-Tools/deadcode.git
       - name: Exercise rendered CI examples with dummy data
         env:
           DEVFORGE_UPSTREAM_SMOKE: '1'

alternatives.html

@@ -504,7 +504,7 @@ <h2>DeadCode <span class="vs">vs</span> knip</h2>
       <tbody>
         <tr>
           <td>Unused export detection</td>
-          <td class="yes">Yes — compiler API</td>
+          <td class="yes">Yes — regex-based scanning</td>
           <td class="yes">Yes — AST analysis</td>
         </tr>
         <tr>

quickstart.html

@@ -240,6 +240,7 @@ <h2>Run your first check</h2>
 
     <div class="code-block">
       <div class="header"><span>DeadCode</span></div>
+      <p>Set the global <code>--project</code> option before the <code>scan</code> subcommand.</p>
       <pre><code><span class="comment"># Scan for unused exports in a TypeScript project</span>
 <span class="cmd">deadcode</span> <span class="flag">--project</span> /path/to/ts-project <span class="cmd">scan</span></code></pre>
     </div>

tests/test_ci_examples.py

@@ -80,3 +80,19 @@ def test_deploy_requires_all_validation_jobs():
     root = Path(__file__).resolve().parents[1]
     ci = yaml.safe_load((root / ".github/workflows/ci.yml").read_text())
     assert {"test", "linkcheck", "html-validate", "pages-artifact", "cli-example-smoke"} <= set(ci["jobs"]["deploy"]["needs"])
+
+
+@pytest.mark.skipif(os.environ.get("DEVFORGE_UPSTREAM_SMOKE") != "1", reason="run in the CLI Example Smoke job")
+def test_rendered_deadcode_quickstart_scans_a_dummy_project(tmp_path):
+    import shlex
+
+    assert shutil.which("deadcode"), "Smoke job must install DeadCode"
+    project = tmp_path / "typescript-project"
+    project.mkdir()
+    (project / "index.ts").write_text("export const unusedDummy = 1;\n")
+    block = next(block for block in code_blocks("quickstart.html") if "deadcode " in block and "pip install" not in block)
+    line = next(line.strip() for line in block.splitlines() if line.strip().startswith("deadcode "))
+    args = [str(project) if arg == "/path/to/ts-project" else arg for arg in shlex.split(line)]
+    result = subprocess.run(args, cwd=tmp_path, capture_output=True, text=True)
+    assert result.returncode == 0, result.stdout + result.stderr
+    assert "No such option" not in result.stderr

tests/test_install_copy.py

@@ -144,3 +144,20 @@ def test_schemaforge_public_copy_matches_supported_formats_and_limits():
         if page.name == "schemaforge-v1-7-0-vscode-extension.html":
             for unsupported in ["Protobuf", "Avro", "OpenAPI"]:
                 assert unsupported not in copy, page
+
+
+def test_deadcode_comparison_describes_the_regex_scanner():
+    text = (ROOT / "alternatives.html").read_text(encoding="utf-8")
+    comparison = text.split('id="deadcode-vs-knip"', 1)[1]
+    cell = re.search(r"<td>Unused export detection</td>\s*<td[^>]*>(.*?)</td>", comparison)
+    assert cell is not None
+    assert "regex-based scanning" in cell.group(1)
+    assert "compiler API" not in cell.group(1)
+
+
+def test_deadcode_quickstart_uses_the_top_level_project_option():
+    # The published console entry point is deadcode.cli:cli. Its --project
+    # option is declared on the Click group, not on the scan subcommand.
+    command = next(block for block in code_blocks("quickstart.html") if "deadcode " in block and "pip install" not in block)
+    line = next(line.strip() for line in command.splitlines() if line.strip().startswith("deadcode "))
+    assert shlex.split(line) == ["deadcode", "--project", "/path/to/ts-project", "scan"]