Summary:
This provides a command-line entry point `load-plugin-v3` (which will
become `load-plugin` eventually), which fetches the GitHub data via
GraphQL and saves the resulting `RelationalStore` to disk.
A change to the Babel config is needed to prevent runtime errors of the
form `_callee7` is not defined, where `_callee7` is a gensym that is
appears exactly once in the source (in use position, not definition
position). I’m not sure exactly what is causing the error or why this
config change fixes it. But while this patch may be fragile, I don’t
think that it’s likely to subtly break anything, so I’m okay with
pushing it for now and dealing with any resulting breakage as it arises.
Paired with @decentralion.
Test Plan:
Run `yarn backend`, then run something like:
```
node bin/sourcecredV3.js load-plugin-v3 \
sourcecred example-github --plugin github
```
Inspect results in `SOURCECRED_DIR/data/OWNER/NAME/github/view.json`,
where `SOURCECRED_DIR` is `/tmp/sourcecred` by default, and `OWNER` and
`NAME` are the repository owner and name.
This example repository takes about 1.1 seconds to run. The SourceCred
repository takes about 45 seconds.
wchargin-branch: cli-load-plugin
Summary:
Due to oclif’s structure, this entry point shares its `commands`
directory with that of the V1 entry point. We’ll therefore add commands
like `start-v3` as we go.
Test Plan:
`yarn backend` works, and `node bin/sourcecredV3.js start` launches the
V1 server.
wchargin-branch: v3-cli
This adds additions and deletions to the v3 Pull data model, and also
uses them in the pull descriptions.
It's basically a port of #340 to v3.
Test plan: Snapshots
This adds methods for serializing the GitHub RelationalView.
We have not put in the work to ensure that these methods generate
canonical data. Getting the issues in a different order, or finding
references in a different order, can change the JSON output even if the
resulting repositories are equivalent.
@decentralion think it's not worth putting in the effort, since we may
switch to a SQL database soon anyway.
Test plan: travis
Paired with @wchargin
Now that we want to implement RelationalView de/serialization, we need a
way to construct one without adding data to it.
Now that we're allowing `addData` to be called explicitly, we also want
to make sure it's idempotent, which necessitated a small change to
reference handling. A new test verifies idempotency.
Test plan: travis
Paired with @wchargin
Summary:
This makes progress on #432. We’d like to look for GitHub references
only within each text node of the Markdown AST. But there are two
complications:
- Text nodes split across formatting, and it’s valid for someone to
write `*Paired* with @decentralion, but *tested* independently`, or
`**Closes** #12345`, or something.
- Sometimes contiguous blocks of text expand to multiple text nodes,
because of how CommonMark approaches smart punctuation. For
instance: the document `It's got "punctuation" and stuff!` has eight
text nodes ([demo][1]).
In this commit, we introduce functions `deformat` and `coalesceText` to
solve these problems. (They go together because `coalesceText` is useful
for testing `deformat`.)
[1]: https://spec.commonmark.org/dingus/?text=It%27s%20got%20%22punctuation%22%20and%20stuff!
wchargin-branch: markdown-deformat
Summary:
We plan to use this to more intelligently extract references from GitHub
text content. See #432.
Test Plan:
In a Node shell, running
```js
const cm = require("commonmark");
var parser = new cm.Parser();
var ast = parser.parse("Hello\nworld");
var html = new cm.HtmlRenderer({softbreak: " "}).render(ast);
console.log(html);
```
prints `<p>Hello world</p>`.
wchargin-branch: commonmark
This commit adds a `description` method that takes a GitHub entity, and
returns a description of that entity. Based on the work in #261.
In contrast to the implementation in #261:
- It won't crash on entities without an author (although we don't have a
test case for this; see #389).
- It handles multi-authors reasonably (although we can't test that, as
we haven't implemented multi-authorship yet; see #218).
Test plan:
Inspect snapshot to see some examples.
Currently, GitHub tests load example data with ad-hoc methods. It makes
it easy for the author of a new test file to forget to clone the test
data (and risk cross-test-file state pollution), or to forget to apply
the correct typing.
This commit factors a shared `example` module which provides a safe way
to access the example data, along with some convenient helpers for
constructing a graph or relational view.
Test plan:
`yarn travis`
Fixes#430.
The Git and GitHub plugins have folders that contain small example data,
as used for tests and snapshots. These folders were called `demoData`
which is misleading since the data isn't used for demos. The folders
themselves contained files called "example", like "example-github.json"
or "exampleRepo.js". Renaming the folders to `example` is cleaner.
Test plan:
`yarn travis --full` passes.
This is a very simple extension of #431 to use the new reference
detection logic added in #429.
Test plan:
Inspect snapshot change for plausibility. Note that the snapshot adds
exactly 16 reference edges, which is the same as the number of
references in the reference snapshot test.
This commit modifies `github/createGraph` to use the `RelationalView`
class created in #424. The code is now much cleaner.
I also fixed some `any`s that were leaking in our test code (due to use
of runtime require for GitHub example data). These anys were discovered
by bumping into uncaught type errors. :)
This commit supersedes #413 and #419.
Test plan:
Observe that the graph snapshot was not changed.
For every `TextContentEntity` (`Issue`, `Pull`, `Review`, `Comment`),
this commit adds a `references` method that iterates over the entities
that the text content entity references.
For every `ReferentEntity` (actually, every entity), this commit adds a
`referencedBy` method which iterates over the text content entities that
reference that referent entity.
This method also adds `referentEntities` and `textContentEntities`
methods to the `RelationalView`, as they are used in both implementation
and test code.
Test plan:
The snapshot tests include every reference, in a format that is very
convenient for inspecting the ground truth on GitHub. For every
reference, it's easy to check that the reference actually exists by
copying the `from` url and pasting it into the browser. I've done this
and they check out. (It's not easy to prove that there are no missing
references, but I'm pretty confident that this code is working.)
Unit tests ensure that the `references` and `referencedBy`
methods are consistent.
Based on offline design discussion with @wchargin, we've decided to
upgrade the `RelationalView` to be *the* comprehensive source for GitHub
data inside SourceCred. The `RelationalView` will contain the full
dataset, including parsed relational information (such as
cross-references between GitHub entities). Then, we will project our
GitHub graph out of the `RelationalView`.
To that end, the `RelationalView` no longer exports raw data blobs.
Instead, it exports nice classes: `Repo`, `Issue`, `Pull`, `Review`,
and `Userlike`. These classes have convenient methods for accessing both
their own data and related entities, e.g. `repo.issues()` yields all
the issues in that repo.
This is effectively a port of #170 into the v3 API. The main difference
is that in v1, the Graph contained this data store, whereas in v3, we
will use this data store to generate the graph.
This supersedes #418.
Test plan:
The snapshot tests are quite readable.
Summary:
This is based on the V1 file `basicPagerank.js`. The API is necessarily
changed for the new graph format, and we export additional utilities
compared to the previous version of the module (useful for testing and
serialization). We also improve the implementation to make it simpler
and easier to understand.
Test Plan:
Unit tests included.
wchargin-branch: v3-graph-markov-chain
Summary:
We’d like to use this test case to generate a Markov chain, which
requires that it not be local to the `graph.js` tests.
Test Plan:
Existing unit tests suffice.
wchargin-branch: expose-advanced-graph
Summary:
This code is independent of the graph abstraction, and so is mostly
copied. The only change is to the structure of the test code (we now
prefer to wrap everything in a big `describe` block with an absolute
path to the module under test).
Test Plan:
Unit tests included.
wchargin-branch: v3-markov-chain
This code is about parsing references out of text, so `parseReferences`
is a better name.
The code that consumes this logic to find all the references in the
GitHub data shall be rightly called `findReferences`
Test plan:
`yarn travis`
Summary:
Closes#417. Submodule commits are dead; long live commits. The ontology
is now:
- A tree includes tree entries.
- A tree entry may have a blob as contents.
- A tree entry may have a tree as contents.
- A tree entry may have a commit as contents.
Test Plan:
Existing unit tests suffice, especially `#commits yields all commits`.
wchargin-branch: git-remove-submodule-commits
Summary:
Submodule commits need not have associated tree objects, in case the
repository to which they belong does not exist in our graph. We’d like
to represent submodule commits as actual commits, which necessitates
this change. See #417 for context.
Test Plan:
Existing unit tests suffice.
wchargin-branch: git-affine-trees
Summary:
This commit adds logic to create the Git graph, modeled after the GitHub
graph creator in #405. In this commit, we do not include the
corresponding porcelain; a Git `GraphView` will be added subsequently.
Kudos to @decentralion for suggesting in #187 that I write the logic to
detect BECOMES edges against the high-level data structures. Due to that
decision, the logic and tests are copied directly from the V1 code
without change, because the high-level data structures are the same. The
new code is exactly the body of the `GraphCreator` class.
Test Plan:
Verify that the new snapshot is likely equivalent to the V1 snapshot,
using the heuristic that the two graphs have the same numbers of nodes
(59) and edges (84). (I have performed this check.)
wchargin-branch: git-v3-create-graph
The `RelationalView` maps the GitHub GraphQL response data into a View
class, which makes it easy to access pieces of GitHub data by their
corresponding `StructuredAddress`.
This will be a valuable companion to the graph, making it possible to
access GitHub node data like the title or body of an issue via the
issue's address. This basically is the supplement to the GitHub graph
that includes the "payloads" from our v1 Graph.
It will also make creating the GitHub graph a lot more convenient,
although I've left that for another commit.
Designed with feedback from @wchargin.
Note: The `RelationalView` objects have a `nominalAuthor` rather than
`author`, so as to distinguish between authorship in the GitHub data
model (entities have at most one author) and in the SourceCred model
(entities may have multiple authors).
Test plan:
Inspect the included snapshots for reasonability, and run unit tests.
The code will be refactored so that references are expressed in terms of
the GitHub node address code; the implementation is copied first so that
the review will be cleaner.
Test plan:
`yarn travis` passes.
Summary:
The public method `checkInvariants` on graph is now cached. The cache is
invalidated when the graph is modified via the public API. As a result
of this change, the time of `yarn ci-test --testPathPattern src/v3/`
decreases from 5.631s to 3.866s (best-of-three timing, but low variance
anyway). This effect becomes much more pronounced as higher-level APIs
check their own invariants by themselves indirectly invoking the graph’s
`checkInvariants` method many times.
Test Plan:
Existing unit tests have been adapted and extended. Tests for the
invariant checking have been updated to call the internal, uncached
method, and new tests have been added to check that the caching behavior
is correct.
wchargin-branch: cache-graph-invariants
This commit:
- adds `github/createGraph.js`
- which ingests GitHub GraphQL response
- and creates a GitHub graph
- adds `github/graphView.js`,
- which takes a Graph
- and validates that all GitHub specific node and edge invariants hold
- every github node may be parsed by `github/node/fromRaw`
- with the right node type
- every github edge may be parsed by `github/edge/fromRaw`
- with the right edge type
- with the right src address prefix
- with the right dst address prefix
- every child node has exactly one parent
- of the right type
- and provides convenient porcelain methods for
- finding repos in the graph
- finding issues of a repo
- finding pulls of a repo
- finding reviews of a pull
- finding comments of a Commentable
- finding authors of Authorables
- finding parent of a ChildAddress
- tests `createGraph`
- via snapshot testing
- by checking the GraphView invariants hold
- tests `graphView`
- by checking individual entities in the example-git repository have
the proper relationships
- by checking that for every class of invariant, errors are thrown if
the invariant is violated
Test plan:
- Extensive unit and snapshot tests added. `yarn travis` passes.
Summary:
This is modeled after the GitHub edge module format. In particular, the
whole length encoding garbage is directly copied. As in that module, we
decline to test the error paths.
Test Plan:
Unit tests added; run `yarn travis`. Snapshots are readable.
wchargin-branch: git-v3-edges
Summary:
This is modeled after the GitHub node module format, with the obvious
alterations plus a bit more type safety in the implementation of `toRaw`
(namely, we check `type` exhaustively).
Test Plan:
Unit tests added; run `yarn travis`.
wchargin-branch: git-v3-nodes
Summary:
Many files are unchanged. Some files have had paths updated, or new
build/test targets added.
The `types.js` file includes payload type definitions. These are
technically independent of the graph abstraction (i.e., nothing from V1
is imported and the code all still works), but it of course implicitly
depends on the V1 model. For now, we include the entirety of this file,
just so that we have a clean copy operation. Subsequent commits will
strip out this extraneous code.
Suggest reviewing with the `--find-copies-harder` argument to Git’s
diffing functions.
Test Plan:
Running `yarn travis --full` passes. Running
./src/v3/plugins/git/demoData/synchronizeToGithub.sh --dry-run
yields “Everything up-to-date”.
wchargin-branch: git-v3-copy
Summary:
We had `edgeExamples`, wherein we constructed examples of edge addresses
(not actual edges) by manual instantiation. We checked that these
matched snapshots, and then we also called `createEdge` a bunch to
create actual edges, and checked that those matched snapshots, too.
Consequently, we had twice as many snapshots as we needed, and also
defined twice as many edge addresses as we needed.
Test Plan:
Note that snapshot contents are either deleted or unchanged.
wchargin-branch: simplify-github-edge-tests
Test Plan:
Observe that the new snapshots are easier to read. Might as well make
sure that they encode the same data as the old snapshots, too. Note that
the backslash character no longer appears in this snapshot file. :-)
wchargin-branch: use-edgeToParts
Summary:
We have `edgeToString`, which formats edges as nicely human-readable
strings. However, these strings have some quotes in them, and so when
they are themselves stringified (e.g., as part of a Jest snapshot), they
become much harder to read. We thus introduce `edgeToParts` to make our
snapshots more readable.
Test Plan:
Unit tests added; run `yarn travis`.
wchargin-branch: add-edgeToParts
Summary:
In #394, we uppercased the constants for GitHub node types. However, we
were using string literals instead of constants in the test cases. These
test cases were supposed to cover every error path, but instead ended up
just covering the “bad type” error path many times.
Any one of the following would have prevented this regression:
1. using string constants instead of literals in the test case;
2. throwing and checking more precise error messages; or
3. being alerted that coverage decreased as a result of the change.
In this commit, we enact the first of these options. I’m open to adding
a coverage bot, but don’t feel strongly about it at this time.
Test Plan:
Running `yarn coverage` now shows 100% coverage for the `nodes.js`
module, whereas previously almost all `throw fail();` lines were
uncovered (and the branch coverage was just 76%).
wchargin-branch: fix-github-node-error-tests
- Switch string constant node and edge types (e.g. "REPO") to exported
consts (eg `export const REPO_TYPE`).
- Add (and internally use) a `_Prefix` psuedomodule which contains
per-type address prefixes
- Test that constructing a StructuredAddress with the wrong type is an
error.
Test plan:
Unit tests pass, snapshots unchanged.
Paired with @wchargin
Summary:
This fixes up all instances of `fromParts([])` that are not in
`address.js` or `address.test.js`.
Paired with @decentralion.
Test Plan:
Running `git grep --name-only -F 'fromParts([])'` yields only the two
modules listed above. Existing unit tests suffice for correctness.
wchargin-branch: use-address-empty
Summary:
This can make invocations of `FooAddress.fromParts([])` a bit more
succinct.
Paired with @decentralion.
Test Plan:
Unit tests added. Run `yarn travis`.
wchargin-branch: address-empty
Similar to #390, we now allow filtering the results from `Graph.edges`
by address prefixes. It's a little more complicated than #390, as we
allow filtering by src, dst, or address.
Test plan:
Unit tests added. `yarn travis` passes.
Paired with @wchargin
Simple API addition to match v1/v2 semantics.
In the future, we can perf optimize this if we switch graph to
store nodes organized by shared prefixes.
Test plan:
Unit tests were added. `yarn travis` passes.
Paired with @wchargin
Summary:
This module includes a raw edge type, a structured edge type, and edge
creation functions that take source and destination and create an edge.
Test Plan:
Unit tests added. These cover all of the successful cases, and none of
the unsuccessful cases. We plan to refactor this code Soon™, and it is
hard to see how to nicely factor the tests without just testing the same
code paths over and over.
wchargin-branch: github-edges
William Chargin
Dandelion Mané