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.

Feedback

• GitHub: https://github.com/xwang0176/ds-snapshot-vscode
• Issues / feedback: https://github.com/xwang0176/ds-snapshot-vscode/issues

v0.1.8 update

Hub Markdown now includes a visible Project Notes (Editable) section. You can add project background and review summary notes in hub.md; these notes are preserved when the hub is regenerated and are included in exported review packages.

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.