Add --recurse mode to fedify lookup and fix separator output

[dahlia]

Summary

This PR implements recursive relationship lookup for fedify lookup and fixes separator rendering in multi-object output flows.

• Added --recurse=<PROPERTY_OR_IRI> to recursively follow object relationships.
• Accepted short form: replyTarget.
• Accepted full IRI: https://www.w3.org/ns/activitystreams#inReplyTo.
• Rejected short form: inReplyTo.
• Added --recurse-depth=<N> with a default depth of 20.
• Enforced parser-level dependency: --recurse-depth requires --recurse.
• Enforced parser-level mutual exclusion: --traverse and --recurse cannot be used together.
• Extended --suppress-errors behavior to recurse mode for best-effort chain traversal.
• Added recursion safeguards: visited tracking for loop protection and depth cap handling.
• Fixed separator output so separators are printed as plain text without extra quotes in recurse/traverse and other multi-object lookup flows.
• Updated docs/cli.md with new options and examples.
• Updated CHANGES.md with both the recurse feature and separator bug fix entries.

Tests

Added and expanded tests in packages/cli/src/lookup.test.ts for parser behavior (--recurse, --recurse-depth dependency, traverse/recurse conflict), accepted/rejected recurse property forms, recursion behavior (depth limit, cycle handling), error behavior with and without --suppress-errors, and recursive target resolution helper behavior.

Manual verification

• Verified live recurse lookup on real fediverse objects, including the documented hollo.social example URL.
• Verified separator output is unquoted in both recurse and traverse flows.

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the fedify lookup command by introducing a powerful recursive lookup mode. Users can now trace object relationships, like reply chains, up to a specified depth, making it easier to explore interconnected data on the fediverse. Additionally, it resolves a minor but important bug that caused separators in multi-object outputs to be incorrectly quoted, improving the consistency and readability of the command's output.

Highlights

