configorama 0.9.17 → 0.10.2

package/README.md

@@ -22,6 +22,7 @@ Configorama extends your configuration with a powerful variable system that reso
 <details>
 <summary>Click to expand</summary>
 
+- [Key Features](#key-features)
 - [Getting Started](#getting-started)
   - [Installation](#installation)
   - [Quick Start](#quick-start)
@@ -30,13 +31,19 @@ Configorama extends your configuration with a powerful variable system that reso
   - [Resolution Flow](#resolution-flow)
   - [Analyzing Without Resolving](#analyzing-without-resolving)
   - [Getting Metadata](#getting-metadata)
+  - [Architecture](#architecture)
+  - [Performance](#performance)
 - [Variable Sources](#variable-sources)
+  - [Summary Table](#summary-table)
   - [Environment Variables](#environment-variables)
   - [CLI Option Flags](#cli-option-flags)
   - [Parameter Values](#parameter-values)
   - [Self References](#self-references)
   - [File References](#file-references)
   - [Sync/Async File References](#syncasync-file-references)
+    - [Passing Arguments to Functions](#passing-arguments-to-functions)
+    - [ConfigContext](#configcontext)
+    - [Functions Without Arguments](#functions-without-arguments)
   - [TypeScript File References](#typescript-file-references)
   - [Terraform HCL Support](#terraform-hcl-support)
   - [Git References](#git-references)
@@ -45,11 +52,18 @@ Configorama extends your configuration with a powerful variable system that reso
   - [If Expressions](#if-expressions)
   - [Filters (Experimental)](#filters-experimental)
   - [Functions (Experimental)](#functions-experimental)
+- [Bundled Plugins](#bundled-plugins)
+  - [CloudFormation](#cloudformation)
 - [API Reference](#api-reference)
   - [Async API](#async-api)
   - [Sync API](#sync-api)
   - [Analyze API](#analyze-api)
   - [Format Utilities](#format-utilities)
+  - [Markdown Files](#markdown-files)
+  - [`buildVariableSyntax(prefix, suffix, excludePatterns?)`](#buildvariablesyntaxprefix-suffix-excludepatterns)
+  - [`Configorama` Class](#configorama-class)
+  - [`configorama/parse-file` Subpath](#configoramaparse-file-subpath)
+  - [TypeScript Types](#typescript-types)
 - [Configuration Options](#configuration-options)
   - [Custom Variable Syntax](#custom-variable-syntax)
   - [allowUnknownVariableTypes](#allowunknownvariabletypes)
@@ -61,7 +75,7 @@ Configorama extends your configuration with a powerful variable system that reso
 - [CLI Usage](#cli-usage)
   - [Basic Commands](#basic-commands)
   - [Command Options](#command-options)
-  - [Examples](#cli-examples)
+  - [CLI Examples](#cli-examples)
 - [Testing](#testing)
   - [Running Tests](#running-tests)
   - [Test Structure](#test-structure)
@@ -79,9 +93,13 @@ Configorama extends your configuration with a powerful variable system that reso
   - [Multi-Stage Resolution](#multi-stage-resolution)
   - [Function Arguments and Context](#function-arguments-and-context)
   - [Programmatic Usage](#programmatic-usage)
-- [What's New](#whats-new)
+- [Comparison vs Serverless Framework Variables](#comparison-vs-serverless-framework-variables)
 - [Alternative Libraries](#alternative-libraries)
+- [Changelog](#changelog)
 - [Inspiration](#inspiration)
+- [License](#license)
+- [Contributing](#contributing)
+- [Support](#support)
 
 </details>
 <!-- end-doc-gen -->
@@ -297,6 +315,59 @@ console.log(result.resolutionHistory)         // Step-by-step resolution for eac
 }
 ```
 
+### Architecture
+
+```
+┌──────────────────┐    ┌─────────────────────┐    ┌──────────────────┐
+│  Input           │───▶│  Configorama core   │───▶│  Output          │
+│                  │    │                     │    │                  │
+│  • Config file   │    │  parser registry    │    │  Resolved config │
+│  • JS/TS object  │    │  (yaml, json, toml, │    │  (+ metadata if  │
+│  • Inline opts   │    │   ini, hcl, md, …)  │    │   requested)     │
+└──────────────────┘    │                     │    └──────────────────┘
+                        │  preProcess()       │
+                        │  ↓                  │
+                        │  populateObject()   │◀───┐  iterates until
+                        │  ↓                  │    │  no variables
+                        │  resolve leaf vars  │────┘  remain
+                        │  ↓                  │
+                        │  apply filters/funcs│
+                        │  ↓                  │
+                        │  return             │
+                        └──────────┬──────────┘
+                                   │
+                                   ▼
+                ┌──────────────────────────────────────┐
+                │           Variable Sources           │
+                │ ┌────────┐ ┌────────┐ ┌────────────┐ │
+                │ │ env    │ │ opt    │ │ file/text  │ │
+                │ │ self   │ │ param  │ │ git/cron   │ │
+                │ │ eval   │ │ if     │ │ + plugins  │ │
+                │ └────────┘ └────────┘ └────────────┘ │
+                │                                      │
+                │  Bundled plugins:                    │
+                │  • plugins/cloudformation            │
+                │                                      │
+                │  Custom: variableSources: [{…}]      │
+                └──────────────────────────────────────┘
+```
+
+Resolution is a **fixed-point loop**: each pass resolves what it can, then `populateObject()` runs again until no `${…}` references remain. Built-in resolvers run first; custom resolvers from `variableSources` are tried in order.
+
+### Performance
+
+A typical 21KB serverless-style config resolves in **~3ms** on warm Node 22.
+
+- Before/after benchmarks against the published `0.9.17` baseline: [`PERF.md`](./PERF.md)
+- Reproducible bench harness: [`scripts/bench.js`](./scripts/bench.js)
+- Run against your own configs:
+  ```bash
+  node scripts/bench.js  # local
+  node scripts/bench.js /path/to/another/configorama  # A/B
+  ```
+
+If your config is slow, please open an issue with the config (or a redacted reproduction). We're happy to profile and tighten the hot path.
+
 ---
 
 ## Variable Sources
@@ -953,7 +1024,7 @@ See [tests/hclTests](./tests/hclTests) for example Terraform files.
 Access repository information from the current working directory's git data.
 
 <!-- doc-gen CODE src=tests/gitVariables/gitVariables.yml -->
-```yaml
+```yml
 ########################
 # Git Variables
 ########################
@@ -1290,6 +1361,48 @@ inRange: ${between(${value}, 50, 100)}  # true
 
 ---
 
+## Bundled Plugins
+
+Plugins ship in the repo under `plugins/` and are opt-in: install their peer dependencies, then wire them into `variableSources`. Plugins are *not* required dependencies of `configorama` itself, so consumers who don't need them aren't paying for them.
+
+### CloudFormation
+
+Resolves CloudFormation stack output values. Single-region, multi-region, and multi-account.
+
+```yaml
+# Default region, default AWS credentials
+apiUrl: ${cf:my-stack.ApiUrl}
+
+# Explicit region
+westUrl: ${cf(us-west-2):west-stack.ApiUrl}
+
+# Cross-account: 'prod' matches PROD_AWS_ACCESS_KEY_ID env vars
+prodUrl: ${cf(prod:us-west-2):prod-stack.ApiUrl}
+```
+
+```javascript
+const configorama = require('configorama')
+const createCloudFormationResolver = require('configorama/plugins/cloudformation')
+
+const cfResolver = createCloudFormationResolver({
+  defaultRegion: 'us-east-1',
+})
+
+const config = await configorama('config.yml', {
+  variableSources: [cfResolver]
+})
+```
+
+Full docs: [`plugins/cloudformation/README.md`](./plugins/cloudformation/README.md). Covers the env-var-prefix alias convention, the refcounted credential mutex for parallel-safe deploys, and the `skipResolution` mode for CI metadata extraction.
+
+Peer dependency (install separately):
+
+```bash
+npm install @aws-sdk/client-cloudformation @aws-sdk/credential-providers
+```
+
+---
+
 ## API Reference
 
 ### Async API
@@ -1477,8 +1590,8 @@ const { format } = require('configorama')
 // Parse YAML
 const yamlObj = format.yaml.parse('key: value')
 
-// Parse JSON5
-const jsonObj = format.json5.parse('{ key: "value", }')
+// Parse JSON (handles JSON5/JSONC too: comments, trailing commas)
+const jsonObj = format.json.parse('{ key: "value", }')
 
 // Parse TOML
 const tomlObj = format.toml.parse('key = "value"')
@@ -1490,11 +1603,133 @@ const iniObj = format.ini.parse('[section]\nkey=value')
 const hclObj = await format.hcl.parse('variable "example" { default = "value" }')
 ```
 
-**Parser methods:**
+**Available parsers:** `format.json`, `format.yaml`, `format.toml`, `format.ini`, `format.hcl`, `format.markdown`.
+
+Each has at minimum a `parse(content)` method; `dump(obj)` / `stringify(obj)` and cross-format converters (e.g. `format.yaml.toJson`, `format.toml.toYaml`) are available where the underlying format supports them. `format.markdown` is a frontmatter parser; see [Markdown Files](#markdown-files) below.
+
+**Real use cases for `format`:**
+
+- Parse a config file without resolving variables (just want the structure):
+  ```javascript
+  const { format } = require('configorama')
+  const fs = require('fs')
+  const raw = format.yaml.parse(fs.readFileSync('config.yml', 'utf8'))
+  // raw is the YAML structure with ${...} strings intact
+  ```
+- Use the same YAML/TOML/JSON5 parsers as configorama itself in your own tooling, so a file that loads in one place loads identically in the other.
+
+---
+
+### Markdown Files
+
+Markdown configs (`.md`, `.mdx`, `.markdown`, `.mdown`, `.mkdn`, `.mkd`) are parsed as YAML/TOML/JSON frontmatter + body. The frontmatter becomes top-level keys; the body is exposed as `_content` on the resolved config (or `_body` if the frontmatter used that key explicitly).
+
+```markdown
+---
+service: my-service
+stage: ${opt:stage, 'dev'}
+---
+
+# Service Docs
+This is the body content.
+```
+
+Resolves to:
+
+```javascript
+{
+  service: 'my-service',
+  stage: 'dev',
+  _content: '# Service Docs\nThis is the body content.'
+}
+```
+
+The body is detached during variable resolution (so `${…}` inside the body text is left alone) and re-attached afterward; only frontmatter keys get variable expansion.
+
+---
+
+### `buildVariableSyntax(prefix, suffix, excludePatterns?)`
+
+Helper for building a properly-escaped regex source string to pass to the `syntax` option. Handles regex-special characters in your delimiters without you having to escape them yourself.
+
+```javascript
+const { buildVariableSyntax } = require('configorama')
+
+// Use {{ ... }} instead of ${ ... }
+const syntax = buildVariableSyntax('{{', '}}')
+
+const config = await configorama('config.yml', { syntax })
+```
+
+**Parameters:**
+
+| Param | Type | Default | Description |
+|---|---|---|---|
+| `prefix` | `string` | `'${'` | Opening delimiter |
+| `suffix` | `string` | `'}'` | Closing delimiter |
+| `excludePatterns` | `string[]` | `['AWS', 'stageVariables']` | Patterns to exclude via negative lookahead (so e.g. `${AWS::Region}` is left untouched by CloudFormation users) |
+
+---
+
+### `Configorama` Class
+
+For advanced use cases (long-lived instances, hooking into init/resolve lifecycle, accessing partial state) the underlying class is exported.
+
+```javascript
+const { Configorama } = require('configorama')
+
+const instance = new Configorama('config.yml', { options: { stage: 'dev' } })
+await instance.init({ stage: 'dev' })
+const resolved = await instance.populateObject(instance.config)
+const metadata = instance.collectVariableMetadata()
+```
+
+Most users should prefer the top-level `configorama()` / `.sync()` / `.analyze()` functions, which are thin wrappers around this class.
+
+---
+
+### `configorama/parse-file` Subpath
+
+For tools that want to parse a config file (auto-detecting format from extension or contents) without going through variable resolution:
 
-Each parser has:
-- `parse(content)` - Parse string to JavaScript object
-- `stringify(obj)` - Convert JavaScript object to format string (if supported)
+```javascript
+const { parseFile, parseFileContents } = require('configorama/parse-file')
+
+// Read from disk
+const raw = parseFile('./config.yml')
+// returns the parsed object with ${...} strings intact
+
+// Or parse already-loaded contents
+const fromString = parseFileContents({
+  contents: 'service: my-app\nstage: ${opt:stage}',
+  filePath: 'in-memory.yml'
+})
+```
+
+Both are synchronous. Useful for build tools that inspect or rewrite configs before handing them to configorama.
+
+---
+
+### TypeScript Types
+
+Type definitions are bundled (`index.d.ts`). TypeScript users get:
+
+- Generic typing on the resolved config: `configorama<MyConfig>('config.yml')` returns `Promise<MyConfig>`
+- Full typing on `ConfigoramaSettings` and `ConfigoramaResult`
+- Editor autocomplete on all options shown in the [Complete Options Reference](#complete-options-reference)
+
+```typescript
+import configorama, { ConfigoramaSettings } from 'configorama'
+
+interface MyConfig {
+  service: string
+  stage: string
+  database: { host: string; port: number }
+}
+
+const config = await configorama<MyConfig>('config.yml', { options: { stage: 'prod' } })
+// config.database.port is typed as number
+```
 
 ---
 
@@ -1583,9 +1818,11 @@ const config = await configorama(configFile, {
 
 **Use cases:**
 - Multi-stage resolution (local resolution, then cloud provider resolves remaining vars)
-- Serverless Framework integration (let framework resolve SSM, CloudFormation refs)
+- Serverless Framework integration (let the framework resolve SSM and other refs it owns)
 - Gradual migration (allow unknown types during transition period)
 
+> CloudFormation refs (`${cf:…}`, `${cf(region):…}`, `${cf(account:region):…}`) are now resolved natively by the bundled [`plugins/cloudformation/`](./plugins/cloudformation/README.md) plugin; no external resolver required.
+
 ---
 
 ### allowUnresolvedVariables
@@ -1654,10 +1891,17 @@ const config = await configorama(configFile, {
 | `allowUnknownVariableTypes` | `boolean \| string[]` | `false` | Allow unknown variable types to pass through |
 | `allowUnresolvedVariables` | `boolean \| string[]` | `false` | Allow known types that can't resolve to pass through |
 | `allowUndefinedValues` | `boolean` | `false` | Allow undefined as a valid end result |
-| `returnMetadata` | `boolean` | `false` | Return both config and metadata about variables |
+| `returnMetadata` | `boolean` | `false` | Return `{ config, metadata }` instead of just the resolved config |
+| `returnPreResolvedVariableDetails` | `boolean` | `false` | Return metadata about variables *without* resolving them (used by `analyze()`) |
+| `useDotEnvFiles` | `boolean` | `false` | Auto-load `.env`, `.env.{stage}`, etc. into `process.env` before resolution (via [env-stage-loader](https://www.npmjs.com/package/env-stage-loader)) |
+| `dotEnvSilent` | `boolean` | `true` (unless `--verbose`) | Suppress the env-stage-loader log lines when `useDotEnvFiles` is on |
+| `dotEnvDebug` | `boolean` | `false` | Enable env-stage-loader debug output |
+| `dynamicArgs` | `object \| Function` | `undefined` | Values passed into `.js`/`.ts` config files when they're imported as the root config |
 | `mergeKeys` | `string[]` | `[]` | Keys to merge in arrays of objects |
 | `filePathOverrides` | `Record<string, string>` | `{}` | Map of file paths to override (for testing/mocking) |
 
+> The config file itself can also set `useDotenv: true` (or `useDotEnv: true`) at the top level to trigger dotenv loading. Useful when you want the behavior intrinsic to the config rather than the JS caller.
+
 **Legacy options (deprecated):**
 
 | Legacy Option | New Equivalent |
@@ -1776,8 +2020,8 @@ interface VariableSource {
 **Advanced example with AWS SSM:**
 
 ```javascript
-const AWS = require('aws-sdk')
-const ssm = new AWS.SSM()
+const { SSMClient, GetParameterCommand } = require('@aws-sdk/client-ssm')
+const ssm = new SSMClient({})
 
 const config = await configorama('config.yml', {
   variableSources: [{
@@ -1790,10 +2034,10 @@ const config = await configorama('config.yml', {
       const paramPath = variable.replace(/^ssm:/, '')
 
       try {
-        const result = await ssm.getParameter({
+        const result = await ssm.send(new GetParameterCommand({
           Name: paramPath,
           WithDecryption: true
-        }).promise()
+        }))
 
         return result.Parameter.Value
       } catch (err) {
@@ -1807,6 +2051,8 @@ const config = await configorama('config.yml', {
 })
 ```
 
+> **See also:** the bundled [`plugins/cloudformation/`](./plugins/cloudformation/README.md) plugin is a working example of a `source: 'remote'` resolver. It handles multi-region and multi-account credential swapping, plus per-instance client and output caching.
+
 ```yaml
 # config.yml
 database:
@@ -1959,6 +2205,22 @@ configorama config.yml --verify
 #   - DB_PASSWORD
 ```
 
+**Allow unknown variable types to pass through unresolved:**
+
+```bash
+# ${ssm:...} and ${custom:...} stay as literal ${ssm:...} strings
+# (typical for multi-stage pipelines where another tool resolves them)
+configorama config.yml --allow-unknown
+```
+
+**Allow undefined values in the final output:**
+
+```bash
+# Don't error on values that resolved to undefined; emit them as nulls
+# (useful for downstream tooling that does its own validation)
+configorama config.yml --allow-undefined
+```
+
 ---
 
 ## Testing
@@ -2087,7 +2349,7 @@ service: my-service
 
 provider:
   name: aws
-  runtime: nodejs18.x
+  runtime: nodejs22.x
   stage: ${opt:stage, 'dev'}
   region: ${opt:region, 'us-east-1'}
 
@@ -2134,7 +2396,7 @@ serverless deploy --stage prod --region us-west-2
 **Dockerfile:**
 
 ```dockerfile
-FROM node:18-alpine
+FROM node:22-alpine
 
 WORKDIR /app
 
@@ -2212,12 +2474,12 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Setup Node.js
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
-          node-version: '18'
+          node-version: '22'
 
       - name: Install dependencies
         run: npm ci
@@ -2251,7 +2513,7 @@ stages:
 
 verify-config:
   stage: verify
-  image: node:18
+  image: node:22
   script:
     - npm ci
     - npx configorama config.yml --verify --stage $CI_ENVIRONMENT_NAME
@@ -2260,14 +2522,14 @@ verify-config:
 
 test:
   stage: test
-  image: node:18
+  image: node:22
   script:
     - npm ci
     - npm test
 
 deploy-production:
   stage: deploy
-  image: node:18
+  image: node:22
   script:
     - npm ci
     - npm run deploy
@@ -2520,14 +2782,14 @@ secrets: ${file(./fetch-secrets.js)}
 
 ```javascript
 // fetch-secrets.js
-const AWS = require('aws-sdk')
-const ssm = new AWS.SSM()
+const { SSMClient, GetParameterCommand } = require('@aws-sdk/client-ssm')
+const ssm = new SSMClient({})
 
 module.exports = async () => {
-  const result = await ssm.getParameter({
+  const result = await ssm.send(new GetParameterCommand({
     Name: '/myapp/api-key',
     WithDecryption: true
-  }).promise()
+  }))
 
   return result.Parameter.Value
 }
@@ -2594,13 +2856,15 @@ const partiallyResolved = await configorama('config.yml', {
   allowUnknownVariableTypes: ['ssm', 'cf']
 })
 
-// Stage 2: External system resolves SSM and CloudFormation refs
-// (e.g., Serverless Dashboard, AWS CloudFormation, etc.)
+// Stage 2: External system resolves SSM and any other refs
+// (e.g., Serverless Dashboard, secrets manager, etc.)
 const fullyResolved = await externalResolver(partiallyResolved)
 ```
 
 **Use case:** Serverless Framework + Serverless Dashboard workflow.
 
+> For CloudFormation refs specifically, the bundled [CF plugin](./plugins/cloudformation/README.md) resolves them natively in Stage 1, so you don't need a second pass.
+
 ---
 
 ### Function Arguments and Context
@@ -2660,14 +2924,14 @@ const config = await configorama('config.yml', {
     description: 'AWS Systems Manager Parameter Store',
     match: /^ssm:/,
     resolver: async (variable) => {
-      const AWS = require('aws-sdk')
-      const ssm = new AWS.SSM()
+      const { SSMClient, GetParameterCommand } = require('@aws-sdk/client-ssm')
+      const ssm = new SSMClient({})
 
       const paramName = variable.replace(/^ssm:/, '')
-      const result = await ssm.getParameter({
+      const result = await ssm.send(new GetParameterCommand({
         Name: paramName,
         WithDecryption: true
-      }).promise()
+      }))
 
       return result.Parameter.Value
     }
@@ -2734,68 +2998,47 @@ timeout: ${selectByEnv(30, 5, ${environment})}
 
 ---
 
-## What's New
-
-How is this different than the Serverless Framework variable system?
+## Comparison vs Serverless Framework Variables
+
+Configorama was forked from the Serverless Framework variable system and extended. The differences:
+
+| Capability | Serverless | Configorama |
+|---|---|---|
+| Framework-agnostic; use outside Serverless | ❌ Serverless-only | ✅ Any tool, any framework |
+| Pluggable variable sources | ❌ Hardcoded | ✅ Custom resolvers, custom syntax |
+| `self:` prefix optional in self-refs | ❌ Required | ✅ `${foo.bar}` works without `self:` |
+| Numbers as defaults | ❌ Coerced to string | ✅ `${env:TIMEOUT, 30}` stays numeric |
+| Format support | YAML/JSON | YAML, JSON/JSON5/JSONC, TOML, INI, HCL, Markdown, TS, JS |
+| Filters (pipe transforms) | ❌ | ✅ `${value \| toUpperCase}` |
+| Built-in functions | ❌ | ✅ `merge()`, custom user functions |
+| Conditional expressions | ❌ | ✅ `${if(cond ? a : b)}` |
+| Eval/math expressions | ❌ | ✅ `${eval(2 + 2)}` |
+| TypeScript file refs | ❌ | ✅ `${file(./config.ts)}` |
+| Git data refs | ❌ | ✅ `${git:branch}`, `${git:sha1}`, etc. |
+| Cron expression refs | ❌ | ✅ `${cron(every monday at 9am)}` |
+| Metadata extraction (analyze without resolving) | ❌ | ✅ `configorama.analyze(...)` |
+| Multi-account CloudFormation refs | ❌ | ✅ via bundled CF plugin |
+| Circular dependency detection | ❌ Hangs | ✅ Helpful error |
 
-1. **Framework-agnostic** - Use with any tool, not just Serverless Framework
-
-2. **Pluggable** - Add custom variable syntax and sources easily
-
-3. **Filters** - Transform values before resolution:
-   ```yaml
-   key: ${opt:stage | toUpperCase}
-   ```
-
-4. **Cleaner self-references** - No need for `self:` prefix:
-   ```yaml
-   keyOne:
-     subKey: hi
-
-   # Before
-   key: ${self:keyOne.subKey}
-
-   # Now (both work)
-   key: ${keyOne.subKey}
-   key: ${self:keyOne.subKey}
-   ```
-
-5. **Numbers as defaults** - Numeric defaults fully supported:
-   ```yaml
-   timeout: ${env:TIMEOUT, 30}
-   port: ${opt:port, 3000}
-   ```
-
-6. **Multiple format support** - TOML, YML, JSON, INI, HCL, etc.
-
-7. **Built-in functions** - Combine and transform values:
-   ```yaml
-   merged: ${merge(${obj1}, ${obj2})}
-   ```
+---
 
-8. **TypeScript support** - Execute TypeScript files directly:
-   ```yaml
-   config: ${file(./config.ts)}
-   ```
+## Alternative Libraries
 
-9. **Conditional expressions** - If/else logic in configs:
-   ```yaml
-   memory: ${if(${stage} === 'prod' ? 1024 : 512)}
-   ```
+How configorama compares to other variable-substitution libraries:
 
-10. **Metadata extraction** - Analyze configs without resolving:
-    ```javascript
-    const meta = await configorama.analyze('config.yml')
-    ```
+| Library | Formats | Variable sources | Custom resolvers | Async | TypeScript |
+|---|---|---|---|---|---|
+| **configorama** | YAML, JSON5, TOML, INI, HCL, MD, TS, JS | env, opt, file, self, git, cron, eval, if, custom | ✅ | ✅ | ✅ |
+| [sls-yaml](https://github.com/01alchemist/sls-yaml) | YAML | env, opt, file, self | ❌ | ❌ | ❌ |
+| [yaml-boost](https://github.com/blackflux/yaml-boost) | YAML | env, file, self, function | partial | ❌ | ❌ |
+| [serverless-merge-config](https://github.com/CruGlobal/serverless-merge-config) | YAML | merge-focused | ❌ | ❌ | ❌ |
+| [serverless-terraform-variables](https://www.npmjs.com/package/serverless-terraform-variables) | YAML + .tfvars | terraform-focused | ❌ | ❌ | ❌ |
 
 ---
 
-## Alternative Libraries
+## Changelog
 
-- [sls-yaml](https://github.com/01alchemist/sls-yaml) - YAML with variable support
-- [yaml-boost](https://github.com/blackflux/yaml-boost) - YAML preprocessing
-- [serverless-merge-config](https://github.com/CruGlobal/serverless-merge-config) - Merge Serverless configs
-- [serverless-terraform-variables](https://www.npmjs.com/package/serverless-terraform-variables) - Terraform variable support
+Version history lives in [CHANGELOG.md](./CHANGELOG.md). It covers everything from 0.9.9 onward; older releases are in `git log`.
 
 ---
 
@@ -2803,10 +3046,13 @@ How is this different than the Serverless Framework variable system?
 
 This is forked from the [Serverless Framework](https://github.com/serverless/serverless/) variable system.
 
-**Mad props to:**
+<details>
+<summary><strong>Mad props to the original contributors</strong></summary>
 
 [erikerikson](https://github.com/erikerikson), [eahefnawy](https://github.com/eahefnawy), [HyperBrain](https://github.com/HyperBrain), [ac360](https://github.com/ac360), [gcphost](https://github.com/gcphost), [pmuens](https://github.com/pmuens), [horike37](https://github.com/horike37), [lorengordon](https://github.com/lorengordon), [AndrewFarley](https://github.com/AndrewFarley), [tobyhede](https://github.com/tobyhede), [johncmckim](https://github.com/johncmckim), [mangas](https://github.com/mangas), [e-e-e](https://github.com/e-e-e), [BasileTrujillo](https://github.com/BasileTrujillo), [miltador](https://github.com/miltador), [sammarks](https://github.com/sammarks), [RafalWilinski](https://github.com/RafalWilinski), [indieisaconcept](https://github.com/indieisaconcept), [svdgraaf](https://github.com/svdgraaf), [infiniteluke](https://github.com/infiniteluke), [j0k3r](https://github.com/j0k3r), [craigw](https://github.com/craigw), [bsdkurt](https://github.com/bsdkurt), [aoskotsky-amplify](https://github.com/aoskotsky-amplify), and all the other folks who contributed to the variable system.
 
+</details>
+
 **Additionally these tools were very helpful:**
 
 - [yaml-boost](https://github.com/blackflux/yaml-boost)
@@ -2821,11 +3067,10 @@ MIT © [David Wells](https://davidwells.io)
 
 ## Contributing
 
-Contributions welcome! Please read the [contributing guidelines](CONTRIBUTING.md) first.
+Bug reports and reproductions are very welcome. Please open an [issue](https://github.com/DavidWells/configorama/issues) with a minimal failing config. PRs are reviewed case-by-case; small targeted fixes with a test case are most likely to land quickly.
 
 ## Support
 
 - 🐛 [Report bugs](https://github.com/DavidWells/configorama/issues)
 - 💡 [Request features](https://github.com/DavidWells/configorama/issues)
 - 📖 [Read the docs](https://github.com/DavidWells/configorama#readme)
-- 💬 [Join discussions](https://github.com/DavidWells/configorama/discussions)