airier 0.0.8 → 0.0.10

package/AGENTS.md

@@ -0,0 +1,319 @@
+# AI Coding Assistant Instructions
+
+Write code that breathes. Think Ruby-like elegance meets modern JavaScript. Every character should earn its place.
+
+## Philosophy: Airy, Minimalist Code
+
+- **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.
+
+## Critical Style Rules
+
+### 1. No Semicolons (Non-negotiable)
+```javascript
+// ✅ CORRECT
+const x = 5
+return x + y
+
+// ❌ WRONG
+const x = 5;
+return x + y;
+```
+
+### 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}`)
+}
+```
+
+### 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 ) => { }
+
+// ❌ WRONG - camelCase
+const timeoutMs = 5000
+const userName = 'John'
+const addNumbers = ( a, b ) => a + b
+const fetchUserData = async ( userId ) => { }
+```
+
+### 4. Keywords: No Space After
+```javascript
+// ✅ CORRECT
+if( x > 5 ) { }
+for( let i = 0; i < 10; i++ ) { }
+while( condition ) { }
+
+// ❌ WRONG
+if (x > 5) { }
+for (let i = 0; i < 10; i++) { }
+```
+
+### 5. Indentation: 4 Spaces
+```javascript
+// ✅ CORRECT
+const process_data = ( data ) => {
+    const filtered = data.filter( item => item.active )
+    return filtered
+}
+
+// ❌ WRONG - 2 spaces
+const process_data = ( data ) => {
+  const filtered = data.filter( item => item.active )
+  return filtered
+}
+```
+
+## 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 ) {` |
+
+## React Specific
+```javascript
+// ✅ CORRECT
+<Component prop={ value } />
+<div className="foo">{ children }</div>
+
+// ❌ WRONG
+<Component prop={value} />
+<div className="foo">{children}</div>
+```
+
+- No `import React from 'react'` needed (modern React)
+- Prefer functional components with hooks
+- PropTypes optional (use TypeScript if you need types)
+
+## Minimalism Rules
+
+### ❌ Don't Over-Engineer
+```javascript
+// ❌ WRONG
+const create_greeting = ( config ) => {
+    const { name, formal = false } = config
+    return formal ? `Hello, ${ name }` : `Hey ${ name }`
+}
+
+// ✅ CORRECT
+const greet = ( name ) => `Hello, ${ name }`
+```
+
+### ❌ 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 )
+```
+
+## Functional Programming Over Loops
+
+Prefer higher-level array methods over primitive loops. They're more readable and declarative.
+
+```javascript
+// ✅ CORRECT - Functional approach
+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] )
+    }
+}
+```
+
+**Prefer in order**: `.map()`, `.filter()`, `.reduce()`, `.find()`, `.some()`, `.every()` over `for`/`while` loops.
+
+## 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.
+
+```javascript
+// ✅ CORRECT
+/**
+ * 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
+}
+
+// ❌ 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
+
+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
+const fetch_user = async ( id ) => {
+    const loading_indicator = start_loading()
+
+    try {
+        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 )
+    }
+}
+
+// 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 }` )
+    }
+}
+
+// Internal functions trust their callers
+const process_user = ( user ) => user.name.toUpperCase()
+
+// ❌ WRONG - Defensive programming everywhere
+const process_user = ( user ) => {
+    if( !user || !user.name ) return null
+    return user.name.toUpperCase()
+}
+```
+
+## 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.
+
+### Logging with `log`
+```javascript
+import { log } from 'mentie'
+
+// ✅ CORRECT - Use mentie's structured logging
+log.info( 'User logged in:', user_id )
+log.debug( 'Processing data:', data )
+log.insane( 'Detailed trace:', complex_object )
+
+// ❌ WRONG - Don't use console.log when mentie is available
+console.log( 'User logged in:', user_id )
+```
+
+### String Utilities
+```javascript
+import { multiline_trim } from 'mentie'
+
+// ✅ CORRECT - Clean multiline strings
+const query = multiline_trim( `
+    SELECT *
+    FROM users
+    WHERE active = true
+` )
+
+// ❌ WRONG - Manual string manipulation
+const query = `SELECT * FROM users WHERE active = true`
+```
+
+### Array Utilities
+```javascript
+import { shuffle_array } from 'mentie'
+
+// ✅ CORRECT - Use mentie's shuffle
+const randomized = shuffle_array( items )
+
+// ❌ WRONG - Implementing your own shuffle
+const randomized = items.sort( () => Math.random() - 0.5 )
+```
+
+**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
+
+## Complete Example
+
+```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
+}
+
+export default fetch_and_process_users
+```
+
+## 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/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.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.js .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:
@@ -43,4 +80,3 @@ If you are cloning this repo and want to reuse it to create an npm package. Thes
 
 1. You need to do the one-time first publishing manually by running `npm publish --access public` in the root of the project. This will create the package on npmjs and allow you to create a granular token. This requires you to rename `.npmrc` to `.npmrc.bak` temporatily.
 1. You need to obtain a NPM_ACCESS_TOKEN on npmjs (https://www.npmjs.com/settings/YOURUSERNAME/tokens/granular-access-tokens/new). Note that granular tokens expire!
-# airier

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,56 @@
+// 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 [
+    // Apply to all JavaScript and JSX files
+    {
+        files: [ '**/*.js', '**/*.jsx', '**/*.cjs', '**/*.mjs' ],
+
+        languageOptions: {
+            parser: babelParser,
+            parserOptions: {
+                ecmaVersion: 2020,
+                requireConfigFile: false,
+                ecmaFeatures: {
+                    jsx: true
+                }
+            },
+            globals: {
+                ...globals.browser,
+                ...globals.node,
+                ...globals.mocha,
+                ...globals.cypress
+            }
+        },
+
+        plugins: {
+            react,
+            'unused-imports': unusedImports
+        },
+
+        settings: {
+            react: {
+                version: 'detect'
+            }
+        },
+
+        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.8",
+  "version": "0.0.10",
   "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
-    }
-}