PRINCIPLES.mdb

These are principles we try to follow as a team working on this product. Anyone can suggest additions or edits. 

## 0. Application architecture
1. Use React as a thin view layer unless absolutely necessary, presenting state that is defined outside of React.

2. Never directly import a method from the WASM module (although it is tempting!). Always pass in our WASM instance as a dependency instead. This anti-pattern was removed in #9415.

3. Reduce the usage of circular dependencies in src/lib/singletons.ts.

4. Make functions and react components take references to singletons to enable unit testing instead of globally importing a singleton.

5. Know and document the life cycle of the data you are working with 
    - How does data get populated?
    - Does data get stale?
    - Does data need to exist across the entire application?
    - Does data need to live within the mount/unmount of a React component?
    - Does data need to live in React?
    - Does data need to live in Javascript memory?
    - When is the data available?
    - Does code depend on data that is async? 
    - Where is the data populated from?
      - User input
      - HTTP request
      - Websocket request
      - WASM instance
      - File system (off disk)

## 1. UX design
1. Animate sparingly
2. Keep distractions from the scene at a minimum

## 2. Modeling Codemods, Command Palette, and Testing

1. Codemods are defined in `src/lang/modifyAst/*.ts` and grouped by categories
    - They take in an AST with all the command arguments, clone it, and return it modified
    - They are generally scoped to the creation of one KCL stdlib function call, yielding one operation in the Feature Tree
    - They are also capable of editing an existing call, in which case they take a `nodeToEdit` path to node
    - Edits are called from the `src/lib/operations.ts` file, in which `prepareToEdit*` functions live, and are responsible of massaging all the operation data back into command-palette-compatible args, just like at create time.
2. Codemods are tested at the integration level, in vitest spec files at `src/lang/modifyAst/*.spec.ts`, also grouped by categories
    - Some of these tests need an engine connection (eg. to check on face or edge-cut artifacts), some don't
    - This is the perfect place to run all argument permutation testing
    - A few e2e playwright test exist today, generally one per command, to test the integration of codemods within `modelingMachine`, the Command Palette, the edit flows, etc.
3. A systematic approach for codemods was outlined in the following diagram.

    - It is about honouring the initial KCL intent, whether it was written by a person, LLM, or generated by another codemod.
    - All the codemods were rewritten during [this effort](https://github.com/KittyCAD/modeling-app/milestone/4), to ensure consistency with respect to these principles and scalable testing.

<img width="4550" height="3271" alt="image" src="https://github.com/user-attachments/assets/7cbb945d-ca4e-4b13-8be3-51343cb6dcf1" />