Add documentation checks for every push and PR by TehseenTech · Pull Request #2 · TehseenTech/digital-evidence-preservation

TehseenTech · 2026-07-20T14:18:42Z

What changed

Added a GitHub Actions workflow triggered by every push and pull request
Added a dependency-free Python validator for required documentation, empty Markdown files, repository path traversal, and broken relative links
Added a pull-request safety and privacy checklist

Why

The repository had no GitHub Actions workflow, so merged documentation changes received no automated validation.

Validation

Workflow uses read-only repository permissions
Job has a five-minute timeout and concurrency cancellation
Validator relies only on Python's standard library
No case data or secrets are used

warpfix

🔍 WarpFix PR Review

This pull request introduces a GitHub Actions workflow to automate documentation checks for every push and pull request. It includes a Python script that validates required documentation files, checks for empty Markdown files, and verifies the integrity of relative links.

📖 Walkthrough

The changes consist of three main files: a pull request template that outlines a safety and privacy checklist, a Python script that performs various documentation validations, and a GitHub Actions workflow that triggers the validation process on pushes and pull requests. The pull request template encourages contributors to ensure that sensitive information is not included in documentation. The Python script checks for the existence of required Markdown files, identifies empty files, and verifies that all relative links are valid. The workflow is designed to run on every push and pull request, ensuring that documentation quality is maintained automatically.

📁 File Changes

File	Change	Impact
`.github/pull_request_template.md`	Added a template for pull requests with a safety and privacy checklist.	🟡 medium
`.github/scripts/check_docs.py`	Introduced a Python script to validate documentation files and links.	🔴 high
`.github/workflows/documentation-checks.yml`	Created a GitHub Actions workflow to automate documentation checks.	🔴 high

📊 Sequence Diagram

sequenceDiagram
    participant User
    participant GitHub
    participant CI
    User->>GitHub: Push or create PR
    GitHub->>CI: Trigger documentation checks
    CI->>CI: Run check_docs.py
    CI-->>GitHub: Report results

⏱ Review Effort & Risk

Metric	Value
Effort	███░░ 3/5 (Moderate) · ~30min
Risk	🟡 MEDIUM

Risk Factors

New automated checks may fail if documentation structure changes.
Potential for false negatives if links are incorrectly formatted.

Labels: documentation automation CI

💡 Key Observations

The implementation relies solely on Python's standard library, which enhances portability.

The workflow uses read-only permissions, minimizing security risks.

_{🤖 Reviewed by WarpFix — AI-Powered Code Review + CI Repair · Security}

warpfix · 2026-07-20T14:19:09Z

@@ -0,0 +1,15 @@
+## Summary
+
+<!-- Explain the documentation change and why it is needed. -->


💅 Nitpick documentation

Consider providing an example of a documentation change in the summary section.

_{🤖 WarpFix}

warpfix · 2026-07-20T14:19:09Z

+- [ ] No victim, client, or active-case data is included
+- [ ] No credentials, financial records, identity numbers, or private media are included
+- [ ] New factual claims cite an authoritative source
+- [ ] Official links were checked


✨ Praise documentation

Great inclusion of a safety and privacy checklist to ensure sensitive data is not included.

_{🤖 WarpFix}

warpfix · 2026-07-20T14:19:09Z

+- [ ] Guidance is defensive and does not promise recovery or legal outcomes
+
+## Validation
+


💅 Nitpick documentation

Consider adding a checklist item for ensuring that all links in the documentation are functional.

_{🤖 WarpFix}

warpfix · 2026-07-20T14:19:09Z

@@ -0,0 +1,88 @@
+"""Validate required documentation and local Markdown links."""


✨ Praise documentation

Good use of docstrings to explain the purpose of the script.

_{🤖 WarpFix}

warpfix · 2026-07-20T14:19:09Z

+LINK_PATTERN = re.compile(r"!?[[^]]*](([^)]+))")
+
+
+def link_target(raw: str) -> str:


🚨 Critical bug

The script does not handle the case where the required files are missing gracefully. Consider adding error handling.

Suggested change

def link_target(raw: str) -> str:

Add a try-except block around file reading operations.

_{🤖 WarpFix}

warpfix · 2026-07-20T14:19:09Z

