docsmith 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2ac73e1aab94e9ac08a563be17f38f86c7bc3c054b1e160de5853f954f9265db
-  data.tar.gz: eab3d09587f2d63754f5b6f2d7a2e8cee767815797ac6a6412416230f97dd8b3
+  metadata.gz: 41620e26ac475ea46a8611b5aab7e808bff7a67e0246f9af0894c59164dd88b2
+  data.tar.gz: 89bb6a2920c4088f72de8b6c6c51d8e7aaffa6547fbaba815ef6f06d14e04ddd
 SHA512:
-  metadata.gz: dc5e70e6755c883572dd43c5ccbc66477da572d20c4bd280d128c5d0f899af92c29ecc6635fa57b1cd607ea49a1deeb6a0567909c8c250c34147e8399e359c45
-  data.tar.gz: 826aaf0e992b57f172f128c05651256d72ca18fa3eb93bfa2df6c9d9073ccc79187e3264a2dae53f60321ae5e8b7bbac113615f52cbb1ef8ee96d1ab23b8de9a
+  metadata.gz: 4670c62789e9c5555dbfdf514aeb9df24e87c422d85d9dd51e1be7270724890151a316595675dccb59b670484d71ac25f5214f09ff7d677e1b7481a7a71eabce
+  data.tar.gz: f7d76c3a04ab77535e9f047dc56b6c05420d2200800c9291fb568f82db99fc752386432c7e2a68a377d4dfa4580ea99ba4da228ce78956f2063c9d403453284f

data/CHANGELOG.md

@@ -1,5 +1,263 @@
+# Changelog
+
+All notable changes to this project will be documented here.
+
 ## [Unreleased]
 
