Merge pull request #89 from muonsoft/cursor/-bc-f3bb1229-b862-4389-b59b-67a226f7ded1-f668

strider2038 · web-flow · commit f9a0063d9e52 · 2026-04-04T13:16:41.000+03:00
Add ISIN validation constraint
diff --git a/.cursor/skills/validation-add-constraint/SKILL.md b/.cursor/skills/validation-add-constraint/SKILL.md
@@ -230,6 +230,7 @@ Add when useful for **standalone boolean checks** (e.g. in conditions, or for `O
 - [ ] `it/*.go`: constraint (StringFuncConstraint or custom struct), godoc, empty/nil handling, BuildViolation
 - [ ] `test/constraints_*_cases_test.go`: test cases + merge into `validateTestCases`
 - [ ] `it/example_test.go`: ExampleXxx_valid, ExampleXxx_invalid with `// Output:`
+- [ ] `CHANGELOG.md`: under `[Unreleased]` → `Added` (or other fitting section), user-facing bullet for the new API
 - [ ] Optional: `validate`: function, tests, examples, godoc
 - [ ] Optional: `is`: function, tests, examples, godoc
 - [ ] `go test ./...` and `golangci-lint run`
diff --git a/AGENTS.md b/AGENTS.md
@@ -182,9 +182,25 @@ func (c NumericConstraint) ValidateString(ctx context.Context, validator *valida
 4. Update documentation if adding public APIs
 5. Add examples for new features
 6. Ensure all tests pass in CI
+7. Update **CHANGELOG.md** when the change is user-visible (see [Changelog](#changelog) below)
+
+## Changelog
+
+The project uses **[Keep a Changelog](https://keepachangelog.com/)** in **`CHANGELOG.md`**.
+
+### Rules for agents and contributors
+
+1. **Always edit `CHANGELOG.md`** in the same branch/PR when your work would matter to library users: new or changed public API, new constraints, message or translation changes, behavior changes, deprecations, removals, security fixes, or notable bug fixes.
+2. **Use the `[Unreleased]` section** at the top. Maintainers move entries under a version heading and date when they cut a release.
+3. **Pick the right subsection**: `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, `Security`. Use `Breaking` only for incompatible changes (or describe breaking impact under `Changed` if you prefer a single list).
+4. **Write for consumers**: short, imperative bullets; mention package or symbol names (`it.IsXxx`, `validate.Xxx`, `validation.ErrXxx`) when helpful. Linking to PRs/issues is optional.
+5. **Do not rewrite published versions**: never change the bullet list under a released version tag except to fix obvious typos or incorrect facts.
+6. **Skip the changelog** only for internal-only changes (refactors, tests, CI, comments) with no user-visible effect.
+7. **Release links**: when adding a new version section, update the comparison links at the bottom of the file (`[Unreleased]: ...compare/vX.Y.Z...HEAD` and `[X.Y.Z]: ...releases/tag/vX.Y.Z`).
 
 ## Resources
 
+- **CHANGELOG.md** - Release history for users and upgraders
 - **README.md** - User-facing documentation
 - **CONTRIBUTING.md** - Contribution guidelines
 - **CODE_OF_CONDUCT.md** - Community standards
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,6 +1,17 @@
-# Release Notes
+# Changelog
 
-## v0.19.0
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- ISIN (International Securities Identification Number) validation: `it.IsISIN()`, `validate.ISIN`, `is.ISIN`, with `validation.ErrInvalidISIN` / `message.InvalidISIN` and English and Russian translations (behavior aligned with Symfony `Isin`).
+
+## [0.19.0] - 2026-02-09
 
 ### Added
 
@@ -15,10 +26,13 @@
 - **Documentation**: README restructured with installation, custom constraints, and property paths; expanded custom constraints guide with interface details and examples.
 - **Skill docs**: SKILLS.md removed; new reference and skill documentation for adding validation constraints.
 
+### Breaking
+
+- Tests using `CheckNoViolations` or validator setup need to be updated to the new signatures and helpers.
+
 ### Fixed
 
 - Correct handling of single violations returned from validatable objects in `validateIt`.
 
-### Breaking Changes
-
-- Tests using `CheckNoViolations` or validator setup need to be updated to the new signatures and helpers.
+[Unreleased]: https://github.com/muonsoft/validation/compare/v0.19.0...HEAD
+[0.19.0]: https://github.com/muonsoft/validation/releases/tag/v0.19.0
diff --git a/errors.go b/errors.go
@@ -15,6 +15,7 @@ var (
 	ErrInvalidEAN8       = NewError("invalid EAN-8", message.InvalidEAN8)
 	ErrInvalidEmail      = NewError("invalid email", message.InvalidEmail)
 	ErrInvalidHostname   = NewError("invalid hostname", message.InvalidHostname)
+	ErrInvalidISIN       = NewError("invalid ISIN", message.InvalidISIN)
 	ErrInvalidIP         = NewError("invalid IP address", message.InvalidIP)
 	ErrInvalidJSON       = NewError("invalid JSON", message.InvalidJSON)
 	ErrInvalidTime       = NewError("invalid time", message.InvalidTime)
diff --git a/is/example_test.go b/is/example_test.go
@@ -253,6 +253,18 @@ func ExampleULID() {
 	// false
 }
 
+func ExampleISIN() {
+	fmt.Println(is.ISIN("US0378331005"))
+	fmt.Println(is.ISIN("US037833100"))
+	fmt.Println(is.ISIN("123456789101"))
+	fmt.Println(is.ISIN("XS2012239364"))
+	// Output:
+	// true
+	// false
+	// false
+	// false
+}
+
 func ExampleUUID() {
 	fmt.Println(is.UUID("83eab6fd-230b-44fe-b52f-463387bd8788"))                                      // v4
 	fmt.Println(is.UUID("83eab6fd-230b-44fe-b52f-463387bd8788", validate.AllowUUIDVersions(4)))       // v4
diff --git a/is/identifiers.go b/is/identifiers.go
@@ -8,6 +8,14 @@ func ULID(value string) bool {
 	return validate.ULID(value) == nil
 }
 
+// ISIN validates whether the value is a valid International Securities Identification Number (ISIN).
+// See [github.com/muonsoft/validation/validate.ISIN] for validation rules and possible errors.
+//
+// See https://en.wikipedia.org/wiki/International_Securities_Identification_Number.
+func ISIN(value string) bool {
+	return validate.ISIN(value) == nil
+}
+
 // UUID validates whether a string value is a valid UUID (also known as GUID).
 //
 // By default, it uses strict mode and checks the UUID as specified in RFC 4122.
diff --git a/it/example_test.go b/it/example_test.go
@@ -41,6 +41,20 @@ func ExampleIsUPCE() {
 	// violation: "This value is not a valid UPC-E."
 }
 
+func ExampleIsISIN_valid() {
+	err := validator.Validate(context.Background(), validation.String("US0378331005", it.IsISIN()))
+	fmt.Println(err)
+	// Output:
+	// <nil>
+}
+
+func ExampleIsISIN_invalid() {
+	err := validator.Validate(context.Background(), validation.String("XS2012239364", it.IsISIN()))
+	fmt.Println(err)
+	// Output:
+	// violation: "This value is not a valid International Securities Identification Number (ISIN)."
+}
+
 func ExampleIsNotBlank() {
 	fmt.Println(validator.Validate(context.Background(), validation.String("", it.IsNotBlank())))
 	fmt.Println(validator.Validate(context.Background(), validation.Countable(len([]string{}), it.IsNotBlank())))
diff --git a/it/identifiers.go b/it/identifiers.go
@@ -16,6 +16,14 @@ func IsULID() validation.StringFuncConstraint {
 		WithMessage(validation.ErrInvalidULID.Message())
 }
 
+// IsISIN validates whether the value is a valid International Securities Identification Number (ISIN).
+// See https://en.wikipedia.org/wiki/International_Securities_Identification_Number.
+func IsISIN() validation.StringFuncConstraint {
+	return validation.OfStringBy(is.ISIN).
+		WithError(validation.ErrInvalidISIN).
+		WithMessage(validation.ErrInvalidISIN.Message())
+}
+
 // UUIDConstraint validates whether a string value is a valid UUID (also known as GUID).
 //
 // By default, it uses strict mode and checks the UUID as specified in RFC 4122.
diff --git a/message/messages.go b/message/messages.go
@@ -33,6 +33,7 @@ const (
 	InvalidEAN8       = "This value is not a valid EAN-8."
 	InvalidEmail      = "This value is not a valid email address."
 	InvalidHostname   = "This value is not a valid hostname."
+	InvalidISIN       = "This value is not a valid International Securities Identification Number (ISIN)."
 	InvalidIP         = "This is not a valid IP address."
 	InvalidJSON       = "This value should be valid JSON."
 	InvalidTime       = "This value is not a valid time."
diff --git a/message/translations/english/messages.go b/message/translations/english/messages.go
@@ -54,6 +54,7 @@ var Messages = map[language.Tag]map[string]catalog.Message{
 		message.InvalidEAN8:     catalog.String(message.InvalidEAN8),
 		message.InvalidEmail:    catalog.String(message.InvalidEmail),
 		message.InvalidHostname: catalog.String(message.InvalidHostname),
+		message.InvalidISIN:     catalog.String(message.InvalidISIN),
 		message.InvalidIP:       catalog.String(message.InvalidIP),
 		message.InvalidJSON:     catalog.String(message.InvalidJSON),
 		message.InvalidTime:     catalog.String(message.InvalidTime),
diff --git a/message/translations/russian/messages.go b/message/translations/russian/messages.go
@@ -57,6 +57,7 @@ var Messages = map[language.Tag]map[string]catalog.Message{
 		message.InvalidEAN8:     catalog.String("Значение не является допустимым EAN-8."),
 		message.InvalidEmail:    catalog.String("Значение адреса электронной почты недопустимо."),
 		message.InvalidHostname: catalog.String("Значение не является корректным именем хоста."),
+		message.InvalidISIN:     catalog.String("Значение не является допустимым международным идентификационным номером ценной бумаги (ISIN)."),
 		message.InvalidIP:       catalog.String("Значение не является допустимым IP адресом."),
 		message.InvalidJSON:     catalog.String("Значение должно быть корректным JSON."),
 		message.InvalidTime:     catalog.String("Значение времени недопустимо."),
diff --git a/test/constraints_identifiers_cases_test.go b/test/constraints_identifiers_cases_test.go
@@ -9,6 +9,7 @@ import (
 var identifierConstraintsTestCases = mergeTestCases(
 	ulidConstraintTestCases,
 	uuidConstraintTestCases,
+	isinConstraintTestCases,
 )
 
 var ulidConstraintTestCases = []ConstraintValidationTestCase{
@@ -28,6 +29,84 @@ var ulidConstraintTestCases = []ConstraintValidationTestCase{
 	},
 }
 
+var isinConstraintTestCases = []ConstraintValidationTestCase{
+	{
+		name:            "IsISIN passes on empty value",
+		isApplicableFor: specificValueTypes(stringType),
+		constraint:      it.IsISIN(),
+		stringValue:     stringValue(""),
+		assert:          assertNoError,
+	},
+	{
+		name:            "IsISIN passes on valid value",
+		isApplicableFor: specificValueTypes(stringType),
+		stringValue:     stringValue("US0378331005"),
+		constraint:      it.IsISIN(),
+		assert:          assertNoError,
+	},
+	{
+		name:            "IsISIN passes on lowercase letters",
+		isApplicableFor: specificValueTypes(stringType),
+		stringValue:     stringValue("us0378331005"),
+		constraint:      it.IsISIN(),
+		assert:          assertNoError,
+	},
+	{
+		name:            "IsISIN violation on wrong length",
+		isApplicableFor: specificValueTypes(stringType),
+		stringValue:     stringValue("US037833100"),
+		constraint:      it.IsISIN(),
+		assert:          assertHasOneViolation(validation.ErrInvalidISIN, message.InvalidISIN),
+	},
+	{
+		name:            "IsISIN violation on invalid pattern",
+		isApplicableFor: specificValueTypes(stringType),
+		stringValue:     stringValue("123456789101"),
+		constraint:      it.IsISIN(),
+		assert:          assertHasOneViolation(validation.ErrInvalidISIN, message.InvalidISIN),
+	},
+	{
+		name:            "IsISIN violation on invalid checksum",
+		isApplicableFor: specificValueTypes(stringType),
+		stringValue:     stringValue("XS2012239364"),
+		constraint:      it.IsISIN(),
+		assert:          assertHasOneViolation(validation.ErrInvalidISIN, message.InvalidISIN),
+	},
+	{
+		name:            "IsISIN violation with given error and message",
+		isApplicableFor: specificValueTypes(stringType),
+		constraint: it.IsISIN().
+			WithError(ErrCustom).
+			WithMessage(
+				`Invalid value "{{ value }}" for {{ custom }}.`,
+				validation.TemplateParameter{Key: "{{ custom }}", Value: "parameter"},
+			),
+		stringValue: stringValue("invalid-isin"),
+		assert:      assertHasOneViolation(ErrCustom, `Invalid value "invalid-isin" for parameter.`),
+	},
+	{
+		name:            "IsISIN passes when condition is false",
+		isApplicableFor: specificValueTypes(stringType),
+		constraint:      it.IsISIN().When(false),
+		stringValue:     stringValue("bad"),
+		assert:          assertNoError,
+	},
+	{
+		name:            "IsISIN violation when condition is true",
+		isApplicableFor: specificValueTypes(stringType),
+		constraint:      it.IsISIN().When(true),
+		stringValue:     stringValue("bad"),
+		assert:          assertHasOneViolation(validation.ErrInvalidISIN, message.InvalidISIN),
+	},
+	{
+		name:            "IsISIN passes when groups not match",
+		isApplicableFor: specificValueTypes(stringType),
+		constraint:      it.IsISIN().WhenGroups(testGroup),
+		stringValue:     stringValue("bad"),
+		assert:          assertNoError,
+	},
+}
+
 var uuidConstraintTestCases = []ConstraintValidationTestCase{
 	{
 		name:            "IsUUID passes on nil",
diff --git a/validate/example_test.go b/validate/example_test.go
@@ -150,6 +150,18 @@ func ExampleULID() {
 	// too large
 }
 
+func ExampleISIN() {
+	fmt.Println(validate.ISIN("US0378331005"))
+	fmt.Println(validate.ISIN("US037833100"))
+	fmt.Println(validate.ISIN("123456789101"))
+	fmt.Println(validate.ISIN("XS2012239364"))
+	// Output:
+	// <nil>
+	// too short
+	// invalid characters
+	// invalid checksum
+}
+
 func ExampleUUID() {
 	fmt.Println(validate.UUID("83eab6fd-230b-44fe-b52f-463387bd8788"))                                      // v4
 	fmt.Println(validate.UUID("83eab6fd-230b-44fe-b52f-463387bd8788", validate.AllowUUIDVersions(4)))       // v4
diff --git a/validate/identifiers.go b/validate/identifiers.go
@@ -2,6 +2,9 @@ package validate
 
 import (
 	"errors"
+	"regexp"
+	"strconv"
+	"strings"
 
 	"github.com/muonsoft/validation/internal/uuid"
 )
@@ -18,6 +21,9 @@ var (
 
 var ulidChars = newCharSet("0123456789ABCDEFGHJKMNPQRSTVWXYZabcdefghjkmnpqrstvwxyz")
 
+// Same pattern as Symfony Isin::VALIDATION_PATTERN (length is checked separately).
+var isinPattern = regexp.MustCompile(`^[A-Z]{2}[A-Z0-9]{9}[0-9]$`)
+
 // ULID validates whether the value is a valid ULID (Universally Unique Lexicographically Sortable Identifier).
 // See https://github.com/ulid/spec for ULID specifications.
 //
@@ -49,6 +55,87 @@ func ULID(value string) error {
 	return nil
 }
 
+// ISIN validates whether the value is a valid International Securities Identification Number (ISIN).
+// Letters are treated case-insensitively (normalized to upper case for validation), matching
+// Symfony\Component\Validator\Constraints\Isin.
+//
+// Possible errors:
+//   - [ErrTooShort] on values with length less than 12;
+//   - [ErrTooLong] on values with length greater than 12;
+//   - [ErrInvalidCharacters] on values that do not match the ISIN pattern;
+//   - [ErrInvalidChecksum] when the check digit is wrong;
+//
+// See https://en.wikipedia.org/wiki/International_Securities_Identification_Number.
+func ISIN(value string) error {
+	if len(value) < 12 {
+		return ErrTooShort
+	}
+	if len(value) > 12 {
+		return ErrTooLong
+	}
+
+	s := strings.ToUpper(value)
+	if !isinPattern.MatchString(s) {
+		return ErrInvalidCharacters
+	}
+	if !isinLuhn(s) {
+		return ErrInvalidChecksum
+	}
+
+	return nil
+}
+
+func isinCharValue(c byte) int {
+	switch {
+	case c >= '0' && c <= '9':
+		return int(c - '0')
+	case c >= 'A' && c <= 'Z':
+		return int(c - 'A' + 10)
+	default:
+		return -1
+	}
+}
+
+func isinLuhn(s string) bool {
+	var b strings.Builder
+	b.Grow(24)
+	for i := 0; i < 12; i++ {
+		v := isinCharValue(s[i])
+		if v < 0 {
+			return false
+		}
+		b.WriteString(strconv.Itoa(v))
+	}
+
+	return luhnValidDigits(b.String())
+}
+
+// luhnValidDigits implements the same checksum as Symfony's LuhnValidator for a decimal string.
+func luhnValidDigits(digits string) bool {
+	if len(digits) == 0 {
+		return false
+	}
+	for i := 0; i < len(digits); i++ {
+		if digits[i] < '0' || digits[i] > '9' {
+			return false
+		}
+	}
+
+	checkSum := 0
+	length := len(digits)
+	for i := length - 1; i >= 0; i-- {
+		d := int(digits[i] - '0')
+		if (i%2)^(length%2) != 0 {
+			checkSum += d
+		} else {
+			doubled := d * 2
+			checkSum += doubled/10 + doubled%10
+		}
+	}
+
+	return checkSum != 0 && checkSum%10 == 0
+}
+
 // UUID validates whether a string value is a valid UUID (also known as GUID).
 //
 // By default, it uses strict mode and checks the UUID as specified in RFC 4122.
diff --git a/validate/identifiers_test.go b/validate/identifiers_test.go
