13 repositories, 13 bugs: what open source taught me about my own tool

I built a tool that draws architecture diagrams from a repository, where every edge cites the file, line and commit it came from. Then I ran it against thirteen repositories it had never seen, and every single one of them found something wrong with it. There were thirteen. These are the ones worth writing down. The list says nothing about those codebases. It says something about testing: a tool that reads other people's repositories has to be tested against other people's repositories, and there is no substitute. The rule the tool works by Nothing is drawn that cannot be cited. Every edge in the output carries the file, the line and the commit that justifies it — click an arrow, see the import statement. If a reference cannot be resolved to something in the repository, it is not quietly dropped and it is not guessed at. It is reported as a gap. That second half is what made these bugs findable. A tool that silently drops what it cannot resolve looks perfect and is useless. A tool that reports gaps by name and count tells you, loudly, every time it is confused. Java: a library sharing your package prefix is not you Guava declares com.google.common . Truth is a separate library, and it lives in com.google.common.truth . My resolver matched on package prefixes, so Truth looked like Guava's own code, and every reference to it became a gap against a package Guava does not contain. 834 false gaps — 28% of the repository. The fix is to require the next path segment to look like a type before peeling, because com.google.common.truth.Truth peels to a package and com.google.common.collect.ImmutableList peels to a class, and those are different shapes. Java: a file importing its own nested type Java requires the import for a nested enum constant even inside the same file. Treating that as a dependency has you drawing an arrow from a file to itself. It accounted for all 137 remaining gaps on Spring Boot and all 34 on Guava. Java: static imports point one segment too deep import