A rust reimplementation of good-fences:
Good-fences is a tool that allows you to segment a TypeScript project into conceptual areas and manage dependencies between those areas. This is mostly a concern for large projects with many people working on them, where it is impossible for every developer to have a wholistic understanding of the entire codebase. JavaScript's module system is a specialized form of anarchy because any file can import any other file, possibly allowing access to code that was really meant to be an internal implementation detail of some larger system. Other languages have concepts like DLL boundaries and the internal keyword to mitigate this. Good-fences provides a way to enforce similar boundaries in the TypeScript world.
The original good-fences implementation came with some limitations:
- Its native dependencies only supported Node.js < v15.
- It had performance issues in some of our biggest projects (scanning 40k+ files).
Rust's safe concurrency and memory safety allows us to re-write original project with additional performance benefits, leaning on swc for javascript/typescript parsing.
good-fences-rs
includes a CLI and an API, under the name @good-fences/api
.
Compatible with x86
and x64
windows and linux platforms.
Linux:
GCLIB
>= 2.27 (preinstalled with ubuntu 18)- Node.js > 14
npm
Via npm.
npm install -g @good-fences/api
Cloning the repo:
git clone https://github.com/Adjective-Object/good-fences-rs-core
cd good-fences-rs-core
yarn
yarn run build
npm install @good-fences/api
Use it in your project:
import { goodFences } from '@good-fences/api';
goodFences({...});
To run the good-fences
cli we need at least two things:
fence.json
configuration files.- A
tsconfig.json
file. (see tsconfig reference)
Let's assume a project like this:
├── my-project
│ ├── src
│ │ ├── **/*.ts
| | ├── index.js
| │ ├── fence.json
| tsconfig.json
From your terminal you can run this:
cd my-project
good-fences src
[paths]
: the cli takes only thepaths
argument, a list, separated with spaces, of all directories that are going to be scanned.
If you have your tsconfig file splitt and want to use the one containing compilerOptions.paths
instead of the default tsconfig.json
good-fences src --project tsconfig.with-paths.json
In cases like the one above, it could be that different tsconfig files have different compilerOptions.baseUrl
configuration, you can override that valua from your specified --project
file with --baseUrl
flag.
good-fences src --project tsconfig.without-baseurl.json --baseUrl .
The --output
flag takes a path. At the end of checking, fence violation errors will be saved to the provided path as json.
good-fences src --output fenceViolations.json
cat fenceViolations.json
For some cases, scanning your cwd
could be needed but most projects have node_modules
that isn't necessary to perform evaluations, in those cases --ignoreExternalFences
makes good-fences skip all directories and files from node_modules
.
good-fences . --ignoreExternalFences
This takes a list of regular expressions as input values, separated with spaces. In case certain directories need to be ignored during the fence evaluation, this will perform regular expression matching on fence paths to ignore them (e.g. --ignoredDirs lib
will not evaluate files under any lib
directory).
good-fences src --ignoredDirs ignored1 ignored2 ...
Development from windows happens in a devcontainer
- Install WSL2 (and restart your computer)
wsl --install
from any terminal window
- Install Docker Engine (and restart your computer)
- Install workspace recommended plugins (including the Dev Containers plugin)
- Build the container with
Ctrl+P > Dev Containers: Rebuild and Reopen in Container
- If installation stalls on
docker inspect --type image ubuntu:24.10
, you may need to feth the base image manually - Run
docker inspect --type image ubuntu:24.10
- If it fails with
Error response from daemon: No such image: ubuntu
, then rundocker pull ubuntu:24.10
- If installation stalls on
- Develop in the container
- (optional) mount the workspace you are building against.
To test
unused-finder
against your repo during development, uncomment the commented-out "mount" in the checked-in.devcontainer
:The provided example mounts// This mounts client-web checked out next to this repo for testing, left checked-in here for convenience. // Don't commit it, though! // "source=${localWorkspaceFolder}/../client-web,target=/workspaces/client-web,type=bind,consistency=cached",
client-web
as a target repo