PeirceMyHeart

PeirceMyHeart is a web application for modeling Charles Peirce's Alpha Existential Graph System, it allows users to construct and prove theorems using Alpha Existential Graphs.

PeirceMyHeart currently works on and is tested aginst Google Chrome and Microsoft Edge. We are in the process of adding Firefox support, most features work on Firefox but there are still some bugs.

How to Run

Click this link to access the application!

...that's it! Get proving!

Development

Developer Details!

All listed commands should be run in the project root (Peirce-My-Heart)

Documentation

The documentation is deployed with the application and can be accessed here

Installing Development Tools

1. Install Node.js and npm. Follow the instructions here

2. Download all dev dependencies using npm. This command will read all dev dependencies from package.json and install them.

npm install 

Familiarizing yourself with Development Tools

We use the following development tools:

1. npm : npm (node package manager) is a package manager for nodejs projects. We use it exclusively to install and manage the rest of our nodejs based development dependencies such as typescript, vite, etc. We also use it to invoke all core development tools via npm run.

2. Vite : Vite is an asset bundler and build system for large web projects with many types of resources such as typescript. Additionally, it provides excellent debugging features. We use it as a build system for Typescript, Asset Compressor, and Live Debugger.

3. gts : gts (Google TypeScript Style) is a set of style guidelines and tools for typescript consistent and readable formatting. It provides defaults for the following tools we use:

   • eslint : an extensible linter for javascript and typescript code. It catches many semantic errors such as unused variables.
   • prettier : an opinionated code formatter that enforces a code style. It enforces syntactic style such as indentation and spacing.

4. Vitest : A unit testing framework native to Vite with support for TypeScript. It allows for github workflow compatibility and running numerous tests with one command.

Linting

Lint the code to make sure your code follows all gts style guidelines. To lint gts will invoke eslint and prettier, based on its defaults and our modifications. Run the following to get style guideline messages about your code:

npm run lint

Github will prevent you from merging your PR until your code meets style guidelines (npm run lint exists with no errors) so it is important to stay on top of this.

gts is a very powerful tool and provides the ability to automatically fix most code you write to be inline with the projects style guidelines. We invoke it through

npm run fix

Building

Build the project to the /dist/ directory using Vite in either development or production mode. In production mode, all code will be compiled and compressed into a single file to ensure extremely fast loading of the web page, however debugging will be impossible. To build in production mode run:

npm run build

In development mode, Vite will include a typescript source map with the compiled js files, allowing you to seamlessly debug the application in browser. To build in development mode run:

npm run build-dev

Debugging

Vite comes bundled with some very powerful debugging tools, the first of which is live recompilation, during which any edits you make to the source file are immediately compiled and changes in the application appear right away in a corresponding web browser window. To open a browser window and start listening for changes you can use the following command:

npm run live-edit

Live editing is very cool but if you want to debug you would have to set breakpoints in the browser debugger which can be annoying. In order to use VS Code debugger while the browser is open is a two step process. First, launch the Vite development server with:

npm run vsc-debug

Then go to the VS Code debug window and select the "Chrome Vite Debug" configuration and run it (Other browsers can be supported through the correct VSC extensions). A new chrome window will open attached to the Vite server, any vs code breakpoints triggered in chrome will be jumped to in VSC.

Testing

Also, test your "backend" changes! Vitest will help here by looking for all .test.ts files in /tests/AEGTree and running them. To perform this locally in a terminal, run the following:

npm run aegtest

Root Files and Folders Overview

/.github/ : The code for github workflows this project uses, used for automatically deploying.

/.vscode/ : .json files necessary to use VSCode as a development environment

/public/ : non-code based resources for the application, icons, images, etc.

/src/ : source code for the application.

/tests/ : testing source .test.ts files made with vitest

/.eslintignore : list of .js and .ts files the linter shouldn't look at

/.eslintrc.json : config for the linter, which catches semantic errors in your typescript code.

/.gitignore : list of files and folders shouldn't be uploaded with git version control

/.npmignore : list of the files NPM shouldn't peep

/.prettierrc.js : config for prettier, which catches syntactic errors in your typescript code.

/LICENSE : The legal jargon for who can use and sell the project.

/package-lock.json : NPM record of all  dependencies and sub-dependencies used for this project.

/package.json : main NPM file, contains information about the project and development dependencies.

/README.md : the information file you're reading right now.

/tsconfig.json : config for the typescript compiler.

/typedoc.json : Documentation generator configuration

/vite.config.js : Vite build system configuration.