SAGE Docstrings (VS Code Extension)

VS Code tooling for SAGE v1.3.6 Python docstrings: tag-aware autocomplete, parsing/diagnostics, quick fixes, navigation, and workspace artifact browsing.

• Extension status: MVP / pre-release (package version 0.1.0)
• Spec compatibility: SAGE v1.3.6
• Language support: Python docstrings only

Design references

• sage-vscode-ext-v1.3.6.md - extension design spec (naming uses AADS, but this repo targets SAGE)
• sage-spec.md - SAGE v1.3.6 specification (also published at https://github.com/mikewcasale/sage-spec)

Current feature set

Editing assistance

• Tag completion + snippets inside Python docstrings (@graph, @agent-guidance, @notice, @custom:<name>, etc.)
• Custom tag registry from .sage/custom-tags.yaml (with .aads fallback)
• Docstring generator (SAGE: Generate Docstring) with adoption levels 1-3
  • Inserts module/class/function/attribute templates
  • Honors @automation.allow-write and @automation.require-approval in module docstrings
  • Optional diff preview before applying
• Syntax highlighting for tag headers and component references in Python strings
• Snippets for module/class/function/attribute docstrings (sage-module, sage-class, sage-func, sage-attr)

Diagnostics + quick fixes

• Parsing diagnostics for tag grammar, indentation, YAML blocks, and invalid booleans
• Validation diagnostics (subset)
  • V001, V002, V003, V004, V005
  • C003, C004
  • S001, S002
• Quick fixes
  • Normalize boolean tokens (yes/no → true/false)
  • Convert hybrid tag values to block form
  • Insert @sensitivity: none for attributes
  • Add @effects stub when @pure is false
  • Replace @thread-safety with @concurrency
• Optional MCP diagnostics if an MCP server is configured

Navigation + discovery

• Go to canonical home from component references
• Find similar components (MCP first, then .sage/similar/*.md, then index)
• Peek component metadata in a markdown preview
• Go to definition for component references

Views

• Components tree view (from index.json / components/*.json)
• Similar tree view (from .sage/similar/*.md)
• Graph webview (raw graph.json display)

CLI integration (optional)

Uses the external SAGE CLI when enabled:

• SAGE: Extract Workspace Artifacts → sage extract --source <workspace> --output .sage/
• SAGE: Validate Workspace → sage validate --source <workspace>
• SAGE: Generate Checklist → sage checklist --diff <base> --output <file>

Workspace artifacts

The extension reads SAGE artifacts if present:

• .sage/index.json
• .sage/canonical-homes.json
• .sage/components/*.json
• .sage/similar/*.md
• .sage/custom-tags.yaml
• .sage/graph.json, .sage/patterns.json, .sage/anti-patterns.json, .sage/agent-guidance.json

If .sage/ is missing, .aads/ is used as a fallback (for older naming).

Settings

All settings are under the sage.* namespace:

• sage.enabled
• sage.schemaVersion
• sage.artifactsPath
• sage.validation.enabled
• sage.validation.level
• sage.validation.publicApiHeuristic
• sage.templates.defaultLevel
• sage.templates.useNoticeDevBlocks
• sage.cli.enabled
• sage.cli.path
• sage.cli.timeoutMs
• sage.mcp.enabled
• sage.mcp.transport (stdio or http)
• sage.mcp.command
• sage.mcp.args
• sage.mcp.httpUrl
• sage.automation.enableSuggestions
• sage.automation.autoApplyAllowWrite
• sage.automation.alwaysRequireDiffPreview

Development

npm install
npm run build

Useful scripts:

• npm run watch
• npm run lint
• npm test

Notes vs design spec

This repo implements the MVP subset of sage-vscode-ext-v1.3.6.md. A few notable gaps compared to the full design spec:

• Graph view is a raw JSON viewer (no interactive graph)
• Component/similar views are simple lists (no search/filter)
• Validation coverage is partial (only the rules listed above)
• Automation suggestions are not yet implemented (only guarded docstring insertion)