DS Snapshot for VS Code

A lightweight VS Code extension for capturing data science evidence, notes, and documentation snapshots from notebooks or code files.

This VS Code prototype is aligned with the JupyterLab version of DS Snapshot. It focuses on local-first evidence capture, rendered Markdown/HTML summaries, review workpapers, a project hub, and a documentation package export.

Minimum use case

After you run a notebook or code block and inspect the output, you can archive:

1. the selected code or current notebook cell code,
2. captured notebook cell outputs when available,
3. additional supporting files you list by path, such as CSV, XLSX, PNG, JSON, notebooks, SQL, or logs,
4. a generated summary.md and summary.html,
5. a project-level hub.md and hub.html,
6. an optional marker that links the notebook/code back to archived evidence,
7. a documentation package for review, handoff, or audit.

Folder structure

The extension creates a project-local archive:

ds-snapshot-archive/
  hub.md
  hub.html
  registry.json
  reviews/
    RW-001.md
    RW-001.html
  evidence/
    RW-001/
      20260625_103012_missing_income_spot_check/
        check_code.py
        summary.md
        summary.html
        meta.json
        outputs/
          cell_000_output_01_01_text_plain.txt
          attached_files/
            sample_output.csv
  documentation_packages/
    documentation_20260625_110000/
      index.html
      hub.md
      hub.html
      README.md
      registry_documentation.json
      reviews/
      evidence/

How to use

1. Open this folder in VS Code Extension Development Host.
2. Open a notebook or a Python file.
3. Select a notebook cell or select code in an editor.
4. Open the DS Snapshot activity bar panel.
5. Click Load Current Block / Cell.
6. Fill in:
   • Review ID
   • Evidence ID
   • Review question
   • Notes
   • Status
7. Optionally add Supporting files, one workspace-relative or absolute path per line, if you want to archive CSV/XLSX/PNG/notebook/SQL/etc.
8. Optionally choose a marker behavior.
9. Click Capture Evidence.
10. Click Export Review Package when you want a focused review package.

Documentation package

The documentation package is a cleaner handoff layer. It copies or regenerates:

• the package hub,
• review workpapers,
• evidence summary Markdown,
• evidence summary HTML,
• a documentation registry with packaging warnings.

It intentionally excludes raw cell outputs, attached files, and check code so the package stays lightweight.

HTML rendering

DS Snapshot keeps Markdown as the source of truth and generates HTML as a rendered copy.

• Capturing evidence writes summary.md and summary.html.
• Updating the hub writes hub.md and hub.html.
• If you manually edit a Markdown file, run DS Snapshot: Render Current Markdown to HTML from the command palette.
• To refresh every generated HTML file under ds-snapshot-archive/, run DS Snapshot: Render All HTML or use the side panel button.

Notes and limitations

• Notebook cell outputs are saved from VS Code's notebook output objects. Rich DataFrame rendering may be saved as HTML, plain text, or another mime-specific raw output depending on the kernel output.
• If you export CSV/XLSX files yourself, add them under Supporting files to archive them into the evidence folder. Use one workspace-relative or absolute path per line.
• Marker replacement is experimental. For notebook cells it replaces or inserts a markdown marker. For normal code files it replaces or inserts a comment marker.
• This prototype does not execute tests, call AI, generate expected outputs, or access notebook kernel variables directly.

Finding the generated files in VS Code

The extension writes files into the workspace folder opened in the Extension Development Host, not into the extension source folder.

After capture, look for:

ds-snapshot-archive/
  hub.md
  hub.html
  reviews/
  evidence/

The panel now shows the exact archive folder, summary Markdown path, summary HTML path, hub Markdown path, and hub HTML path after each capture. You can also click Reveal Archive Folder from the panel.

If you only see a Markdown preview tab such as hub.md, that preview is just VS Code's rendered view. The actual files are still saved under ds-snapshot-archive/ in the workspace folder.

Structured review fields

The VS Code version now matches the JupyterLab version's standard review fields:

• Review Area, such as Data Quality, Data Cleaning, Feature Engineering, Model Function, Model Performance, Output Validation, External File Review, Toy Case Validation, AI Code Audit, or Other.
• Purpose, such as Archive for record, Quick spot check, Investigate concern, Validate fix, Support conclusion, or Reusable check. These fields are written into summary.md, meta.json, registry.json, hub.md, and documentation packages.

Markdown and HTML outputs

DS Snapshot now writes both Markdown and HTML versions during capture. After each evidence capture, the extension writes summary.md, renders summary.html, regenerates hub.md, and renders hub.html automatically. Hub checklist links include both MD and HTML entry points.

v0.1.3 UI update