+            errors.append(f"missing required file: {relative}")
+
+    markdown_files = sorted(
+        path for path in ROOT.rglob("*.md") if ".git" not in path.parts


⚠️ Warning performance

Using rglob may lead to performance issues if there are many files. Consider limiting the search scope if possible.

_{🤖 WarpFix}

warpfix · 2026-07-20T14:19:09Z

+                if not target:
+                    continue
+
+                resolved = (path.parent / target).resolve()


🚨 Critical bug

The script does not check for circular links which could lead to infinite loops.

Suggested change

resolved = (path.parent / target).resolve()

Implement a set to track visited links and prevent circular references.

_{🤖 WarpFix}

warpfix · 2026-07-20T14:19:09Z

+                if not resolved.exists():
+                    errors.append(
+                        f"{relative}:{line_number}: broken relative link: {raw}"
+                    )


⚠️ Warning style

Consider logging the errors instead of printing them directly for better traceability.

Suggested change

)

Use the logging module to log errors.

_{🤖 WarpFix}

warpfix · 2026-07-20T14:19:09Z

+
+on:
+  push:
+  pull_request:


✨ Praise documentation

Well-defined triggers for the workflow to ensure documentation checks on relevant events.

_{🤖 WarpFix}

warpfix · 2026-07-20T14:19:09Z

+jobs:
+  validate:
+    name: Validate documentation
+    runs-on: ubuntu-latest


💅 Nitpick style

Consider specifying a specific version for the checkout action to avoid unexpected changes.

Suggested change

runs-on: ubuntu-latest

Use a specific version like `actions/checkout@v2.3.4`.

_{🤖 WarpFix}

gemini-code-assist

Code Review

This pull request introduces a pull request template and a Python script (check_docs.py) to validate required documentation files and local Markdown links. The review feedback highlights several critical and high-severity issues in the script: the regular expression for matching Markdown links is broken, a listed required file (docs/seo-metadata.md) is missing from the repository, the repository root resolution is fragile if run from other directories, and the script should exclude common directories like .venv or node_modules when scanning for Markdown files to prevent false positives and performance issues.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

warpfix

🔍 WarpFix PR Review

This pull request introduces a GitHub Actions workflow for automated documentation checks on every push and pull request. It includes a Python script that validates required documentation files, checks for empty Markdown files, and verifies the integrity of relative links.

📖 Walkthrough

The PR adds three files: a pull request template that includes a safety and privacy checklist, a Python script that performs various validation checks on documentation files, and a GitHub Actions workflow configuration that triggers these checks on every push and pull request. The pull request template ensures that contributors consider privacy and safety before submitting changes. The Python script checks for the existence of required documentation files, ensures Markdown files are not empty, and validates that all relative links are correct and do not escape the repository structure. The workflow is configured to run with read-only permissions and has a timeout to prevent long-running jobs.

📁 File Changes

File	Change	Impact
`.github/pull_request_template.md`	Added a template for pull requests with a checklist for safety and privacy.	🟡 medium
`.github/scripts/check_docs.py`	Introduced a Python script to validate documentation files and links.	🔴 high
`.github/workflows/documentation-checks.yml`	Created a GitHub Actions workflow to automate documentation checks.	🔴 high

📊 Sequence Diagram

sequenceDiagram
    participant User
    participant GitHub
    participant CI
    User->>GitHub: Push or PR
    GitHub->>CI: Trigger workflow
    CI->>CI: Run check_docs.py
    CI-->>GitHub: Report results

⏱ Review Effort & Risk

Metric	Value
Effort	███░░ 3/5 (Moderate) · ~30min
Risk	🟡 MEDIUM

Risk Factors

Potential for false negatives in link validation
Dependency on the correctness of the Python script
Impact on workflow execution time if many Markdown files are present

Labels: documentation CI enhancement

💡 Key Observations

The validation script relies solely on Python's standard library, which is a positive aspect for portability.

The pull request template encourages contributors to consider safety and privacy, which is crucial for maintaining data integrity.

_{🤖 Reviewed by WarpFix — AI-Powered Code Review + CI Repair · Security}

warpfix · 2026-07-20T14:23:14Z

@@ -0,0 +1,18 @@
+## Summary
+
+<!-- Explain the documentation change and why it is needed. Example: "Update the NCCIA complaint link and clarify the reporting steps." -->


✨ Praise documentation

Great addition of a summary section to clarify the purpose of the documentation changes.

