Add permission display modes

[seapagan]

Adds a long-format permissions option with symbolic, octal, both, and none modes. Includes config support, octal rendering and coloring, tests, README notes, and mdBook usage/config documentation.

Summary by CodeRabbit

• New Features

  • Added a new --permissions option for long-format output, letting you choose symbolic, octal, both, or no permissions display.
  • Added support for setting the same permission display mode in configuration files.

• Bug Fixes

  • Long-format listings now show permission details consistently with the selected display mode.
  • Octal permission values are now rendered in a standard four-digit format.

• Documentation

  • Updated usage and configuration docs to describe the new permission display options and defaults.

[coderabbitai]

Warning

Review limit reached

@seapagan, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 45 minutes and 38 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 783da5cb-6ec5-4f56-8f59-81b2535ca842

📥 Commits

Reviewing files that changed from the base of the PR and between a028256 and 3585287.

📒 Files selected for processing (7)

• src/cli.rs
• src/structs.rs
• src/utils/render.rs
• tests/crate/cli.rs
• tests/crate/render.rs
• tests/crate/settings.rs
• tests/structs.rs

📝 Walkthrough

Walkthrough

Adds a --permissions <MODE> CLI flag and matching config option that controls how Unix permission fields are rendered in long-format output. Supported modes are symbolic (default), octal, both, and none. A new PermissionDisplay enum is introduced in structs.rs, raw mode_bits are captured in FileInfo, a mode_to_octal format helper is added, and the long-format row builder is updated to conditionally append one or two permission cells. Documentation and tests cover all four modes.

Changes

Permission Display Mode Feature

Layer / File(s)	Summary
PermissionDisplay enum, Params and FileInfo field additions src/structs.rs, src/lib.rs	Defines PermissionDisplay enum (Symbolic, Octal, Both, None) with serde kebab-case mapping, adds permissions: PermissionDisplay to Params, RawParams, Default, merge, and From<RawParams>, and adds mode_bits: u32 to FileInfo. Re-exports PermissionDisplay from lib.rs.
mode_bits capture and mode_to_octal helper src/utils/file.rs, src/utils/format.rs	FileDetails and FileInfo gain mode_bits computed as mode & 0o7777. mode_to_octal formats a u32 as a zero-padded four-digit octal string.
--permissions CLI flag definition and parsing src/cli.rs	Adds ARG_PERMISSIONS constant, permissions: Option<PermissionDisplay> field to Flags, registers permissions_arg() in the clap builder with restricted valid values, and maps string values to PermissionDisplay variants in flags_from_matches.
Long-format permission cell rendering src/utils/render.rs	Introduces append_permission_cells which dispatches on params.permissions to push symbolic, octal, both, or no Cells. Refactors long_file_type_text, long_octal_permission_text, and long_permission_text with consistent early returns for the no-colour path.
Tests, integration coverage, and documentation tests/*, README.md, docs/src/*	Adds unit tests for mode_to_octal, CLI parsing, struct merge precedence, and render output for all four modes. Adds a Unix-only integration test exercising --permissions across all modes. Updates README.md, docs/src/config.md, and docs/src/usage.md with --permissions option descriptions.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• seapagan/lsplus#129: Both PRs modify long-format permission cell construction in src/utils/render.rs; the retrieved PR adds colour-level gating whilst this PR layers display-mode switching on top of the same helpers.
• seapagan/lsplus#132: Both PRs touch special-permission-bit rendering (s/S/t/T) in src/utils/render.rs, so the formatting changes interact directly with the new octal and symbolic output paths.

Suggested labels

testing, documentation

🐇 A rabbit hopped by at quarter to three,
Counting bits in the mode — 0755, you see!
Symbolic, octal, or both on one line,
Or none if you'd rather your perms not to shine.
Four little modes, all lined up in a row —
Now lsp -l has quite the octal show! 🎉

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 78.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: adding configurable permission display modes for long-format output.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/permission-display-modes

---

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

_{Comment @coderabbitai help to get the list of available commands.}

[codacy-production]

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

🟢 Metrics 15 complexity · -28 duplication

Metric	Results
Complexity	15
Duplication	-28

View in Codacy

_{NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.}

[coderabbitai]

🧹 Nitpick comments (2)

src/lib.rs (1)

14-16: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Avoid promoting PermissionDisplay to the crate root.

This enum looks like internal CLI/config wiring, and re-exporting it here makes it part of the most visible public surface. Given this crate is treated as the lsp application rather than a supported library API, I’d keep new types like this off the root export list unless an external consumer genuinely needs them. Based on learnings, prefer tighter visibility for app-internal types.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/lib.rs` around lines 14 - 16, The crate root export list in src/lib.rs is
exposing PermissionDisplay unnecessarily, which widens the public surface for an
app-internal type. Remove PermissionDisplay from the pub use structs::{...}
re-export in src/lib.rs, and keep the remaining root exports limited to the
types intended for external use.

Source: Learnings

src/cli.rs (1)

425-431: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Make PermissionDisplay the single source of truth for CLI values.

The four mode strings are now duplicated in the Clap definition and again in the manual match, on top of the Serde naming on the enum itself. Deriving the enum for Clap and reading get_one::<PermissionDisplay>() directly would remove this drift point before the next mode change.

Also applies to: 509-517

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/cli.rs` around lines 425 - 431, The permission mode strings are
duplicated between the Clap argument setup in permissions_arg and the manual
parsing logic that matches CLI values, so make PermissionDisplay the single
source of truth. Derive or otherwise integrate PermissionDisplay with Clap so
the CLI can parse it directly, then update the argument builder and the
downstream match logic to read get_one::<PermissionDisplay>() instead of
hardcoding string lists or re-mapping them manually.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@src/cli.rs`:
- Around line 425-431: The permission mode strings are duplicated between the
Clap argument setup in permissions_arg and the manual parsing logic that matches
CLI values, so make PermissionDisplay the single source of truth. Derive or
otherwise integrate PermissionDisplay with Clap so the CLI can parse it
directly, then update the argument builder and the downstream match logic to
read get_one::<PermissionDisplay>() instead of hardcoding string lists or
re-mapping them manually.

In `@src/lib.rs`:
- Around line 14-16: The crate root export list in src/lib.rs is exposing
PermissionDisplay unnecessarily, which widens the public surface for an
app-internal type. Remove PermissionDisplay from the pub use structs::{...}
re-export in src/lib.rs, and keep the remaining root exports limited to the
types intended for external use.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: a57b56bc-f51c-4387-9a69-78b80fb53a4b

📥 Commits

Reviewing files that changed from the base of the PR and between 5e2a92b and a028256.

📒 Files selected for processing (18)

• README.md
• docs/src/config.md
• docs/src/usage.md
• src/cli.rs
• src/lib.rs
• src/structs.rs
• src/utils/file.rs
• src/utils/format.rs
• src/utils/render.rs
• tests/crate/app.rs
• tests/crate/cli.rs
• tests/crate/file.rs
• tests/crate/render.rs
• tests/crate/settings.rs
• tests/format.rs
• tests/integration.rs
• tests/seams.rs
• tests/structs.rs