-## [0.1.0] - 2026-03-31
+## [0.2.0] - 2026-07-26
+
+### Added
+
+- **`Diff::Result#as_json`** — the canonical diff payload, and now the single
+  source of truth for it. `to_json` delegates to it.
+- **`Diff::Result#modifications` and `#stats`** — explicit change counts.
+- **`Rendering::JsonRenderer#to_h`** — the canonical content envelope; `#render`
+  is `to_h(...).to_json`.
+- **`DocumentVersion#export(**options)`** — the envelope as a Hash, for embedding
+  a version in a larger API response without a JSON round-trip. `as_json` is
+  deliberately NOT overridden on the model, so `render json: @version` still
+  returns plain ActiveRecord attributes.
+- **`schema_version`** on both envelopes, sourced from
+  `Docsmith::JSON_SCHEMA_VERSION`. Clients should branch on this rather than on
+  the gem version.
+- **`include_parsed: true`** on the content export, adding a `data` key with the
+  parsed document for `content_type: "json"`. No-op for other content types.
+- `Docsmith::InvalidJsonContent`, raised when `include_parsed` is set and the
+  content does not parse.
+- `config.html_sanitizer` — controls how `render(:html)` treats stored html
+  content. Accepts `nil` (default: escape), any object responding to `#call`, or
+  `:unsafe_raw`. See the Security note below.
+- `Docsmith::InvalidHtmlSanitizer` error, raised when `html_sanitizer` is set to
+  something that is neither callable, `:unsafe_raw`, nor `nil`.
+
+### Changed
+
+- **Both JSON exports are a new, single, documented shape.** This is a breaking
+  wire-format change with no compatibility flag.
+
+  **`Diff::Result` — nesting no longer produces a different payload.** `as_json`
+  was undefined, so nesting fell through to `Object#as_json` (`instance_values`):
+
+  ```jsonc
+  // BEFORE — result.to_json (documented)
+  { "content_type": "markdown", "from_version": 1, "to_version": 3,
+    "stats": { "additions": 2, "deletions": 0 },
+    "changes": [ { "type": "modification", "position": { "line": 4 }, … } ] }
+
+  // BEFORE — { diff: result }.to_json, i.e. `render json: { diff: result }`
+  // no "stats" at all, and "line" instead of "position"
+  { "diff": { "content_type": "markdown", "from_version": 1, "to_version": 3,
+              "changes": [ { "type": "modification", "line": 4, … } ] } }
+
+  // AFTER — identical either way, plus schema_version and full stats
+  { "schema_version": 1, "content_type": "markdown",
+    "from_version": 1, "to_version": 3,
+    "stats": { "additions": 2, "deletions": 0, "modifications": 1, "total": 3 },
+    "changes": [ { "type": "modification", "position": { "line": 4 }, … } ] }
+  ```
+
+  **`render(:json)` — one envelope instead of two schemas.** It previously returned
+  the bare pretty-printed document for `content_type: "json"` and an envelope for
+  everything else, so no client could parse it generically:
+
+  ```jsonc
+  // BEFORE — content_type "json": no envelope, reformatted
+  { "title": "Doc", "tags": [ "a" ] }
+
+  // BEFORE — any other content_type: envelope, two keys
+  { "content_type": "markdown", "content": "# Hello" }
+
+  // AFTER — one shape for every content_type
+  { "schema_version": 1, "document_id": 7, "version_number": 2,
+    "content_type": "markdown", "content": "# Hello\n\nSecond draft.",
+    "change_summary": "Second draft",
+    "author": { "type": "User", "id": 1 },
+    "metadata": {}, "created_at": "2026-03-01T14:22:00.000Z" }
+  ```
+
+  Also note: `content` is now **always the exact stored string**, byte for byte.
+  JSON documents are no longer pretty-printed on export, so an export matches what
+  was versioned. And `USAGE.md` previously documented a `"version"` key that the
+  implementation never emitted; the envelope now carries `version_number`.
+
+- **`changes` is redesigned: grouped edits with real positions.** The old array had
+  no usable semantics. Each *token* was its own entry, so a one-line heading
+  rewrite produced seven of them. The `position.line` they carried was a **token
+  index, not a line number** — it could exceed the document's line count — and it
+  silently mixed coordinate systems, using an old-document index for deletions and
+  a new-document index for additions, so the values were not even comparable to
+  each other.
+
+  ```jsonc
+  // BEFORE — "my document" -> "<h1>this is a new heading</h1>"
+  // in a 3-line document. Seven entries; "line" reaches 7.
+  "changes": [
+    { "type": "modification", "position": { "line": 1 },
+      "old_content": "my", "new_content": "<h1>" },
+    { "type": "modification", "position": { "line": 2 },
+      "old_content": "document", "new_content": "this" },
+    { "type": "addition", "position": { "line": 3 }, "content": "is" },
+    { "type": "addition", "position": { "line": 4 }, "content": "a" },
+    { "type": "addition", "position": { "line": 5 }, "content": "new" },
+    { "type": "addition", "position": { "line": 6 }, "content": "heading" },
+    { "type": "addition", "position": { "line": 7 }, "content": "</h1>" }
+  ]
+
+  // AFTER — one entry, real offsets and line numbers on both sides
+  "changes": [
+    { "type": "replace",
+      "old": { "start": 0, "end": 11, "line": 1, "column": 1,
+               "text": "my document" },
+      "new": { "start": 0, "end": 30, "line": 1, "column": 1,
+               "text": "<h1>this is a new heading</h1>" } }
+  ]
+  ```
+
+  - A contiguous run of edits collapses into **one** entry. A pure-insert run is
+    `insert`, pure-delete is `delete`, mixed is `replace`.
+  - **Both sides are always present**, so every entry has identical keys. A pure
+    insertion carries a zero-width `old` span marking the insertion point, which
+    also makes the payload applyable as a patch.
+  - `start`/`end` are character offsets (end exclusive); `line`/`column` are real
+    1-indexed positions. `content[start...end] == text`, so clients can slice
+    their own context.
+  - `old` and `new` never share a coordinate space.
+  - `Result#changes` returns the same structure symbol-keyed, so Ruby and JSON
+    agree on what a change is. `Renderers::Base#render_html` consumes it.
+
+- **Edit types and `stats` keys use standard diff vocabulary.** Types are now
+  `insert` / `delete` / `replace` (was `addition` / `deletion` / `modification`),
+  and `stats` is `insertions` / `deletions` / `replacements` / `total`. Ruby readers
+  match: `#insertions`, `#deletions`, `#replacements`. Previously a diff whose every
+  line changed reported `additions: 0, deletions: 0` alongside a non-empty
+  `changes` array; a replacement is now counted once, and for git-style totals you
+  add `replacements` to either side.
+
+- The format-aware parsers were reduced to their tokenizer. `Parsers::Markdown` and
+  `Parsers::Html` had near-identical copies of `compute`; grouping, offsets, and
+  rendering now live once in `Renderers::Base` and subclasses override `tokenize`
+  only. A custom renderer registered via `Renderers::Registry` should do the same.
+
+- **`Comments::Comment#anchor_data` takes a Hash.** The hand-rolled accessor pair
+  that existed only to paper over the `:text` column is gone. Passing a
+  pre-serialized JSON String now stores it as a JSON string literal and reads
+  back as a String, where the old `:text` column parsed it into a Hash. Callers
+  doing `anchor_data: data.to_json` should pass `anchor_data: data`.
+
+### Security
+
+- **Fixed stored XSS in `version.render(:html)` for `content_type: "html"`.** The
+  renderer returned stored content verbatim, so any HTML that originated from a
+  user executed in the browser. html content is now escaped by default and
+  rendered only through an explicitly configured sanitizer.
+
+  Docsmith deliberately ships no sanitizer — a safe one requires a real HTML
+  parser, and adding Nokogiri would break the zero-system-dependency guarantee.
+
+  **This is a breaking change for anyone rendering html documents.** To restore
+  rendering, pick one:
+
+  ```ruby
+  # Recommended — Rails already bundles this via ActionView, so no new gem:
+  config.html_sanitizer = ->(html) { Rails::HTML5::SafeListSanitizer.new.sanitize(html) }
+
+  # Verbatim passthrough, i.e. the old behavior. Only for HTML you fully trust:
+  config.html_sanitizer = :unsafe_raw
+  ```
+
+  A non-callable, non-`:unsafe_raw` value raises `Docsmith::InvalidHtmlSanitizer`
+  instead of degrading to raw output. Markdown and JSON rendering are unaffected,
+  and diff output was already escaped for every content type.
+
+### Fixed
+
+- **`rails generate docsmith:install` never worked.** The generator's action method
+  was named `create_migration`, which shadows `Rails::Generators::Migration`'s own
+  `create_migration(destination, data, config)` — the method `migration_template`
+  calls internally. Running the generator died with `ArgumentError: wrong number of
+  arguments (given 3, expected 0)` before writing a single file, so the documented
+  first step of installing the gem failed outright in 0.1.0. Renamed to
+  `create_migration_file`.
+
+  This went unnoticed because the generator had no test coverage: `railties`
+  provides `rails/generators` and was not a development dependency, so the spec
+  suite could not load the generator at all. `railties` is now a **development**
+  dependency — deliberately not a runtime one, since docsmith targets plain
+  ActiveRecord and nothing in `lib/docsmith.rb` loads Rails. The generator now has
+  specs that run it against a temp directory and execute the migration it produces.
+- JSON payload columns (`metadata`, `anchor_data`) are now `:json` rather than
+  `:text` in the gem's own schemas. They previously read back as a `Hash` on
+  PostgreSQL and as the literal String `"{}"` on SQLite and MySQL, so models saw
+  a different type in tests than in production.
+- `rails generate docsmith:install` no longer emits a PostgreSQL-only migration.
+  It picks `jsonb` for PostgreSQL-derived adapters and `json` elsewhere, so the
+  generated migration runs on MySQL and SQLite instead of failing on `t.jsonb`.
+- `Comments::Anchor.migrate` no longer raises `TypeError` out of the middle of a
+  comment migration when an anchor is missing its `anchored_text` or offsets.
+  Such anchors are now reported as `orphaned`.
+- `Comments::Comment#anchor_data` no longer raises an unrescued
+  `JSON::ParserError` from a plain attribute reader on malformed stored data.
+
+### Demo
+
+- Added an **HTML & Sanitizer** section (`/pages`) built on a `content_type :html`
+  model, showing `render(:html)` output under each `html_sanitizer` mode against
+  content containing a `<script>` tag. Seeded automatically.
+- **Fixed stored XSS in the demo's own views.** Sinatra's stock ERB does not
+  escape `<%= %>`, so an article title, comment body, or tag name containing a
+  `<script>` tag executed in the browser. The route classes now set
+  `erb, escape_html: true`, and the two places that intentionally emit HTML
+  (`layout.erb`'s `yield`, `diff.erb`'s `to_html`) use `<%== %>`.
+- `demo/db/setup.rb` migrates pre-existing demo databases from the old `:text`
+  columns to `:json` via `change_column`, preserving all rows. The `create_table`
+  calls are guarded by `table_exists?`, so without this an existing demo DB would
+  have silently kept its old column types.
+
+### Upgrading
+
+- **No migration is required for existing installs.** The column-type fix affects
+  the schemas Docsmith ships for its own tests and demo; installs generated
+  before this release already have `jsonb` columns, which behave identically.
+  The generator change only matters for new installs on MySQL and SQLite, where
+  the old `t.jsonb` migration could not run at all.
+- If you render `content_type: "html"` documents, set `config.html_sanitizer`
+  before upgrading, or that content will render escaped.
+- If you pass `anchor_data:` a pre-serialized JSON String anywhere, change it to
+  pass the Hash directly.
+- **Update any consumer of the two JSON exports.** Both shapes changed and there is
+  no compatibility flag. Branch on `schema_version` going forward.
+  - If you parsed `render(:json)` for a `content_type: "json"` document, the
+    document is no longer the payload root — read `content` (a string) or pass
+    `include_parsed: true` and read `data`.
+  - If you nested a `Diff::Result` and worked around the missing `stats` by calling
+    `JSON.parse(result.to_json)` first, you can now pass the result directly.
+  - If you read `additions`/`deletions` as an overall change count, read
+    `stats["total"]`, or add `replacements` to either side.
+  - Rename `result.additions` to `result.insertions` and `result.modifications` to
+    `result.replacements`. `result.deletions` keeps its name.
+  - If you walked `result.changes`, it is now grouped edits with `old`/`new` spans
+    rather than a flat token list. Anything reading `c[:line]` or `c[:content]`
+    needs updating — and note that `c[:line]` was never a line number.
+  - If you subclassed a parser or registered a custom diff renderer, override
+    `#tokenize` (returning `[text, start_offset]` pairs) instead of `#compute`.
+- **`config.diff_context_lines` is removed.** It was declared and documented but
+  read by nothing, so it never had any effect. With real `start`/`end` offsets on
+  both sides of every edit, a client can slice whatever context it needs from the
+  document text.
+
+## [0.1.0] - 2026-04-12
+
+First public release.
+
+### Added
 
