[cheol-95]

Change

Codex document skills return :codex-file-citation{...} for generated files, but Ovis chat displayed the directive as text. Parse local source and output citations into Ovis's existing file links, so the viewer can open the file or offer its download. Existing conversation text is unchanged, and code examples and incomplete or unsupported directives remain readable.

This follows the Codex document skills' file-citation output and uses Ovis's existing file-link presentation rather than adding another artifact UI. Live artifact references are left as text; source locators such as page numbers are not used for navigation. Directives containing } inside an attribute value are also left as text.

Closes #2611

Validation

• bun test src/lib/markdown.test.ts: 55 passed. Covers output and source citations, Unicode and spaced paths, Windows paths, inline and fenced code, invalid/incomplete directives, and the existing file-button rendering.
• bun run check fast on macOS (Bun 1.4.2): generated types/themes, typecheck and build passed. Unit suite did not pass: 10,360 passed, 28 failed, 264 skipped across 660 files. Failures include socket teardown (ENOTSOCK), installation, process and platform-specific tests. One unrelated server/usage-login-private.test.ts process was manually terminated after it did not finish (exit 143; no result). The new Markdown suite passed in that run.
• Workflow syntax was skipped by the check on macOS. Integration/browser and native Windows checks were not run locally; fork PR CI needs maintainer approval.
• No browser screenshot or interactive file-open test was run.

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

Run configuration

• Source mode: Auto
• Repository: devswha/ovis
• Branch: main
• File: .coderabbit.yaml
• Commit: 7aecb24
• Layers: Repository YAML
• Review profile: CHILL
• Plan: Advanced
• Run ID: a880facc-dfdd-4f97-9c4c-d5c80090707a

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• Trigger review

No actionable comments were generated in the recent review.

Recent review info

Run configuration

• Source mode: Auto
• Repository: devswha/ovis
• Branch: main
• File: .coderabbit.yaml
• Commit: 7aecb24
• Layers: Repository YAML
• Review profile: CHILL
• Plan: Advanced
• Run ID: 91ac9091-0d3b-4b7a-bbf7-d1a954edd01e

Commits

Reviewing files that changed from the base of the PR and between 7aecb24 and 7ea51bd.

Files selected for processing: 3

• changelog.d/codex-file-citations.md
• shared/markdown.ts
• src/lib/markdown.test.ts

Included review availability: This review used your included allowance. Your plan provides up to 4 included reviews per hour; 3 remain after this review.

Summary

Summary by CodeRabbit

• New Features
  • Codex file citations in chat now open the referenced local file instead of displaying the raw directive. Valid citations show the file name; invalid or incomplete citations remain as text.

The Markdown parser now recognizes supported Codex file citations in chat. It converts valid citations into file nodes that use the existing file-opening path. Unsupported, incomplete, or code-form citations remain readable as text or code.

Changes: Codex file citations

Layer / File(s)	Summary
Citation validation and scanning shared/markdown.ts, src/lib/markdown.test.ts	The inline scanner recognizes citation directives that close on the same line. Attribute validation rejects malformed, duplicate, or unsupported values. Scan tests cover citation openers and closing braces.
File-node conversion and rendering shared/markdown.ts, src/lib/markdown.test.ts, changelog.d/codex-file-citations.md	With inline marks enabled, valid citations become file nodes with the cited path and basename. Tests cover supported paths, invalid and code-form citations, and rendering through the file opener. The changelog records the behavior.

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Bug fix · Severity of issue fixed: Low

Possibly related PRs

• devswha/ovis#2220: It moved the Markdown parser and file-link handling into shared/markdown.ts, which this change extends.

Suggested reviewers: devswha

Merge Risk: Minimal · previous review 7ea51

Unsupported citations containing a brace and Markdown characters can still be formatted, but no merge-blocking regression was established.

Pre-merge checks: 5

Check name	Status	Explanation
Title check		The title clearly and concisely describes the main change: rendering Codex file citations in chat.
Description check		The description includes the required Change and Validation sections. It explains the problem, resulting behavior, linked issue, executed checks, failures, skipped checks, and platform limitations.
Linked Issues check		Issue [#2611] requires actionable file links for Codex local document and PDF citations. shared/markdown.ts recognizes complete :codex-file-citation{...} tokens and converts valid absolute `source…
Out of Scope Changes check		The changes stay within issue [#2611]. The parser change implements citation rendering, the tests verify valid and unsupported cases plus file-opener output, and the changelog documents the fix. No un…
Docstring Coverage		Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentat…

Full details: Linked Issues check

Explanation

Issue [#2611] requires actionable file links for Codex local document and PDF citations. shared/markdown.ts recognizes complete :codex-file-citation{...} tokens and converts valid absolute source and output paths to the existing file node. Invalid, incomplete, non-local, live, and code-form citations remain text or code. src/lib/markdown.test.ts covers citation parsing and existing file-opener rendering.

Full details: Out of Scope Changes check

Explanation

The changes stay within issue [#2611]. The parser change implements citation rendering, the tests verify valid and unsupported cases plus file-opener output, and the changelog documents the fix. No unrelated product behavior is changed.

Full details: Docstring Coverage

Explanation

Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentation-only edits and deletions within surviving functions are included; unchanged diff context and fully deleted functions are excluded. Analyzed 2 functions across 2 files. (1 skipped: 1 unsupported.)

Finishing Touches

Generate unit tests (beta)

• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

• X
• Mastodon
• Reddit
• LinkedIn

[devswha]

Thanks @cheol-95. Review (omo + Codex Terra) found three things, fixed on your branch in 73f4eab:

• A citation could point at a Windows network share (//host/share/a or \\host\share\a, also through \u002f escapes) or contain DEL, which the file:/// handling in shared/fileUri.ts refuses on purpose. The path is now held to the same rule.
• The token took everything up to the next } before checking it was a directive, so an unfinished :codex-file-citation{ swallowed the bold, code or valid citation after it. Only a well-formed directive is a token now.
• A } inside a quoted value ended the directive; quoted values are now read as strings.
  Two tests cover these and fail on 7ea51bd; bun run check fast passed (10,637 unit tests). A 1 MB line of malformed openers or one unclosed value still parses in 20-160 ms, growing linearly.

[devswha]

Codex Terra's check of 73f4eab confirmed those three, and found two small parsing gaps that were already in the first commit; fixed in cf76d15: a value holding an escape JSON cannot read (\q) is no directive, so the markdown inside it stays markdown, and spaces or tabs before the closing } no longer leave a valid citation as text. The new test fails on 73f4eab; bun run check fast passed (10,637 unit tests).

[devswha]

Thanks @cheol-95, this fixes #2611: on main a Codex citation such as :codex-file-citation{path="/tmp/out/report.pdf" purpose="output"} showed as raw text; on this branch it becomes the chat's existing file link (report.pdf), which the file viewer opens or downloads.

Merge-pass checks:

• Same reach as before: the citation produces the same file node a file:/// link already does, so opening it goes through the same file viewer and server access checks; only absolute paths (POSIX, drive or UNC) with purpose source/output are accepted, control characters are refused after unescaping, and a relative path or a mode attribute stays text.
• Malformed or unsupported directives stay plain text (checked: a relative path and a mode="x" directive render unchanged).
• No pathological cost: a 1 MB line of 50,000 unclosed :codex-file-citation{ openers parses in 11 ms (0.8 ms on main), an unclosed 1 MB attribute in 0.7 ms, 40,000 escape-heavy openers in 3 ms.
• Reviews: omo + Codex Terra xhigh found a network-share/DEL path bypass, an unfinished directive swallowing the markdown after it, and a } inside a quoted value ending it; fixed in 73f4eab (path held to fileUri.ts's rule, only well-formed directives are tokens), with tests that fail on 7ea51bd. 1 MB adversarial lines on the fixed head: 19-156 ms, linear.
• cf76d15 (Terra's delta): only escapes JSON can read form a directive, and spaces before } are allowed.
• Left as LOW: a mode attribute leaves the directive as text (no Codex skill emits one), Google Drive citations with https:// paths stay as text (possible follow-up), the literal 21 (the directive prefix length) appears twice.