airier 0.0.9 → 0.1.0

package/AGENTS.md

@@ -0,0 +1,315 @@
+# AI Coding Assistant Instructions
+
+Write code that breathes. Think Ruby-like elegance meets modern js.
+
+Important boundaries:
+
+- You do not touch files specified in `.gitignore`
+- You do not touch `.env` or `.env.*` files
+- You do not touch dotfiles, pattern `.*`
+
+==============================
+
+## 1. Code Philosophy
+
+**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.
+
+**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.
+
+**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.
+
+==============================
+
+## 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
+```
+
+### Using Mentie Helpers
+
+If `mentie` is installed, **always use its utilities**. Check `node_modules/mentie/index.js` for available exports.
+
+```js
+import { log, multiline_trim, shuffle_array } from 'mentie'
+
+log.info( `User logged in:`, user_id )
+
+const query = multiline_trim( `
+    SELECT * FROM users
+    WHERE active = true
+` )
+
+const randomized = shuffle_array( items )
+```
+
+==============================
+
+## 3. Code style preferences
+
+### Always use template literals instead of strings
+```js
+// Use literals for regular strings
+const name = `Ada Localace`
+
+// Use templates for string manipulation too
+const annotated_name = `${ name } ${ Math.random() }`
+```
+
+
+### snake_case for Everything
+```js
+const timeout_ms = 5_000
+const user_name = 'John'
+const fetch_user_data = async ( user_id ) => { }
+```
+
+### Use comments to describe intent
+```js
+import { abort_controller } from 'mentie'
+
+// 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 }` ) ) )
+```
+
+
+### 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 `.map()`, `.filter()`, `.reduce()`, `.find()`, `.some()`, `.every()` over `for`/`while` loops.
+
+```js
+const active_users = users.filter( u => u.active )
+const user_names = active_users.map( u => u.name )
+const total_age = user_names.reduce( ( sum, age ) => sum + age, 0 )
+```
+
+
+### JSDoc for Exported Functions
+
+**CRITICAL**: Every exported function MUST have JSDoc. Verify before finishing!
+
+```js
+/**
+ * Fetches user data from the API
+ * @param {string} user_id - The ID of the user to fetch
+ * @returns {Promise<Object>} User data object
+ */
+export const fetch_user = async ( user_id ) => {
+    const response = await api.get( `/users/${ user_id }` )
+    return response.data
+}
+```
+
+### Error Handling
+
+Only at boundaries (user input, external APIs). Trust internal code. Remember `finally` for cleanup!
+
+```js
+const fetch_user = async ( id ) => {
+
+    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 {
+        stop_loading()
+    }
+}
+```
+
+### 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 } )
+
+    // Keep only active users to prevent wasting time on inactive ones
+    const filtered_users = users.filter( ( { active } ) => active )
+
+    // 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
+}
+
+```
+
+
+### React Specific styling
+
+**Exception to snake_case**: React component names MUST be PascalCase (required by React/JSX).
+
+```js
+// ✅ Components are PascalCase
+const UserProfile = ( { user_id } ) => { }
+const DataTable = () => { }
+
+// ✅ Everything else is snake_case
+const user_name = `John`
+const fetch_user_data = async ( user_id ) => { }
+```
+
+**File naming**: Component files use PascalCase to match component name.
+- `UserProfile.jsx` - Component files
+- `fetch_user_data.js` - Utility files
+
+**Event handlers**:
+- Do not name things after the event (e.g. `on_click`) but name them actions (e.g. `save_user`)
+
+**JSX spacing and structure**:
+```js
+// Styled and stateless sections use arrow functions or variables
+const Header = styled.aside`
+    color: red;
+`
+
+// Use JSX comments to separate sections
+export function UserProfile( { user_id, on_update } ) {
+
+    // Hooks at the top
+    const [ user_data, set_user_data ] = useState( null )
+    const [ is_loading, set_is_loading ] = useState( false )
+
+    // Effects after hooks
+    useEffect( () => {
+        fetch_user_data( user_id ).then( set_user_data )
+    }, [ user_id ] )
+
+    // Event handlers
+    const update_user = () => on_update( user_data )
+
+    // Conditional rendering
+    if( is_loading ) return <LoadingSpinner />
+
+    // 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>
+
+        </>
+}
+
+// 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>
+```
+
+
+
+
+

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 Proof of Attendance Protocol
+Copyright (c) 2024 Mentor Palolaj
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -2,11 +2,13 @@
 
 A shared set of standards and preferences, enforced through eslint and vscode. Priorities: minimalism, readability, documentation.
 
+**Now updated for ESLint 9.x with flat config format and ESM support!**
+
 ## Quickstart
 
 ```shell
 # Install dependencies
-npm install -D airier @babel/eslint-parser @babel/preset-react eslint eslint-plugin-react eslint-plugin-unused-imports husky
+npm install -D airier husky
 mkdir .vscode .husky || echo "Directories already exist"
 
 # Create scripts
@@ -15,20 +17,55 @@ npm pkg set scripts.lint="eslint --fix src"
 # Init husky
 npx husky init
 
-# Download files
-curl https://raw.githubusercontent.com/actuallymentor/airier/main/.eslintrc.cjs --output .eslintrc.cjs
+# Download files (using new ESLint 9 flat config format)
+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
+curl https://raw.githubusercontent.com/actuallymentor/airier/main/AGENTS.md --output AGENTS.md
+
+# Ensure .gitignore ignores all dotfiles by default
+grep -q '^\.\*$' .gitignore || echo -e "\n# Dotfiles\n.*" >> .gitignore
 
 # Add files to git
-git add -f .eslintrc.cjs .babelrc .vscode/* .husky/*
+git add -f eslint.config.js .babelrc AGENTS.md .vscode/* .husky/*
 
 # Make husky executable
 chmod ug+x .husky/*
-git add .husky/pre-commit
+git add -f .husky/pre-commit
 ```
 
+## ESLint 9 Migration
+
+This package now uses ESLint 9.x with the new **flat config format** and **ESM-only**. If you're upgrading from an older version:
+
+1. Remove your old `.eslintrc.*` files (they're no longer supported in ESLint 9)
+2. Use `eslint.config.js` instead
+3. Update your ESLint to version 9.39.2 or later
+4. Ensure your project supports ESM (Node.js 20+)
+
+### Usage
+
+```javascript
+// eslint.config.js
+import { eslint_config } from 'airier'
+
+export default eslint_config
+```
+
+## AI Assistant Instructions
+
+This package includes an `AGENTS.md` file that instructs AI coding assistants (like Claude, GPT, Copilot) to follow the same minimalist, "airy" code style that the ESLint rules enforce.
+
+When working with AI assistants, share this file with them to ensure they write code matching your style:
+- No semicolons
+- Spacing in brackets: `[ 1, 2, 3 ]`, `{ key: value }`, `func( args )`
+- 4-space indentation
+- Minimalist, Ruby-like aesthetics
+- Modern ES modules only
+
+The AI instructions complement the automated linting by teaching assistants *why* the code should look this way, not just enforcing it after the fact.
+
 ## Making changes
 
 The relevant source files are in `modules/`. If you make a change, you can update the package by:

package/eslint.config.example.js

@@ -0,0 +1,3 @@
+import { eslint_config } from 'airier'
+
+export default eslint_config

package/eslint.config.js

@@ -0,0 +1,4 @@
+import { eslint_config } from './index.js'
+
+// Export the flat config array
+export default eslint_config

package/index.js

@@ -0,0 +1,6 @@
+// Import the modules using ES Module syntax
+import eslint_config from './modules/eslint_config.js'
+import styleguide from './modules/styleguide.js'
+
+// Export the objects
+export { eslint_config, styleguide }

package/modules/eslint_config.js

@@ -0,0 +1,69 @@
+// Import required modules
+import eslint from '@eslint/js'
+import react from 'eslint-plugin-react'
+import unusedImports from 'eslint-plugin-unused-imports'
+import babelParser from '@babel/eslint-parser'
+import globals from 'globals'
+
+// Import the styleguide module
+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' ],
+
+        languageOptions: {
+            parser: babelParser,
+            parserOptions: {
+                ecmaVersion: 2020,
+                requireConfigFile: false,
+                babelOptions: {
+                    presets: [ '@babel/preset-react' ]
+                },
+                ecmaFeatures: {
+                    jsx: true
+                }
+            },
+            globals: {
+                ...globals.browser,
+                ...globals.node,
+                ...globals.mocha,
+                ...globals.cypress
+            }
+        },
+
+        plugins: {
+            react,
+            'unused-imports': unusedImports
+        },
+
+        settings: {
+            react: {
+                version: '19'
+            }
+        },
+
+        rules: {
+            // ESLint recommended rules
+            ...eslint.configs.recommended.rules,
+
+            // React recommended rules
+            ...react.configs.recommended.rules,
+
+            // Custom styleguide rules
+            ...styleguide
+        }
+    }
+]

package/modules/{styleguide.cjs → styleguide.js}

@@ -3,7 +3,7 @@
 // warn: we recomment this to change, but there are instances where you can choose to ignore it
 // error: there is no reason for you to do this
 
-module.exports = {
+export default {
 
     /* ///////////////////////////////
     // Built-in rules
@@ -15,9 +15,6 @@ module.exports = {
     // Indentation setting
     "indent": [ "warn", 4 ],
 
-    // Allow unnamed exports
-    "import/no-anonymous-default-export": 0,
-
     // Prefer arrow callbacks
     "prefer-arrow-callback": "warn",
 
@@ -56,7 +53,7 @@ module.exports = {
     // Prefer the use of destructuring
     "prefer-destructuring": "warn",
 
-    // Warn of unused variables, function argumebnts may have documentation value so are ignored
+    // Warn of unused variables, function arguments may have documentation value so are ignored
     "no-unused-vars": [ "warn", { vars: 'all', args: 'none' } ],
 
     // No use of "var"
@@ -93,4 +90,4 @@ module.exports = {
     // /////////////////////////////*/
     "unused-imports/no-unused-imports": "warn",
 
-}
+}

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "airier",
-  "version": "0.0.9",
+  "version": "0.1.0",
   "description": "Opinionated Eslint and VSCode style guide",
-  "main": "index.cjs",
+  "type": "module",
+  "main": "index.js",
   "scripts": {
     "lint": "eslint --fix ."
   },
@@ -16,12 +17,35 @@
     "url": "https://github.com/actuallymentor/airier/issues"
   },
   "homepage": "https://github.com/actuallymentor/airier#readme",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "keywords": [
+    "eslint",
+    "eslint-config",
+    "style-guide",
+    "code-style",
+    "javascript",
+    "react",
+    "minimalist",
+    "airy"
+  ],
+  "files": [
+    "index.js",
+    "modules/",
+    ".babelrc",
+    "eslint.config.js",
+    "eslint.config.example.js",
+    "AGENTS.md"
+  ],
   "peerDependencies": {
-    "eslint-plugin-unused-imports": "^3.1.0",
-    "@babel/eslint-parser": "^7.24.1",
+    "@babel/eslint-parser": "^7.28.5",
     "@babel/preset-react": "^7.24.1",
-    "eslint": "^8.57.0",
-    "eslint-plugin-react": "^7.34.1",
+    "@eslint/js": "^9.39.2",
+    "eslint": "^9.39.2",
+    "eslint-plugin-react": "^7.37.5",
+    "eslint-plugin-unused-imports": "^4.3.0",
+    "globals": "^15.0.0",
     "husky": "^9.0.11"
   }
-}
+}

package/.eslintrc.cjs

@@ -1,7 +0,0 @@
-// const { eslint_config } = require( './index.cjs' )
-const { eslint_config } = require( 'airier' )
-
-// Export the default eslint config
-module.exports = {
-    ...eslint_config
-}

package/.eslintrc.onlystyles.example.js

@@ -1,6 +0,0 @@
-const { eslint_config } = require( 'airier' )
-
-// Export the default eslint config
-module.exports = {
-    ...eslint_config
-}

package/.husky/pre-commit

@@ -1,21 +0,0 @@
-#!/usr/bin/env sh
-. "$(dirname -- "$0")/_/husky.sh"
-
-echo "\n🤖 [ precommit hook ] linting before committing..."
-
-
-# If errors, make it clear they cannot commit
-if ! lint_outcome=$( npm run lint ); then
-    echo "🚨 [ precommit hook ] lint encountered blocking issues, fix them before committing\n"
-    echo "$lint_outcome"
-    exit 1
-fi
-
-# If warnings, suggest they fix them
-if echo $lint_outcome | grep -q "warning"; then
-    echo "⚠️ [ precommit hook ] lint encountered warnings, consider fixing them before pushing\n"
-    echo "$lint_outcome"
-    exit 0
-fi
-
-echo "✅ [ precommit hook ] lint encountered no blocking issues\n"

package/.vscode/settings.json

@@ -1,27 +0,0 @@
-{
-	"i18n-ally.localesPaths": [
-		"public/locales"
-	],
-	"i18n-ally.keystyle": "nested",
-	"eslint.validate": [
-		"javascript",
-		"javascriptreact",
-		"typescript",
-		"typescriptreact"
-	],
-	"editor.codeActionsOnSave": {
-		"source.fixAll.eslint": "explicit"
-	},
-	"editor.renderWhitespace": "all",
-	"editor.formatOnSave": true,
-	"eslint.format.enable": true,
-	"eslint.run": "onType",
-	"explorer.fileNesting.enabled": true,
-	"explorer.fileNesting.patterns": {
-		"vite.config.js": "*.js,.babelrc,.nvmrc,index.html,.gitignore",
-		".env": ".env*,.*.json",
-		"firebase.json": "fire*,.fire*",
-		"package.json": "package-lock.json, yarn.lock, pnpm-lock.yaml,.eslint*,config.*,.npm*,.nvm*,.ncu*",
-		"README.md": "*.md,LICENSE",
-	}
-}

package/index.cjs

@@ -1,6 +0,0 @@
-// Import the modules using ES Module syntax
-const eslint_config = require('./modules/eslint_config.cjs')
-const styleguide = require('./modules/styleguide.cjs')
-
-// Export the objects in an object literal
-module.exports = { eslint_config, styleguide }

package/modules/eslint_config.cjs

@@ -1,50 +0,0 @@
-// Import the styleguide module using ES Module syntax
-const styleguide = require( './styleguide.cjs' )
-
-// Export the configuration object using `export default`
-module.exports = {
-
-    // Recommended features
-    "extends": [ "eslint:recommended", "plugin:react/recommended" ],
-
-    // Plugins
-    plugins: [ 'unused-imports' ],
-
-    // React settings
-    "settings": {
-        "react": { "version": "detect" }
-    },
-
-    // Parser features
-    parser: "@babel/eslint-parser",
-    parserOptions: {
-        requireConfigFile: false,
-        ecmaFeatures: {
-            jsx: true
-        }
-    },
-
-    // Rules
-    rules: {
-        // Import styleguide
-        ...styleguide
-    },
-
-    // What environment to run in
-    env: {
-        node: true,
-        browser: true,
-        mocha: true,
-        jest: false,
-        es6: true
-    },
-
-    // What global variables should be assumed to exist
-    globals: {
-        context: true,
-        cy: true,
-        it: true,
-        Cypress: true,
-        expect: true
-    }
-}