_{🤖 WarpFix}

warpfix · 2026-07-20T14:23:14Z

+<!-- Check every applicable item before requesting review. -->
+
+- [ ] No victim, client, or active-case data is included
+- [ ] No credentials, financial records, identity numbers, or private media are included


✨ Praise documentation

The safety and privacy checklist is a valuable addition to ensure compliance and protect sensitive information.

_{🤖 WarpFix}

warpfix · 2026-07-20T14:23:14Z

+- [ ] All added or changed documentation links work
+- [ ] Guidance is defensive and does not promise recovery or legal outcomes
+
+## Validation


✨ Praise documentation

Including a validation section is excellent for ensuring that documentation checks are performed.

_{🤖 WarpFix}

warpfix · 2026-07-20T14:23:14Z

+import re
+import sys
+from pathlib import Path
+from urllib.parse import unquote


✨ Praise style

Using pathlib for file handling improves readability and cross-platform compatibility.

_{🤖 WarpFix}

warpfix · 2026-07-20T14:23:14Z

+    else:
+        value = value.split(maxsplit=1)[0]
+    return unquote(value.split("#", 1)[0].split("?", 1)[0])
+


⚠️ Warning logic

Consider adding a check to ensure that the 'REQUIRED' files are not empty or contain only comments.

Suggested change

Add a check after loading the files to validate their content.

_{🤖 WarpFix}

warpfix · 2026-07-20T14:23:15Z

+                        f"{relative}:{line_number}: empty relative link target "
+                        "(add a path or remove the link)"
+                    )
+                    continue


🚨 Critical logic

The link validation does not account for external links, which could lead to false positives.

Suggested change

continue

Add a condition to skip validation for links that start with http or https.

_{🤖 WarpFix}

warpfix · 2026-07-20T14:23:15Z

+                        f"{relative}:{line_number}: link escapes repository: "
+                        f"{raw} (use a path inside the repository)"
+                    )
+                    continue


⚠️ Warning documentation

The error message for broken links could be more informative by suggesting possible fixes.

Suggested change

continue

Include a suggestion to check the target path and filename in the error message.

_{🤖 WarpFix}

warpfix · 2026-07-20T14:23:15Z

+permissions:
+  contents: read
+
+concurrency:


✨ Praise performance

The use of concurrency settings is a good practice to optimize workflow execution.

_{🤖 WarpFix}

warpfix · 2026-07-20T14:23:15Z

+    name: Validate documentation
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+


✨ Praise performance

Specifying a timeout for the job is a good way to prevent hanging processes.

_{🤖 WarpFix}

warpfix · 2026-07-20T14:23:15Z

+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+


✨ Praise style

Using the latest version of the checkout action ensures that you benefit from the latest features and fixes.

_{🤖 WarpFix}

warpfix

🔍 WarpFix PR Review

This pull request introduces a GitHub Actions workflow for validating documentation on every push and pull request. It includes a Python script that checks for required documentation files, validates Markdown links, and ensures compliance with a safety and privacy checklist.

📖 Walkthrough

The changes consist of three main files: a pull request template that outlines a summary and a safety checklist, a Python script that validates the presence of required documentation files and checks for broken links in Markdown files, and a GitHub Actions workflow that triggers the validation process on every push and pull request. The workflow is designed to run with read-only permissions and includes concurrency management to prevent overlapping runs.

📁 File Changes

File	Change	Impact
`.github/pull_request_template.md`	Added a template for pull requests that includes a summary section and a safety checklist.	🟡 medium
`.github/scripts/check_docs.py`	Introduced a Python script to validate required documentation files and check for broken Markdown links.	🔴 high
`.github/workflows/documentation-checks.yml`	Created a GitHub Actions workflow to automate the documentation validation process.	🔴 high

📊 Sequence Diagram

sequenceDiagram
    participant User as User
    participant GitHub as GitHub Actions
    participant Validator as Documentation Validator
    User->>GitHub: Push or PR
    GitHub->>Validator: Trigger validation workflow
    Validator->>Validator: Check required files
    Validator->>Validator: Validate Markdown links
    Validator-->>GitHub: Return validation results
    GitHub-->>User: Notify validation status

⏱ Review Effort & Risk

Metric	Value
Effort	███░░ 3/5 (Moderate) · ~30min
Risk	🟡 MEDIUM

