If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/lightbend/config shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Missing license — unclear to depend on

• Last commit 3d ago
• 32+ active contributors
• Distributed ownership (top contributor 15% of recent commits)
• CI configured
• Tests present
• ⚠ No license — legally unclear to depend on

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live lightbend/config repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/lightbend/config.

What it runs against: a local clone of lightbend/config — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in lightbend/config | Confirms the artifact applies here, not a fork | | 2 | Default branch main exists | Catches branch renames | | 3 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 4 | Last commit ≤ 33 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of lightbend/config. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/lightbend/config.git
#   cd config
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of lightbend/config and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "lightbend/config(\\.git)?\\b" \\
  && ok "origin remote is lightbend/config" \\
  || miss "origin remote is not lightbend/config (artifact may be from a fork)"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "config/src/main/java/com/typesafe/config/ConfigFactory.java" \\
  && ok "config/src/main/java/com/typesafe/config/ConfigFactory.java" \\
  || miss "missing critical file: config/src/main/java/com/typesafe/config/ConfigFactory.java"
test -f "config/src/main/java/com/typesafe/config/impl/ConfigParser.java" \\
  && ok "config/src/main/java/com/typesafe/config/impl/ConfigParser.java" \\
  || miss "missing critical file: config/src/main/java/com/typesafe/config/impl/ConfigParser.java"
test -f "config/src/main/java/com/typesafe/config/impl/ConfigImpl.java" \\
  && ok "config/src/main/java/com/typesafe/config/impl/ConfigImpl.java" \\
  || miss "missing critical file: config/src/main/java/com/typesafe/config/impl/ConfigImpl.java"
test -f "config/src/main/java/com/typesafe/config/Config.java" \\
  && ok "config/src/main/java/com/typesafe/config/Config.java" \\
  || miss "missing critical file: config/src/main/java/com/typesafe/config/Config.java"
test -f "config/src/main/java/com/typesafe/config/impl/Tokenizer.java" \\
  && ok "config/src/main/java/com/typesafe/config/impl/Tokenizer.java" \\
  || miss "missing critical file: config/src/main/java/com/typesafe/config/impl/Tokenizer.java"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 33 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~3d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/lightbend/config"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Lightbend Config is a JVM configuration library that parses and merges HOCON files (Human-Optimized Config Object Notation—a JSON superset with comments, includes, and substitutions) into immutable Config objects. It supports Java properties, JSON, and HOCON formats, handles type coercion (e.g., "512k" → bytes, "yes" → boolean), and enables environment variable and system property overrides without external dependencies. Monolithic Java library under config/src/main/java/com/typesafe/config/. Public API in the root package (Config.java, ConfigFactory.java, ConfigValue.java, etc.); implementation details isolated in impl/ subdirectory (AbstractConfigObject, AbstractConfigValue, ConfigBeanImpl). Parser, resolver, and includer logic separated into distinct classes (ConfigIncluderFile, ConfigIncluderURL, ConfigIncluderClasspath). Scala tests parallel the Java structure.

JVM application developers (Java and Scala) who need to manage application configuration files across multiple formats and environments. Common use cases: Akka/Play Framework users managing application.conf and reference.conf, library maintainers defining defaults, and ops teams needing human-friendly config with variable substitution and include mechanisms.

Production-ready and actively maintained. The codebase shows ~1.1M lines of code with solid Java/Scala split, comprehensive CI/CD via GitHub Actions (workflows/ci.yml exists), multiple release pipelines (RELEASING.md present), and a maintained NEWS.md changelog. No signs of abandonment—this is a Lightbend (formerly Typesafe) core library used across the Akka ecosystem.

Very low risk for core stability; the library has zero external dependencies ("plain Java with no dependencies" per README) and extensive test coverage (test directory structure visible). Risks are minimal: single-maintainer ownership by Lightbend means breaking changes flow top-down, but adoption is wide (Akka/Play depend on it) so breaking changes are rare and well-announced via NEWS.md.

The repo shows active maintenance with CI/CD pipelines configured (ci.yml, release.yml), contributing guidelines in CONTRIBUTING.md, and release procedures in RELEASING.md. Specific ongoing work not visible in file list alone—check GitHub issues and recent commits for current PRs.

git clone https://github.com/lightbend/config.git && cd config && sbt compile && sbt test

Daily commands: sbt compile compiles; sbt test runs the test suite. For interactive exploration: sbt console opens a REPL with the library loaded. No server or daemon—this is a library, not an application.

• config/src/main/java/com/typesafe/config/ConfigFactory.java — Primary entry point for loading and parsing HOCON configurations; every user interaction starts here.
• config/src/main/java/com/typesafe/config/impl/ConfigParser.java — Core parsing engine that tokenizes and builds the AST; all HOCON syntax validation and interpretation happens here.
• config/src/main/java/com/typesafe/config/impl/ConfigImpl.java — Internal implementation backbone managing resolution, merging, and substitution of config values across all formats.
• config/src/main/java/com/typesafe/config/Config.java — Primary public API interface defining all methods users call to query and extract configuration values.
• config/src/main/java/com/typesafe/config/impl/Tokenizer.java — Lexical analyzer that converts raw HOCON text into tokens; foundational to all parsing logic.
• build.sbt — Build configuration defining dependencies, module structure, and release automation for the entire library.
• HOCON.md — Complete HOCON specification document defining syntax, semantics, and features that the parser must implement.

Add support for a new config file format

1. Create a new parser class extending or implementing parsing logic similar to PropertiesParser.java (config/src/main/java/com/typesafe/config/impl/PropertiesParser.java)
2. Register the parser in ConfigDocumentParser.java by adding a new ConfigSyntax enum case and parsing branch (config/src/main/java/com/typesafe/config/impl/ConfigDocumentParser.java)
3. Add the new ConfigSyntax variant to ConfigParseOptions to allow users to specify the format (config/src/main/java/com/typesafe/config/ConfigParseOptions.java)

Implement a custom resource includer for loading configs from a custom source

1. Create a class implementing ConfigIncluder interface with include() and withFallback() methods (config/src/main/java/com/typesafe/config/ConfigIncluder.java)
2. Return ConfigParseable objects from your include methods to parse loaded resources (config/src/main/java/com/typesafe/config/ConfigParseable.java)
3. Pass your custom includer to ConfigParseOptions.withIncluder() when loading configs (config/src/main/java/com/typesafe/config/ConfigParseOptions.java)

Add a new configuration value type with custom parsing and serialization

1. Create a new class extending AbstractConfigValue with your custom type's logic (config/src/main/java/com/typesafe/config/impl/AbstractConfigValue.java)
2. Add a factory method in ConfigValueFactory to construct instances of your type (config/src/main/java/com/typesafe/config/ConfigValueFactory.java)
3. Update ConfigParser or Tokenizer to recognize your type's syntax during parsing (config/src/main/java/com/typesafe/config/impl/ConfigParser.java)

Add environment variable or system property substitution logic

1. Examine SubstitutionExpression to understand how ${var} expressions are parsed (config/src/main/java/com/typesafe/config/impl/SubstitutionExpression.java)
2. Extend resolution logic in ResolveContext.resolve() to handle custom substitution patterns (config/src/main/java/com/typesafe/config/impl/ResolveContext.java)
3. Ensure ConfigResolveOptions allows controlling fallback behavior for missing substitutions (config/src/main/java/com/typesafe/config/ConfigResolveOptions.java)

• Pure Java, no external — undefined

No required environment variables or external services. Key gotcha: substitution resolution happens in a separate phase—reference.conf and application.conf values must be resolved together or substitutions may fail; see the NOTE in README about this. Type coercion is lenient (string "yes" → boolean true) but has limits; check ConfigException for the exact failure modes. Include paths are relative to the config file by default; use file:// or classpath: prefixes to override. Memory size and duration parsing ("512k", "10 seconds") only work in specific config keys if not explicitly requested.