-- Initial release
+- `Docsmith::Versionable` mixin — include in any ActiveRecord model to enable versioning
+- Snapshot-based versioning: full content snapshots for HTML, Markdown, and JSON with instant rollback to any version
+- Format-aware diff engine: word-level diffs for Markdown, tag-atomic diffs for HTML
+- Inline and document-level comments with threading, resolution, and version migration
+- Debounced auto-save with configurable threshold per class
+- Per-class and global configuration via `docsmith_config` block
+- Lifecycle events: `version_created`, `version_restored`, `version_tagged`
+- Standalone `Docsmith::Document` service API — works without a model mixin
+- `rails generate docsmith:install` generator with migration
+- Zero system dependencies — pure Ruby on top of ActiveRecord and diff-lcs

data/CODE_OF_CONDUCT.md

@@ -1,132 +1,11 @@
-# Contributor Covenant Code of Conduct
+# Code of Conduct
 
-## Our Pledge
+This is a small open source project, maintained by one person. If you contribute, a few things I ask:
 
-We as members, contributors, and leaders pledge to make participation in our
-community a harassment-free experience for everyone, regardless of age, body
-size, visible or invisible disability, ethnicity, sex characteristics, gender
-identity and expression, level of experience, education, socio-economic status,
-nationality, personal appearance, race, caste, color, religion, or sexual
-identity and orientation.
+**Be straight.** If something is broken, say so. If you disagree with a design decision, explain why. Honest feedback is welcome — rudeness isn't.
 
