@plasius/schema 1.0.8 → 1.0.9

package/CONTRIBUTING.md

@@ -0,0 +1,201 @@
+# Contributing to @plasius/schema
+
+First off: thanks for taking the time to contribute!
+This document explains how to work on the project, how to propose changes, and what we expect in pull requests.
+
+> TL;DR
+>
+> - Be respectful and follow the Code of Conduct.
+> - Open an issue before large changes; small fixes can go straight to a PR.
+> - Write tests, keep coverage steady or improving.
+> - Use Conventional Commits.
+> - Don’t include real PII in code, issues, tests, or logs.
+
+---
+
+## Code of Conduct
+
+Participation in this project is governed by our **Code of Conduct** (see `CODE_OF_CONDUCT.md`). By participating, you agree to abide by it.
+
+## Licensing & CLA
+
+This project is open source (see `LICENSE`). To protect contributors and users, we require contributors to agree to our **Contributor License Agreement (CLA)** before we can merge PRs (see `legal/CLA.md`). You’ll be prompted automatically by the CLA bot on your first PR.
+
+> If your company has special legal needs, please contact the maintainers before sending large PRs.
+
+## Security
+
+**Never** report security issues in public issues or PRs. Instead, follow the process in `SECURITY.md`.
+
+---
+
+## What this project does
+
+`@plasius/schema` provides a small, strongly-typed schema library:
+
+- A fluent field builder (e.g. `field().string().required()`),
+- Built-in validators for common standards (ISO/RFC/OWASP, etc.),
+- PII annotations + redaction utilities,
+- Type inference for safe, consistent entities across projects.
+
+Contributions typically fall into: new validators, field builder features, type improvements, docs, and tooling quality.
+
+---
+
+## Getting started (local dev)
+
+### Prerequisites
+
+- Node.js (use the version specified in `.nvmrc` if present: `nvm use`).
+- npm (we use npm scripts in this repo).
+
+### Install
+
+```bash
+npm ci
+```
+
+### Build
+
+```bash
+npm run build
+```
+
+### Test
+
+```bash
+npm test
+# or, if using Vitest in watch mode
+npm run test:watch
+```
+
+### Lint & format
+
+```bash
+npm run lint
+npm run format
+```
+
+> Tip: set up your editor to run ESLint and Prettier on save.
+
+---
+
+## How to propose a change
+
+### 1) For bugs
+
+- Search existing issues first.
+- Open a new issue with:
+  - Clear title, steps to reproduce, expected vs actual behaviour,
+  - Minimal repro (code snippet or small repo),
+  - Environment info (OS, Node, package version).
+
+### 2) For features / refactors
+
+- For anything non-trivial, open an issue first and outline the proposal.
+- If the change affects public API or architecture, add an ADR draft (see `docs/adrs/`).
+
+### 3) Good first issues
+
+We label approachable tasks as **good first issue** and **help wanted**.
+
+---
+
+## Branch, commit, PR
+
+**Branching**
+
+- Fork or create a feature branch from `main`: `feat/xyz` or `fix/abc`.
+
+**Commit messages** (Conventional Commits)
+
+- `feat: add ISO-3166 alpha-3 validator`
+- `fix: correct RFC5322 email regex edge-case`
+- `docs: expand PII redaction examples`
+- `refactor: simplify field builder pipeline`
+- `test: add cases for currency code`
+- `chore: bump dev deps`
+
+**Pull Requests**
+
+- Keep PRs focused and small when possible.
+- Include tests for new/changed behaviour.
+- Update docs (README, JSDoc, ADRs) as needed.
+- Add a clear description of what & why, with before/after examples if useful.
+- Ensure CI is green (lint, build, tests).
+
+**PR checklist**
+
+- [ ] Title uses Conventional Commits
+- [ ] Tests added/updated
+- [ ] Lint passes (`npm run lint`)
+- [ ] Build passes (`npm run build`)
+- [ ] Docs updated (README/ADR/CHANGELOG if needed)
+- [ ] No real PII in code, tests, or logs
+
+---
+
+## Coding standards
+
+- **Language:** TypeScript with `strict` types.
+- **Style:** ESLint + Prettier.
+- **Tests:** Prefer Vitest (or Jest) + `@testing-library/*` for React-facing bits.
+- **Public API:** Aim for backward compatibility; use SemVer and mark breaking changes clearly (`feat!:` or `fix!:`).
+- **Performance:** Avoid excessive allocations in hot paths; prefer immutable patterns but mind GC pressure.
+- **Docs:** Add TSDoc comments for exported types/functions.
+
+### Validators
+
+- Add tests covering common/edge cases.
+- Cite the source/standard (e.g., ISO/RFC) in comments.
+- Keep regexes readable (use `x`/comments where possible) and benchmark if complex.
+
+### PII handling
+
+- Never include real PII in fixtures or examples.
+- Ensure redaction/cleaning functions operate **before** logging.
+- Add tests confirming no PII leaks to logs or thrown errors.
+
+---
+
+## Adding dependencies
+
+- Minimise runtime dependencies; prefer dev dependencies.
+- Justify any new runtime dependency in the PR description (size, security, maintenance).
+- Avoid transitive heavy deps unless critical.
+
+---
+
+## Versioning & releases
+
+- We follow **SemVer**.
+- Breaking changes require a major bump and migration notes.
+- Keep the `CHANGELOG.md` (or release notes) clear about user-facing changes.
+
+---
+
+## Documentation
+
+- Update `README.md` with new features or setup steps.
+- Add or update ADRs in `docs/adrs/` for architectural decisions.
+- Keep examples minimal, copy-pasteable, and tested when feasible.
+
+---
+
+## Maintainers’ process (overview)
+
+- Triage new issues weekly; label and assign.
+- Review PRs for correctness, tests, and docs.
+- Squash-merge with Conventional Commit titles.
+- Publish from CI when applicable.
+
+---
+
+## Questions
+
+If you have questions or want feedback before building:
+
+- Open a discussion or issue with a short proposal,
+- Or draft a PR early (mark as **Draft**) to get directional feedback.
+
+Thanks again for contributing 💛