• New Recursion Mode: Introduced --recurse and --recurse-depth options to fedify lookup for recursively following object relationships, such as reply chains.
• Property Specification: Allowed --recurse to accept both short-form Fedify property names (e.g., replyTarget) and full IRIs (e.g., https://www.w3.org/ns/activitystreams#inReplyTo).
• Command-Line Logic: Implemented parser-level validation ensuring --recurse-depth is used only with --recurse, and that --recurse and --traverse are mutually exclusive.
• Error Handling: Extended --suppress-errors to provide best-effort chain traversal in recurse mode and added safeguards like visited tracking and depth capping to prevent infinite loops.
• Output Formatting Fix: Corrected an issue where separators were printed with extra quotes in multi-object output flows, ensuring they are now plain text.
• Documentation and Tests: Updated CLI documentation with new options and examples, and expanded test coverage for the new recurse features and parser behavior.

Changelog

• @fedify/cli
  • Fixed fedify lookup printing separators with extra quotes between adjacent objects/items in some output paths (e.g., recurse/traverse flows). Separators are now printed as plain text consistently. [[Add --recurse mode to fedify lookup and fix separator output #608]]
  • Added --recurse and --recurse-depth options to fedify lookup for recursively following object relationships (e.g., reply chains via replyTarget / inReplyTo). --traverse and --recurse are now mutually exclusive, --recurse-depth depends on --recurse, and --suppress-errors now works in recurse mode as best-effort lookup. [[Add --recurse to fedify lookup for recursive object-reference lookup #606], [Add --recurse mode to fedify lookup and fix separator output #608]]

Activity

• No human activity has occurred on this pull request yet.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a valuable recursive lookup feature to the fedify lookup command and fixes an issue with separator rendering. The implementation is well-structured, with clear separation of concerns in the new helper functions like collectRecursiveObjects. The command-line options are thoughtfully designed to be mutually exclusive with traversal mode, and the addition of comprehensive tests ensures the new functionality is robust. The documentation updates are also clear and helpful.

[Copilot]

Pull request overview

Adds a new recursive lookup mode to fedify lookup for following object relationships (e.g., reply chains), and adjusts multi-object output so separators are emitted as plain text (unquoted).

Changes:

• Added --recurse / --recurse-depth lookup mode with cycle protection, depth limiting, and best-effort behavior via --suppress-errors.
• Reworked lookup-mode parsing to make --traverse and --recurse mutually exclusive and to require --recurse when using --recurse-depth.
• Updated output separator printing in recurse/traverse and other multi-object flows, plus docs/changelog and expanded CLI tests.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
packages/cli/src/lookup.ts	Implements recurse mode, recursion helpers, and updates separator printing paths.
packages/cli/src/lookup.test.ts	Adds parser and recursion helper tests for recurse mode and error/cycle/depth behaviors.
packages/cli/src/config.ts	Extends lookup config schema with recurse and recurseDepth.
docs/cli.md	Documents --recurse, --recurse-depth, updated --suppress-errors, and usage notes.
CHANGES.md	Adds changelog entries for recurse feature and separator output fix.

[codecov]

Codecov Report

❌ Patch coverage is 48.08260% with 352 lines in your changes missing coverage. Please review.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
packages/cli/src/lookup.ts	41.15%	325 Missing and 1 partial ⚠️
packages/cli/src/imagerenderer.ts	70.42%	19 Missing and 2 partials ⚠️
packages/cli/src/config.ts	86.48%	5 Missing ⚠️

Files with missing lines	Coverage Δ
packages/cli/src/docloader.ts	100.00% <100.00%> (ø)
packages/cli/src/config.ts	83.33% <86.48%> (-0.67%)	⬇️
packages/cli/src/imagerenderer.ts	42.45% <70.42%> (+28.82%)	⬆️
packages/cli/src/lookup.ts	43.50% <41.15%> (-0.38%)	⬇️

... and 1 file with indirect coverage changes

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[dahlia]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces a recursive lookup feature (--recurse) to the fedify lookup command, allowing users to traverse object relationships like reply chains, and also includes a fix for separator rendering in multi-object outputs. However, a critical security vulnerability exists in how output is handled when the --output option is used: the writeObjectToStream function truncates the output file on every call and leaks file descriptors, leading to data loss and potential resource exhaustion. It is recommended to refactor the output logic to open the file stream once and pass it to the writing function. Additionally, there are suggestions to improve code maintainability and simplify a helper function.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

[dahlia]

/gemini review

[dahlia]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces a significant new feature, --recurse, to the fedify lookup command, allowing for recursive traversal of object relationships. It also includes a fix for separator quoting in multi-object outputs and a crucial security enhancement that disallows private address lookups by default. The implementation is robust, with comprehensive tests covering new functionality, edge cases, and security considerations. My review includes suggestions to further improve security by adopting a safer default parameter, enhance maintainability by refactoring the process exit logic, and increase the clarity of the changelog.

_{Note: Security Review did not run due to the size of the PR.}

[Copilot]

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

packages/cli/src/imagerenderer.ts:149

• downloadImage() now validates URLs with validatePublicUrl() and manually follows up to 10 redirects (and will skip private/localhost targets and redirect chains). This is a user-visible behavior/security change for image rendering in fedify lookup, but it isn’t mentioned in the PR description/CHANGES summary; please document it (or add a changelog entry) so users understand why some images may no longer render.

export async function downloadImage(url: string): Promise<string | null> {
  try {
    let targetUrl = url;
    let response: Response | null = null;
    for (let redirectCount = 0; redirectCount < 10; redirectCount++) {
      await validatePublicUrl(targetUrl);
      response = await fetch(targetUrl, { redirect: "manual" });
      if (
        response.status === 301 || response.status === 302 ||
        response.status === 303 || response.status === 307 ||
        response.status === 308
      ) {
        const location = response.headers.get("location");
        if (location == null) {
          await response.body?.cancel();
          return null;
        }
        await response.body?.cancel();
        targetUrl = new URL(location, targetUrl).href;
        continue;
      }
      break;
    }
    if (response == null) return null;
    if (!response.ok) {
      await response.body?.cancel();
      return null;
    }
    const imageData = new Uint8Array(await response.arrayBuffer());
    const extension = new URL(targetUrl).pathname.split(".").pop() || "jpg";
    if (
      extension.includes("/") || extension.includes("\\") ||
      extension.includes("..")
    ) {
      return null;
    }
    const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "fedify"));
    const tempPath = path.join(tempDir, `image.${extension}`);

    await fs.writeFile(tempPath, imageData);

    return tempPath;
  } catch (_error) {
    return null;
  }

[dahlia]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces a recursive lookup feature to fedify lookup and resolves a separator rendering bug. The implementation is robust, including new CLI options, updated documentation, and thorough tests. Security is well-addressed through a hardened image downloader and distinct document loaders for recursive fetches, which correctly restrict access to private addresses. The overall code quality is high, and the noted areas for maintainability enhancement, particularly by refactoring the large runLookup function and other readability improvements, remain valid.

[Copilot]

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 3 comments.

[dahlia]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces a new --recurse feature to the fedify lookup command, enabling users to recursively follow object relationships such as reply and quote chains up to a specified depth. It adds --recurse and --recurse-depth options, making them mutually exclusive with --traverse. The command's security is enhanced by disallowing private/localhost document loads by default, with a new -p/--allow-private-address option to re-enable this for explicit lookups, though recursive fetches strictly disallow private addresses. The --suppress-errors option now also applies to recursive operations. Code changes include updating configuration schemas to support new options, refactoring document loaders to incorporate allowPrivateAddress and cache isolation, and improving image downloading with redirect validation and path traversal prevention. The output handling for fedify lookup has been refactored for better stream management and error reporting, including specific hints for private address or authorization issues. Documentation and tests have been updated to reflect these new features and security measures.

[Copilot]

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 2 comments.

[dahlia]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces a powerful recursive lookup feature to the fedify lookup command and significantly hardens the CLI against Server-Side Request Forgery (SSRF) vulnerabilities. The implementation of --recurse and --recurse-depth is robust, with proper handling of depth limits and cycles. The security improvements, particularly in imagerenderer and the new default-deny policy for private addresses in lookup, are excellent. The code is well-structured, and the addition of comprehensive tests is commendable. I have one suggestion to improve security consistency across the CLI toolchain by changing a default parameter.

[Copilot]

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 1 comment.

[dahlia]

/gemini review

[dahlia]

@codex review

[gemini-code-assist]

Code Review

This pull request introduces a recursive lookup feature (--recurse) to the fedify lookup command, allowing users to traverse object relationships like reply chains. It also includes significant security enhancements by preventing fetches to private/localhost addresses by default in both lookup and image downloading, with manual overrides for development. The implementation correctly handles redirects and validates URLs to prevent SSRF vulnerabilities. A bug related to quoted separator output in multi-object lookups has also been fixed. The changes are accompanied by thorough tests and documentation updates. The lookup command has been refactored to support different modes and manage output streams robustly.

_{Note: Security Review did not run due to the size of the PR.}

[Copilot]

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 3 comments.

[dahlia]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces a powerful recursive lookup feature to fedify lookup and significantly hardens the CLI against security vulnerabilities like SSRF and path traversal. The changes are well-structured, with clear separation of concerns, robust error handling, and comprehensive tests. The addition of --recurse and --recurse-depth is well-documented, and the fix for separator output improves the user experience for multi-object lookups. The security enhancements, particularly the strict handling of private addresses in recursive fetches and image downloads, are excellent. The code quality is high, and the changes are a great addition to the project.

_{Note: Security Review did not run due to the size of the PR.}

[Copilot]

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated no new comments.