Create log mechanism

[leoyala]

Summary

Creates the mechanism to show the logs of a tracked dataset. Users are able to pass a dataset ID or path to display the changes over time for the given dataset if it has been tracked already.

Changes

• New log CLI command
• New cache SQL store build mechanism
• New log and animation

Test plan

• uv run pytest passes

Summary by CodeRabbit

• New Features

  • Added dstrack log for viewing dataset snapshot history by path or dataset ID.
  • Supports limits, reverse ordering, and compact one-line output.
  • History and search results stay consistent as local indexes refresh automatically.
  • Added clearer handling for corrupted or incomplete history records.

• Documentation

  • Expanded guidance on dataset history, storage layout, and snapshot semantics.
  • Clarified that dstrack tracks dataset metadata rather than storing file contents.
  • Added API documentation pages and updated the project roadmap.

• Style

  • Added an animated landing-page logo with reduced-motion support.

[codecov]

Codecov Report

❌ Patch coverage is 96.39175% with 14 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/dstrack/cache.py	93.39%	7 Missing ⚠️
src/dstrack/_log_render.py	94.79%	5 Missing ⚠️
src/dstrack/store.py	97.91%	2 Missing ⚠️

📢 Thoughts on this report? Let us know!

[coderabbitai]

Warning

Review limit reached

@leoyala, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 17 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 96828225-f4b8-4c8d-9f85-04af9e718559

📥 Commits

Reviewing files that changed from the base of the PR and between 2a60a25 and 63422cb.

📒 Files selected for processing (4)

• docs/index.md
• src/dstrack/_log.py
• tests/test_log.py
• tests/test_store.py

📝 Walkthrough

Walkthrough

Changes

Dataset history command

Layer / File(s)	Summary
Store history contracts src/dstrack/store.py	Adds typed log records, committed-log parsing, dataset inspection, and HEAD-based lineage traversal.
Snapshot index synchronization src/dstrack/cache.py, src/dstrack/errors.py	Adds a versioned SQLite index that synchronizes from dataset logs and supports lineage and path queries.
Log command and timeline rendering src/dstrack/_cli.py, src/dstrack/_log.py, src/dstrack/_log_render.py, src/dstrack/console.py	Adds target resolution, index lifecycle handling, history querying, Rich timeline output, and escaped console messages.
History command validation tests/test_log.py	Tests history display, ordering, filtering, target resolution, index rebuilding, empty datasets, and corruption handling.
History workflow documentation docs/decisions/..., docs/getting_started.md, docs/roadmap.md	Documents the log workflow, .cache/index.db layout, synchronization behavior, and completed roadmap status.

Documentation site content

Layer / File(s)	Summary
Product scope and introduction README.md, docs/index.md	Describes semantic dataset tracking, audit-trail behavior, and the distinction from byte-level data storage.
API documentation pages docs/API/paths.md, docs/API/store.md	Adds API documentation directives and icons for paths and store modules.

Animated documentation logo

Layer / File(s)	Summary
Procedural logo generation docs/gen_logo.py	Adds procedural geometry, shading, rasterization, SVG output, PNG output, and symmetry validation.
Scroll-driven logo animation docs/javascripts/logo-animation.js, docs/index.md, zensical.toml	Adds canvas-based slab animation, reduced-motion handling, navigation reinitialization, a logo anchor, and site script wiring.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant LogCommand
  participant CacheIndex
  participant Store
  participant RichTimeline
  User->>LogCommand: Run dstrack log target
  LogCommand->>CacheIndex: Synchronize index
  CacheIndex->>Store: Read changed log.jsonl and HEAD
  LogCommand->>CacheIndex: Query committed lineage
  LogCommand->>RichTimeline: Render history
  RichTimeline-->>User: Display snapshot timeline

Loading

Possibly related PRs

• leoyala/dstrack#29: Defines the local snapshot store layout and cache/index semantics.
• leoyala/dstrack#39: Updates snapshot persistence through log.jsonl and HEAD.

Suggested labels: documentation

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title is related to the main change: it accurately signals the new log functionality, even though it is broad.
Docstring Coverage	✅ Passed	Docstring coverage is 90.29% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch 44-create-log-mechanism

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Test Results

   48 files  ±    0     48 suites  ±0   1m 49s ⏱️ +19s
  263 tests +   57    263 ✅ +   57  0 💤 ±0  0 ❌ ±0 
6 312 runs  +1 368  6 312 ✅ +1 368  0 💤 ±0  0 ❌ ±0 

Results for commit 63422cb. ± Comparison against base commit c7f7a37.

♻️ This comment has been updated with latest results.

[coderabbitai]

Actionable comments posted: 3

🧹 Nitpick comments (1)

docs/gen_logo.py (1)

14-20: 🧹 Nitpick | 🔵 Trivial

Consider guarding the gen_logo.py ↔ logo-animation.js constant sync in CI.

These grid/projection constants (and the LAYERS palette below) are duplicated from docs/javascripts/logo-animation.js, and the header comment notes they must stay in sync or the animation's first frame diverges from the emitted SVG. I verified they currently match exactly, but nothing enforces it. Running this script in CI and diffing the committed docs/assets/* (or asserting the constants against the JS source) would catch silent drift.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/gen_logo.py` around lines 14 - 20, Update the CI validation around
gen_logo.py to regenerate the committed docs/assets output and fail when the
generated files differ, or otherwise assert that its grid/projection constants
and LAYERS palette match logo-animation.js. Keep the check focused on detecting
drift between these two sources.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/index.md`:
- Around line 16-20: Remove the earlier duplicate “Why dstrack?” section from
docs/index.md, including its heading and copy, and retain the later canonical
section unchanged.
- Around line 18-20: Update the introductory description in docs/index.md to
remove the claim that dstrack can reproduce past data states. Replace it with
wording that accurately limits the capability to reconstructing recorded dataset
metadata or history, while preserving the surrounding explanation of auditing
and detecting changes.

In `@src/dstrack/_log.py`:
- Around line 84-95: Extend the exception handling around cache.sync,
_resolve_target, and cache.query_history to catch OSError and the SQLite
database error type used by the cache layer. Route these failures through the
existing console.error(str(e)) and typer.Exit(code=1) path, preserving the
current handling for DatasetNotFoundError, StoreCorruptionError, and ValueError.

---

Nitpick comments:
In `@docs/gen_logo.py`:
- Around line 14-20: Update the CI validation around gen_logo.py to regenerate
the committed docs/assets output and fail when the generated files differ, or
otherwise assert that its grid/projection constants and LAYERS palette match
logo-animation.js. Keep the check focused on detecting drift between these two
sources.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: f1e28096-5b88-47d8-b654-24541afce7c9

📥 Commits

Reviewing files that changed from the base of the PR and between c7f7a37 and 2a60a25.

⛔ Files ignored due to path filters (3)

• docs/assets/dstrack-favicon.png is excluded by !**/*.png
• docs/assets/dstrack-logo.png is excluded by !**/*.png
• docs/assets/dstrack-logo.svg is excluded by !**/*.svg

📒 Files selected for processing (18)

• README.md
• docs/API/paths.md
• docs/API/store.md
• docs/decisions/0003-local-snapshot-store-layout.md
• docs/gen_logo.py
• docs/getting_started.md
• docs/index.md
• docs/javascripts/logo-animation.js
• docs/roadmap.md
• src/dstrack/_cli.py
• src/dstrack/_log.py
• src/dstrack/_log_render.py
• src/dstrack/cache.py
• src/dstrack/console.py
• src/dstrack/errors.py
• src/dstrack/store.py
• tests/test_log.py
• zensical.toml