penpot/common/AGENTS.md

Penpot Common – Agent Instructions

A shared module with code written in Clojure, ClojureScript, and JavaScript. Contains multiplatform code that can be used and executed from the frontend, backend, or exporter modules. It uses Clojure reader conditionals to specify platform-specific implementations.

General Guidelines

To ensure consistency across the Penpot stack, all contributions must adhere to these criteria:

1. Testing & Validation

If code is added or modified in src/, corresponding tests in test/common_tests/ must be added or updated.

• Environment: Tests should run in both JS (Node.js) and JVM environments.
• Location: Place tests in the test/common_tests/ directory, following the namespace structure of the source code (e.g., app.common.colors -> common-tests.colors-test).
• Execution: Tests should be executed on both JS (Node.js) and JVM environments:
  • Isolated:
    • JS: To run a focused ClojureScript unit test: edit the test/common_tests/runner.cljs to narrow the test suite, then pnpm run test:js.
    • JVM: pnpm run test:jvm --focus common-tests.my-ns-test
  • Regression:
    • JS: Run pnpm run test:js without modifications on the runner (preferred)
    • JVM: Run pnpm run test:jvm

2. Code Quality & Formatting

• Linting: All code changes must pass linter checks:
  • Run pnpm run lint:clj for CLJ/CLJS/CLJC
• Formatting: All code changes must pass the formatting check
  • Run pnpm run check-fmt:clj for CLJ/CLJS/CLJC
  • Run pnpm run check-fmt:js for JS
  • Use pnpm run fmt to fix all formatting issues (pnpm run fmt:clj or pnpm run fmt:js for isolated formatting fix).

Code Conventions

Namespace Overview

The source is located under src directory and this is a general overview of namespaces structure:

• app.common.types.* – Shared data types for shapes, files, pages using Malli schemas
• app.common.schema – Malli abstraction layer, exposes the most used functions from malli
• app.common.geom.* – Geometry and shape transformation helpers
• app.common.data – Generic helpers used across the entire application
• app.common.math – Generic math helpers used across the entire application
• app.common.json – Generic JSON encoding/decoding helpers
• app.common.data.macros – Performance macros used everywhere

Reader Conditionals

We use reader conditionals to differentiate implementations depending on the target platform where the code runs:

#?(:clj  (import java.util.UUID)
   :cljs (:require [cljs.core :as core]))

Both frontend and backend depend on common as a local library (penpot/common {:local/root "../common"}).