Risk Factors

Potential for false negatives in link validation
Dependence on the correct structure of Markdown files
New workflow may introduce CI/CD pipeline complexity

Labels: documentation CI/CD enhancement

💡 Key Observations

The pull request template encourages thorough documentation practices.

The Python script is dependency-free, which enhances portability.

The workflow includes concurrency management to avoid conflicts.

_{🤖 Reviewed by WarpFix — AI-Powered Code Review + CI Repair · Security}

warpfix · 2026-07-20T14:23:39Z

@@ -0,0 +1,18 @@
+## Summary
+
+<!-- Explain the documentation change and why it is needed. Example: "Update the NCCIA complaint link and clarify the reporting steps." -->


💅 Nitpick documentation

Consider providing a more specific example in the summary section to guide contributors.

_{🤖 WarpFix}

warpfix · 2026-07-20T14:23:39Z

+<!-- Check every applicable item before requesting review. -->
+
+- [ ] No victim, client, or active-case data is included
+- [ ] No credentials, financial records, identity numbers, or private media are included


✨ Praise documentation

Great addition of a safety and privacy checklist to ensure compliance.

_{🤖 WarpFix}

warpfix · 2026-07-20T14:23:39Z

+- [ ] Official links were checked
+- [ ] All added or changed documentation links work
+- [ ] Guidance is defensive and does not promise recovery or legal outcomes
+


💅 Nitpick documentation

Consider adding a brief explanation for each checklist item for clarity.

_{🤖 WarpFix}

warpfix · 2026-07-20T14:23:39Z

+
+ROOT = Path(__file__).resolve().parents[2]
+REQUIRED = (
+    Path("README.md"),


💅 Nitpick style

Consider using a constant for the encoding type to avoid magic strings.

Suggested change

Path("README.md"),

ENCODING = 'utf-8'

text = path.read_text(encoding=ENCODING)

_{🤖 WarpFix}

warpfix · 2026-07-20T14:23:39Z

+def main() -> int:
+    """Validate required files and repository-local Markdown links."""
+    errors: list[str] = []
+


⚠️ Warning logic

Ensure that the 'REQUIRED' files are always present in the repository to avoid runtime errors.

_{🤖 WarpFix}

warpfix · 2026-07-20T14:23:39Z

+        except (OSError, UnicodeError) as exc:
+            errors.append(f"unable to read {relative}: {exc}")
+            continue
+


🚨 Critical error handling

The script does not handle cases where the Markdown file cannot be read due to permission issues.

Suggested change

Consider adding a specific error message for permission errors.

_{🤖 WarpFix}

warpfix · 2026-07-20T14:23:39Z

+                if target.startswith("/"):
+                    resolved = (ROOT / target.lstrip("/")).resolve()
+                else:
+                    resolved = (path.parent / target).resolve()


⚠️ Warning performance

The link validation logic could be optimized to avoid multiple calls to resolve paths.

Suggested change

resolved = (path.parent / target).resolve()

Cache resolved paths to improve performance.

_{🤖 WarpFix}

warpfix · 2026-07-20T14:23:39Z

+                        "(check the target path and filename)"
+                    )
+
+    if errors:


🚨 Critical logic

The script does not exit with a non-zero status code if no Markdown files are found, which may lead to false positives in CI.

Suggested change

if errors:

Return 1 if errors are found, including the case of no Markdown files.

_{🤖 WarpFix}

warpfix · 2026-07-20T14:23:39Z

+  contents: read
+
+concurrency:
+  group: docs-${{ github.workflow }}-${{ github.ref }}


✨ Praise documentation

Well-structured workflow configuration for documentation checks.

_{🤖 WarpFix}

warpfix · 2026-07-20T14:23:39Z

+    name: Validate documentation
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+


💅 Nitpick style

Consider specifying a specific version for the checkout action to avoid unexpected changes.

Suggested change

uses: actions/checkout@v4.0.0

_{🤖 WarpFix}

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 27e38a9d0b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

TehseenTech added 3 commits July 20, 2026 19:18

Add documentation CI workflow

e5f3882

Add documentation validation script

2d0a217

Add safe contribution checklist

27e38a9

warpfix Bot reviewed Jul 20, 2026

View reviewed changes

TehseenTech marked this pull request as ready for review July 20, 2026 14:19