-We pledge to act and interact in ways that contribute to an open, welcoming,
-diverse, inclusive, and healthy community.
+**Be patient.** I review issues and PRs in my own time. If something takes a while, a polite nudge is fine.
 
-## Our Standards
+**Be constructive.** Bug reports with reproducible examples, PRs with context, questions that show you tried first — these make the project better for everyone.
 
-Examples of behavior that contributes to a positive environment for our
-community include:
-
-* Demonstrating empathy and kindness toward other people
-* Being respectful of differing opinions, viewpoints, and experiences
-* Giving and gracefully accepting constructive feedback
-* Accepting responsibility and apologizing to those affected by our mistakes,
-  and learning from the experience
-* Focusing on what is best not just for us as individuals, but for the overall
-  community
-
-Examples of unacceptable behavior include:
-
-* The use of sexualized language or imagery, and sexual attention or advances of
-  any kind
-* Trolling, insulting or derogatory comments, and personal or political attacks
-* Public or private harassment
-* Publishing others' private information, such as a physical or email address,
-  without their explicit permission
-* Other conduct which could reasonably be considered inappropriate in a
-  professional setting
-
-## Enforcement Responsibilities
-
-Community leaders are responsible for clarifying and enforcing our standards of
-acceptable behavior and will take appropriate and fair corrective action in
-response to any behavior that they deem inappropriate, threatening, offensive,
-or harmful.
-
-Community leaders have the right and responsibility to remove, edit, or reject
-comments, commits, code, wiki edits, issues, and other contributions that are
-not aligned to this Code of Conduct, and will communicate reasons for moderation
-decisions when appropriate.
-
-## Scope
-
-This Code of Conduct applies within all community spaces, and also applies when
-an individual is officially representing the community in public spaces.
-Examples of representing our community include using an official email address,
-posting via an official social media account, or acting as an appointed
-representative at an online or offline event.
-
-## Enforcement
-
-Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported to the community leaders responsible for enforcement at
-[INSERT CONTACT METHOD].
-All complaints will be reviewed and investigated promptly and fairly.
-
-All community leaders are obligated to respect the privacy and security of the
-reporter of any incident.
-
-## Enforcement Guidelines
-
-Community leaders will follow these Community Impact Guidelines in determining
-the consequences for any action they deem in violation of this Code of Conduct:
-
-### 1. Correction
-
-**Community Impact**: Use of inappropriate language or other behavior deemed
-unprofessional or unwelcome in the community.
-
-**Consequence**: A private, written warning from community leaders, providing
-clarity around the nature of the violation and an explanation of why the
-behavior was inappropriate. A public apology may be requested.
-
-### 2. Warning
-
-**Community Impact**: A violation through a single incident or series of
-actions.
-
-**Consequence**: A warning with consequences for continued behavior. No
-interaction with the people involved, including unsolicited interaction with
-those enforcing the Code of Conduct, for a specified period of time. This
-includes avoiding interactions in community spaces as well as external channels
-like social media. Violating these terms may lead to a temporary or permanent
-ban.
-
-### 3. Temporary Ban
-
-**Community Impact**: A serious violation of community standards, including
-sustained inappropriate behavior.
-
-**Consequence**: A temporary ban from any sort of interaction or public
-communication with the community for a specified period of time. No public or
-private interaction with the people involved, including unsolicited interaction
-with those enforcing the Code of Conduct, is allowed during this period.
-Violating these terms may lead to a permanent ban.
-
-### 4. Permanent Ban
-
-**Community Impact**: Demonstrating a pattern of violation of community
-standards, including sustained inappropriate behavior, harassment of an
-individual, or aggression toward or disparagement of classes of individuals.
-
-**Consequence**: A permanent ban from any sort of public interaction within the
-community.
-
-## Attribution
-
-This Code of Conduct is adapted from the [Contributor Covenant][homepage],
-version 2.1, available at
-[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
-
-Community Impact Guidelines were inspired by
-[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
-
-For answers to common questions about this code of conduct, see the FAQ at
-[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
-[https://www.contributor-covenant.org/translations][translations].
-
-[homepage]: https://www.contributor-covenant.org
-[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
-[Mozilla CoC]: https://github.com/mozilla/diversity
-[FAQ]: https://www.contributor-covenant.org/faq
-[translations]: https://www.contributor-covenant.org/translations
+That's it. No enforcement ladder, no formal committee. If something feels off, reach out at swastik.thapaliya@gmail.com and we'll sort it out like adults.

data/README.md

@@ -1,5 +1,7 @@
 # Docsmith
 
+[![Gem Version](https://badge.fury.io/rb/docsmith.svg)](https://rubygems.org/gems/docsmith)
+
 Docsmith adds snapshot-based versioning, format-aware diffs, and inline comments to any
 ActiveRecord model — with zero system dependencies.
 
@@ -35,10 +37,36 @@ article.save!
 article.save_version!(author: current_user, summary: "First draft")
 
 result = article.diff_from(1)
-result.additions   # word-level count for markdown
+result.stats       # => {"insertions"=>1, "deletions"=>0, "replacements"=>1, "total"=>2}
+result.changes     # grouped edits with character offsets and line numbers
 result.to_html     # <ins>/<del> markup
+result.as_json     # canonical JSON payload, identical when nested
+```
+
+## Example App
+
+A self-contained Sinatra demo is in [`demo/`](demo/). It shows versioning, diffs, and comments working end-to-end — no Rails required.
+
+```bash
+cd demo
+bundle install
+bundle exec rackup
+# open http://localhost:9292
 ```
 
+The demo loads the gem from the parent directory as a path dependency, so the
+`bundle exec` prefix is required. `bundle exec ruby app.rb` also works and
+serves on port 4567.
+
+Two sections: **Articles** covers markdown versioning, diffs, tags, and comments.
+**HTML & Sanitizer** uses `content_type :html` to show what `render(:html)` returns
+under each `config.html_sanitizer` mode, side by side, against content containing a
+`<script>` tag.
+
+The demo installs `rails-html-sanitizer` to demonstrate the recommended sanitizer
+setup, and `erubi` to turn on ERB escaping. Neither is a Docsmith dependency — the
+gem itself still has none beyond ActiveRecord, ActiveSupport, and diff-lcs.
+
 ## Documentation
 
 See **[USAGE.md](USAGE.md)** for full documentation including:
@@ -61,6 +89,12 @@ bundle exec rspec    # run tests
 bin/console          # interactive console
 ```
 
+## How this was built
+
+Honest note: this gem was built over two weekends using [Claude Code](https://claude.ai/code) with the superpowers plugin. Not vibe-coding — the planning, architecture decisions, and implementation were all deliberate. If you're curious how it came together, the planning docs and implementation notes are in [docs/superpowers](docs/superpowers).
+
+Early designs got ambitious fast — branching, merging, conflict resolution. Turns out that's a lot of machinery for what is ultimately a document version manager. I stripped it back to what actually matters: snapshots, diffs, and comments. You can see all the planning in [docs/superpowers](docs/superpowers).
+
 ## License
 
 MIT — see [LICENSE.txt](LICENSE.txt).