ci: review CLI contract changes for docs impact

Draft
DA
4mo ago
+172-0

Why

firecrawl-docs#1195 establishes the deterministic reconciliation baseline and initial drift report. This linked follow-up adds advisory semantic review for CLI contract changes that fixed extractors may not cover.

Summary

  • Run an advisory Codex review when a relevant internal CLI pull request is opened, updated, reopened, or marked ready for review.
  • Inspect commands, aliases, arguments, flags, defaults, validation, authentication, output formats, response handling, packaging, and release behavior.
  • Compare the diff with current firecrawl-docs and return No documentation impact, Documentation gap, or Ambiguous.
  • Upsert one PR comment with evidence, affected docs, the smallest next action, and an optional proposed docs patch.
  • Keep analysis read-only and isolate comment permissions in a separate job. The agent cannot edit files, push branches, open PRs, or merge changes.

Safety and activation gates

  • Depends on firecrawl-docs#1195 so the agent reads the merged reconciliation baseline from docs main.
  • Requires a repository or organization OPENAI_API_KEY; without it, the job emits a notice and exits successfully.
  • Runs only for non-draft, same-repository PRs. Fork PR coverage is intentionally deferred because Actions secrets are not exposed to untrusted forks.
  • The review is advisory and is not a required check.

Test plan

  • Parse the workflow as YAML.
  • Syntax-check the embedded GitHub Script.
  • Verify immutable action pins, path coverage, per-PR cancellation, fork/draft guards, read-only sandboxing, and isolated write permissions.
  • Run git diff --check and confirm only the workflow and prompt are added.
  • After the API key is configured, verify an internal CLI contract change receives one updated documentation-impact comment on successive pushes.

No CLI runtime behavior or documentation content changes in this PR.


View with [code]smith Autofix with [code]smith
Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.


Summary by cubic

Adds an advisory CI check that reviews CLI PRs for documentation impact and posts a single upserted comment with the outcome and evidence. No runtime or docs content changes.

  • New Features
    • Add .github/workflows/docs-impact.yml and .github/prompts/docs-impact.md.
    • Triggers on open/sync/reopen/ready_for_review for same-repo, non-draft PRs touching CLI/release paths.
    • Runs openai/codex-action in read-only mode against the PR merge ref and firecrawl-docs main, returning No impact/Documentation gap/Ambiguous with evidence and smallest next action.
    • Publishes or updates one comment via a separate job with minimal write perms; the analysis cannot change code or docs.
    • Requires OPENAI_API_KEY; skipped if missing. Advisory only.