gemini-code-assist Bot reviewed Jul 20, 2026

View reviewed changes

Comment thread .github/scripts/check_docs.py Outdated

Comment thread .github/scripts/check_docs.py

Comment thread .github/scripts/check_docs.py Outdated

Comment thread .github/scripts/check_docs.py

TehseenTech added 2 commits July 20, 2026 19:22

Fix documentation link validation

9e48d7e

Clarify documentation PR checklist

8066e7c

warpfix Bot reviewed Jul 20, 2026

View reviewed changes

chatgpt-codex-connector Bot reviewed Jul 20, 2026

View reviewed changes

Comment thread .github/scripts/check_docs.py Outdated

Comment thread .github/scripts/check_docs.py Outdated

Comment thread .github/scripts/check_docs.py Outdated

TehseenTech merged commit 55214be into main Jul 20, 2026
2 checks passed

		@@ -0,0 +1,15 @@
		## Summary

		<!-- Explain the documentation change and why it is needed. -->

		- [ ] Guidance is defensive and does not promise recovery or legal outcomes

		## Validation

		@@ -0,0 +1,88 @@
		"""Validate required documentation and local Markdown links."""

		LINK_PATTERN = re.compile(r"!?[[^]]*](([^)]+))")


		def link_target(raw: str) -> str:

	def link_target(raw: str) -> str:
	Add a try-except block around file reading operations.

	resolved = (path.parent / target).resolve()
	Implement a set to track visited links and prevent circular references.

	runs-on: ubuntu-latest
	Use a specific version like `actions/checkout@v2.3.4`.

		@@ -0,0 +1,18 @@
		## Summary

		<!-- Explain the documentation change and why it is needed. Example: "Update the NCCIA complaint link and clarify the reporting steps." -->


	Add a check after loading the files to validate their content.

	continue
	Add a condition to skip validation for links that start with http or https.

	continue
	Include a suggestion to check the target path and filename in the error message.

	Path("README.md"),
	ENCODING = 'utf-8'
	text = path.read_text(encoding=ENCODING)


	Consider adding a specific error message for permission errors.

	resolved = (path.parent / target).resolve()
	Cache resolved paths to improve performance.

	if errors:
	Return 1 if errors are found, including the case of no Markdown files.

Conversation

TehseenTech commented Jul 20, 2026

What changed

Why

Validation

Uh oh!

warpfix Bot left a comment

Choose a reason for hiding this comment

🔍 WarpFix PR Review

📁 File Changes

⏱ Review Effort & Risk

💡 Key Observations

Uh oh!

warpfix Bot Jul 20, 2026

Choose a reason for hiding this comment

Uh oh!

warpfix Bot Jul 20, 2026

Choose a reason for hiding this comment

Uh oh!

warpfix Bot Jul 20, 2026

Choose a reason for hiding this comment

Uh oh!

warpfix Bot Jul 20, 2026

Choose a reason for hiding this comment

Uh oh!

warpfix Bot Jul 20, 2026

Choose a reason for hiding this comment

Uh oh!

warpfix Bot Jul 20, 2026

Choose a reason for hiding this comment

Uh oh!

warpfix Bot Jul 20, 2026

Choose a reason for hiding this comment

Uh oh!

warpfix Bot Jul 20, 2026

Choose a reason for hiding this comment

Uh oh!

warpfix Bot Jul 20, 2026

Choose a reason for hiding this comment

Uh oh!

warpfix Bot Jul 20, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

warpfix Bot left a comment

Choose a reason for hiding this comment

🔍 WarpFix PR Review

📁 File Changes

⏱ Review Effort & Risk

💡 Key Observations

Uh oh!

warpfix Bot Jul 20, 2026

Choose a reason for hiding this comment

Uh oh!

warpfix Bot Jul 20, 2026

Choose a reason for hiding this comment

Uh oh!

warpfix Bot Jul 20, 2026

Choose a reason for hiding this comment

Uh oh!

warpfix Bot Jul 20, 2026

Choose a reason for hiding this comment

Uh oh!

warpfix Bot Jul 20, 2026

Choose a reason for hiding this comment

Uh oh!

warpfix Bot Jul 20, 2026

Choose a reason for hiding this comment

Uh oh!

warpfix Bot Jul 20, 2026

Choose a reason for hiding this comment

Uh oh!

warpfix Bot Jul 20, 2026