Open Source Engineering as a Product Discipline

Publishing source code to a public repository is trivial. Building, distributing, and sustaining an open-source library or tool that other engineering teams can safely embed into their critical production infrastructure is an entirely different engineering discipline.

Many open-source initiatives falter not because their underlying algorithms are flawed, but because they treat open source as a code dump—a one-time release thrown over the wall without operational rigor. In private application development, engineers share unspoken institutional knowledge: team conventions, internal documentation, direct Slack channels for debugging, and the ability to coordinate breaking changes across co-located codebases in a single atomic commit.

In open source, that shared context disappears. Your consumers are distributed across different time zones, running diverse operating systems, binding against different runtime versions, and operating under strict uptime and security requirements. They cannot ask the original author for an ad-hoc architecture walkthrough.

Every artifact published to the world—the repository layout, public API surface, distribution tarball, package export map, automated continuous integration (CI) pipeline, issue template, and semantic version tag—functions as an interface. Open-source engineering is therefore a product discipline: it requires treating consumer trust, API boundary isolation, supply-chain verification, and contributor ergonomics as core architectural requirements rather than afterthoughts.

---

1. The Core Paradigm: Open Source as a Public Product

When an engineering team consumes an open-source dependency, they take on an architectural dependency and a long-term operational commitment. If a library introduces an unannounced breaking change in a minor release, leaks private types into public entry points, or ships an unsigned tarball containing malicious dependencies, the downstream impact can cause production outages or security incidents.

Treating open source with product discipline means engineering for predictability across every phase of the library's lifecycle.

| Dimension | Casual Code Sharing | Product-Discipline Open Source | | :--- | :--- | :--- | | API Boundary | Everything in src/ exported arbitrarily | Minimal public exports; private internals strictly encapsulated | | Compatibility Contract | Ad-hoc versioning based on maintainer sentiment | Strict Semantic Versioning 2.0.0; automated breaking-change detection | | Distribution Hygiene | Raw source files or monolithic bundles published | Dual-module packaging (ESM/CJS conditional exports), stripped tarballs | | Dependency Topology | Core frameworks bundled as direct dependencies | Host runtimes isolated via strict peerDependencies | | Supply Chain Security | Mutable git tags; unpinned third-party actions | Immutable commit SHA pinning, SLSA provenance, Sigstore/Cosign signing | | Quality Verification | Local test passes on maintainer's workstation | Multi-platform, multi-runtime CI matrices with automated doctest validation | | Contributor Onboarding | Undocumented local workstation dependencies | Hermetic environments (Devcontainers/Nix), reproducible task runners | | Architecture Evolution | Maintainer merges PRs based on intuition | Formal RFC process, Architectural Decision Records (ADRs), issue forms |

The Consumer Trust Contract

At the heart of production open source lies the Consumer Trust Contract. This contract is governed by two complementary principles: Semantic Versioning and Hyrum's Law.

+-------------------------------------------------------------------------+
|                        THE PUBLIC TRUST CONTRACT                        |
|                                                                         |
|  Semantic Versioning (Explicit Contract)                                |
|  - MAJOR: Incompatible API breaks (type changes, removals)              |
|  - MINOR: Backwards-compatible features, non-breaking additions         |
|  - PATCH: Backwards-compatible defect and security fixes                |
|                                                                         |
|  Hyrum's Law (Implicit Contract)                                        |
|  - "With sufficient users, all observable behaviors are depended on."  |
|  - Observable timing, map iteration order, error messages, side effects |
|                                                                         |
|  Defensive Architecture (Maintainer Enforcement)                       |
|  - Minimal exported API surface area                                    |
|  - Encapsulated internal implementation details (e.g. src/internal/)    |
|  - Intentional randomization of non-contractual behaviors               |
|  - Automated static type & ABI drift detection in CI                    |
+-------------------------------------------------------------------------+

Semantic Versioning 2.0.0 (MAJOR.MINOR.PATCH)

Semantic Versioning (SemVer) is not a loose suggestion; it is a formal state machine that governs dependency resolution in package managers like npm, Cargo, Pip, and Pub.

Under SemVer:

1. PATCH (e.g., 1.2.3 -> 1.2.4): Allocated strictly for backwards-compatible bug fixes. It must not alter existing function signatures, change public runtime behavior, or introduce new features.
2. MINOR (e.g., 1.2.3 -> 1.3.0): Allocated for new, backwards-compatible capabilities. New classes, functions, or optional parameters may be introduced, but existing consumer code must compile and run without modification. Deprecation warnings for planned breaking changes may be introduced here.
3. MAJOR (e.g., 1.2.3 -> 2.0.0): Allocated for any backwards-incompatible modification. Removing a public method, reordering required arguments, widening error scopes, or narrowing return types requires a major version increment.

In statically typed ecosystems (TypeScript, Rust, Go, Dart), subtle changes that appear non-breaking at runtime can break consumer compilation:

• Adding an optional parameter to an interface or abstract class: In languages like TypeScript or Dart, if consumers implement that interface rather than just call it, adding a new member breaks downstream implementations.
• Narrowing return types or widening parameter types: Changing a return type from User | null to User or altering parameter contravariance can trigger compiler errors in strict typing configurations.
• Exporting re-exported external types: If your library exports a type from an underlying dependency, updating that dependency to a new version constitutes a breaking change for your library.

Hyrum's Law in Practice

Formulated by software engineer Hyrum Wright, Hyrum's Law observes:

"With a sufficient number of users of an API, it does not matter what you promise on the contract: all observable behaviors of your system will be depended on by somebody."

When an open-source tool gains widespread adoption, consumers inevitably couple their applications to observable implementation quirks that were never part of the documented contract:

• The iteration order of keys returned by an internal dictionary or map.
• The exact phrasing of an error message string checked by downstream regular expressions.
• The precise millisecond timing or microtask scheduling of an asynchronous call.
• The order in which lifecycle hooks or event listeners fire.

If maintainers refactor internal code and change an undocumented behavior, consumers experience it as a breaking change. To defend against Hyrum's Law without freezing implementation development forever:

1. Intentionally randomize non-contractual behaviors: Go's runtime famously randomizes map iteration orders across executions specifically to prevent downstream developers from relying on deterministic dictionary sorting.
2. Standardize and type error payloads: Never rely on raw string error messages for error identification. Provide typed error classes with static error codes (e.g., code: 'ERR_INVALID_PAYLOAD'), discouraging consumers from parsing message text.
3. Sanitize public events and side effects: Ensure internal state mutations are batched and emitted through intentional, deterministic event interfaces.

Information Hiding & API Surface Minimization

