@noego/stitch 1.0.0 → 1.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noego/stitch",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "",
   "license": "ISC",
   "author": "",

package/readme.md

@@ -2,6 +2,113 @@
 
 Stitch merges multiple YAML files into a single, validated artifact. It’s ideal for modular OpenAPI specs and other structured YAML, with CLI, Node, and browser support — plus VSCode schema integration for real‑time validation.
 
+> Note: OpenAPI is used throughout as a familiar example, but Stitch is schema‑agnostic and works with any YAML configuration.
+
+## Core Features
+
+- Deterministic ordering: Globs expand to files sorted alphabetically; the order in `stitch.yaml` decides precedence (later wins).
+- Deep merge for objects: Keys are joined recursively; later files override earlier values for the same key.
+- Arrays replace, not concatenate: When a key maps to an array, the array from the later file fully replaces the earlier one.
+- Flexible validation: Lightweight OpenAPI shape checks or full JSON Schema validation via AJV.
+- Multi-environment: Same engine for CLI/Node, plus browser helpers for Vite.
+- Watch + output: Rebuild on changes; write YAML/JSON to file with a generated-file header.
+
+### How merging works (keys and arrays)
+
+Given two files merged in order: `base.yaml`, then `override.yaml`.
+
+Objects (keys are joined, later overrides):
+
+```yaml
+# base.yaml
+info:
+  title: My API
+  version: 1.0.0
+  contact:
+    name: Team A
+
+# override.yaml
+info:
+  version: 1.1.0
+  contact:
+    email: team@example.com
+```
+
+Result:
+
+```yaml
+info:
+  title: My API          # from base
+  version: 1.1.0         # overridden by override
+  contact:
+    name: Team A         # preserved from base
+    email: team@example.com
+```
+
+Arrays (later replaces earlier, no concat):
+
+```yaml
+# base.yaml
+servers:
+  - url: https://api.example.com
+  - url: https://staging.example.com
+
+# override.yaml
+servers:
+  - url: http://localhost:3000
+```
+
+Result:
+
+```yaml
+servers:
+  - url: http://localhost:3000
+```
+
+Primitives (later replaces earlier):
+
+```yaml
+# base.yaml
+openapi: 3.0.3
+
+# override.yaml
+openapi: 3.1.0
+```
+
+Result: `openapi: 3.1.0`
+
+### Works With Any YAML
+
+- Schema‑agnostic: Stitch performs generic YAML deep merges; it is not tied to OpenAPI.
+- Validation choices: For non‑OpenAPI configs, either skip `--validate` or provide your own JSON Schema path.
+
+## Config File (stitch.yaml)
+
+Stitch expects a YAML config whose top-level key is `stitch`, an array of file paths and/or glob patterns. Paths are resolved relative to the config file’s directory. Files are merged in the order listed; glob matches are sorted alphabetically.
+
+Minimal example:
+
+```yaml
+# stitch.yaml
+stitch:
+  - openapi/base.yaml
+  - openapi/components/**/*.yaml
+  - openapi/paths/**/*.yaml
+  - overrides/*.yaml
+```
+
+Notes
+- Required key: `stitch` must be an array.
+- Relative base: paths/globs are resolved relative to the config file location.
+- Ordering: list order decides precedence; later files override earlier ones.
+- Globs: `*`, `**`, `?`, and character classes are supported.
+- JSON is fine too: JSON is a subset of YAML, so a `.json` config with the same shape works.
+- OpenAPI is just an example here: use any YAML file layout and names for your domain.
+
+Using a different config file
+- CLI: pass the config file as a positional argument, e.g. `stitch build my-config.yaml` or `stitch watch my-config.yaml`.
+- Programmatic: `stitch.build({ input: 'my-config.yaml', ... })` or `engine.build('my-config.yaml', ...)`.
+
 ## Why Stitch
 
 - Modularize YAML: Keep specs split across files and folders without losing clarity.
@@ -102,8 +209,8 @@ const result = stitchFromContent([
 
 ## Validation
 
-- Basic: `--validate` enables lightweight OpenAPI shape checks (`openapi`, `info`).
-- JSON Schema: `--validate schemas/schema.json` enables full AJV validation against your schema.
+- Basic: `--validate` enables lightweight OpenAPI shape checks (`openapi`, `info`). If your content is not OpenAPI, skip this flag.
+- JSON Schema: `--validate schemas/schema.json` enables full AJV validation against your schema (works for any YAML domain).
 
 ## VSCode Integration
 
@@ -124,9 +231,7 @@ Manual configuration example (`.vscode/settings.json`):
 }
 ```
 
-Alternative paths
-- "@noego/forge/schema.json" – Package export (if supported by VSCode)
-- "node_modules/@noego/forge/schema.json" – Direct node_modules path (most reliable)
+
 
 ## Example Project Structure
 
@@ -156,4 +261,3 @@ stitch install @noego/dinner/schema.json --target "**/*.yaml"
 ## License
 
 MIT
-