PRINCIPLES.md

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/app.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, to ensure consistency with respect to these principles and scalable testing.

3. Code style

1. Never use any or as in typescript. We do not want leave things untyped or coerce types. You should instead type narrow or use helpers like hasProperty and isRecord from @src/lib/utils.ts where needed.