feat/docs: Enhance AI Agent Integration, Refactor Documentation, and Improve CLI Usability#12
Merged
feat/docs: Enhance AI Agent Integration, Refactor Documentation, and Improve CLI Usability#12
Conversation
- Changed default behavior from clipboard copy to stdout. - Remove `-p` (`--print`) flag as printing is now the default. - Add `-c` (`--copy`) flag to support clipboard copying for human users. - Improve compatibility with AI agents (Cursor, Windsurf) and Unix pipelines.
- Create a detailed guide document to help AI agents and users understand JFocus strategies. - Define optimal analysis workflow (Do NOT read entire file). - Explain CLI syntax, options (-c, -v), and examples.
- Add configuration rules for AI agents (e.g., Cursor, Windsurf) to autonomously use JFocus. - Mandate usage of `jfocus <file> <method>` over full-file reading. - Establish "Trust Model" treating JFocus output as the single source of truth.
…dards
- Translate `README.ko.md` to English (`README.md`) with a professional senior engineer tone.
- Add language switchers ([🇰🇷 Korean | 🇺🇸 English]) to both files.
- Refine `README.ko.md` based on expert feedback:
- Strengthen intro with problem-solving tagline.
- Clarify AST 'Symbol Resolution' technical details.
- Add qualitative results ("Reduced Hallucination") to benchmarks.
|
Warning Rate limit exceeded
⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. 📝 WalkthroughWalkthroughAdds comprehensive English and Korean documentation and AI-agent guidance, automates installer scripts to configure PATH/alias, and changes the CLI to use a copy-to-clipboard flag instead of the previous print flag. Changes
Sequence Diagram(s)(omitted) Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches🧪 Generate unit tests (beta)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 7
🤖 Fix all issues with AI agents
In `@src/main/java/com/jher235/jfocus/docs/rules.md`:
- Around line 1-15: README.md's inline .cursorrules block and rules.md are out
of sync: the README includes a "Trust Model" section (item "Trust Model") that
is missing from src/main/java/com/jher235/jfocus/docs/rules.md, which will
produce an incomplete .cursorrules if users copy rules.md verbatim. Fix by
making rules.md the single source of truth: add the missing "Trust Model"
section content from README.md into rules.md (ensuring the section header and
items match the README's wording), then change README.md to reference rules.md
for the .cursorrules content instead of duplicating it (or replace the inline
block with a short pointer to rules.md); ensure references to ".cursorrules"
remain consistent.
In `@src/README.ko.md`:
- Around line 307-353: The outer markdown code fence in README.ko.md around the
ContextExtractor examples is closed prematurely by inner ```java fences; update
the outer fence to use a longer fence (e.g., ````markdown) or switch to an
alternate fence style (e.g., ~~~markdown) so the inner ```java blocks (shown
around ContextExtractor.extractContext() and extractRecursive()) do not
terminate it; ensure all occurrences for the ContextResult/DependencyResolver
examples keep matching fence counts.
- Around line 365-393: Update the broken relative link and relocate the
misplaced bullet: change the link target
`src/main/java/com/jher235/jfocus/docs/rules.md` (inside the "1. `.cursorrules`
설정" block) to the correct `docs/rules.md`, and move the `jfocus <file> <method>`
bullet currently under the "Trust Model" section into the "Command Usage"
section so it appears alongside other command examples; refer to the "Trust
Model" and "Command Usage" headings and the `jfocus <file> <method>` bullet to
locate the text to modify.
In `@src/README.md`:
- Around line 304-351: The README's example uses a fenced ```markdown block that
contains an inner ```java fenced block which breaks rendering; update the outer
fence to a higher-count fence (e.g., ````markdown) or replace the outer fenced
block with an HTML <pre><code> section so the inner ```java block remains
intact, ensuring the code snippets for the extractContext(MethodDeclaration),
extractRecursive(...), and DependencyResolver example render correctly.
- Around line 360-388: Update the `.cursorrules` block in README.md to fix the
broken relative link and move the misplaced command: change the href
`src/main/java/com/jher235/jfocus/docs/rules.md` to
`main/java/com/jher235/jfocus/docs/rules.md` so the link resolves correctly, and
relocate the line `jfocus <file> <method> : Extracts context for the method.`
from the "Trust Model" section into the "Command Usage" section (replacing the
`...` placeholder) so command usage items are grouped together; ensure the block
still contains the other `jfocus` examples and the Trust Model only contains
trust-related bullets.
- Around line 15-24: The Table of Contents links contain an extra leading hyphen
in each fragment (e.g., "#-introduction", "#-benchmarks", "#-features",
"#-installation", "#-usage", "#-for-ai-agents-cursor-windsurf",
"#-contributing", "#-license"); edit the TOC entries under "## 📝 Table of
Contents" to remove the leading hyphen from every link fragment so they match
GitHub's generated anchors (e.g., change "#-introduction" to "#introduction",
"#-for-ai-agents-cursor-windsurf" to "#for-ai-agents-cursor-windsurf", etc.).
In `@src/scripts/install.sh`:
- Around line 70-81: The RC detection logic incorrectly prefers
$BASH_VERSION/$ZSH_VERSION causing piped installs (curl | bash) to always pick
bash; update the logic in the install script to consult the login shell first
(use $SHELL with the existing case pattern) before falling back to
$ZSH_VERSION/$BASH_VERSION checks, e.g., move the case "$SHELL" block ahead of
the version checks and only use $BASH_VERSION/$ZSH_VERSION as a secondary
heuristic; ensure the variable RC_FILE is set to "$HOME/.zshrc" for zsh shells
and "$HOME/.bashrc" for bash shells using the existing symbols RC_FILE, $SHELL,
$ZSH_VERSION, and $BASH_VERSION.
🧹 Nitpick comments (1)
src/scripts/install.sh (1)
92-94: Minor:datecalled twice could yield different filenames at midnight boundary.The backup filename (line 93) and the printed message (line 94) each invoke
dateindependently. Store it in a variable instead.Proposed fix
+ BACKUP_SUFFIX=$(date +%Y%m%d) - cp "$RC_FILE" "$RC_FILE.backup-$(date +%Y%m%d)" - echo "📦 Created backup: $RC_FILE.backup-$(date +%Y%m%d)" + cp "$RC_FILE" "$RC_FILE.backup-$BACKUP_SUFFIX" + echo "📦 Created backup: $RC_FILE.backup-$BACKUP_SUFFIX"
- Update `rules.md` to include the 'Trust Model' section as requested by code review. - Remove duplicate rules content from `README.md` and link to `rules.md` instead. - Ensure consistency between documentation and actual agent instructions.
Refactored - This ensures that users running the one-liner via curl | bash will have the jfocus alias correctly appended to their actual login shell's config file (e.g., .zshrc) instead of being incorrectly defaulted to .bashrc.
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Fix all issues with AI agents
In `@src/README.ko.md`:
- Around line 299-301: The heading "### 📄 출력 결과 예시 (Output Example)" is
indented and won't render as a Markdown heading; remove the leading whitespace
before that heading so the line starts with "###" (i.e., change the line
containing "### 📄 출력 결과 예시 (Output Example)" to have no leading spaces) to
ensure it renders correctly.
In `@src/README.md`:
- Around line 296-298: The "### 📄 Output Example" heading in the README is
indented and therefore won't render as a Markdown heading; edit the README to
remove the leading whitespace so the line beginning with "### 📄 Output Example"
starts at column 1 (no leading spaces or tabs) so Markdown parsers will render
it as a proper heading.
🧹 Nitpick comments (1)
src/scripts/install.sh (1)
92-97: Minor:dateis invoked twice, producing potentially different filenames.On line 96 the backup is created with one
date +%Y%m%dinvocation, and on line 97 a different invocation is echoed to the user. At a day boundary these could differ. Trivial in practice, but capturing the value once is cleaner.Proposed fix
+ BACKUP_SUFFIX="$(date +%Y%m%d)" - cp "$RC_FILE" "$RC_FILE.backup-$(date +%Y%m%d)" - echo "📦 Created backup: $RC_FILE.backup-$(date +%Y%m%d)" + cp "$RC_FILE" "$RC_FILE.backup-$BACKUP_SUFFIX" + echo "📦 Created backup: $RC_FILE.backup-$BACKUP_SUFFIX"
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Fix all issues with AI agents
In `@src/README.ko.md`:
- Around line 15-24: The TOC links currently use fragments with a leading hyphen
(e.g. "#-소개", "#-효과-benchmarks", "#-주요-기능", "#-설치-방법", "#-사용-방법", "#-기여하기",
"#-라이선스") which won't resolve on GitHub; update each entry in the TOC to remove
the leading hyphen so they read "#소개", "#효과-benchmarks", "#주요-기능", "#설치-방법",
"#사용-방법", "#for-ai-agents-cursor-windsurf" (if present), "#기여하기", and "#라이선스" to
match the actual anchor IDs of the headings.
In `@src/README.md`:
- Around line 145-147: The Windows PowerShell README section ("#### Windows
(PowerShell)") contains a sentence fragment; change "Can be executed without
administrator privileges." to a complete sentence such as "This script can be
executed without administrator privileges." and keep the following sentence
about PATH behavior intact so the two lines read clearly together.
- Update SHA256 checksums in `install.sh` and `install.ps1` for the latest build. - Fix logic in `install.sh` to correctly detect user shell (zsh/bash) when piped via curl.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
📝 Description
This Pull Request introduces a significant set of enhancements aimed at making JFocus more powerful and user-friendly, especially for AI agent integration. It includes a comprehensive overhaul of the documentation, a core functional change to improve AI agent compatibility, and several CLI usability improvements.
The documentation has been refined to meet senior engineering standards, translated for a global audience, and now includes detailed guidance for AI agents. A key functional change switches the default output to stdout, aligning JFocus with standard Unix tooling and AI agent workflows, while retaining clipboard functionality via a new flag.
✨ What does this PR do?
Documentation Overhaul & Localization:
README.ko.mdhas been translated into a newREADME.md(English) with a professional, senior engineering tone, ensuring clarity and accessibility for a global audience.README.ko.mdandREADME.mdhave been refined based on expert feedback. This includes strengthening the introduction with a problem-solving tagline, clarifying technical details like AST 'Symbol Resolution', and adding qualitative results ("Reduced Hallucination") to the benchmarks section.[🇰🇷 Korean | 🇺🇸 English]language switchers to both README files for easy navigation between versions.Enhanced AI Agent Integration:
jfocus <file> <method>for precise context extraction, preventing inefficient full-file reading.-c,-v), and examples.CLI Usability & AI Compatibility Improvements:
-c(--copy) Flag: A new-cor--copyflag has been introduced to explicitly support clipboard copying for human users who prefer this functionality.-p(--print) Flag: The-p(--print) flag has been removed as printing to stdout is now the default behavior.jfocuscommand.Summary by CodeRabbit
New Features
Documentation