# baler-dev/boxpletion architecture

> Architecture diagram of the GitHub repository baler-dev/boxpletion, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/baler-dev/boxpletion
- Repository: https://github.com/baler-dev/boxpletion

## Overview

boxpletion is a VS Code/Positron extension that suggests completions inside R `box::use()` declarations; it reads source and package metadata rather than loading or running imported modules. The user types in an R document, the editor invokes the completion provider, and the hint engine parses the partial declaration before consulting local/global module files or installed package libraries. It then returns module, folder, exported-name, or wildcard suggestions. The excerpts show the main calls; the README documents the user-facing capabilities, while the package-library fallback and configuration are visible in the extension source.

Main entry points: [`src/hints.ts`](https://github.com/baler-dev/boxpletion/blob/main/src/hints.ts) (Hint engine), [`src/extension.ts`](https://github.com/baler-dev/boxpletion/blob/main/src/extension.ts) (Completion provider), [`src/context.ts`](https://github.com/baler-dev/boxpletion/blob/main/src/context.ts) (Context parser), [`src/resolve.ts`](https://github.com/baler-dev/boxpletion/blob/main/src/resolve.ts) (Module listing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_editor["Editor integration"]
  node_extension["Completion provider<br/>[extension.ts]"]
end

subgraph group_hints["Hint generation"]
  node_hint_engine["Hint engine<br/>[hints.ts]"]
  node_context_parser["Context parser<br/>[context.ts]"]
end

subgraph group_sources["Module and package discovery"]
  node_module_listing["Module listing<br/>[resolve.ts]"]
  node_module_resolution["Module file lookup<br/>[resolve.ts]"]
  node_export_parser["Module export parser<br/>[exports.ts]"]
  node_package_discovery["Package discovery<br/>[packages.ts]"]
  node_namespace_parser["Namespace parser<br/>[packages.ts]"]
end

node_user(("R document user"))
node_vscode["VS Code / Positron"]
node_rscript["Rscript"]

node_user -->|"types in"| node_vscode
node_vscode -->|"requests completions"| node_extension
node_extension -->|"requests hints"| node_hint_engine
node_extension -->|"queries library paths"| node_rscript
node_extension -->|"passes roots and text"| node_hint_engine
node_hint_engine -->|"parses context"| node_context_parser
node_hint_engine -->|"lists modules"| node_module_listing
node_hint_engine -->|"finds module file"| node_module_resolution
node_hint_engine -->|"reads module exports"| node_export_parser
node_hint_engine -->|"lists packages"| node_package_discovery
node_hint_engine -->|"reads package exports"| node_namespace_parser
node_hint_engine -->|"returns suggestions"| node_extension
node_extension -->|"registers provider"| node_vscode

click node_extension "https://github.com/baler-dev/boxpletion/blob/main/src/extension.ts"
click node_hint_engine "https://github.com/baler-dev/boxpletion/blob/main/src/hints.ts"
click node_context_parser "https://github.com/baler-dev/boxpletion/blob/main/src/context.ts"
click node_module_listing "https://github.com/baler-dev/boxpletion/blob/main/src/resolve.ts"
click node_module_resolution "https://github.com/baler-dev/boxpletion/blob/main/src/resolve.ts"
click node_export_parser "https://github.com/baler-dev/boxpletion/blob/main/src/exports.ts"
click node_package_discovery "https://github.com/baler-dev/boxpletion/blob/main/src/packages.ts"
click node_namespace_parser "https://github.com/baler-dev/boxpletion/blob/main/src/packages.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_extension,node_user toneBlue
class node_hint_engine,node_context_parser toneAmber
class node_module_listing,node_module_resolution,node_export_parser,node_package_discovery,node_namespace_parser toneMint
class node_vscode,node_rscript toneIndigo
```

## Components

### Editor integration

- [Completion provider](https://github.com/baler-dev/boxpletion/blob/main/src/extension.ts): `src/extension.ts`

### Hint generation

- [Hint engine](https://github.com/baler-dev/boxpletion/blob/main/src/hints.ts): `src/hints.ts`
- [Context parser](https://github.com/baler-dev/boxpletion/blob/main/src/context.ts): `src/context.ts`

### Module and package discovery

- [Module listing](https://github.com/baler-dev/boxpletion/blob/main/src/resolve.ts): `src/resolve.ts`
- [Module file lookup](https://github.com/baler-dev/boxpletion/blob/main/src/resolve.ts): `src/resolve.ts`
- [Module export parser](https://github.com/baler-dev/boxpletion/blob/main/src/exports.ts): `src/exports.ts`
- [Package discovery](https://github.com/baler-dev/boxpletion/blob/main/src/packages.ts): `src/packages.ts`
- [Namespace parser](https://github.com/baler-dev/boxpletion/blob/main/src/packages.ts): `src/packages.ts`

### Other components

- **R document user**
- **VS Code / Positron**
- **Rscript**

## Connections

- R document user → VS Code / Positron: types in (evidence: `README.md`)
- VS Code / Positron → Completion provider: requests completions (evidence: `src/extension.ts`)
- Completion provider → Hint engine: requests hints (evidence: `src/extension.ts`)
- Completion provider → Rscript: queries library paths (evidence: `src/extension.ts`)
- Completion provider → Hint engine: passes roots and text (evidence: `src/extension.ts`)
- Hint engine → Context parser: parses context (evidence: `src/hints.ts`)
- Hint engine → Module listing: lists modules (evidence: `src/hints.ts`)
- Hint engine → Module file lookup: finds module file (evidence: `src/hints.ts`)
- Hint engine → Module export parser: reads module exports (evidence: `src/hints.ts`)
- Hint engine → Package discovery: lists packages (evidence: `src/hints.ts`)
- Hint engine → Namespace parser: reads package exports (evidence: `src/hints.ts`)
- Hint engine → Completion provider: returns suggestions (evidence: `src/extension.ts`)
- Completion provider → VS Code / Positron: registers provider (evidence: `src/extension.ts`)