feat: add doc-map input for path-scoped doc injection #137

New Issue

2026-05-15T03:11:24Z

rodin commented

2026-05-15 03:11:24 +00:00

Why

Callers want a reviewer that audits code against project-specific design docs. The current action has no way to inject local repo files as context — only external pattern repos via patterns-repo.

The right model: a config file in the caller's repo maps source paths to governing docs. review-bot reads the map, intersects with changed paths in the PR, and injects only the relevant docs. This keeps context surgical — a PR touching one module gets its governing doc, not the entire docs tree.

What

New action input: `doc-map`

doc-map:
  description: >-
    Path to a YAML file mapping source path globs to governing design docs.
    review-bot intersects the map with changed PR paths and injects matching
    docs as context alongside the diff.
  required: false
  default:

Config file format (`.review-bot/doc-map.yml` in the caller's repo)

mappings:
  - paths:
      - "lib/gargoyle/engine/signal_risk/**"
    docs:
      - docs/domain/contexts/risk/risk-controls.md
  - paths:
      - "lib/gargoyle/risk/kill_switch/**"
    docs:
      - docs/domain/contexts/risk/kill-switch.md
      - docs/domain/user-lifecycle.md
  - paths:
      - "lib/gargoyle/trading/**"
    docs:
      - docs/domain/contexts/trading/

paths — glob patterns matched against changed files in the PR diff
docs — local file paths or directories (all .md files under a directory) to inject
Multiple paths entries can map to the same doc; docs are deduplicated
If no paths match, no docs are injected (reviewer runs with system prompt only)

Behavior

Read and parse doc-map file
Get changed file paths from the PR diff
For each mapping, check if any changed path matches any glob in paths
Collect all matching docs, deduplicate
Read each doc file (or all .md files under a directory) from the local checkout
Inject doc content into the system prompt after the system-prompt-file content, under a ## Design Documents heading
If a doc path does not exist, log a warning and skip (do not fail the review)

Context size guard

If total injected doc content exceeds a configurable limit (default: 100KB), truncate with a notice. Prevents accidental context window overflow when a PR touches many modules.

Acceptance criteria

doc-map input added to action.yml
YAML config parsed and validated (unknown keys = warning, not error)
Glob matching against PR changed paths
Docs injected into system prompt under ## Design Documents heading
Directory paths expand to all .md files under that directory
Missing doc paths: warn and skip, do not fail
No matching paths: no docs injected, review runs normally
Context size guard (configurable, default 100KB)
Tests covering: match, no-match, missing file, directory expansion, deduplication
CHANGELOG updated

Example workflow usage

- name: AI Review (Doc Adherence)
  uses: https://gitea.weiker.me/rodin/review-bot/.gitea/actions/review@<version>
  with:
    reviewer-token: ${{ secrets.GPT_REVIEW_TOKEN }}
    reviewer-name: doc-adherence-reviewer
    llm-base-url: http://172.18.0.1:8081/openai/v1
    llm-api-key: ${{ secrets.HAI_API_KEY }}
    llm-model: gpt-5
    doc-map: .review-bot/doc-map.yml
    system-prompt-file: .review-bot/system-prompts/doc-adherence.txt
    temperature: "0"
    timeout: "600"

## Why Callers want a reviewer that audits code against project-specific design docs. The current action has no way to inject local repo files as context — only external pattern repos via `patterns-repo`. The right model: a config file in the caller's repo maps source paths to governing docs. review-bot reads the map, intersects with changed paths in the PR, and injects only the relevant docs. This keeps context surgical — a PR touching one module gets its governing doc, not the entire docs tree. ## What ### New action input: `doc-map` ```yaml doc-map: description: >- Path to a YAML file mapping source path globs to governing design docs. review-bot intersects the map with changed PR paths and injects matching docs as context alongside the diff. required: false default: ``` ### Config file format (`.review-bot/doc-map.yml` in the caller's repo) ```yaml mappings: - paths: - "lib/gargoyle/engine/signal_risk/**" docs: - docs/domain/contexts/risk/risk-controls.md - paths: - "lib/gargoyle/risk/kill_switch/**" docs: - docs/domain/contexts/risk/kill-switch.md - docs/domain/user-lifecycle.md - paths: - "lib/gargoyle/trading/**" docs: - docs/domain/contexts/trading/ ``` - `paths` — glob patterns matched against changed files in the PR diff - `docs` — local file paths or directories (all `.md` files under a directory) to inject - Multiple `paths` entries can map to the same doc; docs are deduplicated - If no paths match, no docs are injected (reviewer runs with system prompt only) ### Behavior 1. Read and parse `doc-map` file 2. Get changed file paths from the PR diff 3. For each mapping, check if any changed path matches any glob in `paths` 4. Collect all matching `docs`, deduplicate 5. Read each doc file (or all `.md` files under a directory) from the local checkout 6. Inject doc content into the system prompt after the `system-prompt-file` content, under a `## Design Documents` heading 7. If a doc path does not exist, log a warning and skip (do not fail the review) ### Context size guard If total injected doc content exceeds a configurable limit (default: 100KB), truncate with a notice. Prevents accidental context window overflow when a PR touches many modules. ## Acceptance criteria - [ ] `doc-map` input added to action.yml - [ ] YAML config parsed and validated (unknown keys = warning, not error) - [ ] Glob matching against PR changed paths - [ ] Docs injected into system prompt under `## Design Documents` heading - [ ] Directory paths expand to all `.md` files under that directory - [ ] Missing doc paths: warn and skip, do not fail - [ ] No matching paths: no docs injected, review runs normally - [ ] Context size guard (configurable, default 100KB) - [ ] Tests covering: match, no-match, missing file, directory expansion, deduplication - [ ] CHANGELOG updated ## Example workflow usage ```yaml - name: AI Review (Doc Adherence) uses: https://gitea.weiker.me/rodin/review-bot/.gitea/actions/review@<version> with: reviewer-token: ${{ secrets.GPT_REVIEW_TOKEN }} reviewer-name: doc-adherence-reviewer llm-base-url: http://172.18.0.1:8081/openai/v1 llm-api-key: ${{ secrets.HAI_API_KEY }} llm-model: gpt-5 doc-map: .review-bot/doc-map.yml system-prompt-file: .review-bot/system-prompts/doc-adherence.txt temperature: "0" timeout: "600" ``` ## Related grgl/gargoyle#778 — the first consumer of this feature

rodin referenced this issue from a commit

2026-05-15 03:25:59 +00:00

feat(#137): add doc-map input for path-scoped doc injection

rodin referenced this issue

2026-05-15 03:26:16 +00:00

feat(#137): add doc-map input for path-scoped doc injection #138

rodin referenced this issue from a commit

2026-05-15 03:32:32 +00:00

fix(#137): address review findings in docmap.go

rodin referenced this issue from a commit

2026-05-15 03:32:32 +00:00

test(#137): add tests for validateDocPath and path traversal rejection