The archive actions are simplified into four main buttons: Open Latest Summary, Open Hub, Open Archive Folder, and Package Documentation. Less common repair actions, such as opening raw Markdown or rebuilding HTML, are available under More actions.

Privacy and Security

DS Snapshot is designed as a local-first evidence capture tool. Captured evidence is written to your local workspace folder. The extension does not require an account, API key, cloud service, or telemetry service to operate.

The Agent Review Helper can create a local validator script at tools/validate_agent_proof.py. For safety and transparency, DS Snapshot opens this script and prepares the command, but it does not run the validator automatically. Review the script and run the command manually in your terminal if you want to validate a proof run.

v0.1.8 update

Hub Markdown now opens as a Documentation Hub with an editable documentation template at the top and automatically generated DS Snapshot evidence as the appendix. The editable area includes documentation info, executive summary, business context, scope, data and inputs, methodology, results and evidence, validation checks, caveats, next steps, and review notes. Existing user edits are preserved when the hub is regenerated.

Evidence reviewer notes

Each evidence summary.md includes a Reviewer Notes (Editable) section near the top. You can add follow-up review comments or validation notes there and render the Markdown to HTML. The editable section is preserved if the evidence summary is regenerated.

v0.2.0 update

The VS Code version now supports updating review status after capture. Use the current Review ID, Evidence ID, selected Status, and optional Notes, then click Update Evidence Status. The extension updates registry.json, the Hub checklist, the review workpaper, and the evidence summary. If Notes are provided, a status update entry is appended to the evidence Reviewer Notes (Editable) section.

Version 0.2.1 update

• Duplicate Evidence IDs under the same Review ID are automatically versioned as _v2, _v3, and so on.
• The resolved Evidence ID is used in the registry, hub, evidence summary, review package, and status update workflow.
• The original user-entered Evidence ID is preserved in original_evidence_id in the registry.

Delete Evidence / Delete Review

Use the side panel to delete a single evidence record or an entire review. Delete Evidence uses the current Review ID and Evidence ID. Delete Review uses the current Review ID and removes all evidence under that review. The registry, hub, and review workpaper are regenerated after deletion.

Version 0.2.3 update

The panel now uses collapsible sections to reduce visual clutter:

• Structured review fields contains Review Area, Purpose, Marker behavior, and Supporting files.
• Evidence Management contains Render All HTML, Update Evidence Status, Delete Evidence, Delete Review, and Export Review Package.
• The Supporting files placeholder is simplified to one example path.

Version 0.2.4

• Cleaned notebook and text markers. Markers no longer display summary HTML / MD links; evidence links are available from the Hub checklist.

Version 0.2.5 update

The side panel now includes an Archive location field. By default, DS Snapshot writes to:

ds-snapshot-archive

This is interpreted as a workspace-relative folder. You can change it to another workspace-relative path, for example:

reviews/ds-snapshot-archive

You can also use an absolute local path, for example on Windows:

E:\\project-review\\ds-snapshot-archive

Click Save Archive Location or use any archive action after changing the field. The setting is saved to the current VS Code workspace as dsSnapshot.archivePath.

Version 0.2.6 update

• Open Hub now opens hub.md using VS Code's built-in Markdown Preview instead of opening hub.html in the external browser.
• Open Latest Summary now opens the latest summary.md using VS Code's built-in Markdown Preview.
• The optional Open Summary HTML Source action opens the generated HTML file inside VS Code as a file tab, rather than launching the browser.

Version 0.2.7 update

• Fixed archive image preview behavior for captured notebook image outputs, such as Matplotlib PNG plots.
• Evidence summary.md now uses relative links from the summary file to archived outputs, so VS Code Markdown Preview can display images correctly.
• Generated summary.html now supports Markdown image syntax and renders images inline.
• Hub and review workpaper links now use relative paths from the generated Markdown file, which works better inside VS Code preview.

Version 0.2.9 update

• Captured notebook text outputs are now shown inline in summary.md and generated summary.html, with a preview limit to keep summaries readable. The full .txt artifact is still saved and linked.
• Hub pages now link only to Markdown summaries. HTML versions are still generated and available in the corresponding evidence folders.
• Generated archive timestamps now use US Eastern Time (America/New_York) instead of UTC/local-machine display time.

0.3.3 Documentation Hub Template

• Renamed the main hub title to Documentation Hub.
• Replaced the old editable Project Notes section with a review-ready analysis/model documentation template.
• Keeps existing DS Snapshot hub-generated content under Appendix: DS Snapshot Evidence.
• Adds local SVG placeholder previews so the Markdown template demonstrates image support without external links.
• Preserves existing user-edited hub content when regenerating the hub; unchanged legacy default notes are upgraded to the new template.