Skip to content

[plugins] npm resolution (PR #3): robust npm pack parse, fetcher-dir contract, docs #5

Closed

Description

@kreneskyp

Context

feat/npm-source-resolution (PR #3) lands npm source resolution: resolveSource({type:"npm", …}) → resolveNpm → defaultNpmFetcher (npm pack + tar), exact-version caching, version-as-sha pin, plus the npmPackArgs helper and an option-like-package injection guard. It is green (tsc, 100% coverage, eslint, quire) and smoke-tested live (npm pack is-number@7.0.0 resolved + cached). A /code-review pass found the non-blocking items below.

Tasks

  • Medium — fragile npm-output parse. defaultNpmFetcher (src/resolve.ts ~lines 54–61) does JSON.parse(out.slice(out.indexOf("[")))[0]. A prepack/prepare script that prints a [ (e.g. [build] done) makes indexOf land on the wrong bracket and the parse throws; if there is no [, indexOf returns -1, slice(-1) yields the last char, and JSON.parse/[0] throw a cryptic error. Fix: parse npm's --json output robustly (e.g. take the last JSON value, or guard idx < 0 / empty-array and throw a descriptive SourceError). Add a test with prepack-style noise / no-bracket output.
  • Medium — undocumented fetcher contract. resolveNpm cache-hit (src/resolve.ts ~lines 167–178) returns dir: <cacheDir>/package, ignoring the dir a custom NpmFetcher returned on the miss path. A custom fetcher that extracts elsewhere is authoritative on miss but silently overridden on later resolves. Fix: document that an NpmFetcher MUST extract to <destDir>/package, or persist + read the fetcher's returned dir.
  • Low — stale docs (now also npm). Update: resolveSource docstring "git is the only side effect"; ResolveOptions.cacheRoot comment (only mentions <cacheRoot>/git/<key>); ResolvedSource.sha comment "(git sources)". All now also apply to npm sources.
  • Low — disk accumulation. The unpinned-spec re-fetch path leaves the prior tarball in cacheDir; clean it up.

Acceptance criteria

  • Prepack-noise / no-bracket npm output handled gracefully (descriptive error, with a test).
  • Fetcher <destDir>/package contract documented (or the returned dir honored).
  • Docstrings updated; src/resolve.ts stays at 100% coverage.

References

  • PR: feat: resolve npm sources via npm pack #3 · branch feat/npm-source-resolution
  • Spec: spec/functional/FR-004-source-resolution.md
  • Related: the option-like-package guard already added in this PR (reqArg in src/sources.ts, FR-004-CON-3) — see the git-hardening issue for extending it to git fields.

Activity

  1. kreneskyp commented on Jun 28, 2026

    @kreneskyp
    ContributorAuthor

    Build-out complete — pushed to feat/npm-source-resolution (PR #3), commit dfb3cd6. All four review follow-ups implemented with Red-Green TDD.

    • Medium — fragile npm-output parse: extracted pure exported parseNpmPackJson(out) that scans every candidate [ and returns the first parsing to a non-empty JSON array, so prepack/prepare stdout noise (e.g. [build] done) no longer mis-parses; no-bracket / empty-array output now throws a descriptive SourceError instead of a cryptic crash. (+3 tests)
    • Medium — fetcher-dir contract: documented on NpmFetcher that a fetcher MUST extract to <destDir>/package, and that an exact-version cache hit serves <cacheDir>/package directly (custom dir honored on miss, ignored on later cached resolves).
    • Low — stale docs: resolveSource side-effect note, ResolveOptions.cacheRoot, and ResolvedSource.sha now all cover npm sources.
    • Low — disk accumulation: unpinned re-fetch now rmSynces the cache dir before re-extract so stale tarballs don't pile up. (+1 test)

    Gates: tests 31 passed (+4) · src/resolve.ts 100% coverage · tsc --noEmit clean · eslint + prettier clean · quire validate clean (pre-existing warnings only).

    Note: the make lint wrapper's nested format:check fails on a pre-existing corepack version mismatch (configured pnpm@10.33.4 vs installed 11.5.2) — unrelated; eslint + prettier pass run directly. Worth aligning packageManager.

  2. kreneskyp commented on Jun 28, 2026

    @kreneskyp
    ContributorAuthor

    Merged. PR #3 (npm source resolution + these review follow-ups) squash-merged to main as 4d7b41d. All four follow-ups (robust npm-pack parse, fetcher-dir contract, stale docs, cache hygiene) are in main, plus the spec backsync (FR-004-AC-12/13, CON-4, TC-027/028). First leg of the kit release train done.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    pluginsPlugin system / discovery / marketplace

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions