From 471d6b628ef2bfa493cf0f5b8bdde2d865811064 Mon Sep 17 00:00:00 2001 From: "Gustavo \"Guz\" L de Mello" Date: Fri, 9 Jan 2026 11:18:23 -0300 Subject: [PATCH] chore: developing structure file --- CONTRIBUTING.md | 3 ++ DEVELOPING.md | 130 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 133 insertions(+) create mode 100644 DEVELOPING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index df70dc2..df16f33 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,5 +1,8 @@ # Contribuiting +[See the development guide](./DEVELOPING.md) to know what is the structure of +these initial states of development. + ## Style Guide ### Code diff --git a/DEVELOPING.md b/DEVELOPING.md new file mode 100644 index 0000000..b60df3f --- /dev/null +++ b/DEVELOPING.md @@ -0,0 +1,130 @@ +# DepGraph + +DepGraph is a small website and utility for querying information about project +dependencies count and their licenses. + +This file defines the design of the project and basic guidelines for what will +be develop. + +## Developing + +### Tech Stack + +- Back-end: [Go](https://go.dev); + - Routing: [Smalltrip](https://code.capytal.cc/loreddev/smalltrip). +- Front-end: Server-side generated with [`html/template`](https://pkg.go.dev/html/template) + - [HTMX](https://htmx.org/) for bits of interactivity; + - [TailwindCSS](https://tailwindcss.com/) for some or all styling; + - Hot Reloading will be provided by [`x/xtemplate`](https://code.capytal.cc/loreddev/x/src/branch/main/xtemplate/xtemplate.go). +- Tools: + - Linting: [`golangci-lint`, version 2](https://golangci-lint.run/); + - Formatting: [`gofumpt`](https://github.com/mvdan/gofumpt) and + [`goimports`](https://pkg.go.dev/golang.org/x/tools/cmd/goimports), + both already provided by `golangci-lint`; + - Deployment & Building: [Docker](https://docker.com) and [Nix](https://nixos.org/); + +### Design + +The project design should be language/ecosystem-agnostic, so any sort of +module system of any language can be developed for the project. However, +the main focus will be primarily Go and JavaScript. + +``` +DepGraph + |- cache # Key-Value Cache provider or adapter for DBs + |- repository # Retrievers to get data from Gitea, GitLab, etc + |- service # Transform the data from repositories into a fs.FS + | filesystem that adapters can use + |- adapter # Adapters are who does the magic, they get the + | filesystem and detect files such as go.mod, + | package.json, etc to know what adapter to use + |- adapter/go # Adapter for Go's module system + |- adapter/npm # Adapter for NodeJS/NPM/JavaScript module system + |- router # Router for the web interface and API + |- templates # HTML templates for the front-end + |- cmd # CLI interface of the aplication + |- main.go # Entry point of the program +``` + +After the project is more mature and has a solid working, it may be refactored +to add some more structure to the project and a better CLI, Web API and +interface and Go interface: + +```diff +DepGraph + |- cache # Key-Value Cache provider or adapter for DBs + |- repository # Retrievers to get data from Gitea, GitLab, etc + |- service # Transform the data from repositories into a fs.FS + | filesystem that adapters can use + |- adapter # Adapters are who does the magic, they get the + | filesystem and detect files such as go.mod, + | package.json, etc to know what adapter to use + |- adapter/go # Adapter for Go's module system + |- adapter/npm # Adapter for NodeJS/NPM/JavaScript module system +-|- router # Router for the web interface and API +-|- template # HTML templates for the front-end ++|- api # Code related to the web api and interface ++|- api/router # Router for the web interface and API ++|- api/template # HTML templates for the front-end + |- cmd # CLI interface of the aplication ++|- cmd/cmd.go # Root command of the application ++|- cmd/api.go # Subcommand for running the web interface + |- main.go # Entry point of the program ++|- depgraph.go # Entry point for the Go API interface +``` + +#### Adapters + +##### The Dependency Data Format + +Since for displaying the dependencies we just need a minimal amount of +information, we will probably end up probably end up with a data format/struct +something similar to this pseudo-code: + +```diff +Dependency{ + url: "https://example.com" # The URL of the dependency + (NPM, pkg.go.dev, git repository, etc) + version: "v1.6.9" # The version of the dependency + hash: "ABCDEFGHIJKLMNOPQR" # The HASH of the dependency + dependencies: []Dependency # The dependency's depedencies ++ license: "MIT" # SPDX License, info: https://spdx.dev/ +} +``` + +*Note: the license field is not necessary for the start of development and is +more related for future (possible) features.* + +In other words, it will be a [Tree](https://en.wikipedia.org/wiki/Tree_(abstract_data_type)). + +##### The Go Adapter + +The Go adapter should, in principle, be simple and mostly rely on the +conventions of the Go module system. To reduce the amount of requests +we may need to do for third-party websites, we will try to find multiple files, +from least- to most-request-heavy: + +1. Check for a `go.sum` file + - If the file exists we quit and use it as the "de-facto" list of dependencies; + - To parse it we just need to iterate over each line and get the + `module name`, `version` and `hash` that are separated by spaces. + Check the [`go.sum` file documentation](https://go.dev/ref/mod#go-sum-files); + - The `go.sum` file already has a hash that we can use to pin the + dependency and use on the cache. +2. Check for a `go.mod` file + - If it exists, we use [`golang.org/x/mod/modfile`](https://pkg.go.dev/golang.org/x/mod/modfile) + to parse it and have a list of dependencies; + - To reduce the amount of requests, we just hash the `module-name+version` + combination to use in the cache. We could in the future request each + module files and hash their `go.mod` file like how [`go.sum` does it](https://go.dev/ref/mod#go-sum-files). + 3. If no `go.sum` or `go.mod` file exists, and we want to be feature-complete, + we would then need to download the module source code and use one of: + - Use [golang.org/x/tools/go/packages](https://pkg.go.dev/golang.org/x/tools/go/packages) + - Use `go list -f '{{join .Imports "\n"}}' .`, but it doesn't return the + versions of the packages and needs the source code to be on the OS's + filesystem (There may be some Go interface for this instead of CLI). +- We also would check for `go.work.sum` and `go.work` in the same way to get + workspaces' dependencies. +- This process could be recursive to get *all* dependencies in the project and + don't be limited by just the root. It depends if also Gitea/GitHub's and other + providers' APIs have some endpoint to search specific files.