syntropylog 0.12.1 → 0.12.3

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.12.3
+
+### Patch Changes
+
+- **SECURITY.md:** Document supply-chain alerts that may appear on the **yaml** package: (1) **URLs** — documentation links only (caniuse, MDN), no runtime network requests; (2) **Behavioral (medium)** — stringify/serialization analysis, vendor states no malicious activity. Clarifies that SyntropyLog uses only `parse` with schema `json`.
+
+## 0.12.2
+
+### Patch Changes
+
+- **Socket / security:** Addressed Socket.dev alerts and clarified behavior in docs. Native addon no longer uses shell (`execSync`): resolves `ldd` path via `PATH` and `fs.existsSync` only. Documented filesystem access (native loader + `loadLoggerConfig`), environment variables (only `PATH` in optional native addon), dynamic require (static paths only), and URL/network (no runtime URLs). SECURITY.md now lists the single env var read (`PATH`) and README Security & Compliance section covers network, env, dynamic require, and filesystem.
+
+  **Docs - Universal Adapter:** README section 3 reworked: mapping is defined once with `UniversalLogFormatter` (outside the executor); executor receives the mapped object and can send it to multiple backends (e.g. Prisma, TypeORM, Mongoose) in one block. Single example shows one mapping → one object → three destinations with `Promise.all`.
+
+- **YAML / supply chain:** Replaced **js-yaml** with **yaml** (eemeli/yaml). The new dependency has no external packages (no argparse), removing the transitive alerts for URLs, filesystem, and env vars that came from js-yaml’s CLI helper. `loadLoggerConfig` now uses `parse(..., { schema: 'json' })` for safe parsing.
+
 ## 0.12.0
 
 First release after 0.11.3. Includes all framework refinements validated end-to-end with the examples repo (0.11.4 was never published to npm).
@@ -151,7 +167,7 @@ _Nothing at the moment._
 
 ### Security
 
-- **loadLoggerConfig**: Use js-yaml's `JSON_SCHEMA` when parsing YAML files to avoid prototype pollution and dangerous types. Use only with configuration files under deployment team control.
+- **loadLoggerConfig**: Use the **yaml** package (eemeli/yaml) with schema `json` when parsing YAML files to avoid prototype pollution and dangerous types; **yaml** has no external dependencies (no argparse). Use only with configuration files under deployment team control.
 
 ### Fixed
 

package/CONTRIBUTING.md

@@ -88,27 +88,47 @@ We welcome code contributions! To contribute code, please follow these steps:
 
 ## Release process (maintainers)
 
-Guía detallada: [docs/PREPARAR_PUBLICACION.md](docs/PREPARAR_PUBLICACION.md).
+Detailed guide: [docs/PREPARAR_PUBLICACION.md](docs/PREPARAR_PUBLICACION.md) (Spanish).
 
-**Ramas auxiliares (feature, develop, etc.):** en cada push y en los PRs se ejecuta solo el workflow **CI** (lint, build, tests, benchmark con addon nativo). No se publica nada en npm. Así puedes validar que todo pase antes de integrar a `main`.
+**Feature and develop branches:** On every push and on PRs, only the **CI** workflow runs (lint, build, tests, benchmark with native addon). Nothing is published to npm. This lets you validate everything before merging into `main`.
 
-**Solo al hacer push a `main`** se ejecuta el workflow **Release** (build del addon en todas las plataformas y, si hay changesets, versionado/publicación en npm).
+**Only when pushing to `main`** does the **Release** workflow run (build the addon on all platforms and, if there are changesets, versioning/publishing to npm).
 
-Releases use [Changesets](https://github.com/changesets/changesets) and GitHub Actions. **Para que la versión suba en npm, siempre tienes que hacer una de estas dos cosas:**
+Releases use [Changesets](https://github.com/changesets/changesets) and GitHub Actions. **To have a new version published to npm, you must do one of the following:**
 
-### Opción A: Usar el PR que crea el action
+### Option A: Use the PR created by the action
 
-1. **Añade un changeset** al cambiar la librería: `pnpm changeset` (elige tipo de versión y describe el cambio).
-2. **Push a `main`**. El workflow crea un PR **"Version Packages"** con el bump (ej. 0.9.12 → 0.9.13) y el CHANGELOG actualizado. **Todavía no publica en npm.**
-3. **Mergea ese PR** en `main`. Ese merge vuelve a disparar el workflow y **ahí sí** se ejecuta `publish` y la nueva versión aparece en npm.
+1. **Add a changeset** when changing the library: `pnpm changeset` (choose version bump type and describe the change).
+2. **Push to `main`**. The workflow creates a **"Version Packages"** PR with the version bump (e.g. 0.9.12 → 0.9.13) and updated CHANGELOG. **Nothing is published to npm yet.**
+3. **Merge that PR** into `main`. That merge triggers the workflow again and **then** `publish` runs and the new version appears on npm.
 
-### Opción B: Subir la versión a mano (sin PR)
+### Option B: Bump the version manually (no PR)
 
-1. Con changesets ya en el repo, en local: `pnpm run version-packages`. Eso actualiza `package.json`, CHANGELOG y borra los changesets.
-2. **Commit** (package.json, CHANGELOG.md, y los .changeset/*.md borrados) y **push a `main`**.
-3. El workflow corre, no hay changesets que aplicar, y ejecuta **publish** → la versión sube a npm.
+1. With changesets already in the repo, run locally: `pnpm run version-packages`. This updates `package.json`, CHANGELOG, and removes the consumed changesets.
+2. **Commit** (package.json, CHANGELOG.md, and the removed .changeset/*.md files) and **push to `main`**.
+3. The workflow runs, there are no changesets to apply, and it runs **publish** → the new version is published to npm.
 
-En ambos casos, **main** y **npm** quedan con la misma versión.
+In both cases, **main** and **npm** end up with the same version.
+
+## Repository size and what not to commit
+
+The repo should stay small so clones are fast. The following are in `.gitignore` and **must not** be committed:
+
+- `node_modules/`, `dist/`, `coverage/`
+- `assets/` (images; the README uses an external logo URL)
+- `docs/`, `.cursor/`, `.turbo`
+
+**If `assets/` or `coverage/` are already tracked**, remove them from Git (files stay on disk, only tracking is removed). Check first with `git ls-files assets/ coverage/`; if that lists files, run:
+
+```bash
+git rm -r --cached assets/
+git rm -r --cached coverage/
+git commit -m "chore: stop tracking assets and coverage"
+```
+
+If the path is not tracked, `git rm --cached` will report "did not match any file(s)" — that’s expected; nothing to do.
+
+The clone size (~36 MB) is mostly **Git history** (old copies of heavy files). To reduce it you would need to rewrite history (e.g. `git filter-repo` or BFG to remove `assets/` from the past). That changes commit hashes and requires a force-push; only do it if the team agrees.
 
 ## Getting Help
 

package/README.md

@@ -160,33 +160,86 @@ await syntropyLog.init({
 
 ## 3. Universal Adapter — log to any backend
 
-**What:** Send each log to PostgreSQL, MongoDB, Elasticsearch, S3, etc. by implementing a single `executor`. No vendor lock-in; you receive one structured object per log (already masked).
+**What:** Send each log to PostgreSQL, MongoDB, Elasticsearch, S3, etc. by implementing a single `executor`. No vendor lock-in. You define **once** how the log entry maps to your schema; the executor only receives that mapped object and persists it (ORM, raw client, HTTP). If `executor` throws, SyntropyLog logs the error and continues (Silent Observer).
 
-**How:** Use `AdapterTransport` + `UniversalAdapter`:
+**How:** Use `AdapterTransport` + `UniversalAdapter` + `UniversalLogFormatter`. Three steps:
+
+---
+
+### 1. Define the mapping (outside the executor)
+
+Define how each log entry field maps to your persistence shape. One place, no repetition in code. Use `UniversalLogFormatter` with a `mapping` object: keys = your schema (e.g. DB columns), values = path in the log entry.
+
+| Log entry path | Meaning |
+|----------------|--------|
+| `level` | Log level |
+| `message` | Message string |
+| `serviceName` | From init config |
+| `correlationId` | From context |
+| `timestamp` | ISO string |
+| `meta` | Merged metadata (use as payload/JSON column) |
+
+Example: map to a table with columns `level`, `message`, `serviceName`, `correlationId`, `payload`, `timestamp`.
+
+```typescript
+import { UniversalLogFormatter } from 'syntropylog';
+
+const logToDbMapping = {
+  level:         'level',
+  message:       'message',
+  serviceName:   'serviceName',
+  correlationId: 'correlationId',
+  payload:       'meta',
+  timestamp:     'timestamp',
+};
+
+const formatter = new UniversalLogFormatter({ mapping: logToDbMapping });
+```
+
+The formatter turns every log entry into an object with exactly those keys. Change the mapping here when your schema changes; the executor stays the same.
+
+---
+
+### 2. The object the executor receives
+
+When you attach this formatter to the transport, the `executor` receives **that mapped object** (not the raw log entry). So the executor only sees something like `{ level, message, serviceName, correlationId, payload, timestamp }`. Your only job in the executor is to **persist** that object.
+
+---
+
+### 3. Sending that object to your backend
+
+One mapping produces one object shape. You can send **that same object** to as many backends as you want in a single executor: same `data`, different destinations (e.g. Prisma, TypeORM, Mongoose, Elasticsearch, S3). No field list — the shape comes from the mapping.
+
+**Example: one mapped object → three destinations**
 
 ```typescript
 import { AdapterTransport, UniversalAdapter } from 'syntropylog';
+import { prisma } from './prisma';
+import { getRepository } from 'typeorm';
+import { SystemLog as TypeOrmSystemLog } from './entities/SystemLog';
+import { SystemLogModel } from './models/SystemLog';
 
 const dbTransport = new AdapterTransport({
   name: 'db',
+  formatter,
   adapter: new UniversalAdapter({
-    executor: async (logEntry) => {
-      await prisma.systemLog.create({
-        data: {
-          level:         logEntry.level,
-          message:       logEntry.message,
-          serviceName:   logEntry.serviceName,
-          correlationId: logEntry.correlationId,
-          payload:       logEntry.meta,
-          timestamp:     new Date(logEntry.timestamp),
-        },
-      });
+    executor: async (data) => {
+      const row = {
+        ...data,
+        timestamp: new Date(data.timestamp as string),
+      };
+      // Same object, three destinations (e.g. Postgres + TypeORM DB + MongoDB)
+      await Promise.all([
+        prisma.systemLog.create({ data: row }),
+        getRepository(TypeOrmSystemLog).save(row),
+        SystemLogModel.create(row),
+      ]);
     },
   }),
 });
 ```
 
-`logEntry` has: `level`, `message`, `serviceName`, `correlationId`, `timestamp`, `meta`. If `executor` throws, SyntropyLog logs the error and continues (Silent Observer).
+Use one transport and one executor; add or remove destinations in that same block. Use this transport in your `init()` (e.g. in `logger.transports` or `logger.transportList` + `logger.env`).
 
 ---
 
@@ -569,6 +622,17 @@ Secure this route (e.g. auth, internal only). When debugging in a POD is finishe
 
 ## Security & Compliance
 
+**Network & URLs:** This package does not contact any external URLs or IPs at runtime. The only network I/O is what you configure (e.g. your `executor` sending logs to your PostgreSQL, Elasticsearch, or API). URLs in this README and in `package.json` are documentation and metadata only (badges, repository links); they are not used for outbound connections.
+
+**Environment variables:** The main package does not read any. The optional native addon (`syntropylog-native`) reads only `PATH` on Linux to locate the `ldd` binary for musl/glibc detection. No credentials or other env vars are read. See [SECURITY.md](./SECURITY.md) for the full list.
+
+**Dynamic require:** The package does not use dynamic `require(variable)` or user-controlled paths. Module paths are static string literals (e.g. `require('syntropylog-native')`, `require('./index.js')`). The native addon loader chooses one of several fixed `.node` paths based on platform/arch; no user input is used to build require paths.
+
+**Filesystem access:** The package only reads the files described below; it does not scan or read arbitrary paths.
+
+- **Native addon loader** (`syntropylog-native`): Reads only (1) the presence of native `.node` binaries inside the package’s own directory (`__dirname`) to choose the correct build for the current OS/arch, and (2) on Linux only, the system `ldd` binary (e.g. `/usr/bin/ldd`) to detect musl vs glibc. No user or application files are read.
+- **Config loader** (`loadLoggerConfig`): Reads only paths you control. If you use it, it reads at most one file: either the path you pass in `opts.configPath`, or a file under `opts.configDir` with a name derived from `opts.defaultBase` and `opts.environment` (default: `./config/logger.yaml` or `./config/logger-{env}.yaml`). You can avoid filesystem access entirely by not calling `loadLoggerConfig` and passing config directly to `init()`.
+
 | Dynamically configurable | Fixed at init |
 |--------------------------|---------------|
 | Log level, additive masking rules, transports (debug: add console only for visual help in a POD; existing stay; `resetTransports()` to remove added) | Core masking config (`maskChar`, `maxDepth`), Redis/HTTP/broker |

package/dist/index.cjs

@@ -2397,8 +2397,8 @@ class ConsoleTransport extends Transport {
  * @file src/logger/transports/optionalChalk.ts
  * @description Built-in chalk-like API using ANSI escape codes. No chalk dependency.
  * Used by ClassicConsoleTransport, PrettyConsoleTransport, CompactConsoleTransport, ColorfulConsoleTransport.
- * Does not read process.env; pass disableColors from transport options (e.g. for NO_COLOR use
- * disableColors: process.env.NO_COLOR != null && process.env.NO_COLOR !== '' && process.env.NO_COLOR !== '0').
+ * This module does not read environment variables. Pass disableColors from transport options;
+ * to respect the NO_COLOR convention, set disableColors from your app (e.g. from the NO_COLOR env var). See SECURITY.md.
  */
 const RESET = '\x1b[0m';
 function wrap(s, codes) {
@@ -2450,9 +2450,8 @@ let cachedWithColors = null;
 let cachedNoColors = null;
 /**
  * Returns a chalk-like instance using built-in ANSI colors. No external chalk dependency.
- * Does not read process.env. Pass disableColors from transport options; when true, output has no colors.
- * When false, colors are used only if stdout is a TTY. To respect NO_COLOR, pass
- * disableColors: process.env.NO_COLOR != null && process.env.NO_COLOR !== '' && process.env.NO_COLOR !== '0'.
+ * Does not read environment variables. Pass disableColors from transport options; when true, output has no colors.
+ * When false, colors are used only if stdout is a TTY. To respect NO_COLOR, derive disableColors in your app and pass it here. See SECURITY.md.
  */
 function getOptionalChalk(disableColors) {
     if (disableColors) {

package/dist/index.d.ts

@@ -796,8 +796,8 @@ declare class ConsoleTransport extends Transport {
  * @file src/logger/transports/optionalChalk.ts
  * @description Built-in chalk-like API using ANSI escape codes. No chalk dependency.
  * Used by ClassicConsoleTransport, PrettyConsoleTransport, CompactConsoleTransport, ColorfulConsoleTransport.
- * Does not read process.env; pass disableColors from transport options (e.g. for NO_COLOR use
- * disableColors: process.env.NO_COLOR != null && process.env.NO_COLOR !== '' && process.env.NO_COLOR !== '0').
+ * This module does not read environment variables. Pass disableColors from transport options;
+ * to respect the NO_COLOR convention, set disableColors from your app (e.g. from the NO_COLOR env var). See SECURITY.md.
  */
 /** Chalk-like API: chainable style that returns wrapped string when called. */
 type ChalkLike = {

package/dist/index.mjs

@@ -2375,8 +2375,8 @@ class ConsoleTransport extends Transport {
  * @file src/logger/transports/optionalChalk.ts
  * @description Built-in chalk-like API using ANSI escape codes. No chalk dependency.
  * Used by ClassicConsoleTransport, PrettyConsoleTransport, CompactConsoleTransport, ColorfulConsoleTransport.
- * Does not read process.env; pass disableColors from transport options (e.g. for NO_COLOR use
- * disableColors: process.env.NO_COLOR != null && process.env.NO_COLOR !== '' && process.env.NO_COLOR !== '0').
+ * This module does not read environment variables. Pass disableColors from transport options;
+ * to respect the NO_COLOR convention, set disableColors from your app (e.g. from the NO_COLOR env var). See SECURITY.md.
  */
 const RESET = '\x1b[0m';
 function wrap(s, codes) {
@@ -2428,9 +2428,8 @@ let cachedWithColors = null;
 let cachedNoColors = null;
 /**
  * Returns a chalk-like instance using built-in ANSI colors. No external chalk dependency.
- * Does not read process.env. Pass disableColors from transport options; when true, output has no colors.
- * When false, colors are used only if stdout is a TTY. To respect NO_COLOR, pass
- * disableColors: process.env.NO_COLOR != null && process.env.NO_COLOR !== '' && process.env.NO_COLOR !== '0'.
+ * Does not read environment variables. Pass disableColors from transport options; when true, output has no colors.
+ * When false, colors are used only if stdout is a TTY. To respect NO_COLOR, derive disableColors in your app and pass it here. See SECURITY.md.
  */
 function getOptionalChalk(disableColors) {
     if (disableColors) {

package/dist/types/config/loadLoggerConfig.d.ts

@@ -35,9 +35,11 @@ export interface LoggerConfigLoaderOptions {
  * It does NOT read environment variables directly; all state must be passed via `opts`.
  * If no file is found, it returns an empty object, making the config file optional.
  *
- * **Security:** A restricted schema (JSON_SCHEMA) is used to avoid prototype pollution
+ * **Security:** A restricted schema (`json`) is used to avoid prototype pollution
  * and dangerous types. Only use with configuration files under deployment team
- * control (controlled paths and permissions).
+ * control (controlled paths and permissions). This function reads only the paths
+ * derived from opts (configPath, configDir, defaultBase, environment); no other
+ * filesystem access is performed.
  *
  * @param opts - Options to customize the loading behavior.
  * @returns A partial `LoggerOptions` object, or an empty object if no file is found.

package/dist/types/logger/transports/optionalChalk.d.ts

@@ -2,8 +2,8 @@
  * @file src/logger/transports/optionalChalk.ts
  * @description Built-in chalk-like API using ANSI escape codes. No chalk dependency.
  * Used by ClassicConsoleTransport, PrettyConsoleTransport, CompactConsoleTransport, ColorfulConsoleTransport.
- * Does not read process.env; pass disableColors from transport options (e.g. for NO_COLOR use
- * disableColors: process.env.NO_COLOR != null && process.env.NO_COLOR !== '' && process.env.NO_COLOR !== '0').
+ * This module does not read environment variables. Pass disableColors from transport options;
+ * to respect the NO_COLOR convention, set disableColors from your app (e.g. from the NO_COLOR env var). See SECURITY.md.
  */
 /** Chalk-like API: chainable style that returns wrapped string when called. */
 export type ChalkLike = {
@@ -23,8 +23,7 @@ export type ChalkLike = {
 };
 /**
  * Returns a chalk-like instance using built-in ANSI colors. No external chalk dependency.
- * Does not read process.env. Pass disableColors from transport options; when true, output has no colors.
- * When false, colors are used only if stdout is a TTY. To respect NO_COLOR, pass
- * disableColors: process.env.NO_COLOR != null && process.env.NO_COLOR !== '' && process.env.NO_COLOR !== '0'.
+ * Does not read environment variables. Pass disableColors from transport options; when true, output has no colors.
+ * When false, colors are used only if stdout is a TTY. To respect NO_COLOR, derive disableColors in your app and pass it here. See SECURITY.md.
  */
 export declare function getOptionalChalk(disableColors: boolean): ChalkLike;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "syntropylog",
-  "version": "0.12.1",
+  "version": "0.12.3",
   "engines": {
     "node": ">=20.0.0"
   },
@@ -140,7 +140,7 @@
     "provenance": true
   },
   "dependencies": {
-    "js-yaml": "^4.1.1"
+    "yaml": "^2.8.2"
   },
   "optionalDependencies": {
     "syntropylog-native": "0.1.0"
@@ -153,7 +153,6 @@
     "@rollup/plugin-json": "^6.1.0",
     "@rollup/plugin-node-resolve": "^16.0.0",
     "@rollup/plugin-typescript": "^12.1.2",
-    "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.13.5",
     "@typescript-eslint/eslint-plugin": "8.56.1",
     "@typescript-eslint/parser": "8.56.1",