package/README.md

@@ -9,8 +9,6 @@
 
 Entity definition & validation helpers for the Plasius ecosystem.
 
-This package is part of the **Plasius LTD** selective open-source strategy. For more on our approach, see [ADR-0013: Selective Open Source](https://github.com/plasius/plasius/blob/main/docs/architecture/adr/ADR-0013-selective-open-source.md). This package is maintained as open source to foster community trust and enable integration, while the core Plasius platform remains proprietary.
-
 Apache-2.0. ESM + CJS builds. TypeScript types included.
 
 ---

package/docs/adrs/adr-0001: schema.md

@@ -0,0 +1,41 @@
+# ADR-0001: Schema Library Purpose and Scope
+
+## Status
+
+- Proposed → Accepted
+- Date: 2025-09-12
+- Version: 1.0
+- Supersedes: N/A
+- Superseded by: N/A
+
+## Context
+
+Managing consistent data structures across a distributed system is difficult. Without a central schema library, each service or package can diverge in how it defines and validates entities, leading to duplication, mismatches, and security gaps (especially around handling Personally Identifiable Information, or PII).
+
+We need a way to:
+
+- Define entities and fields in a consistent, strongly-typed way.
+- Provide validation functions for standard data types and codes (ISO, RFC, OWASP, etc).
+- Support annotation of PII fields so they can be masked or cleaned when logged or transmitted.
+- Offer a foundation that other Plasius packages (e.g. entity-types, state, renderer) can depend upon.
+
+## Decision
+
+We will build a **schema library** (`@plasius/schema`) that:
+
+- Provides a fluent builder API (`field().string().required()` etc.).
+- Exposes reusable validators for standards like ISO-3166 country codes, ISO-4217 currency codes, RFC 5322 emails, etc.
+- Implements utilities for PII handling (masking, redaction).
+- Exports TypeScript types that infer entity structures from schema definitions.
+- Is published as an open source package for transparency and reuse.
+
+## Consequences
+
+- **Positive:** Consistent validation, stronger typing, centralised handling of PII, reduced duplication across Plasius projects, easier onboarding of new developers.
+- **Negative:** Adds a dependency layer that all other packages must import, requiring careful versioning and backward compatibility management.
+- **Neutral:** External adopters may use the library without adopting the full Plasius ecosystem, which is acceptable and encouraged.
+
+## Alternatives Considered
+
+- **Do nothing:** Continue defining ad-hoc validation in each package. (Rejected: inconsistent and unsafe.)
+- **Use an existing library (e.g. Zod, Yup, Joi):** These provide schema validation but lack PII auditing integration and may not align with our field-builder pattern. (Rejected for core use, though we may draw inspiration.)

package/docs/adrs/adr-template.md

@@ -0,0 +1,65 @@
+# Architectural Decision Record (ADR)
+
+## Title
+
+> _Concise, descriptive title of the decision (e.g., “Use Azure Container Apps for n8n Deployment”)_
+
+---
+
+## Status
+
+- Proposed | Accepted | Rejected | Superseded | Deprecated
+- Date: YYYY-MM-DD
+- Version: 1.0
+- Supersedes: ADR-XXXX (if applicable)
+- Superseded by: ADR-YYYY (if applicable)
+
+---
+
+## Tags
+
+> _Short keywords to help search and group ADRs (e.g., infra, frontend, security, devops, ai, database)._
+
+---
+
+## Context
+
+> _Describe the problem we are solving, relevant background, and constraints.  
+> Why are we making this decision? What triggered it?_
+
+---
+
+## Decision
+
+> _What is the decision we have made? Clear, affirmative statement of the chosen path._
+
+---
+
+## Alternatives Considered
+
+- **Option A**: Description (pros/cons)
+- **Option B**: Description (pros/cons)
+- **Option C**: Description (pros/cons)
+
+> _Why were these alternatives not chosen?_
+
+---
+
+## Consequences
+
+- Positive outcomes (benefits, opportunities)
+- Negative outcomes (risks, trade-offs)
+- Any technical debt created or avoided
+- Impact on future decisions
+
+---
+
+## Related Decisions
+
+> _Link to related ADRs (if any)_
+
+---
+
+## References
+
+> _Links to docs, benchmarks, discussions, or external resources that influenced this decision_

package/legal/CORPORATE_CLA.md

@@ -33,6 +33,8 @@ This Agreement is effective upon signature by the authorized representative of t
 
 ---
 
+### **@plasius/schema**
+
 **Corporation Legal Name:** \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_
 
 **Authorized Representative:** \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_

package/legal/INDIVIDUAL_CLA.md

@@ -1,6 +1,6 @@
 # Individual Contributor License Agreement (CLA)
 
-**Project:** Intuitive Purchases (Plasius LTD)  
+**Project:** @plasius/schema (Plasius LTD)  
 **Version:** 1.0 — 2025‑09‑12  
 **Contact:** [contributors@plasius.co.uk](mailto:contributors@plasius.co.uk)
 
@@ -10,7 +10,7 @@
 
 - **"You"** (or **"Contributor"**) means the individual signing this CLA and submitting Contributions to the Project.
 - **"Contribution"** means any original work of authorship, including code, documentation, data, designs, or feedback that You submit to the Project in any form (e.g., pull request, issue comment, email, file upload).
-- **"Project"** means the Intuitive Purchases repositories and related materials owned or managed by **Plasius LTD**.
+- **"Project"** means the @plasius/schema repositories and related materials owned or managed by **Plasius LTD**.
 
 ## 2. Copyright License Grant
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plasius/schema",
-  "version": "1.0.8",
+  "version": "1.0.9",
   "description": "Entity schema definition & validation helpers for Plasius ecosystem",
   "type": "module",
   "main": "./dist/index.cjs",