Skip to content

About

Understand your codebase (without really reading it)

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

13 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Projections

Understand your codebase (without really reading it)

At this point, there's simply too much code to actually read it line-by-line... but that doesn't mean we shouldn't understand the systems we create and are responsible for. Projections is a prototype for creating repeatable, customizable representations of your codebase, for both points in time (e.g. commits) and changes (e.g. pull requests). You can use projections to illustrate module dependencies, service architectures, database schemas, security policies, tool output, and really anything you can imagine. Projections are deterministic by default, but can contain generative aspects when useful.

To get started, you can give your agent this prompt:

Set up Projections by following https://github.com/githubnext/projections/blob/main/SETUP.md, configure/implement a few projections specifically for my codebase, and show them to me in the viewer.

Alternatively, head to the quick start guide and first projection guide.

Projections is an early exploration by GitHub Next. Feel free to open a Discussion or chat with us on X!

An animated dependency graph of a simple shop application: OrderService, which both controllers inject and which depends on the repository, payments and order search, turns red and leaves; CheckoutService, which takes the repository and payments, and OrderQueries, which takes only search, arrive

The Mechanics

Every projection has three components:

  • Extractor: Creates a static JSON representation of your system. Runs on compute you control (e.g. GitHub Actions or dev machines), and can use any language, dependencies, or tools you like. You can perform static code analysis, run scripts, boot your server locally, etc. Determinism is strongly recommended but not enforced.
  • Comparator: Diffs two extractions to determine what changed and what stayed the same. A default is built in, and custom ones are implemented using Common Expression Language rules. Deterministic, and can run anywhere.
  • Renderer: Displays extractions and their comparisons. Implemented in JavaScript (e.g. React), run in a browser.

You can mix-and-match built-in and custom implementations within a projection. For example, you could write a custom extractor to derive the structure of your application components based on your team's conventions, while using the default comparator and the general graph renderer.

flowchart LR
  repo[Your repository] --> extractor[Extractor] --> extraction[(Extraction)]
  extraction --> comparator[Comparator] --> comparison[(Comparison)]
  extraction --> renderer[Renderer]
  comparison --> renderer
Loading

Built-ins

Projections has a variety of built-in extractors, comparators, and renderers. Here are some example projections you can make with them:

Public API

Show what interface changes will break callers.

Four breaking changes to a TypeScript client library: Client.search removed, a required Response.headers added, createClient taking an options object, and withRetry removed

Pipelines

Show the stage dependencies in your CI workflows.

A CI workflow: the deploy job is removed, e2e and deploy-staging run after build, and deploy-production waits for both of them

Security policy

Show what behaviors runtime security policies will restrict.

A Tetragon credentials policy: its scope broadened from payments to checkout and payments, a new rule that kills curl and wget reading the service account token, newly enforced, and the security_mmap_file hook no longer covered

There are also built-ins provided for dependency injection, database schemas, infrastructure plans, dependencies, command output, and a bunch more. Check out the gallery and the docs for more.

Status

Projections is an early prototype, pre-1.0. Features are incomplete, breaking changes are basically guaranteed, and there's no way all the documentation is correct. Nonetheless, if you're so inclined, we'd really love for you to give it a try and let us know what you think!

About

Understand your codebase (without really reading it)

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages