docs/design/outline-command.md (5)

105-105: ⚡ Quick win

Clarify --pub-members flag semantics.

The option is listed as --pub-members without indicating whether it's a boolean flag or takes a value. Based on lines 261-266, it appears to be a boolean flag that filters members. Consider adding the flag notation (e.g., no <VALUE> placeholder) to make this immediately clear in the core options list.

🤖 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 `@docs/design/outline-command.md` at line 105, The docs list the option
`--pub-members` ambiguously; update the `--pub-members` entry to clearly show
it's a boolean flag (no value expected) and that it filters output to public
members only—e.g., remove any `<VALUE>` placeholder and append a short note like
"boolean flag; filters to public members" or "use without value". Also ensure
the description aligns with the behavior implemented in the code path handling
`--pub-members` so readers understand it's an on/off flag.

---

316-316: 💤 Low value

Clarify metadata printing behavior.

The statement "should not print role, isImport, or isExported labels by default" uses "by default," implying there might be a mode where these are printed. However, no such mode is documented elsewhere. If text output should never print these metadata flags (since they're implicit in the item selection), consider rephrasing to remove the ambiguity: "Text output does not print role, isImport, or isExported labels."

🤖 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 `@docs/design/outline-command.md` at line 316, Update the sentence about
metadata printing to remove the ambiguous "by default" phrase: change the line
that currently reads "It should not print `role`, `isImport`, or `isExported`
labels by default." to an unambiguous statement such as "Text output does not
print `role`, `isImport`, or `isExported` labels." Ensure the exact metadata
identifiers `role`, `isImport`, and `isExported` are preserved so readers can
locate the referenced flags.

---

180-183: ⚖️ Poor tradeoff

Clarify match field categories for dual-role items.

The three-category model (structure items, import items, export edge items) for --match fields does not clearly specify which fields apply when an item has both isImport=true and isExported=true (e.g., pub use foo as bar in Rust).

Consider specifying that:

• Items where isImport=true include import-related fields (target, binding name, alias)
• Items where isExported=true include export-related fields (exported name, target, alias)
• Items can match against the union of applicable field sets when both flags are true

This would align the match logic with the flag-based model rather than treating items as mutually exclusive categories.

🤖 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 `@docs/design/outline-command.md` around lines 180 - 183, Clarify the --match
field categories by documenting that structure items include fields "symbol
name", "signature", "first source line"; import-related fields (applies when
isImport=true) include "imported target", "binding name", "alias", "signature",
"first source line"; export-related fields (applies when isExported=true)
include "exported name", "target", "alias", "signature", "first source line";
and when an item has both isImport=true and isExported=true it should be matched
against the union of the applicable import and export field sets (not treated as
mutually exclusive) so commands like `pub use foo as bar` can match on either
import or export attributes as appropriate.

---

607-621: ⚖️ Poor tradeoff

Clarify flag optionality in OutlineFlatSymbol.

OutlineFlatSymbol declares is_import, is_exported, and is_public as Option<bool>, but the JSON contract (lines 448-451) states that:

• isImport and isExported are always present on items
• isPublic is absent or null for items, optional for members

Consider one of these approaches:

1. Keep current flexible design: Document that consumers must check role first, then interpret flags (items ignore is_public, members ignore is_import/is_exported).

2. Match JSON contract exactly: Make is_import/is_exported required (bool) and document that serialization should always emit them for streamed entries (since streamed entries include both items and members).

Option 1 is more flexible for internal use; option 2 matches the stated JSON contract more precisely.

🤖 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 `@docs/design/outline-command.md` around lines 607 - 621, OutlineFlatSymbol
currently uses Option<bool> for is_import, is_exported and is_public but the
JSON contract requires isImport and isExported to always be present while
isPublic is optional for members; update the struct to make is_import and
is_exported plain bool (retain is_public as Option<bool>), update any
constructors/serializers used by OutlineFlatSymbol to always emit those two
flags for streamed entries, and add a brief doc comment on
OutlineFlatSymbol/OutlineRole explaining that consumers should treat
is_import/is_exported as always present and is_public as optional for members to
match the JSON contract.

---

58-58: ⚡ Quick win

Forward reference to undefined term.

The alias definition references target before it is defined in the glossary. Consider adding a glossary entry for "Target" or reordering the definitions so that readers encounter the term before it's referenced.

🤖 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 `@docs/design/outline-command.md` at line 58, The glossary entry for "Alias"
references the term `target` before `target` is defined; fix by either adding a
dedicated glossary entry for "Target" (defining what `target` means in this
context) or by reordering the glossary so the `target` definition appears before
the "Alias" entry; update the "Alias" line to reference the newly defined
`target` symbol consistently.

docs/design/outline-rule-extraction.md (1)

788-788: 💤 Low value

Consider adding more detail on the member attachment algorithm.

Line 788 mentions "syntax containment" but doesn't fully specify how direct members are determined:

• Is "direct" membership based on immediate AST parent-child relationship?
• How does the algorithm distinguish between direct members and nested items to avoid "arbitrary recursive nesting" (line 358)?
• What is the behavior when member ranges overlap or when a language has ambiguous nesting?

While this level of detail might be acceptable for a design document, adding a brief explanation of the attachment algorithm would help reviewers verify the approach is sound before implementation.

For example:

8. Attach direct members by AST containment:
   - For each top-level item, find all member-role entries whose range falls within the item's range
   - Exclude member entries that are nested inside other member entries (to avoid recursive nesting)
   - Derive member publicness where the language exposes it

🤖 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 `@docs/design/outline-rule-extraction.md` at line 788, Add a concise
specification of the member-attachment algorithm to clarify "syntax
containment": describe that direct membership is determined by AST containment
(a member-role entry whose source range is fully within the parent's range),
explain that members nested inside other member entries should be excluded to
prevent arbitrary recursive nesting, specify tie-breaking for overlapping ranges
(e.g., prefer the smallest enclosing range or the nearest sibling based on AST
depth), and note that member visibility/publicness is derived from
language-specific metadata when available; reference the terms "syntax
containment", "member-role entries", "member ranges", and "direct members" so
reviewers can map this algorithm to the rest of the document.

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes