Inspect source repositories

Source Code & Repository Inspection

A README describes what the author hoped to build; the source code and tests reveal what actually runs. Always verify critical technical claims in primary source code.

Workflow

1. Pin the exact version and commit:
   • Record the repository URL, release tag or version, commit SHA, and inspection date for every finalist (owner/repo@<commit-sha> or vX.Y.Z).
   • Cite specific file paths and line ranges (path/to/file.ts#L42-L88) for every non-trivial architectural claim.
2. Inspect the manifest and entry points first:
   • Read package.json / Cargo.toml / pyproject.toml / composer.json / go.mod:
     • Check exports / main / bin entry points, engine/runtime constraints, peer dependencies, and native addon hooks (binding.gyp, preinstall, postinstall).
     • Count and inspect direct and heavy transitive dependencies.
3. Trace the critical path from public API to execution:
   • Follow the actual call graph of the feature we need:
     • Public API function -> input validation -> state/memory management -> I/O or subprocess boundary -> error handling and retries -> cleanup/disposal.
   • Check for hidden global singletons, blocking synchronous I/O, swallowed errors, hardcoded timeouts, or assumptions about filesystem/network access.
4. Interrogate tests and examples for realism:
   • Read the test suite (test/, spec/, __tests__/):
     • Do tests exercise real edge cases, concurrency, malformed inputs, and failure recovery, or do they only mock out the hard parts?
     • Do example scripts work against current APIs, or are they broken artifacts from an older major version?
5. Scan issues, PRs, and release notes for sharp edges:
   • Search open and recently closed issues/PRs for keywords matching our use case (memory leak, ESM, Windows, timeout, streaming, concurrency, breaking).
   • Distinguish between a finished, stable, small library (few recent commits because its scope is complete and bug-free) and an abandoned broken project (unanswered breaking bugs against current runtimes).

Anti-Patterns to Avoid

• Claiming full codebase review after skimming two files: State explicitly which modules and code paths were inspected and which were not.
• Treating dead or feature-flagged stubs as working features: Verify that exported functions are wired to real logic, not TODO placeholders or cloud-only endpoints.