airier 0.0.10 → 0.1.0

package/AGENTS.md

@@ -1,168 +1,185 @@
 # AI Coding Assistant Instructions
 
-Write code that breathes. Think Ruby-like elegance meets modern JavaScript. Every character should earn its place.
+Write code that breathes. Think Ruby-like elegance meets modern js.
 
-## Philosophy: Airy, Minimalist Code
+Important boundaries:
 
-- **Minimalism First**: Don't add features that weren't requested. Three similar lines beats a premature abstraction. If unused, delete completely.
-- **Readability Through Spacing**: Code needs room to breathe. Spacing makes structure visible at a glance.
-- **Modern JavaScript Only**: Use `const`/`let`, arrow functions, destructuring, template literals, ES modules.
+- You do not touch files specified in `.gitignore`
+- You do not touch `.env` or `.env.*` files
+- You do not touch dotfiles, pattern `.*`
 
-## Critical Style Rules
+==============================
 
-### 1. No Semicolons (Non-negotiable)
-```javascript
-// ✅ CORRECT
-const x = 5
-return x + y
+## 1. Code Philosophy
 
-// ❌ WRONG
-const x = 5;
-return x + y;
-```
+**Code is written for human eyes**: Code is a description of the intent of a programmer, it must communicate the intent. For machines, the syntax and style is not relevant. Therefore, code style must be optimised for human eyes and mental models.
 
-### 2. Spacing Everywhere
-```javascript
-// ✅ CORRECT - Airy and readable
-const arr = [ 1, 2, 3 ]
-const obj = { foo: 'bar' }
-const result = my_func( arg1, arg2 )
-if( condition ) {
-    console.log( `Value: ${ variable }` )
-}
-const arrow = ( a, b ) => a + b
-
-// ❌ WRONG - Cramped
-const arr = [1, 2, 3]
-const obj = {foo: 'bar'}
-const result = myFunc(arg1, arg2)
-if(condition) {
-    console.log(`Value: ${variable}`)
-}
-```
+**More comments is better than less comments**: Reading code can clarify function but not intention. Comments are a reminder to self, or an explanation to coworkers.
 
-### 3. snake_case for Everything
-```javascript
-// ✅ CORRECT
-const timeout_ms = 5000
-const user_name = 'John'
-const add_numbers = ( a, b ) => a + b
-const fetch_user_data = async ( user_id ) => { }
+**Readability Through Spacing**: Code needs room to breathe. Spacing makes structure visible at a glance.
+
+**Remember**: Code is read far more than it's written. Make it beautiful, make it breathe, make it obvious.
 
-// ❌ WRONG - camelCase
-const timeoutMs = 5000
-const userName = 'John'
-const addNumbers = ( a, b ) => a + b
-const fetchUserData = async ( userId ) => { }
+==============================
+
+## 2. Syntax preferences
+
+Code should be elegant, not use superfluous characters, and have space to breathe. For example: do not use semicolons, add space in brackets. The linter will show you syntax preferences, to that end with every change learn the styling by:
+
+1. save your changes and look at the syntax
+2. run `npm run lint` and ignore the command output
+3. look at how the linter changed the style, and mimic it in future responses.
+
+==============================
+
+## 3. Tooling preferences
+
+### LLM agent context
+
+Any LLM including you should always:
+
+- Read the `AGENTS.md` file for instructions
+- Check if `SPECIFICATION.md` exists, if so read it
+- Check if `SPECIFICATION.*.md` patterned files exist, if so read them for context
+- Check for all `*.md` files in the project root
+
+### Node.js usage
+
+- Use `nvm` for version management, with the latest LTS (24) in the `.nvmrc`
+- Do not modify files in `node_modules/`
+- Environment variables are stored in `.env` which is supported by node without dependencies
+- Frontend code should use Vite for bundling
+- Backend code should use Node.js
+- Prefer javascript over typescript, including when setting up vite projects
+
+### React usage
+
+- Frontends should be built in react
+- React should be used in frontend mode (no server components)
+- Routing is done with `react-router` BrowserRouter
+- State is put in the URL where possible using the `use-query-params` npm package
+- State that is used in multiple places at once uses `zustand`
+- Components follow a structure inspired by Atomic Design where they are split into:
+  - Atoms: stateless components
+  - Molecules: stateful components (may use Atoms)
+  - Pages: components rendered by the router
+
+File structure in a react project:
+
+```bash
+.
+├── assets
+├── package-lock.json
+├── package.json
+├── public
+│   ├── assets
+│   ├── favicon.ico
+│   ├── logo192.png
+│   ├── logo512.png
+│   └── robots.txt
+├── src
+│   ├── App.jsx
+│   ├── components
+│   │   ├── atoms
+│   │   ├── molecules
+│   │   └── pages
+│   ├── hooks
+│   ├── index.css
+│   ├── index.jsx
+│   ├── modules
+│   ├── routes
+│   │   └── Routes.jsx
+│   └── stores
+└── vite.config.js
 ```
 
-### 4. Keywords: No Space After
-```javascript
-// ✅ CORRECT
-if( x > 5 ) { }
-for( let i = 0; i < 10; i++ ) { }
-while( condition ) { }
+### Using Mentie Helpers
 
-// ❌ WRONG
-if (x > 5) { }
-for (let i = 0; i < 10; i++) { }
-```
+If `mentie` is installed, **always use its utilities**. Check `node_modules/mentie/index.js` for available exports.
 
-### 5. Indentation: 4 Spaces
-```javascript
-// ✅ CORRECT
-const process_data = ( data ) => {
-    const filtered = data.filter( item => item.active )
-    return filtered
-}
+```js
+import { log, multiline_trim, shuffle_array } from 'mentie'
 
-// ❌ WRONG - 2 spaces
-const process_data = ( data ) => {
-  const filtered = data.filter( item => item.active )
-  return filtered
-}
+log.info( `User logged in:`, user_id )
+
+const query = multiline_trim( `
+    SELECT * FROM users
+    WHERE active = true
+` )
+
+const randomized = shuffle_array( items )
 ```
 
-## Spacing Quick Reference
+==============================
 
-| Element | Pattern | Example |
-|---------|---------|---------|
-| Arrays | `[ items ]` | `[ 1, 2, 3 ]` |
-| Objects | `{ key: value }` | `{ foo: 'bar' }` |
-| Function calls | `func( args )` | `my_func( a, b )` |
-| Arrow functions | `( args ) => { }` | `const fn = ( x ) => x * 2` |
-| Template literals | `${ expr }` | `` `Hello ${ name }` `` |
-| Blocks | `keyword( cond ) {` | `if( x > 5 ) {` |
+## 3. Code style preferences
 
-## React Specific
-```javascript
-// ✅ CORRECT
-<Component prop={ value } />
-<div className="foo">{ children }</div>
+### Always use template literals instead of strings
+```js
+// Use literals for regular strings
+const name = `Ada Localace`
 
-// ❌ WRONG
-<Component prop={value} />
-<div className="foo">{children}</div>
+// Use templates for string manipulation too
+const annotated_name = `${ name } ${ Math.random() }`
 ```
 
-- No `import React from 'react'` needed (modern React)
-- Prefer functional components with hooks
-- PropTypes optional (use TypeScript if you need types)
 
-## Minimalism Rules
+### snake_case for Everything
+```js
+const timeout_ms = 5_000
+const user_name = 'John'
+const fetch_user_data = async ( user_id ) => { }
+```
 
-### ❌ Don't Over-Engineer
-```javascript
-// ❌ WRONG
-const create_greeting = ( config ) => {
-    const { name, formal = false } = config
-    return formal ? `Hello, ${ name }` : `Hey ${ name }`
-}
+### Use comments to describe intent
+```js
+import { abort_controller } from 'mentie'
 
-// ✅ CORRECT
-const greet = ( name ) => `Hello, ${ name }`
+// Load the users with a timeout to prevent hanging
+const fetch_options = abort_controller( { timeout_ms: 10_000 } )
+const { uids } = await fetch( 'https://...', fetch_options ).then( res => res.json() )
+
+// Parallel fetch resulting data to optimise speed
+const downstream_data = await Promise.all( uids.map( async uid => fetch( `https://...?uid=${ uid }` ) ) )
 ```
 
-### ❌ Don't Add Unrequested Features
-```javascript
-// ❌ WRONG - validation, logging, backup not requested
-const save_user = ( user, options = {} ) => {
-    if( options.validate ) validate( user )
-    if( options.log ) console.log( user )
-    return db.save( user )
-}
 
-// ✅ CORRECT
-const save_user = ( user ) => db.save( user )
+### Prioritise semantic clarity over optimisation
+Don't reassign variables. Create new bindings for each transformation step.
+```js
+// Parse a dataset - each step is clear and traceable
+const data = []
+const filtered_data = data.filter( ( { relevant_number } ) => relevant_number > 1.5 )
+const restructured_data = filtered_data.map( ( { base_value, second_value } ) => ( { composite_value: base_value * second_value } ) )
+return restructured_data
+```
+
+
+### Lean towards onelining single statements
+Single statements can be on one line. Multiple statements need blocks.
+```js
+// ✅ Single statement - oneline it
+if( condition ) log.info( `Message` )
+const filtered_data = data.filter( ( { relevant_property } ) => relevant_property )
 ```
 
-## Functional Programming Over Loops
 
-Prefer higher-level array methods over primitive loops. They're more readable and declarative.
+### Functional Programming Over Loops
+
+Prefer `.map()`, `.filter()`, `.reduce()`, `.find()`, `.some()`, `.every()` over `for`/`while` loops.
 
-```javascript
-// ✅ CORRECT - Functional approach
+```js
 const active_users = users.filter( u => u.active )
-const user_names = users.map( u => u.name )
-const total = numbers.reduce( ( sum, n ) => sum + n, 0 )
-
-// ❌ WRONG - Primitive loops
-const active_users = []
-for( let i = 0; i < users.length; i++ ) {
-    if( users[i].active ) {
-        active_users.push( users[i] )
-    }
-}
+const user_names = active_users.map( u => u.name )
+const total_age = user_names.reduce( ( sum, age ) => sum + age, 0 )
 ```
 
-**Prefer in order**: `.map()`, `.filter()`, `.reduce()`, `.find()`, `.some()`, `.every()` over `for`/`while` loops.
 
-## JSDoc for Exported Functions
+### JSDoc for Exported Functions
 
-**CRITICAL**: Every exported function MUST have JSDoc comments. Before finishing, always verify JSDoc is present and up-to-date for all changed exports.
+**CRITICAL**: Every exported function MUST have JSDoc. Verify before finishing!
 
-```javascript
-// ✅ CORRECT
+```js
 /**
  * Fetches user data from the API
  * @param {string} user_id - The ID of the user to fetch
@@ -172,148 +189,127 @@ export const fetch_user = async ( user_id ) => {
     const response = await api.get( `/users/${ user_id }` )
     return response.data
 }
-
-// ❌ WRONG - No JSDoc
-export const fetch_user = async ( user_id ) => {
-    const response = await api.get( `/users/${ user_id }` )
-    return response.data
-}
 ```
 
-**Before completing any task**: Review all modified exports and ensure their JSDoc is accurate and current.
+### Error Handling
 
-## Error Handling
+Only at boundaries (user input, external APIs). Trust internal code. Remember `finally` for cleanup!
 
-Only at boundaries (user input, external APIs). Trust internal code.
-
-**IMPORTANT**: Remember the `finally` block! It's perfect for cleanup operations and runs regardless of success/failure.
-
-```javascript
-// ✅ CORRECT - Using finally for cleanup
+```js
 const fetch_user = async ( id ) => {
-    const loading_indicator = start_loading()
 
     try {
+        start_loading()
         const response = await api.get( `/users/${ id }` )
         return response.data
     } catch( error ) {
         throw new Error( `Failed to fetch user: ${ error.message }` )
     } finally {
-        // Always runs - perfect for cleanup
-        stop_loading( loading_indicator )
+        stop_loading()
     }
 }
+```
 
-// Also valid - Simple boundary error handling
-const get_user = async ( id ) => {
-    try {
-        const response = await api.get( `/users/${ id }` )
-        return response.data
-    } catch( error ) {
-        throw new Error( `Failed to fetch user: ${ error.message }` )
-    }
-}
+### Complete example of well styled code
+
+```js
+/**
+ * Fetches and processes active users from the API
+ * @param {Object} options
+ * @param {Array} options.user_ids - User ids to fetch
+ * @param {Number} options.limit - Limit the amount of users to fetch
+ * @returns {Promise<Array>} Processed user objects
+ */
+export async function fetch_and_process_users( { user_ids, limit=5 } = {} )  {
+
+    // Get users to ensure up to date data
+    const users = await api.get( `/users`, { user_ids, limit } )
 
-// Internal functions trust their callers
-const process_user = ( user ) => user.name.toUpperCase()
+    // Keep only active users to prevent wasting time on inactive ones
+    const filtered_users = users.filter( ( { active } ) => active )
 
-// ❌ WRONG - Defensive programming everywhere
-const process_user = ( user ) => {
-    if( !user || !user.name ) return null
-    return user.name.toUpperCase()
+    // Annotate users with value based on local conversion so we can show the user the computed values
+    const annotated_users = filtered_users.map( ( { score, user } ) => ( { score: score * local_conversion_value, ...user } ) )
+
+    // Return users with annotated data
+    return annotated_users
 }
-```
 
-## Using Mentie Helpers (If Installed)
+```
 
-If the `mentie` package is installed in the project, **always use its utilities** instead of reinventing them.
 
-**IMPORTANT**: Check `node_modules/mentie/index.js` (or the package's main export file) to see all available exports and their usage before implementing any utility functions yourself.
+### React Specific styling
 
-### Logging with `log`
-```javascript
-import { log } from 'mentie'
+**Exception to snake_case**: React component names MUST be PascalCase (required by React/JSX).
 
-// ✅ CORRECT - Use mentie's structured logging
-log.info( 'User logged in:', user_id )
-log.debug( 'Processing data:', data )
-log.insane( 'Detailed trace:', complex_object )
+```js
+// ✅ Components are PascalCase
+const UserProfile = ( { user_id } ) => { }
+const DataTable = () => { }
 
-// ❌ WRONG - Don't use console.log when mentie is available
-console.log( 'User logged in:', user_id )
+// ✅ Everything else is snake_case
+const user_name = `John`
+const fetch_user_data = async ( user_id ) => { }
 ```
 
-### String Utilities
-```javascript
-import { multiline_trim } from 'mentie'
+**File naming**: Component files use PascalCase to match component name.
+- `UserProfile.jsx` - Component files
+- `fetch_user_data.js` - Utility files
 
-// ✅ CORRECT - Clean multiline strings
-const query = multiline_trim( `
-    SELECT *
-    FROM users
-    WHERE active = true
-` )
+**Event handlers**:
+- Do not name things after the event (e.g. `on_click`) but name them actions (e.g. `save_user`)
 
-// ❌ WRONG - Manual string manipulation
-const query = `SELECT * FROM users WHERE active = true`
-```
+**JSX spacing and structure**:
+```js
+// Styled and stateless sections use arrow functions or variables
+const Header = styled.aside`
+    color: red;
+`
 
-### Array Utilities
-```javascript
-import { shuffle_array } from 'mentie'
+// Use JSX comments to separate sections
+export function UserProfile( { user_id, on_update } ) {
 
-// ✅ CORRECT - Use mentie's shuffle
-const randomized = shuffle_array( items )
+    // Hooks at the top
+    const [ user_data, set_user_data ] = useState( null )
+    const [ is_loading, set_is_loading ] = useState( false )
 
-// ❌ WRONG - Implementing your own shuffle
-const randomized = items.sort( () => Math.random() - 0.5 )
-```
+    // Effects after hooks
+    useEffect( () => {
+        fetch_user_data( user_id ).then( set_user_data )
+    }, [ user_id ] )
 
-**Check for mentie**:
-1. Look in `package.json` dependencies to see if mentie is installed
-2. If present, read `node_modules/mentie/index.js` to see all available exports
-3. Use mentie's utilities instead of reimplementing them
+    // Event handlers
+    const update_user = () => on_update( user_data )
 
-## Complete Example
+    // Conditional rendering
+    if( is_loading ) return <LoadingSpinner />
 
-```javascript
-/**
- * Fetches and processes users from the API
- * @param {Object} filters - Query filters to apply
- * @returns {Promise<Array>} Processed user objects with id, name, and email
- */
-const fetch_and_process_users = async ( filters = {} ) => {
-    const users = await api.get( '/users', { params: filters } )
-
-    const processed = users
-        .filter( user => user.active )
-        .map( user => ( {
-            id: user.id,
-            name: user.name,
-            email: user.email
-        } ) )
-
-    return processed
+    // Do not add () around returned jsx.
+    return <>
+
+            { /* Profile header section */ }
+            <Header title={ user_data.name } />
+
+            { /* Profile details */ }
+            <div className="profile">
+                { user_data.details }
+            </div>
+
+            { /* Actions */ }
+            <Button on_click={ update_user }>Save</Button>
+
+        </>
 }
 
-export default fetch_and_process_users
+// Lists need keys
+const user_list = users.map( ( user ) => <UserCard key={ user.id } user={ user } /> )
+
+// Props always have spacing
+<Component prop={ value } />
+<div className="foo">{ children }</div>
 ```
 
-## Checklist
 
-- [ ] No semicolons
-- [ ] Spacing in all brackets: `[ ]`, `{ }`, `( )`, `${ }`
-- [ ] snake_case for all variables and functions
-- [ ] 4-space indentation
-- [ ] `const`/`let` only (never `var`)
-- [ ] Arrow functions preferred
-- [ ] Higher-level functions (.map, .filter, .reduce) over loops
-- [ ] JSDoc on ALL exported functions (verify before finishing!)
-- [ ] Consider `finally` block for cleanup in try/catch
-- [ ] Check if `mentie` is installed and use its helpers (log, multiline_trim, etc.)
-- [ ] No unnecessary features or abstractions
-- [ ] Dead code completely removed
 
----
 
-**Remember**: Code is read far more than it's written. Make it beautiful, make it breathe, make it obvious.
+

package/README.md

@@ -18,7 +18,7 @@ npm pkg set scripts.lint="eslint --fix src"
 npx husky init
 
 # Download files (using new ESLint 9 flat config format)
-curl https://raw.githubusercontent.com/actuallymentor/airier/main/eslint.config.js --output eslint.config.js
+curl https://raw.githubusercontent.com/actuallymentor/airier/main/eslint.config.example.js --output eslint.config.js
 curl https://raw.githubusercontent.com/actuallymentor/airier/main/.vscode/settings.json --output .vscode/settings.json
 curl https://raw.githubusercontent.com/actuallymentor/airier/main/.husky/pre-commit --output .husky/pre-commit
 curl https://raw.githubusercontent.com/actuallymentor/airier/main/.babelrc --output .babelrc

package/modules/eslint_config.js

@@ -10,6 +10,16 @@ import styleguide from './styleguide.js'
 
 // Export the flat config as an array
 export default [
+    // Global ignores for build output and dependencies
+    {
+        ignores: [
+            '**/dist/**',
+            '**/build/**',
+            '**/node_modules/**',
+            '**/.next/**',
+            '**/coverage/**'
+        ]
+    },
     // Apply to all JavaScript and JSX files
     {
         files: [ '**/*.js', '**/*.jsx', '**/*.cjs', '**/*.mjs' ],
@@ -19,6 +29,9 @@ export default [
             parserOptions: {
                 ecmaVersion: 2020,
                 requireConfigFile: false,
+                babelOptions: {
+                    presets: [ '@babel/preset-react' ]
+                },
                 ecmaFeatures: {
                     jsx: true
                 }
@@ -38,7 +51,7 @@ export default [
 
         settings: {
             react: {
-                version: 'detect'
+                version: '19'
             }
         },
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "airier",
-  "version": "0.0.10",
+  "version": "0.1.0",
   "description": "Opinionated Eslint and VSCode style guide",
   "type": "module",
   "main": "index.js",