Skip to content

Commit 7390fa3

Browse files
cs-rajcs-raj
authored
Merge pull request #35 from contentstack/development
Added Security fixes, cursor rules and skill files
2 parents eec9b23 + 522b4c9 commit 7390fa3

File tree

14 files changed

+372
-25
lines changed

14 files changed

+372
-25
lines changed

‎.cursor/rules/README.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Cursor (optional)
2+
3+
**Cursor** users: start at **[AGENTS.md](../../AGENTS.md)**. All conventions live in **`skills/*/SKILL.md`**.
4+
5+
This folder only points contributors to **`AGENTS.md`** so editor-specific config does not duplicate the canonical docs.

‎.ruby-version‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
2.6
1+
3.1.4

‎AGENTS.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# Contentstack Utils Ruby – Agent guide
2+
3+
**Universal entry point** for contributors and AI agents. Detailed conventions live in **`skills/*/SKILL.md`**.
4+
5+
## What this repo is
6+
7+
| Field | Detail |
8+
|--------|--------|
9+
| **Name:** | [contentstack/contentstack-utils-ruby](https://github.com/contentstack/contentstack-utils-ruby) |
10+
| **Purpose:** | Ruby gem that renders Contentstack rich text and JSON RTE (including GraphQL-shaped payloads) to HTML, with pluggable rendering via `ContentstackUtils::Model::Options` subclasses. |
11+
| **Out of scope (if any):** | This package does not ship an HTTP client or stack SDK; it pairs with the separate Contentstack Ruby delivery client for entry data and `_embedded_items`. |
12+
13+
## Tech stack (at a glance)
14+
15+
| Area | Details |
16+
|------|---------|
17+
| Language | Ruby **≥ 3.1** (see `contentstack_utils.gemspec` and `.ruby-version` for local dev) |
18+
| Build | **Bundler** + **RubyGems**; `contentstack_utils.gemspec`, `Gemfile` |
19+
| Tests | **RSpec**; specs under `spec/**/*_spec.rb`, loaded via `spec/spec_helper.rb` |
20+
| Lint / coverage | No RuboCop in-repo; **SimpleCov** in `spec/spec_helper.rb`; API docs via **YARD** (`.yardopts`, `rake yard`) |
21+
| Runtime deps | **activesupport** (7.x), **nokogiri** (HTML / XML for legacy RTE strings) |
22+
23+
## Commands (quick reference)
24+
25+
| Command type | Command |
26+
|--------------|---------|
27+
| Install deps | `bundle install` |
28+
| Build (default task) | `bundle exec rake` (runs **spec**) |
29+
| Test | `bundle exec rake spec` or `bundle exec rspec` |
30+
| Docs | `bundle exec rake yard` |
31+
32+
**CI / automation:** There is no dedicated workflow that runs `rspec` on every push; local verification is `bundle exec rake`. Other workflows include branch checks (PRs into `master`), release publish, CodeQL, policy/SCA scans—see `.github/workflows/`.
33+
34+
## Where the documentation lives: skills
35+
36+
| Skill | Path | What it covers |
37+
|-------|------|----------------|
38+
| Code review | `skills/code-review/SKILL.md` | PR checklist for this gem |
39+
| Contentstack Utils SDK | `skills/contentstack-utils/SKILL.md` | Public API, models, CDA vs GQL paths, versioning |
40+
| Development workflow | `skills/dev-workflow/SKILL.md` | Branches, Bundler/Rake, gem build, workflows |
41+
| Framework & packaging | `skills/framework/SKILL.md` | Gemspec, dependencies, Ruby version, release |
42+
| Ruby style and layout | `skills/ruby-style/SKILL.md` | Module layout, naming, matching existing code |
43+
| Testing | `skills/testing/SKILL.md` | RSpec layout, mocks, SimpleCov, WebMock |
44+
45+
An index with “when to use” hints is in `skills/README.md`.
46+
47+
## Using Cursor (optional)
48+
49+
If you use **Cursor**, **`.cursor/rules/README.md`** is the only file under `.cursor/rules`; it points to **`AGENTS.md`**—same docs as everyone else.

‎CHANGELOG.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
11
# Changelog
22

3+
## [1.2.4](https://github.com/contentstack/contentstack-utils-ruby/tree/v1.2.4) (2026-04-15)
4+
- Fixed Security issues.
5+
36
## [1.2.3](https://github.com/contentstack/contentstack-utils-ruby/tree/v1.2.3) (2026-03-30)
47
- Fixed GQL JSON test helper parsing for hash-based fixtures by serializing Ruby hashes to JSON.
58
- Normalized non-doc fragment list fixtures into doc-root shape to keep nested list fragment specs stable.

‎Gemfile.lock‎

Lines changed: 15 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,32 @@
11
PATH
22
remote: .
33
specs:
4-
contentstack_utils (1.2.3)
5-
activesupport (>= 8.0)
6-
nokogiri (>= 1.19)
4+
contentstack_utils (1.2.4)
5+
activesupport (>= 7.0, < 8)
6+
nokogiri (>= 1.13, < 1.19)
77

88
GEM
99
remote: https://rubygems.org/
1010
specs:
11-
activesupport (8.1.3)
11+
activesupport (7.2.3.1)
1212
base64
13+
benchmark (>= 0.3)
1314
bigdecimal
1415
concurrent-ruby (~> 1.0, >= 1.3.1)
1516
connection_pool (>= 2.2.5)
1617
drb
1718
i18n (>= 1.6, < 2)
18-
json
1919
logger (>= 1.4.2)
20-
minitest (>= 5.1)
20+
minitest (>= 5.1, < 6)
2121
securerandom (>= 0.3)
2222
tzinfo (~> 2.0, >= 2.0.5)
23-
uri (>= 0.13.1)
24-
addressable (2.8.9)
23+
addressable (2.9.0)
2524
public_suffix (>= 2.0.2, < 8.0)
2625
base64 (0.3.0)
27-
bigdecimal (4.0.1)
26+
benchmark (0.5.0)
27+
bigdecimal (4.1.1)
2828
concurrent-ruby (1.3.6)
29-
connection_pool (3.0.2)
29+
connection_pool (2.5.5)
3030
crack (1.0.1)
3131
bigdecimal
3232
rexml
@@ -36,17 +36,13 @@ GEM
3636
hashdiff (1.2.1)
3737
i18n (1.14.8)
3838
concurrent-ruby (~> 1.0)
39-
json (2.19.3)
4039
logger (1.7.0)
41-
minitest (6.0.2)
42-
drb (~> 2.0)
43-
prism (~> 1.5)
44-
nokogiri (1.19.2-arm64-darwin)
40+
minitest (5.27.0)
41+
nokogiri (1.18.10-arm64-darwin)
4542
racc (~> 1.4)
46-
prism (1.9.0)
47-
public_suffix (7.0.5)
43+
public_suffix (6.0.2)
4844
racc (1.8.1)
49-
rake (13.3.1)
45+
rake (13.4.1)
5046
rexml (3.4.4)
5147
rspec (3.13.2)
5248
rspec-core (~> 3.13.0)
@@ -70,12 +66,11 @@ GEM
7066
simplecov_json_formatter (0.1.4)
7167
tzinfo (2.0.6)
7268
concurrent-ruby (~> 1.0)
73-
uri (1.1.1)
7469
webmock (3.26.2)
7570
addressable (>= 2.8.0)
7671
crack (>= 0.3.2)
7772
hashdiff (>= 0.4.0, < 2.0.0)
78-
yard (0.9.38)
73+
yard (0.9.41)
7974

8075
PLATFORMS
8176
arm64-darwin-22

‎contentstack_utils.gemspec‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ Gem::Specification.new do |s|
99
s.authors = [%q{Contentstack}]
1010
s.email = ["support@contentstack.com"]
1111

12-
s.required_ruby_version = '>= 3.0'
12+
s.required_ruby_version = '>= 3.1'
1313

1414
s.license = "MIT"
1515
s.homepage = "https://github.com/contentstack/contentstack-utils-ruby"
@@ -21,8 +21,8 @@ Gem::Specification.new do |s|
2121
s.test_files = s.files.grep(%r{^spec/})
2222
s.require_paths = ["lib"]
2323

24-
s.add_dependency 'activesupport', '>= 8.0'
25-
s.add_dependency 'nokogiri', '>= 1.19'
24+
s.add_dependency 'activesupport', '>= 7.0', '< 8'
25+
s.add_dependency 'nokogiri', '>= 1.13', '< 1.19'
2626

2727
s.add_development_dependency 'rake', '~> 13.0'
2828
s.add_development_dependency 'rspec', '~> 3.13'

‎lib/contentstack_utils/version.rb‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
11
module ContentstackUtils
2-
VERSION = "1.2.3"
2+
VERSION = "1.2.4"
33
end

‎skills/README.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Skills – Contentstack Utils Ruby
2+
3+
Source of truth for detailed guidance. Read [AGENTS.md](../AGENTS.md) first, then open the skill that matches your task.
4+
5+
## When to use which skill
6+
7+
| Skill folder | Use when |
8+
|--------------|----------|
9+
| `code-review` | Preparing or reviewing a PR |
10+
| `contentstack-utils` | Changing rendering behavior, JSON RTE / GQL paths, options API, or public `lib/` entry points |
11+
| `dev-workflow` | Setting up the repo, running tests/docs, opening PRs, understanding CI and release |
12+
| `framework` | Gemspec, Bundler, Ruby version constraints, activesupport/nokogiri dependencies, gem build/release |
13+
| `ruby-style` | File layout, modules, or staying consistent with existing Ruby style in this repo |
14+
| `testing` | Adding or changing specs, fixtures, mocks, or coverage |
15+
16+
Each folder contains `SKILL.md` with YAML frontmatter (`name`, `description`).

‎skills/code-review/SKILL.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
---
2+
name: code-review
3+
description: Use when reviewing or preparing a PR for this gem—behavior, tests, API compatibility, and release notes.
4+
---
5+
6+
# Code review – Contentstack Utils Ruby
7+
8+
## When to use
9+
10+
- Authoring a pull request that changes rendering, models, or dependencies
11+
- Reviewing someone else’s PR before merge
12+
- Checking release readiness (version + changelog)
13+
14+
## Instructions
15+
16+
### Blockers (fix before merge)
17+
18+
- **Tests:** `bundle exec rake` (or `bundle exec rspec`) passes locally
19+
- **Breaking API:** unintended removal or signature change of public methods on **`ContentstackUtils`**, **`ContentstackUtils::GQL`**, or **`ContentstackUtils::Model::Options`** without version bump and changelog entry
20+
- **Security:** no secrets in code, fixtures, or logs; HTML output changes reviewed for injection or XSS risk when embedding untrusted fields
21+
22+
### Major (should address)
23+
24+
- **CHANGELOG.md** updated for user-visible behavior fixes or features
25+
- **`lib/contentstack_utils/version.rb`** updated when publishing a release (if this PR is release-bound)
26+
- New JSON/RTE node types or GQL shapes covered by **`spec/lib/utils_spec.rb`** (or focused new spec files)
27+
- Dependency range changes in **`contentstack_utils.gemspec`** justified and compatible with Ruby **≥ 3.1**
28+
29+
### Minor (nice to have)
30+
31+
- **README.md** examples match actual class names (**`Options`**, not a non-existent **`Option`** unless aliased)
32+
- YARD or comments only where they clarify non-obvious RTE or GQL mapping
33+
34+
### Process
35+
36+
- Respect **CODEOWNERS** and branch policy (**`master`** vs **`staging`**) described in [dev-workflow](../dev-workflow/SKILL.md)
37+
38+
## References
39+
40+
- [AGENTS.md](../../AGENTS.md)
41+
- [Development workflow](../dev-workflow/SKILL.md)
42+
- [Contentstack Utils SDK](../contentstack-utils/SKILL.md)
43+
- [Framework & packaging](../framework/SKILL.md)
44+
- [Testing](../testing/SKILL.md)

‎skills/contentstack-utils/SKILL.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
---
2+
name: contentstack-utils
3+
description: Use when changing the public Ruby API, RTE rendering (HTML string or JSON), GQL payloads, Model::Options/Metadata, or integration boundaries with the delivery client.
4+
---
5+
6+
# Contentstack Utils SDK – Contentstack Utils Ruby
7+
8+
## When to use
9+
10+
- Implementing or fixing HTML output for rich text / JSON RTE
11+
- Extending or subclassing rendering options (`ContentstackUtils::Model::Options`)
12+
- Parsing GraphQL-shaped RTE (`ContentstackUtils::GQL`)
13+
- Changing load paths or public entry points under `lib/` (gemspec and dependency ranges: see [framework](../framework/SKILL.md))
14+
15+
## Instructions
16+
17+
### Entry points
18+
19+
- **`lib/contentstack_utils.rb`** — requires version and `utils`
20+
- **`lib/contentstack_utils/utils.rb`** — main module **`ContentstackUtils`** with class methods:
21+
- **`render_content(content, options)`** — legacy HTML string RTE (array of strings or single string); uses Nokogiri and `_embedded_items` on the entry passed via options
22+
- **`json_to_html(content, options)`** — JSON RTE document tree (Hash/Array) for CDA-style payloads with embedded items on the entry
23+
- Internal helpers such as **`json_doc_to_html`** (used by GQL path)
24+
- **`ContentstackUtils::GQL`** — **`json_to_html(content, options)`** for GraphQL responses: expects keys like `json` and optional `embedded_itemsConnection.edges`; reuses `ContentstackUtils.json_doc_to_html` with a GQL-specific reference resolver
25+
26+
### Models and extension points
27+
28+
- **`ContentstackUtils::Model::Options`** (`lib/contentstack_utils/model/options.rb`) — default **`render_option`**, **`render_mark`**, **`render_node`**; subclass for custom HTML (see tests under `spec/mock/custom_render_option.rb`)
29+
- **`ContentstackUtils::Model::Metadata`** — built from DOM nodes (HTML path) or JSON reference nodes
30+
- **`ContentstackUtils::Interface::Rendarable`** (`lib/contentstack_utils/interface/renderable.rb`) — base for options; implement **`render_option`** in subclasses
31+
32+
### Data contracts
33+
34+
- **CDA / delivery JSON path:** options may carry an **`entry`** hash with **`_embedded_items`** keyed by field UIDs
35+
- **GQL path:** payload uses **`embedded_itemsConnection.edges`** with **`node`** objects; reference resolution matches **`metadata.item_uid`** to **`node.system.uid`**
36+
37+
### Boundaries
38+
39+
- HTTP and stack access belong to the separate **Contentstack Ruby** client; this gem only renders given content + embedded metadata
40+
41+
### Versioning
42+
43+
- Public API and behavior changes should be reflected in `CHANGELOG.md` and `lib/contentstack_utils/version.rb`
44+
45+
## References
46+
47+
- Product overview: [README.md](../../README.md)
48+
- [Framework & packaging](../framework/SKILL.md)
49+
- [Testing](../testing/SKILL.md)
50+
- [Ruby style and layout](../ruby-style/SKILL.md)
51+
- [Contentstack documentation](https://www.contentstack.com/docs/)

0 commit comments

Comments
 (0)