How swark-io/swark works
1. Project type and boundary
- This is a VS Code extension named Swark. Its core boundary is the editor: it runs inside VS Code, reads files from the active workspace, calls the VS Code Language Model API via GitHub Copilot, and writes a Markdown/Mermaid diagram back into the workspace for preview.
2. Entry point and command wiring
- src/extension.ts is the extension activation entrypoint.
- It registers the main command implemented in src/commands/create-architecture.ts, which is the orchestration layer for the whole flow.
- The README’s default keybinding and command palette flow both route into this command.
3. User input and workspace selection
- src/io/input-selection.ts handles selecting the target folder or workspace scope.
- This is the first user-facing decision point and defines the repository slice that will be analyzed.
4. Repository ingestion
- src/io/repository-reader.ts is responsible for finding and loading source files from the selected folder.
- It is constrained by extension filters and exclusion patterns described in the README settings, so the input to the LLM is a curated subset of the repo rather than the whole workspace.
5. Token budgeting and file selection
- src/io/language-counter.ts and src/llm/token-count-utils.ts support estimating how much content can fit into the model context.
- The extension dynamically adjusts how many files it reads based on the configured swark.maxFiles and the model’s token limits, so file selection is bounded by both user config and LLM capacity.
6. Prompt construction
- src/llm/prompt-builder.ts transforms the selected code files into a structured prompt.
- This is the main handoff from repository data into model input: it bundles code context plus instructions for producing an architecture diagram in Mermaid syntax.
7. LLM interaction
- src/llm/model-interactor.ts performs the actual request to the VS Code Language Model API / GitHub Copilot.
- src/llm/debug-utils.ts likely supports logging or inspection of prompt/response behavior for troubleshooting.
- The architecture depends on Copilot as the only external AI provider; no separate API keys or third-party model service are used.
8. Diagram post-processing and Mermaid-specific handling
- src/view/mermaid/serde.ts, link-generator.ts, and cycle-detector.ts form a Mermaid-focused normalization layer.
- cycle-detector.ts is especially important because the README exposes a swark.fixMermaidCycles setting; this suggests the extension can patch or avoid Mermaid graph cycles that would otherwise break rendering.
- This layer is the boundary between raw LLM output and renderable diagram content.
9. Output generation and persistence
- src/view/output-formatter.ts assembles the final Markdown content, including the Mermaid block and any log/details needed for inspection.
- src/view/output-writer.ts writes the artifacts into the workspace’s swark-output folder as two files per run: the diagram Markdown and a log Markdown file.
- This is the main persistence boundary of the system.
10. Preview/UI layer
- src/view/viewer.ts opens or presents the generated Markdown so the user can immediately inspect the diagram inside VS Code.
- The extension therefore has a “generate then preview” UX, rather than exporting only to a raw file.
11. Telemetry and observability
- src/telemetry.ts collects usage, model, timing, and error events.
- Per the README, telemetry is privacy-preserving: it excludes source code and file contents, and is sent to Azure Application Insights via VS Code telemetry tooling.
12. Quality and verification
- There are focused tests under src/view/tests and src/view/mermaid/tests, indicating the most logic-heavy areas are output formatting and Mermaid graph handling.
- The repo also includes GitHub Actions in .github/workflows/build.yml, showing the extension is built and validated in CI rather than relying only on local development.
13. Overall data flow
- The end-to-end architecture is: user selects scope → repository files are discovered and filtered → token budget determines how much code to include → prompt is built → Copilot/LLM generates Mermaid architecture → Mermaid is optionally repaired/normalized → Markdown diagram and log files are written → the diagram is opened in VS Code preview.
14. Key architectural constraint
- The main design constraint is LLM context size: nearly every subsystem before model invocation exists to maximize useful code inclusion while staying within token limits, and every subsystem after invocation exists to make the generated Mermaid reliably renderable and reviewable.
Main entry points: repository-reader.ts Repo reader · create-architecture.ts Create arch · model-interactor.ts Model interactor · input-selection.ts Scope picker
Components 16
VS Code shell
Activation and command entrypoints inside the editor
- Extension · VS Code extension activation entrypoint
src/extension.ts - Create arch · Main command that coordinates the full generation flow
src/commands/create-architecture.ts
Repository intake
Scope selection and workspace file loading
- Scope picker · Chooses the target folder or workspace slice
src/io/input-selection.ts - Repo reader · Discovers and loads source files from the selected scope
src/io/repository-reader.ts - Language count · Estimates language size for model budgeting
src/io/language-counter.ts - Token utils · Token counting helpers used to fit context limits
src/llm/token-count-utils.ts
LLM pipeline
Prompting and Copilot model interaction
- Prompt builder · Turns selected files into a structured model prompt
src/llm/prompt-builder.ts - Model interactor · Calls the VS Code Language Model API via GitHub Copilot
src/llm/model-interactor.ts - Debug utils · Supports logging and inspection of prompt and response behavior
src/llm/debug-utils.ts
Diagram output
Mermaid normalization, markdown assembly, and preview
- Mermaid serde · Parses and serializes Mermaid-oriented diagram content
src/view/mermaid/serde.ts - Link generator · Builds Mermaid links used in the generated diagram
src/view/mermaid/link-generator.ts - Cycle detector · Detects or fixes Mermaid cycles that can break rendering
src/view/mermaid/cycle-detector.ts - Output formatter · Assembles final markdown with Mermaid and logs
src/view/output-formatter.ts - Output writer · Writes diagram and log markdown into the workspace output folder
src/view/output-writer.ts - Viewer · Opens the generated markdown for in-editor preview
src/view/viewer.ts
Observability
Telemetry and debug support
- Telemetry · Collects privacy-preserving usage and error events
src/telemetry.ts
Connections 16
- Extension → Create arch: registers · Activation wires the main command
- Create arch → Scope picker: select scope · Command asks the user for the target workspace slice
- Scope picker → Repo reader: scope · Selected folder drives repository ingestion
- Repo reader → Language count: measure · Reader estimates content size before expanding context
- Language count → Token utils: budget · Language sizing feeds token budgeting
- Token utils → Repo reader: limit files · Token budget constrains how many files are loaded
- Repo reader → Prompt builder: files · Curated source files are handed to prompt construction
- Prompt builder → Model interactor: prompt · Structured prompt is sent to the model interactor
- Debug utils → Model interactor: inspect · Debug support observes request and response behavior
- Model interactor → Mermaid serde: diagram · Model output is normalized as Mermaid-like content
- Mermaid serde → Link generator: linkify · Serialized diagram content gets link generation support
- Link generator → Cycle detector: validate · Link structure is checked for cycle issues
- Cycle detector → Output formatter: repair · Repaired Mermaid is assembled into final markdown
- Output formatter → Output writer: persist · Formatted output is written to workspace files
- Output writer → Viewer: preview · Written markdown is opened in the VS Code viewer
- Create arch → Telemetry: emit events · The command reports timing, usage, and errors