Every class, function, type, and constant exported from a package's entry point represents an immutable compatibility commitment until the next major version release. A sprawling public API surface dramatically expands maintenance overhead, restricts refactoring opportunities, and increases vulnerability to Hyrum's Law.

                      PACKAGE BOUNDARY ISOLATION
                      
    CONSUMER APPLICATIONS (External Import)
           |
           | import { EngineClient } from '@pkg/core'
           v
    +-------------------------------------------------------------+
    | PUBLIC API ENTRYPOINT (src/index.ts / lib.rs / lib/pkg.dart)|
    | - EngineClient (class)                                      |
    | - ClientOptions (interface)                                 |
    | - ExecutionResult (type)                                    |
    +-------------------------------------------------------------+
           | (Internal Wiring Only)
           v
    +-------------------------------------------------------------+
    | PRIVATE / INTERNAL IMPLEMENTATION (src/internal/*)          |
    | - BufferManager (memory allocator)                          |
    | - SocketProtocolHandler (transport logic)                   |
    | - TokenBucketRateLimiter (internal rate limiting)           |
    | - TelemetryBatchProcessor (metrics collector)               |
    +-------------------------------------------------------------+
           ^
           | (BLOCKED: Compiler / Tooling Enforces Isolation)
    CONSUMER ATTEMPTS DIRECT IMPORT:
    import { BufferManager } from '@pkg/core/internal/buffer' 
    ❌ REJECTED BY EXPORT MAP / COMPILER VISIBILITY RULES

Different ecosystems provide distinct mechanisms to enforce encapsulation:

• Go: Any package residing inside a directory named internal/ (e.g., pkg/core/internal/codec) cannot be imported by any package outside the parent directory tree. The Go compiler enforces this rule at build time.
• Dart / Flutter: Code placed in lib/src/ is considered private implementation detail by convention. The Dart analyzer emits diagnostic warnings if an external package attempts to import files from package:<name>/src/.
• TypeScript / Node.js: The package root entrypoint (src/index.ts) selectively re-exports public symbols. Modern Node.js exports maps in package.json prevent consumers from deep-importing internal files (e.g., importing my-lib/dist/internal/helper.js will trigger a runtime package path resolution error).

---

2. Packaging, Distribution & Supply Chain Security

Building robust software locally is only half the battle. How artifacts are packaged, distributed, and cryptographically verified determines whether downstream consumers can safely install them.

Modern Dual-Module Packaging in TypeScript/JavaScript

In modern JavaScript and TypeScript environments, package maintainers must support two distinct module systems: ECMAScript Modules (ESM) using import / export, and legacy CommonJS (CJS) using require() / module.exports.

Failing to configure dual packaging properly leads to the Dual Package Hazard. If an application or its transitive dependencies import both the ESM and CJS builds of the same package within a single Node.js process:

• Two independent instances of the module's code are loaded and executed.
• Module-level state, singletons, and memory caches are duplicated.
• instanceof checks fail because class definitions across the two instances refer to distinct object prototypes in heap memory.

Modern package authors resolve this using conditional exports maps in package.json. The order of conditions inside exports is critical: TypeScript and Node.js evaluate conditions sequentially. The "types" condition must always appear first.

{
  "name": "@openstair/resilience-core",
  "version": "1.4.0",
  "description": "Deterministic circuit breaker and fault tolerance primitives for distributed services.",
  "license": "Apache-2.0",
  "type": "module",
  "main": "./dist/cjs/index.cjs",
  "module": "./dist/esm/index.js",
  "types": "./dist/types/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/types/index.d.ts",
      "import": "./dist/esm/index.js",
      "require": "./dist/cjs/index.cjs"
    },
    "./telemetry": {
      "types": "./dist/types/telemetry.d.ts",
      "import": "./dist/esm/telemetry.js",
      "require": "./dist/cjs/telemetry.cjs"
    },
    "./package.json": "./package.json"
  },
  "files": [
    "dist",
    "README.md",
    "LICENSE"
  ],
  "sideEffects": false,
  "engines": {
    "node": ">=18.0.0",
    "npm": ">=9.0.0"
  },
  "peerDependencies": {
    "typescript": ">=5.0.0"
  },
  "peerDependenciesMeta": {
    "typescript": {
      "optional": true
    }
  },
  "publishConfig": {
    "access": "public",
    "provenance": true
  }
}

Key fields in this production configuration:

• "files" whitelist: Only the compiled dist/ artifacts, README.md, and LICENSE are included in the published tarball. Test suites, benchmarks, internal scripts, and CI configurations are excluded, reducing download sizes and attack surfaces.
• "sideEffects": false: Informs bundlers (Webpack, Rollup, Vite, esbuild) that importing the package causes no global side effects (such as modifying window or registering global polyfills). This enables tree-shaking to eliminate unused code.
• "publishConfig.provenance": true: Signals npm to generate a cryptographic SLSA provenance attestation during GitHub Actions publishing using OpenID Connect (OIDC).

Dependency Topology: Peer Dependencies vs Direct Dependencies

A frequent error in library design is declaring host runtime libraries or framework bindings as direct dependencies rather than peerDependencies.

                  DEPENDENCY TOPOLOGY HAZARDS
                  
  INCORRECT: Direct Dependency        CORRECT: Peer Dependency
  
      Host Application                    Host Application
     /                \                  /                \
    v                  v                v                  v
 React 18.2      ComponentLib         React 18.2      ComponentLib
                      |                                    |
                      v                                    | (peer: ^18.0)
                  React 18.3                               v
                                                   (Resolves to Host)
  Result: Two copies of React in heap!  Result: Single shared instance.
  Contexts fail, hooks crash.           Contexts & hooks work reliably.

If a UI component library or state management plugin lists react or @angular/core under dependencies:

• The package manager may install two distinct versions of the framework: one in the root node_modules and another nested under node_modules/my-library/node_modules/react.
• When the application runs, React hooks throw invariant violations (Invalid hook call: Cannot read properties of null (reading 'useContext')) because the library executes against a secondary, uninitialized React instance.
• Bundle sizes inflate as the entire runtime framework is duplicated in the client bundle.

Rule: Any dependency where the library expects to share singletons, context instances, or global runtime state with the host application must be defined as a peerDependency. Use peerDependenciesMeta with "optional": true when a feature is an optional integration.

Software Supply Chain Security & Provenance

Modern package registries (npm, PyPI, crates.io, RubyGems) have become prime targets for software supply chain attacks. Common threat vectors include account takeover of maintainers, typo-squatting, malicious pull request injection, and compromised build runners.

To protect consumers, production-discipline open source applies four defense-in-depth layers:

1. Software Bill of Materials (SBOM): An SBOM provides a machine-readable, cryptographically verifiable inventory of every direct and transitive dependency included in a release. Industry standards include CycloneDX and SPDX. Generating an SBOM in CI allows consumers to scan for known Common Vulnerabilities and Exposures (CVEs) before deploying.
2. SLSA (Supply-chain Levels for Software Artifacts) Provenance: SLSA establishes verifiable standards for build integrity. Generating SLSA Level 3 provenance in CI guarantees that published binaries or tarballs were produced by an authorized workflow from a specific, un-tampered commit SHA in the official repository, eliminating build-runner tampering.
3. Sigstore & Cosign Artifact Signing: Sigstore provides keyless cryptographic signing backed by OpenID Connect (OIDC) identities (such as a verified GitHub Actions runner token) and a public transparency log (Rekor). Consumers verify signatures using tools like cosign verify to ensure the release was produced by the legitimate repository pipeline.
4. Immutable Action Pinning: GitHub Actions workflows must pin third-party actions to full 40-character hexadecimal commit SHAs rather than mutable git tags or branches (e.g., actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 rather than actions/checkout@v4). Tags can be maliciously rewritten if an upstream maintainer account is compromised.

Licensing Models & Intellectual Property

Choosing a license determines how organizations can evaluate, adopt, and contribute to an open-source project. An ambiguous or absent license prevents enterprise adoption.

| License | Category | Patent Grant Provision | Patent Retaliation Clause | Copyleft Scope | Source Code Disclosure | | :--- | :--- | :--- | :--- | :--- | :--- | | MIT | Permissive | Silent (No express patent license) | None | None | None (Attribution notice only) | | Apache 2.0 | Permissive | Express worldwide patent license | Express termination if consumer sues on patents | None | None (Attribution and notice of changes) | | MPL 2.0 | Weak Copyleft | Express worldwide patent license | Express patent retaliation termination | File-level copyleft | Modifications to licensed files must be open | | GPLv3 | Strong Copyleft | Express worldwide patent license | Express patent retaliation termination | Whole-program (Derivative work) | Complete source code must be shared under GPLv3 |

Apache 2.0 vs. MIT

While both MIT and Apache 2.0 are permissive licenses, the Apache License 2.0 is generally preferred for production infrastructure, libraries, and developer tools:

• Section 3 (Patent Grant): Every contributor explicitly grants licensees a perpetual, worldwide, non-exclusive, royalty-free patent license covering patent claims necessarily infringed by their contribution.
• Patent Defense / Retaliation Clause: If a consumer or licensee initiates patent litigation against any entity alleging that the software infringes their patents, any patent licenses granted to that litigant under the Apache 2.0 license terminate immediately.

This provides substantial legal protection for both maintainers and downstream consumers that the shorter, copyright-only MIT license does not address.

DCO vs. CLA

To ensure incoming contributions can be legally licensed without future ownership disputes, maintainers use one of two mechanisms:

• Developer Certificate of Origin (DCO 1.1): Contributors append a standard sign-off to git commits (git commit -s, generating Signed-off-by: Jane Doe <jane@example.com>). This certifies that the contributor created the patch, had the right to submit it under the project's open-source license, and made it publicly available. It incurs zero administrative friction.
• Contributor License Agreement (CLA): A formal legal contract signed by individual contributors or their employers, often assigning copyrights or providing broad intellectual property licenses to a governing foundation or company. While CLAs provide maximum corporate protection, they often discourage casual community contributions.

---

3. Automated CI/CD Quality Gates & Release Automation

Relying on maintainers to remember every validation step—linting, formatting, type checking, cross-platform compilation, and API consistency checks—is a recipe for broken releases. Production open source codifies all quality gates into deterministic, automated CI/CD workflows.

                           CI/CD RELEASE PIPELINE
                           
    Pull Request Opened
           │
           ▼
    +─────────────────────────────────────────────────────────────+
    | Matrix Validation: Ubuntu, macOS, Windows × Node 18, 20, 22 |
    | ├── Lint & Formatting (Prettier / ESLint)                   |
    | ├── Type Integrity (tsc --noEmit)                           |
    | ├── API Surface Boundary Check (No internal type leaks)     |
    | ├── Automated Doctest Verification (README code runs)       |
    | └── Test Matrix with Unit & Integration Coverage            |
    +─────────────────────────────────────────────────────────────+
           │
           ▼ (All matrix jobs pass & PR merged to main)
    +─────────────────────────────────────────────────────────────+
    | Release Orchestration (Changesets / Semantic Release)        |
    | ├── Conventional Commits parsed (feat, fix, feat!)          |
    | ├── Semantic Version computed automatically                 |
    | ├── CHANGELOG.md generated with migration notes             |
    | ├── Git commit tagged (v1.4.0)                              |
    | ├── SLSA provenance attestation generated                   |
    | └── Tarball published to registry with OIDC token           |
    +─────────────────────────────────────────────────────────────+

Multi-Platform, Multi-Runtime Matrix Testing

Software that executes flawlessly on a maintainer's macOS workstation can fail on a consumer's Windows or Linux CI server:

• Path separator differences: Windows uses backslashes (\), whereas POSIX systems use forward slashes (/). Hardcoded string concatenation of paths breaks immediately on Windows.
• File locking semantics: Windows prevents deleting, renaming, or modifying open file descriptors; POSIX allows unlinking open files.
• Line ending quirks: CRLF versus LF can break regex parsers, checksum verifiers, and script interpreters.
• Runtime LTS variance: New language syntax or standard library methods introduced in Node.js 22 (or Python 3.12) will throw runtime syntax errors if executed on supported LTS versions such as Node.js 18.

CI workflows must run automated test suites against a full matrix of operating systems (ubuntu-latest, macos-latest, windows-latest) and supported runtime LTS versions.

Automated API Breaking Change Detection

Human code review frequently misses subtle API breaking changes. An interface field might be made non-optional, a generic constraint might be narrowed, or a return type signature might lose an overloaded variant.

Static analysis tools catch these regressions before a pull request can be merged:

• TypeScript: @microsoft/api-extractor analyzes exported declarations and generates an API report file (etc/my-package.api.md). This report documents the exact public API surface. If a PR alters the public API, the report file changes. If the change was accidental or unreviewed, CI fails.
• Rust: cargo-semver-checks inspects the crate's public API against the previously published version on crates.io, automatically flagging breaking changes that require a major version bump.
• Dart: pana (Package Analysis) validates platform interfaces, dependency constraints, and documentation scores.

Automated Example & Doctest Verification

One of the quickest ways an open-source project loses credibility is publishing a README.md whose getting-started snippet fails to compile. As codebases undergo refactoring, documentation examples silently go stale unless they are executed as part of the test suite.

Production projects enforce documentation accuracy by:

1. Extracting code snippets from Markdown files into ephemeral test files during CI.
2. Compiling and running the snippets against the current build.
3. Treating any documentation compilation failure as a blocking test failure.

Production-Grade GitHub Actions Workflow

Below is a hardened, production-ready GitHub Actions CI configuration implementing matrix testing, immutable commit SHA action pinning, least-privilege token permissions, and automated API checks.

name: CI & Quality Gates

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

permissions:
  contents: read

jobs:
  validate:
    name: Matrix Test (${{ matrix.os }} - Node ${{ matrix.node-version }})
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        node-version: [18.x, 20.x, 22.x]

    steps:
      - name: Checkout repository
        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2

      - name: Setup Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
        with:
          node-version: ${{ matrix.node-version }}
          cache: "npm"

      - name: Hermetic dependency installation
        run: npm ci --ignore-scripts

      - name: Code formatting & lint verification
        run: npm run lint

      - name: Static type check
        run: npm run typecheck

      - name: API boundary & internal leak validation
        run: node scripts/verify-api-boundaries.mjs

      - name: Execute test suite with coverage
        run: npm test -- --coverage

      - name: Verify README code examples (Doctest)
        run: npm run test:doctests

      - name: Compile distribution bundles
        run: npm run build

      - name: Dry-run package distribution tarball
        run: npm pack --dry-run

---

4. Architectural Boundary Enforcement in Practice

To prevent developers from accidentally exposing internal helpers or leaking private types through public exports, high-discipline projects implement automated boundary validators.

The following self-contained TypeScript utility uses the official TypeScript Compiler API to traverse a package entrypoint (src/index.ts), inspect every exported symbol, and verify that no return type, parameter, or type reference leaks internal classes or types declared within src/internal/ or decorated with @internal.

import ts from "typescript";
import path from "node:path";

export interface BoundaryViolation {
  exportName: string;
  kind: "Value" | "Type";
  leakedSymbolName: string;
  declarationFilePath: string;
}

/**
 * Validates that public entrypoints do not leak internal symbols
 * defined in private/internal subdirectories or marked with @internal.
 */
export function validateApiBoundaries(
  entrypointPath: string,
  tsconfigPath: string
): { success: boolean; violations: BoundaryViolation[] } {
  // 1. Parse tsconfig.json using TypeScript system APIs
  const configFile = ts.readConfigFile(tsconfigPath, ts.sys.readFile);
  if (configFile.error) {
    throw new Error(`Failed to read tsconfig: ${configFile.error.messageText}`);
  }

  const parsedConfig = ts.parseJsonConfigFileContent(
    configFile.config,
    ts.sys,
    path.dirname(tsconfigPath)
  );

  // 2. Initialize the TypeScript Program and Type Checker
  const program = ts.createProgram([entrypointPath], parsedConfig.options);
  const checker = program.getTypeChecker();
  const sourceFile = program.getSourceFile(entrypointPath);

  if (!sourceFile) {
    throw new Error(`Entrypoint file not found: ${entrypointPath}`);
  }

  const violations: BoundaryViolation[] = [];
  const entrySymbol = checker.getSymbolAtLocation(sourceFile);

  if (!entrySymbol) {
    return { success: true, violations: [] };
  }

  // 3. Inspect every publicly exported symbol
  const exportedSymbols = checker.getExportsOfModule(entrySymbol);

  for (const exp of exportedSymbols) {
    const declarations = exp.getDeclarations() || [];
    for (const decl of declarations) {
      inspectNodeForLeaks(decl, exp.getName(), checker, violations);
    }
  }

  return {
    success: violations.length === 0,
    violations,
  };
}

function inspectNodeForLeaks(
  node: ts.Node,
  exportName: string,
  checker: ts.TypeChecker,
  violations: BoundaryViolation[]
): void {
  // Traverse AST children to locate referenced type nodes or signatures
  node.forEachChild((child) => {
    if (ts.isTypeNode(child) || ts.isTypeReferenceNode(child)) {
      const type = checker.getTypeFromTypeNode(child);
      const symbol = type.aliasSymbol || type.getSymbol();
      if (symbol) {
        verifySymbolOrigin(symbol, exportName, violations);
      }
    }
    // Recurse into child nodes (e.g. method signatures, parameter lists)
    inspectNodeForLeaks(child, exportName, checker, violations);
  });
}

function verifySymbolOrigin(
  symbol: ts.Symbol,
  exportName: string,
  violations: BoundaryViolation[]
): void {
  const declarations = symbol.getDeclarations() || [];

  for (const decl of declarations) {
    const filePath = decl.getSourceFile().fileName;

    // Check if the declaration resides inside an internal/ or private/ directory
    const isInternalPath = /[/\\](internal|private)[/\\]/.test(filePath);

    // Check if the declaration contains an @internal JSDoc annotation
    const hasInternalTag = ts
      .getJSDocTags(decl)
      .some((tag) => tag.tagName.text === "internal");

    if (isInternalPath || hasInternalTag) {
      violations.push({
        exportName,
        kind: symbol.flags & ts.SymbolFlags.Type ? "Type" : "Value",
        leakedSymbolName: symbol.getName(),
        declarationFilePath: filePath,
      });
    }
  }
}

Running this script in pre-commit hooks and CI quality gates prevents internal refactoring changes from accidentally becoming public API commitments.

---

5. Contributor Ergonomics & Maintainer Governance

Even with pristine code, open-source projects fail when maintainers suffer burnout or contributors struggle with hostile onboarding processes. Good governance and ergonomics build sustainable human systems around the code.

Hermetic Developer Environments

The phrase "works on my machine" is the hallmark of inadequate project tooling. If contributing to a repository requires installing specific global CLI versions, configuring undocumented environment variables, or debugging platform-specific node-gyp build failures, prospective contributors will abandon their pull requests.

Hermetic developer environments eliminate workstation drift:

• Devcontainers (.devcontainer/devcontainer.json): Configures an isolated, containerized VS Code or IDE environment pre-populated with required SDKs, linters, extensions, and database dependencies.
• Nix Flakes: Provides cross-platform, hermetic dependency sandboxes with exact cryptographic hashes for compilers, runtimes, and system binaries.
• Zero-Assumption Setup Scripts: If containers or Nix are impractical, provide a single deterministic setup task (e.g., pnpm run bootstrap or make setup) that validates prerequisites, installs pinned dependencies using frozen lockfiles, and runs local tests cleanly.

RFC Process & Architectural Decision Records (ADRs)

In mature open-source projects, significant features are not implemented on a whim through massive unsolicited pull requests. Unsolicited architectural PRs force maintainers into an uncomfortable dilemma: reject hundreds of hours of volunteer effort or accept code that misaligns with the project's long-term vision.

To avoid this friction:

1. Request for Comments (RFC) Process: For non-trivial features, public API changes, or architectural shifts, maintainers require an RFC. The RFC document details the problem statement, proposed API syntax, backwards compatibility impact, alternatives considered, and adoption tradeoffs. The community discusses the design asynchronously before any implementation code is written.
2. Architectural Decision Records (ADRs): Stored directly in the repository (e.g., docs/decisions/0004-use-webcrypto-over-node-crypto.md), ADRs capture the context, options evaluated, and rationale for major architectural choices. When future contributors ask why a certain library or pattern was chosen, the ADR provides permanent institutional memory, preventing repeated debates over settled decisions.

Structured Issue Forms & Sustainable Triage

Issue trackers easily devolve into unstructured complaint forums if maintainers allow free-form text submissions. Unstructured reports like "It doesn't work" require multiple rounds of back-and-forth questioning just to identify the operating system, package version, and reproduction steps.

Modern open-source engineering uses GitHub Issue Forms (defined via declarative YAML files in .github/ISSUE_TEMPLATE/):

• Mandatory reproduction fields requiring a minimal, runnable GitHub repository or StackBlitz / CodeSandbox link.
• Dropdown menus pinned to supported versions.
• Checkboxes confirming the user has searched existing open and closed issues.
• Separation between bug reports, feature proposals, and community questions (directing questions to GitHub Discussions or Discord rather than the bug tracker).

---

6. Actionable Production Verification Checklist

Before publishing any open-source package or major release, evaluate the project against this production checklist:

Repository Architecture & Encapsulation

• [ ] Public API surface is explicitly declared in root entry points; private implementation resides in encapsulated directories (src/internal/ or lib/src/).
• [ ] Export boundary validator script executes in CI, verifying that no private types or classes are leaked.
• [ ] Non-contractual behaviors (iteration order, error strings) are insulated against Hyrum's Law through typed errors or intentional randomization.

Packaging, Distribution & Dependency Topology

• [ ] Dual-module packaging (exports map with "import", "require", and "types") is validated without the Dual Package Hazard.
• [ ] The "types" condition is placed first in conditional exports maps.
• [ ] Host runtimes and shared frameworks (React, Angular, TypeScript) are declared under peerDependencies, not dependencies.
• [ ] Package tarball whitelist ("files" array in package.json) excludes test suites, internal scripts, and CI configurations.
• [ ] "sideEffects": false is specified if the package has no global runtime side effects.

CI/CD Quality Gates & Automation

• [ ] Test matrix executes across Linux (ubuntu-latest), macOS (macos-latest), and Windows (windows-latest).
• [ ] Test matrix validates all actively supported runtime LTS versions.
• [ ] Automated breaking change detection (api-extractor, cargo-semver-checks, or pana) verifies ABI stability on every PR.
• [ ] Documentation code snippets and README.md examples are compiled and verified as automated doctests.
• [ ] Third-party GitHub Actions are pinned to immutable 40-character commit SHAs.
• [ ] Default workflow token permissions are restricted to permissions: contents: read.

Supply Chain Security & Licensing

• [ ] SLSA build provenance attestations are enabled during release publication.
• [ ] Software Bill of Materials (SBOM) generation (CycloneDX or SPDX) is integrated into release builds.
• [ ] Repository includes a formal open-source license file (preferably Apache 2.0 or MIT).
• [ ] Developer Certificate of Origin (DCO sign-offs via git commit -s) or CLA automation is enforced on pull requests.
• [ ] A dedicated SECURITY.md file defines a private vulnerability disclosure channel.

Contributor Ergonomics & Governance

• [ ] Hermetic developer environment provided via Devcontainers, Nix, or a single-command setup script.
• [ ] Structured GitHub Issue Forms enforce minimal reproductions and environment specifications.
• [ ] Major architectural changes require an asynchronous RFC prior to pull request submission.
• [ ] Settled architectural decisions are documented as version-controlled Architectural Decision Records (ADRs).

---

7. Conclusion: Building Sustainable Open-Source Systems

Open-source engineering is not simply traditional software engineering made public. It is a specialized product discipline that demands clarity, defensive API design, supply-chain paranoia, and deep empathy for downstream consumers.

When an open-source project provides clear boundaries, deterministic packaging, automated quality gates, and transparent governance, it builds enduring trust. Downstream engineering teams can integrate the software knowing their builds will not randomly fail on a Friday afternoon due to an unannounced breaking change or an insecure transitive dependency.

By applying product discipline to open source, maintainers protect their code, protect their community, and build tools that stand the test of time.