Skip to content

Commit 6830a95

Browse files
reeshika-hreeshika-h
committed
Added cursor rules and skills
1 parent 8a0caee commit 6830a95

File tree

12 files changed

+458
-0
lines changed

12 files changed

+458
-0
lines changed

‎.cursor/rules/README.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Cursor Rules – Contentstack Utils (Java)
2+
3+
This directory contains Cursor AI rules for **contentstack-utils-java**. Rules give persistent context so the AI follows project conventions and Contentstack RTE / embedded-item patterns.
4+
5+
## How rules are applied
6+
7+
- **File-specific rules** use the `globs` frontmatter: they apply when you open or edit files matching that pattern.
8+
- **Always-on rules** use `alwaysApply: true`: they are included in every conversation in this project.
9+
10+
## Rule index
11+
12+
| File | Applies when | Purpose |
13+
|------|--------------|---------|
14+
| **dev-workflow.md** | (Reference only; no glob) | Development workflow: branches, running tests, PR expectations, optional TDD. |
15+
| **java.mdc** | Editing any `**/*.java` file | Java 17 standards: naming, package layout under `com.contentstack.utils`, JSON/Jsoup, Javadoc, dependencies. |
16+
| **contentstack-utils-java.mdc** | Editing `src/main/java/**/*.java` | Utils-specific patterns: `Utils` / `GQL`, RTE and embedded JSON, `DefaultOption` / callbacks; alignment with entry JSON shapes (no HTTP client in this module). |
17+
| **testing.mdc** | Editing `src/test/**/*.java` | Testing patterns: JUnit 4, fixtures, JaCoCo, Surefire (including `testFailureIgnore`). |
18+
| **code-review.mdc** | Always | PR / review checklist: API stability, error handling, backward compatibility, dependencies and security (e.g. SCA), tests. |
19+
20+
## Related
21+
22+
- **AGENTS.md** (repo root) – Main entry point for AI agents: project overview, entry points, commands, pointers to rules and skills.
23+
- **skills/** – Reusable skill docs (`contentstack-utils-java`, `testing`, `code-review`, `framework`) for deeper guidance on specific tasks.

‎.cursor/rules/code-review.mdc‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
---
2+
description: PR and code review checklist – API stability, errors, compatibility, security, tests
3+
alwaysApply: true
4+
---
5+
6+
# Code review checklist – Contentstack Utils (Java)
7+
8+
Use this checklist when reviewing pull requests or before opening a PR.
9+
10+
## API design and stability
11+
12+
- [ ] **Public API:** New or changed public methods on `Utils`, `GQL`, `DefaultOption`, or `interfaces` are necessary, documented (Javadoc), and justified for `com.contentstack.sdk:utils` consumers.
13+
- [ ] **Backward compatibility:** No breaking changes unless explicitly versioned (e.g. major) and noted in `Changelog.md`.
14+
- [ ] **Naming:** Consistent with existing Utils style and Contentstack RTE / embedded terminology.
15+
16+
## Error handling and robustness
17+
18+
- [ ] **JSON safety:** Missing keys / `_embedded_items` handled predictably; no new NPEs or silent behavior changes without rationale.
19+
- [ ] **Null safety:** `JSONObject` / `JSONArray` access uses `opt*` / `has` patterns consistent with existing code.
20+
21+
## Dependencies and security
22+
23+
- [ ] **Dependencies:** New or upgraded dependencies in `pom.xml` are justified; versions do not introduce known regressions for SDK consumers.
24+
- [ ] **SCA:** Address security findings (e.g. Snyk on PRs, `.github/workflows/sca-scan.yml`) in scope or track with a follow-up.
25+
26+
## Testing
27+
28+
- [ ] **Coverage:** New or modified behavior has tests under `src/test/java/com/contentstack/utils/` and fixtures under `src/test/resources/` when needed.
29+
- [ ] **Surefire:** Because `testFailureIgnore` is enabled, confirm results in **`target/surefire-reports/`**, not only exit code.
30+
31+
## Severity (optional)
32+
33+
- **Blocker:** Must fix before merge (e.g. breaking public API without approval, critical vulnerability, no tests for new behavior).
34+
- **Major:** Should fix (e.g. undocumented HTML/JSON behavior change, missing Javadoc on new public API).
35+
- **Minor:** Nice to fix (e.g. style, typos in comments).

‎.cursor/rules/contentstack-utils-java.mdc‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
---
2+
description: Contentstack Utils patterns — RTE, embedded items, GraphQL JSON; no in-module HTTP client
3+
globs:
4+
- "src/main/java/**/*.java"
5+
---
6+
7+
# Contentstack Utils (Java) – SDK rules
8+
9+
Apply when editing the Utils library. Behavior should stay aligned with [Content Delivery API](https://www.contentstack.com/docs/apis/content-delivery-api/) entry JSON and with how the [Java Delivery SDK](https://www.contentstack.com/docs/developers/sdks/content-delivery-sdk/java) fetches entries (this module does **not** perform HTTP calls itself).
10+
11+
## Entry points
12+
13+
- **`com.contentstack.utils.Utils`** — `render`, `renderContent`, `renderContents`, `jsonToHTML` for REST/CDA-style JSON with `_embedded_items`; dot-paths into the entry (e.g. `group.field`).
14+
- **`com.contentstack.utils.GQL`** — `jsonToHTML` for GraphQL-shaped responses (`embedded_itemsConnection`, `edges`, `node`, JSON RTE under `json`). Do not instantiate `GQL` (private constructor).
15+
16+
## Rendering and options
17+
18+
- Implement **`com.contentstack.utils.interfaces.Option`** or extend **`com.contentstack.utils.render.DefaultOption`** for custom embedded HTML, marks, and nodes.
19+
- Use **`com.contentstack.utils.interfaces.NodeCallback`** and metadata helpers where the codebase already does.
20+
- **`com.contentstack.utils.helper.Metadata`**, **`embedded.StyleType`**, **`embedded.ItemType`** classify embedded content.
21+
22+
## Data flow
23+
24+
- **No standalone HTTP client:** this library transforms **already-fetched** JSON. API keys, delivery tokens, and `includeEmbeddedItems()` belong to the Java SDK or app code, documented in root `README.md`.
25+
- Shared traversal lives in **`AutomateCommon`**; JSON RTE trees in **`NodeToHTML`**. Preserve JSON key assumptions (`_embedded_items`, HTML classes such as `embedded-entry`) unless versioning a breaking change.
26+
27+
## Errors
28+
29+
- Prefer null-safe `opt*` / `has` on `JSONObject` / `JSONArray` consistent with existing code.

‎.cursor/rules/dev-workflow.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# Development workflow – Contentstack Utils (Java)
2+
3+
Use this as the standard workflow when contributing to **contentstack-utils-java**. For Java style and test conventions, see **java.mdc** and **testing.mdc**.
4+
5+
## Branches
6+
7+
- Default integration for PRs is often **`staging`**; merging into **`master`** may be restricted (see `.github/workflows/check-branch.yml`).
8+
- Feature/fix branches often use ticket-style names (e.g. `fix/DX-5734`).
9+
10+
## Running tests
11+
12+
- **All tests:** `mvn test`
13+
- **Build only:** `mvn clean compile`
14+
- **Sample module** (after installing the parent JAR): `mvn -f sample/pom.xml compile` — see `sample/README.md` for credentials and env vars if using the Delivery SDK.
15+
16+
Run tests before opening a PR. Review **`target/surefire-reports/`** if anything looks flaky (`testFailureIgnore` is set in `pom.xml`).
17+
18+
## Pull requests
19+
20+
- Ensure the build passes: `mvn clean test` (and sample compile if you changed `sample/`).
21+
- Follow the **code-review** rule (`.cursor/rules/code-review.mdc`) for the PR checklist.
22+
- Keep public API backward-compatible unless releasing a breaking version; update `Changelog.md` when behavior changes.
23+
24+
## Optional: TDD
25+
26+
If the team uses TDD, follow RED–GREEN–REFACTOR: failing test first, then implementation, then refactor. The **testing** rule and **skills/testing** describe structure and Surefire/JaCoCo behavior.
27+
28+
## CI and security
29+
30+
- **Java 17** in publish workflow (`.github/workflows/maven-publish.yml`).
31+
- **Snyk** Maven scan on PRs (`.github/workflows/sca-scan.yml`).
32+
- **Javadoc:** `mvn javadoc:javadoc` (optional locally); attach phase may use `-Xdoclint:none` per `pom.xml`.
33+
34+
## Lint / format
35+
36+
- No Checkstyle/Spotless in repo — match existing style in surrounding files.

‎.cursor/rules/java.mdc‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
---
2+
description: Java 17 and com.contentstack.utils conventions for the Utils SDK
3+
globs:
4+
- "**/*.java"
5+
---
6+
7+
# Java standards – Contentstack Utils (Java)
8+
9+
Apply these conventions when editing Java code in this repository.
10+
11+
## Language and runtime
12+
13+
- **Java 17** via `maven-compiler-plugin` `<release>17</release>` in `pom.xml`. Ignore legacy `maven.compiler.source/target` `1.8` properties; the compiler plugin is authoritative.
14+
- Avoid raw types; use proper generics where applicable.
15+
16+
## Package and layout
17+
18+
- Production code lives under **`com.contentstack.utils`** and subpackages (`render`, `node`, `embedded`, `helper`, `interfaces`).
19+
- Keep the existing package structure; do not introduce new top-level packages without team alignment.
20+
21+
## Naming
22+
23+
- **Classes:** PascalCase (e.g. `Utils`, `DefaultOption`, `AutomateCommon`).
24+
- **Methods / variables:** camelCase.
25+
- **Test classes:** Mix of `*Tests`, `*Test`, `Test*` already in use (see **testing.mdc**).
26+
27+
## JSON and HTML
28+
29+
- Prefer **`org.json`** (`JSONObject`, `JSONArray`) for public APIs and internals, consistent with `Utils` and `GQL`.
30+
- Use **Jsoup** for RTE HTML parsing; follow patterns in `AutomateCommon` and `Utils`.
31+
32+
## Validation and utility types
33+
34+
- `javax.validation.constraints` (e.g. `@NotNull`) appear on some public methods; keep Javadoc aligned with actual null behavior.
35+
- Hide construction with private constructors where the codebase already does (e.g. `GQL`, `AutomateCommon`).
36+
37+
## Dependencies
38+
39+
- This artifact is a small JAR (`com.contentstack.sdk:utils`) consumed by the Contentstack Java SDK. Prefer minimal, well-scoped dependencies; justify new ones in `pom.xml`.
40+
- This repo does **not** use Lombok; do not introduce it without an explicit team decision.
41+
42+
## General
43+
44+
- Document public API with Javadoc; keep examples in line with real usage (`Utils.render`, `GQL.jsonToHTML`, `DefaultOption`).

‎.cursor/rules/testing.mdc‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
---
2+
description: JUnit 4 testing patterns, fixtures, Surefire, JaCoCo for contentstack-utils-java
3+
globs:
4+
- "src/test/**/*.java"
5+
---
6+
7+
# Testing rules – Contentstack Utils (Java)
8+
9+
Apply when writing or editing tests. The project uses **JUnit 4** and **JaCoCo** (see `pom.xml`).
10+
11+
## Test naming and layout
12+
13+
- **Unit tests** use class names such as `UtilTests`, `DefaultOptionTests`, `AssetLinkTest`, `TestRte`, `TestMetadata`, or prefixes/suffixes `Test*`, `*Test`, `*Tests`. Place code under `src/test/java/com/contentstack/utils/` (mirror of main).
14+
- There is **no** separate `*IT` integration suite in this repo; all tests are standard Maven Surefire tests. Optional **`sample/`** may use the Delivery SDK with env vars (see `sample/README.md`).
15+
16+
## JUnit 4 usage
17+
18+
- Use **`org.junit.Test`**, **`Assert`**, **`@BeforeClass`**, **`@FixMethodOrder`** where appropriate (match surrounding test class style).
19+
20+
## Fixtures and data
21+
22+
- JSON fixtures live under **`src/test/resources/`** (e.g. `multiple_rich_text_content.json`, `reports/`). Load via paths relative to the module root or classpath as existing tests do (`ReadResource`, `UtilTests`).
23+
- Keep tests **offline** — no API keys or network required for default unit tests.
24+
25+
## Surefire
26+
27+
- **`testFailureIgnore`** is set to **`true`** in `pom.xml`. Always check **`target/surefire-reports/`** when investigating failures; do not rely only on Maven’s exit code.
28+
29+
## Coverage
30+
31+
- **JaCoCo** runs on `test`; reports under **`target/site/jacoco/`**. Maintain or improve coverage when changing production code in `Utils`, `GQL`, or `AutomateCommon`.

‎AGENTS.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# Contentstack Utils (Java) – Agent guide
2+
3+
This document is the main entry point for AI agents working in **contentstack-utils-java**. Repo: [contentstack-utils-java](https://github.com/contentstack/contentstack-utils-java).
4+
5+
## Project
6+
7+
- **Name:** Contentstack Utils (Java) — Maven artifact `com.contentstack.sdk:utils`.
8+
- **Purpose:** Library for **rendering Rich Text Editor (RTE) content and embedded items** from Contentstack entry JSON (REST/CDA-style with `_embedded_items`) and GraphQL-shaped responses. It does **not** perform HTTP calls or manage API keys; use it with the [Contentstack Java Delivery SDK](https://www.contentstack.com/docs/developers/sdks/content-delivery-sdk/java) after fetching entries.
9+
10+
## Tech stack
11+
12+
- **Language:** Java **17** (`maven-compiler-plugin` `<release>17</release>` in `pom.xml`).
13+
- **Build:** Maven.
14+
- **Testing:** JUnit 4, Maven Surefire, JaCoCo (see `pom.xml`; Surefire uses `testFailureIgnore`).
15+
- **JSON / HTML:** `org.json`, Jsoup, `commons-text`; `javax.validation` API; `spring-web` is a compile dependency (not a public HTTP client surface for this module).
16+
17+
## Main entry points
18+
19+
- **`Contentstack.stack(...)`** — Not in this repo; provided by the Java SDK (see root `README.md`).
20+
- **`com.contentstack.utils.Utils`** — `render`, `renderContent`, `jsonToHTML`, variant helpers, etc.
21+
- **`com.contentstack.utils.GQL`** — GraphQL entry `jsonToHTML`.
22+
- **`com.contentstack.utils.render.DefaultOption`** / **`interfaces.Option`** — custom RTE/embedded rendering.
23+
- **Paths:** `src/main/java/com/contentstack/utils/` (production), `src/test/java/com/contentstack/utils/` (tests). Optional **`sample/`** demonstrates Delivery SDK + Utils together.
24+
25+
## Commands
26+
27+
- **Build and test:** `mvn clean test`
28+
- **Compile only:** `mvn clean compile`
29+
- **Single test class:** `mvn test -Dtest=UtilTests`
30+
- **Javadoc (optional):** `mvn javadoc:javadoc`
31+
32+
CI uses Java **17** (`.github/workflows/maven-publish.yml`). **Snyk** runs on PRs (`.github/workflows/sca-scan.yml`).
33+
34+
## Rules and skills
35+
36+
### `.cursor/rules/`
37+
38+
| Resource | Role |
39+
|----------|------|
40+
| **README.md** | Index of all rules and when they apply |
41+
| **dev-workflow.md** | Branches, tests, PRs, optional TDD |
42+
| **java.mdc** | Applies to `**/*.java`: Java 17, `com.contentstack.utils`, JSON/Jsoup |
43+
| **contentstack-utils-java.mdc** | Applies to `src/main/java/**/*.java`: Utils/GQL, RTE, embedded JSON |
44+
| **testing.mdc** | Applies to `src/test/**/*.java`: JUnit 4, fixtures, JaCoCo |
45+
| **code-review.mdc** | Always applied: PR checklist |
46+
47+
### `skills/`
48+
49+
| Skill | Use when |
50+
|-------|----------|
51+
| **contentstack-utils-java** | Changing RTE, embedded items, `Utils` / `GQL`, `DefaultOption`, callbacks |
52+
| **testing** | Adding or refactoring tests and fixtures |
53+
| **code-review** | Reviewing PRs or pre-merge self-review |
54+
| **framework** | Editing `pom.xml`, plugins, publishing, or `sample/` dependency management |
55+
56+
See **`skills/README.md`** for details. For editor-wide Cursor user skills (if configured), this repo’s project skills live only under **`./skills/`**.
57+
58+
## Official documentation
59+
60+
- [Contentstack Developers](https://www.contentstack.com/docs/)
61+
- [Content Delivery API](https://www.contentstack.com/docs/apis/content-delivery-api/)
62+
- Root **`README.md`** — Maven coordinates and embedded-items examples

‎skills/README.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Skills – Contentstack Utils (Java)
2+
3+
This directory contains **skills**: reusable guidance for AI agents (and developers) on specific tasks. Each skill is a folder with a `SKILL.md` file (YAML frontmatter: `name`, `description`).
4+
5+
## When to use which skill
6+
7+
| Skill | Use when |
8+
|-------|----------|
9+
| **contentstack-utils-java** | Implementing or changing RTE/embedded behavior: `Utils`, `GQL`, `DefaultOption`, callbacks, JSON shapes for CDA/GraphQL entries. |
10+
| **testing** | Writing or refactoring tests: JUnit 4, fixtures, Surefire, JaCoCo, offline unit tests. |
11+
| **code-review** | Reviewing a PR or preparing your own: API stability, compatibility, dependencies/security, tests. |
12+
| **framework** | Changing `pom.xml`, Java release level, plugins (Surefire, JaCoCo, javadoc, GPG, Central publishing), or sample module dependency management. |
13+
14+
## How agents should use skills
15+
16+
- **contentstack-utils-java:** Apply when editing `src/main/java/com/contentstack/utils/**` or adding RTE/embedded-related behavior. Follow existing JSON/HTML contracts and public API rules.
17+
- **testing:** Apply when creating or modifying `src/test/**`. Respect `testFailureIgnore` and JaCoCo layout.
18+
- **code-review:** Apply when simulating or performing a PR review; use the checklist and optional severity levels.
19+
- **framework:** Apply when touching build or release tooling; keep consumer impact (Java SDK) in mind.
20+
21+
Each skill’s `SKILL.md` contains more detail and cross-links to `.cursor/rules/`.

‎skills/code-review/SKILL.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
---
2+
name: code-review
3+
description: Use when reviewing PRs or before opening a PR — API design, compatibility, dependencies, security, tests
4+
---
5+
6+
# Code review – Contentstack Utils (Java)
7+
8+
Use this skill when performing or preparing a pull request review for this repository.
9+
10+
## When to use
11+
12+
- Reviewing another contributor’s PR.
13+
- Self-review before submission.
14+
- Verifying changes meet API, compatibility, security, and test standards.
15+
16+
## Instructions
17+
18+
Work through the checklist below. Optionally tag items with **Blocker**, **Major**, or **Minor**.
19+
20+
### 1. API design and stability
21+
22+
- [ ] **Public API:** New or changed public surface on `Utils`, `GQL`, `DefaultOption`, or `interfaces` is documented and justified for Maven consumers.
23+
- [ ] **Backward compatibility:** Breaking changes only with version/changelog alignment.
24+
- [ ] **Naming:** Consistent with existing Utils and RTE terminology.
25+
26+
**Severity:** Unapproved breaking API change = Blocker. Missing Javadoc on new public API = Major.
27+
28+
### 2. Robustness
29+
30+
- [ ] **JSON:** No unintended behavior change for `_embedded_items` / GraphQL shapes without tests and release notes.
31+
- [ ] **HTML output:** Customer-visible markup changes are documented.
32+
33+
**Severity:** Silent breaking HTML/JSON behavior = Major.
34+
35+
### 3. Dependencies and security
36+
37+
- [ ] **Dependencies:** Version bumps in `pom.xml` are intentional; consider Snyk/SCA.
38+
- [ ] **SCA:** Address or defer security findings with a ticket.
39+
40+
**Severity:** New critical/high CVE in scope = Blocker.
41+
42+
### 4. Testing
43+
44+
- [ ] **Coverage:** New logic has tests; Surefire reports reviewed when using global `testFailureIgnore`.
45+
- [ ] **Quality:** Tests are deterministic and assert meaningful behavior.
46+
47+
**Severity:** No tests for new behavior = Blocker.
48+
49+
### 5. Optional severity summary
50+
51+
- **Blocker:** Breaking API without approval, security issue, missing tests for new code.
52+
- **Major:** Missing docs, risky dependency bump, unclear JSON/HTML behavior.
53+
- **Minor:** Style, typos, minor refactors.
54+
55+
## References
56+
57+
- Project rule: `.cursor/rules/code-review.mdc`
58+
- Testing skill: `skills/testing/SKILL.md`

‎skills/contentstack-utils-java/SKILL.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
---
2+
name: contentstack-utils-java
3+
description: Use when implementing RTE, embedded items, Utils/GQL, DefaultOption — JSON shapes and no HTTP client in-module
4+
---
5+
6+
# Contentstack Utils (Java) – skill
7+
8+
Use this skill when changing **`Utils`**, **`GQL`**, **`DefaultOption`**, callbacks, or embedded/RTE behavior in this repository.
9+
10+
## Scope
11+
12+
This artifact (`com.contentstack.sdk:utils`) **renders** RTE and embedded content from JSON already obtained from Contentstack. **Authentication, stack keys, delivery tokens, and `includeEmbeddedItems()`** are handled by the **[Contentstack Java SDK](https://www.contentstack.com/docs/developers/sdks/content-delivery-sdk/java)** (or your own HTTP layer), not by this repo.
13+
14+
## Core types
15+
16+
- **`com.contentstack.utils.Utils`** — `render`, `renderContent`, `renderContents`, `jsonToHTML` (CDA-style JSON with `_embedded_items`).
17+
- **`com.contentstack.utils.GQL`** — `jsonToHTML` for GraphQL entry shapes.
18+
- **`com.contentstack.utils.render.DefaultOption`** / **`interfaces.Option`** — custom rendering; see root `README.md`.
19+
- **`com.contentstack.utils.helper.Metadata`** — embedded metadata.
20+
21+
## JSON contracts
22+
23+
- REST: `_embedded_items`; RTE HTML classes such as `embedded-entry`, `embedded-asset`.
24+
- GraphQL: `embedded_itemsConnection`, `edges`, `node`, `uid` matching metadata.
25+
26+
## References
27+
28+
- Project rule: `.cursor/rules/contentstack-utils-java.mdc`
29+
- Root `README.md` for usage with `Contentstack.stack`, `Entry`, `Query`.

0 commit comments

Comments
 (0)