Document explicit config selection decision (#289)

[lodyai]

Summary

This branch documents the Netsuke-owned explicit configuration selection policy raised in issue #289.

Closes #289.

ExecPlan: docs/execplans/3-11-3-expose-config-path-and-netsuke-config.md

Review walkthrough

• Start with docs/adr-004-explicit-config-selection-outside-orthoconfig.md to review the decision to keep selector precedence in config_merge.rs rather than OrthoConfig.
• Then review docs/execplans/3-11-3-expose-config-path-and-netsuke-config.md for the corrected helper signatures recorded in the completed plan.

Validation

• markdownlint docs/adr-004-explicit-config-selection-outside-orthoconfig.md docs/execplans/3-11-3-expose-config-path-and-netsuke-config.md: pass
• make markdownlint: pass
• make nixie: pass
• make check-fmt: pass
• coderabbit review --agent: pass, zero findings

Summary by Sourcery

Document the decision and behavior for explicit configuration file selection in Netsuke and align the exec plan with the current helper signatures and error propagation semantics.

Documentation:

• Add ADR 004 describing why explicit configuration selection is handled in config_merge.rs instead of OrthoConfig and detailing selector precedence and failure semantics.
• Update the execution plan to reflect the injected environment lookup in resolve_config_path and the error-propagating behavior of collect_diag_file_layers.

[coderabbitai]

Important

Review skipped

Draft detected.

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

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 51d95cff-7fe1-4ec9-83b3-44b82e2c0789

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch issue-289-document-resolve-config-path-env-config-path-collect-diag-file-layers-and-push-layers-result-add-adr-for-explicit-config-selection-align-netsuke-design-md-and-execplan-with-final-api-signatures

---

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

[sourcery-ai]

Reviewer's Guide

Documents and clarifies Netsuke’s explicit configuration selection policy by adding an ADR and updating the existing exec plan to reflect the final helper signatures and error-propagation behavior for config-path resolution and diagnostic layer collection.

Sequence diagram for diagnostic layer collection with explicit config

sequenceDiagram
    participant Cli
    participant ConfigMerge
    participant FileSystem
    participant OrthoConfig
    participant Diagnostics

    Cli->>ConfigMerge: collect_diag_file_layers
    ConfigMerge->>ConfigMerge: resolve_config_path
    alt explicit path resolved
        ConfigMerge->>FileSystem: load_layers_from_path
        alt load_layers_from_path ok
            FileSystem-->>ConfigMerge: Vec MergeLayer
            ConfigMerge-->>Cli: OrthoResult Vec MergeLayer
        else load_layers_from_path error
            FileSystem-->>ConfigMerge: OrthoError
            ConfigMerge-->>Diagnostics: push_layers_result
            ConfigMerge-->>Cli: OrthoResult error
        end
    else no explicit path
        ConfigMerge->>OrthoConfig: config_discovery
        OrthoConfig-->>ConfigMerge: first_pass_layers
        ConfigMerge->>OrthoConfig: project_scope_layers
        alt project_scope_layers ok
            OrthoConfig-->>ConfigMerge: project_layers
            ConfigMerge-->>Cli: OrthoResult Vec MergeLayer
        else project_scope_layers error
            OrthoConfig-->>ConfigMerge: OrthoError
            ConfigMerge-->>Cli: OrthoResult error
        end
    end

Loading

Flow diagram for explicit config selection in config_merge.rs

flowchart TD
    A[Start resolve_config_path] --> B[cli.config present?]
    B -- yes --> C[Use cli.config]
    B -- no --> D[env_config_path NETSUKE_CONFIG]
    D -- found --> E[Use NETSUKE_CONFIG path]
    D -- not found --> F[env_config_path NETSUKE_CONFIG_PATH]
    F -- found --> G[Use NETSUKE_CONFIG_PATH path]
    F -- not found --> H[No explicit config path]

    C --> I[Return Some PathBuf]
    E --> I
    G --> I
    H --> J[Return None]

Loading

File-Level Changes

Change	Details	Files
Generalize config-path resolution to use an injected environment lookup and update documented helper signature and precedence behavior.	Change resolve_config_path signature to accept a generic var_os lookup function so env access can be injected (e.g., for tests). Update resolve_config_path implementation to clone cli.config instead of mapping via PathBuf::from and to call env_config_path with the injected lookup for both primary and legacy env vars. Clarify in documentation that empty environment values are ignored and that precedence is --config > NETSUKE_CONFIG > NETSUKE_CONFIG_PATH.	docs/execplans/3-11-3-expose-config-path-and-netsuke-config.md
Tighten and document error propagation semantics for diagnostic file layer collection.	Update collect_diag_file_layers signature in documentation to return OrthoResult<Vec<MergeLayer<'static>>> instead of Vec<MergeLayer<'static>> to propagate errors. Describe that explicit config load failures are now propagated as OrthoError and prevent fallback to automatic discovery. Clarify that when a direct project load fails during diagnostics, the error is propagated instead of returning first-pass layers.	docs/execplans/3-11-3-expose-config-path-and-netsuke-config.md
Add an ADR defining the decision to keep explicit config selection in config_merge.rs instead of OrthoConfig and describe the resulting behavior.	Introduce ADR 004 documenting the context, decision drivers, options, and rationale for handling explicit configuration selection in Netsuke’s CLI adapter rather than OrthoConfig. Record the accepted behavior for resolve_config_path, env_config_path, collect_diag_file_layers, push_layers_result, and automatic discovery fallback. Describe consequences for failure-closed explicit selection, ownership boundaries between Netsuke and OrthoConfig, and coupled documentation updates for future precedence changes.	docs/adr-004-explicit-config-selection-outside-orthoconfig.md

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#289	Add a section to docs/developers-guide.md documenting the four helpers (resolve_config_path, env_config_path, collect_diag_file_layers, push_layers_result): their purpose, inputs, outputs, and interaction with the two-pass merge pipeline.	❌	The diff only touches docs/execplans/3-11-3-expose-config-path-and-netsuke-config.md and adds docs/adr-004-explicit-config-selection-outside-orthoconfig.md; developers-guide.md is not modified.
#289	Create an ADR that records the decision to implement explicit config path selection outside OrthoConfig, including rationale, alternatives, and consequences.	✅
#289	Update documentation to reflect the final explicit config selection behavior: (a) netsuke-design.md §2037 should document full precedence (--config > NETSUKE_CONFIG > NETSUKE_CONFIG_PATH > automatic discovery) and NETSUKE_CONFIG_PATH as a backward-compatible alias; (b) ExecPlan docs/execplans/3-11-3-expose-config-path-and-netsuke-config.md §624–689 should be updated to match the final implemented helper signatures and behavior.	❌	Only the ExecPlan file is updated to reflect the new signatures and behavior; netsuke-design.md is not modified, so the precedence order and NETSUKE_CONFIG_PATH alias documentation remain uncorrected.

Possibly linked issues

• Document resolve_config_path, env_config_path, collect_diag_file_layers, and push_layers_result; add ADR for explicit config selection; align netsuke-design.md and ExecPlan with final API signatures #289: They concern the same explicit config selection decision, adding an ADR and updating ExecPlan helper signatures accordingly.

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.