Detecting Stale Registry Stubs with Execution Smoke Tests

Your internal registry lists 420 shared packages. A developer pulls @internal/session-keys into a critical path, runs the build, and hits an immediate failure: the entry point requires a build artifact that was never published, or it imports a missing native binding. The package has existed in the index for two years. It has a name, a semantic version, a README, and an owner who left the company eighteen months ago.

It is not a component. It is a registry stub: a row in a database holding valid metadata around dead code.

Why Manifests Hide Broken Code

Registry crawlers and package managers inspect manifests, not execution paths. If package.json or pyproject.toml contains valid syntax and points to a file that physically exists on disk, indexing tooling marks the item healthy. The catalog counter increments.

This is the primary reason why registry metadata misrepresents component health. A manifest records authorial intent at the moment of publishing; it does not guarantee that the module can run inside a current environment. A component count is not an inventory. An inventory requires verifying that the asset can be loaded into memory and executed.

Common failure modes that bypass manifest validation:

• Missing transitive bindings: The code imports an unlisted peer dependency or assumes a global runtime variable that was deprecated.
• Unresolved build steps: The manifest points main to dist/index.js, but the publish pipeline skipped the compile step, leaving the target missing or empty.
• Rotten environment assumptions: The module relies on legacy runtime flags or outdated standard library behaviours that throw unhandled exceptions upon import.
• Empty exports: The entry point exists, but an unresolved cyclic dependency causes it to export undefined.

The Minimum Viable Execution Test

You do not need an exhaustive integration suite to detect registry stubs. You need a repeatable smoke harness that treats the artifact as an untrusted black box and verifies basic execution.

A minimal execution test exercises three stages in an isolated process:

1. Resolution and import: Load the declared entry point into an isolated runtime. If the module throws on evaluation, fails to resolve an internal import, or exits non-zero, it is dead.
2. Export shape validation: Inspect the loaded module namespace. If the export map is empty, exports undefined, or fails to export named symbols declared in its types or manifest, the contract is broken.
3. Callable invocation: If the module exports pure functions or constructors with documented default fixtures, invoke them once.

Here is the pattern implemented as a self-contained Node.js harness:

import { pathToFileURL } from "node:url";
import { resolve } from "node:path";

export async function smokeTest(pkgPath, entryRel) {
  const target = pathToFileURL(resolve(pkgPath, entryRel)).href;
  
  let mod;
  try {
    mod = await import(target);
  } catch (err) {
    return { verdict: "FAILED", reason: `Import threw: ${err.message}` };
  }

  const keys = Object.keys(mod);
  if (keys.length === 0 && typeof mod.default === "undefined") {
    return { verdict: "FAILED", reason: "Module exports nothing" };
  }

  const undefinedExports = keys.filter((k) => typeof mod[k] === "undefined");
  if (undefinedExports.length > 0) {
    return { verdict: "FAILED", reason: `Undefined exports: ${undefinedExports.join(", ")}` };
  }

  return { verdict: "PROVISIONAL", exports: keys };
}

This harness separates functional validation into explicit verdicts:

• FAILED: The entry point could not be imported, threw during top-level evaluation, or produced empty exports.
• INCONCLUSIVE: The harness cannot construct the required runtime context or input parameters. This marks a boundary of the harness, not a proven defect in the artifact.
• PROVISIONAL: The module imports cleanly and exports well-formed primitives, but full correctness under production workloads has not been asserted.
• CERTIFIED: The module imports cleanly, satisfies its export contract, and passes explicit property-based tests under isolated execution.

Running this check against an internal index separates actual assets from rows in a database. If an artifact cannot survive an isolated import, remove it from the catalog. Manifests do not run in production; executables do.