Developer tool · Released
wrap-git
Wraps a GitHub profile and returns summarised repositories, commits, language coverage, contributions and a yearly recap.
- verifiedwrap-git README — the package's own account of itself
- TypeScript
- Node.js
- GitHub GraphQL API
The artifact
artifactwrap-git — PACKAGE PAGE ON NPMreserved · 16/10
What it wraps, and why that is not trivial
GitHub’s API answers questions about objects: this account, this repository, this commit. It does not answer questions about a person’s year. Getting from one to the other means knowing which of GitHub’s several activity surfaces to ask, paging through the answers, and reassembling them into a shape a screen can use. The package’s own README describes the job as interacting with the GitHub API with minimal effort and summarising what comes back.wrap-git is that reassembly, published as a dependency rather than copied between projects. Which makes it a contract: a consumer installs a version, imports a function, and is entitled to a typed shape in return. That framing is what makes the rest of this page possible — a contract can be read in full from the outside, and reading it from the outside is exactly what was done, because the source repository is not here.
- verifiedwrap-git README — the package's own account of itself
- verifiedwrap-git 3.0.1 — the published type surface
Who built it
- Engineering role
- Sole author
- Team
- Sole author, on the evidence of the MIT licence shipped inside the package. No collaborator list has been checked.
The surface it commits to
Everything below was read from the package as installed: node_modules/wrap-git, version 3.0.1, pinned in this repository’s lockfile by hash. It describes what shipped. It is not a reading of the source, and it says nothing about how any of this was written, reviewed or tested.The published surface is eleven functions, one error class and six exported types. The functions share one shape — a login first, then whatever the call needs, then an optional token last — so a consumer learns the calling convention once. One transport sits under all of them, a single generic githubGraphQL, which means there is one place a request is formed and one place a failure comes from. That failure is typed: WrapGitError carries a status, a message and a detail string rather than letting a raw rejection reach the caller.The surface is not tidy everywhere. Fifteen functions are declared across the core modules and eleven are exported; calculateGitHubRank, which the shipped README advertises as a feature, is reachable only through the recap’s rank field. Eight any types survive in the public declarations, one of them an entire return shape. The recap returns a key called Commits, capitalised, beside starsEarned and year. And getMonthlyContributions takes a day array rather than a login, which makes it the one exported function that fetches nothing. None of that is inferred from the source; all of it is in the files a consumer installs.
- verifiedwrap-git 3.0.1 — the published type surface
- verifiedwrap-git 3.0.1 — six defects in the published artifact
- verifiedwrap-git README — the package's own account of itself
Published type declarations
The contract a consumer actually receives, readable without the source.
- verifiedwrap-git 3.0.1 — the published type surface
Opportunity and defect register
- verifiedwrap-git — 16 documented gaps and opportunities
Example consumer application
A small Next.js page calling the package directly. It lives in its own repository and is not deployed from here.
- verifiedwrap-git — a separate example application
Correct downstream, or hold the release
Correct downstream, or hold the release
Correct it in the consumer and keep the record. This repository resolves languages by year itself, and the defect became entry 7 of a register kept here — one of two entries marked bug-proven.How this was decided
- Context
- GitFace was built against wrap-git 3.0.1 and found two of its functions wrong rather than merely narrow. getGitHubLanguagesByYear filtered commits by login where the API required an email address, and could see only public owned repositories, so a year spent in private or organization work came back empty. The one-call yearly recap had a defect of its own. Meanwhile the portfolio depends on the published version, not on a working copy.
- verifiedwrap-git — 16 documented gaps and opportunities
- verifiedwrap-git — imported by 7 files in this portfolio
- Options considered
- Ship the affected views with the defect in place
- Hold those views until a corrected version of the package is published
- Implement the correction in the consumer and write the fault down against the package
- verifiedwrap-git — 16 documented gaps and opportunities
- Trade-off
- Two implementations of one idea, and a published package that still carries the fault. Anyone installing 3.0.1 gets the version that was worked around, and the workaround lives in a repository they have no reason to read. That cost is real, and the register exists because of it.What it bought was a view that could be right without waiting on a release, and a written record instead of a silent patch. The register runs to sixteen entries across correctness, scope and cost, each naming the requirement that exposed it and the API change that would close it. It is a list of what is wrong with the author’s own package, kept in the open rather than in his head.
- verifiedwrap-git — 16 documented gaps and opportunities
- verifiedwrap-git 3.0.1 — six defects in the published artifact
- Outcome
- The correction sits in this repository’s data layer. The register is committed here at docs/wrap-git-opportunities.md, sixteen entries, none of them yet closed in a published version — the version this portfolio installs is still 3.0.1, the one the register was written against.
- verifiedwrap-git — 16 documented gaps and opportunities
- verifiedwrap-git v3.0.1 — published package, installed and pinned here
- verifiedwrap-git — 16 documented gaps and opportunities
- verifiedwrap-git — imported by 7 files in this portfolio
- verifiedwrap-git 3.0.1 — the published type surface
- verifiedwrap-git 3.0.1 — six defects in the published artifact
The surface, drawn
- Fig. 1
The whole contract a consumer receives, and the six places it does not hold together. Read from the shipped declarations, not from source.source · wrap-git — the published surface, drawndiagram — drawn from a source audit, not a capture
Using it
Step through the sequence — every step is also readable in order without doing so.
- 01 — A TYPED RESPONSE IN AN EDITORproduct screenwrap-git — A TYPED RESPONSE IN AN EDITORreserved · 16/10
- 02 — THE DEMO APPLICATIONproduct screenwrap-git — THE DEMO APPLICATIONreserved · 16/10
The example consumer
A small application was built to call the package directly rather than through this portfolio. It is a separate project in its own repository, and it is not embedded or deployed here.
Nothing on this page executes wrap-git. Every statement about the package was read from the files it ships, not from watching it run.
Not built yet — an embedded version of those calls, replaying recorded responses so a reader never meets a rate limit. Live execution can replace it later without a content change.
What is actually known
- Published version
- 3.0.1Pinned in this repository’s lockfile by integrity hash. It is the version installed here and the version everything on this page was read from.
- Public surface
- 11 functions, 6 types
- verifiedwrap-git 3.0.1 — the published type surface
- Documented faults
- 16 entries
- verifiedwrap-git — 16 documented gaps and opportunities
- Consumers verifiable from here
- 1
- verifiedwrap-git — imported by 7 files in this portfolio
Evidence
9 sources · how each was obtained
- verifiedwrap-git v3.0.1 — published package, installed and pinned herenpm-package · attests existence · captured 2026-08-19declared ^3.0.1 in package.json; package-lock pins wrap-git-3.0.1.tgz by sha512 integrity; 39 files, 128 KB on disk; MIT licence naming Smachew Gedefaw C., dated Nov 2025Proves that a package of this name and version was published and is installed here. It carries no figure for installs, dependents or use by anyone, and none should be inferred from it.
- verifiedwrap-git 3.0.1 — the published type surfacenpm-package · attests structure · captured 2026-08-19read the shipped .d.ts files: 11 exported functions, 1 error class and 6 exported types; 15 functions declared across the core modules; one generic transport githubGraphQL<T>; 8 any types in the public declarationsRead from the published artifact rather than from source. It shows what shipped. It says nothing about how any of it was written, reviewed or tested, and nothing about what happens when it runs.
- verifiedwrap-git 3.0.1 — six defects in the published artifactnpm-package · attests structure · captured 2026-08-19module field resolves to ./dist/index.mjs, which the package does not ship (main and types both resolve); author field is an empty string; the shipped README advertises calculateGitHubRank, which is not exported; 4 of 15 declared functions are unexported; 8 any types in the public surface; the recap returns Commits capitalised beside starsEarned and yearFaults in the published artifact only. They say nothing about the source repository, its history, its tests or how the package was developed — only about what a consumer receives on install.
- verifiedwrap-git README — the package's own account of itselfdocument · attests existence · captured 2026-08-1997 lines shipped inside the package; read in fullEstablishes what the package claims to do and how it asks to be called. It is the author's description, not an independent check that any of it behaves as described.
- verifiedwrap-git — imported by 7 files in this portfoliorepository · attests structure · captured 2026-08-19grep for imports from ‘wrap-git’ across src: 7 files, including src/app/api/github/route.ts and src/lib/github-activity.tsProves this portfolio depends on the package. One consumer, written by the same author, is not evidence of adoption and is not offered as any.
- verifiedwrap-git — 16 documented gaps and opportunitiesdocument · attests existence · captured 2026-08-19176 lines, 16 entries numbered 1-15 plus 7b, authored while building GitFace against the package; 2 marked bug-provenA register of known faults, written by the package's own author. It records what was found; it is not itself a test.
- verifiedwrap-git — a separate example applicationrepository · attests existence · captured 2026-08-1917 commits, sole author, December 2025; a Next.js page whose wrap-git-consuming component is 16 lines, the remainder being generated shadcn and Radix primitivesA local working copy, and a different repository from the one the package declares as its source. Its total line count is dominated by generated UI files, so the authored work is the 16-line component and nothing more should be read into its size.
- provisionalwrap-git — repository URL declared by the packageexternal-reference · attests existence · captured 2026-08-19repository.url reads git+https://github.com/sgc93/wrap-git-ts.git; homepage reads https://smachewgedefaw.vercel.appThe package declares this URL. It was not fetched from this machine, so whether it resolves, and what it contains, are unconfirmed here.
- provisionalwrap-git — the published surface, drawnFig. 1diagram · attests structure · drawn 2026-08-21drawn from ev.wrapgit.public-surface and ev.wrapgit.package-defects; the eleven exported names, six types, one transport and six defects are read off the shipped declarationsAn illustration, not a capture. It depicts the shape the source audit established, and it is provisional because a person drew it and nobody can re-run drawing. It is not evidence that the system behaves as drawn. It describes the published package only. Nothing on it says how the package was written, reviewed or tested.
Links
Still open
What this case study does not yet cover, and what would close it.
Awaiting a written account
- The constraints this was built under were not recorded.
Never measured
- Start and end dates were never recorded for this project.
- No outcome was measured while this project was active.
- Commit history for this project has not been audited.
Awaiting first-person reflection
- What this project taught has not been written up yet.
- A first-hand account of this work has not been written yet.