• HOCON (Human-Optimized Config Object Notation) — HOCON is the core format this library parses; understanding its superset features (comments, includes, substitutions, lenient syntax) is essential to using the library effectively
• Configuration substitution and reference resolution — The library's killer feature is substitution syntax (${foo}, ${?bar}, environment variables); understanding the two-phase parsing and resolution model is critical for debugging config merge issues
• Immutable value semantics — All Config and ConfigValue objects are immutable; this design enables thread-safe sharing and predictable config composition via withFallback without side effects
• Type coercion in weakly-typed config systems — The library automatically converts string config values to requested types (boolean, int, duration, memory size); understanding the coercion rules prevents runtime surprises
• Config origin tracking for error diagnostics — ConfigOrigin metadata (file path, line number) is preserved during parsing and merging; this enables precise error messages and debugging of multi-file config inheritance
• Multi-source configuration merging (fallback chains) — The withFallback() mechanism allows composing defaults from reference.conf, application.conf, system properties, and custom sources in a predictable priority order
• Classpath resource resolution with ConfigIncluder — The plugin-style ConfigIncluder interface enables loading configs from files, URLs, or classpath; understanding include resolution order is essential for managing config distribution in JARs

• lightbend/akka — Primary consumer of this library; Akka uses HOCON for actor system configuration (akka.conf files)
• lightbend/play-framework — Play Framework users rely on this library for application.conf and reference.conf management
• lightbend/scala-logging — Companion library in the Lightbend ecosystem; often used alongside Config for application setup
• typesafehub/config-compat — Provides backward compatibility shims for older Config API versions, useful for migration scenarios
• spring-cloud/spring-cloud-config — Spring Framework's equivalent config solution; reference for understanding alternative approaches to distributed config management

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for ConfigNodePath and ConfigNodeInclude parsing edge cases

The repo has complex parsing logic in ConfigNodePath.java and ConfigNodeInclude.java (include file resolution) but these are implementation details with likely incomplete test coverage. New contributors can add edge case tests for path resolution with special characters, circular includes, and malformed include directives. This improves robustness for a critical parsing component.

• [ ] Review existing tests in config/src/test for ConfigNodePath and ConfigNodeInclude coverage
• [ ] Add test cases for edge cases: paths with dots/slashes, circular includes, missing files, relative vs absolute paths
• [ ] Add tests for include file resolution order and precedence (file vs classpath vs URL)
• [ ] Run full test suite to ensure no regressions

Add ConfigLoadingStrategy implementation examples and tests for custom loaders

ConfigLoadingStrategy.java and DefaultConfigLoadingStrategy.java exist but there's no documentation or examples showing how to implement custom loading strategies. The CONTRIBUTING.md doesn't cover this extension point. This is valuable because it's a public API that enables users to customize config loading behavior (e.g., loading from databases, custom file types).

• [ ] Create a new example class in config/src/test showing a custom ConfigLoadingStrategy implementation
• [ ] Add unit tests for the custom strategy (e.g., loading from a mock data source)
• [ ] Add a subsection to CONTRIBUTING.md documenting how to extend ConfigLoadingStrategy with code example
• [ ] Verify the example compiles and tests pass

Expand ConfigMemorySize and duration parsing tests for edge cases and locale handling

ConfigMemorySize.java handles parsing of memory sizes like '512k' and similar parsing exists for durations ('10 seconds'), but these are string-to-numeric conversions that are error-prone across different locales and formats. The test suite likely lacks comprehensive coverage for boundary cases, invalid formats, and internationalization issues.

• [ ] Review existing tests for ConfigMemorySize in config/src/test
• [ ] Add tests for edge cases: zero values, very large values, mixed case inputs ('512K', '512KB'), missing units, invalid units
• [ ] Add tests for duration parsing with various units and spacing variations
• [ ] Add tests for locale-specific decimal separators (comma vs period) if applicable
• [ ] Ensure all tests pass and document any known limitations in HOCON.md

• Add test coverage for edge cases in ConfigMemorySize parsing (e.g., 'KB' vs 'K', fractional sizes like '1.5G'). See config/src/main/java/com/typesafe/config/ConfigMemorySize.java and add tests in the test/ directory for boundary cases.
• Enhance error messages in ConfigException subclasses to include the ConfigOrigin (file:line) in all thrown exceptions. Grep for new ConfigException in impl/ and add origin context to at least 5 currently under-reported failures.
• Document the ConfigIncluder extension points in a new guide section in HOCON.md. The public interfaces ConfigIncluder, ConfigIncluderFile, etc. exist but lack usage examples for custom includers; add 2-3 runnable code examples showing classpath, file, and URL inclusion.

The lightbend/config library demonstrates a generally secure architecture with a zero-dependency design, reducing supply chain risks. However, key vulnerabilities exist around dynamic class instantiation (ConfigBeanFactory), file/URL inclusion mechanisms (ConfigIncluder variants), and potential information disclosure through configuration value serialization. The library is primarily a parser and configuration manager without direct injection risks like SQL or XSS. Main recommendations focus on preventing exploitation of the dynamic loading features when processing untrusted configuration files, implementing strict path validation for includes, and adding sensitive data masking. The codebase appears well-maintained but would benefit from explicit security guidelines in documentation regarding safe configuration sources.

• Medium · Dynamic Class Loading and Reflection — config/src/main/java/com/typesafe/config/ConfigBeanFactory.java. The codebase includes ConfigBeanFactory.java which performs runtime reflection-based object instantiation from configuration values. This could potentially be exploited if untrusted configuration files are parsed, allowing instantiation of arbitrary classes available on the classpath. Fix: Implement strict whitelist validation for class instantiation. Document clearly that configuration files should only be loaded from trusted sources. Consider adding a security manager check or explicit allowlist for classes that can be instantiated.
• Medium · File Inclusion Vulnerability in ConfigIncluder — config/src/main/java/com/typesafe/config/ConfigIncluderFile.java and ConfigIncluderURL.java. The ConfigIncluderFile.java and ConfigIncluderURL.java classes handle file and URL inclusion from configuration directives. Without proper validation, this could allow path traversal attacks or loading of sensitive files if configuration is user-controlled. Fix: Implement path normalization and validation to prevent directory traversal. Restrict include operations to a specific base directory. Add logging for all included files. Document that configuration includes should only reference trusted sources.
• Medium · Potential XML External Entity (XXE) Vulnerabilities — config/src/main/java/com/typesafe/config/impl/PropertiesParser.java. While the codebase primarily handles HOCON and JSON, if PropertiesParser.java or other parsers process external entity references or use XML parsing without proper XXE prevention, it could be vulnerable. Fix: Ensure all XML parsing (if any) has XXE prevention enabled by disabling external entity processing. Review parser implementations for safe deserialization practices.
• Low · Sensitive Information in Configuration Values — config/src/main/java/com/typesafe/config/impl/AbstractConfigValue.java and related value classes. The configuration library can store sensitive values (passwords, API keys, tokens) in ConfigValue objects. If configuration files are logged, cached, or exposed in error messages without sanitization, sensitive data could leak. Fix: Implement toString() overrides that mask sensitive values. Add documentation warning against storing secrets in configuration files. Recommend using environment variables or secure vaults for sensitive data. Implement log filtering for configuration values.
• Low · No Dependency Verification Mechanism — build.sbt. The README indicates 'no dependencies' which is positive from a supply chain perspective, but the build system (build.sbt) should be reviewed to ensure no transitive dependencies are introduced that could pose security risks. Fix: Maintain the zero-dependency policy strictly. Regularly scan build configuration for any transitive dependencies. Use dependency locking in build tools to prevent unexpected dependency injection.
• Low · Missing Security Headers in CI/CD Configuration — .github/workflows/ci.yml and .github/workflows/release.yml. GitHub Actions workflows (ci.yml, release.yml) may need review to ensure secrets are properly handled and build artifacts are signed/verified. Fix: Review CI/CD pipeline to ensure: secrets are not logged, artifacts are signed, build environment variables are properly scoped, and releases are authenticated. Use GitHub's security features like branch protection and required approvals.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.