@reicek/neataptic-ts 0.1.16 → 0.1.19

package/.github/copilot-instructions.md

@@ -4,6 +4,17 @@ Purpose
 -------
 When generating, modifying, or suggesting code that touches files under `src/` or `test/`, follow the project `STYLEGUIDE.md` rules and perform the quick validations listed below before returning suggestions.
 
+Educational docs preference (JSDoc)
+----------------------------------
+This is a public-facing, educational library. JSDoc comments are compiled into user-facing documentation (for example the aggregated READMEs under `src/**/README.md` generated by the docs workflow).
+
+When you touch code under `src/` or `test/`, prefer improving JSDoc so the generated docs are:
+- **Interesting and explanatory**, not just type signatures.
+- **Example-driven**: include small examples in the main description (prefer fenced code blocks like ```ts) so the docs generator preserves them.
+- **Conceptual**: include a brief “what/why” explanation and any important semantics (defaults, invariants, error cases, performance notes).
+
+Keep examples short, dependency-light, and consistent with the current public API (avoid imaginary helpers or absolute file paths).
+
 **CRITICAL: Fix-first strategy for test failures**
 ---------------------------------------------------
 When asked to fix multiple test failures:
@@ -77,6 +88,8 @@ Strict rules to enforce (apply to any suggestion touching `src/` or `test/`)
 
 2. JSDoc: exported classes/functions/constants and public methods must have JSDoc with `@param` and `@returns` where appropriate. Add short `@example` when behavior is non-obvious.
 
+   JSDoc-for-constants rule: All exported or shared default constants in `src/` and `test/` must include a concise educational JSDoc explaining what the value controls (e.g., decay factor meaning, floor rates). Keep descriptions short and clarifying.
+
 3. Tests: follow the single-expect rule. Each `it()` (or `test()`) must have exactly one top-level `expect(...)` statement. If multiple assertions are needed, split into multiple `it()` cases or use helper assertions.
 
 4. Constants: replace magic numbers with named `export const` or class-private `static #` constants with a short JSDoc.
@@ -87,6 +100,71 @@ Strict rules to enforce (apply to any suggestion touching `src/` or `test/`)
 
 7. Types: avoid `any` and `unknown` in `src/` and `test/`. Use precise types or `// eslint-disable-next-line @typescript-eslint/no-explicit-any` with a short justification comment.
 
+8. Local helper structure preference:
+   - For new or refactored functions that introduce internal helpers, order the function as:
+       1) Local variables/constants at top
+       2) Declarative logic (calls to helpers)
+       3) Return (fold)
+       4) Internal helper function declarations at the end of the parent function
+    - Helpers should be small and pure where practical, with step-level inline comments and JSDoc.
+
+9. Mandatory implementation pattern (always; keep cognitive complexity low):
+   - Applies to all new code and any modified/refactored code in `src/` and `test/`.
+   - Prefer a *declarative top-level flow* ("collect → transform → fold/return") over deeply nested control flow.
+   - Avoid ternary chains (especially nested) for multi-branch fallback logic; use named resolver helpers with early returns instead.
+   - When normalizing legacy/loose data, isolate type assertions/casting into a single helper and keep the rest strongly typed.
+   - Keep helpers after the fold, and give each helper a single responsibility (SOLID: SRP). If the logic reads like a decision tree, it likely wants 2–4 small helpers.
+
+10. General multi-pass decomposition requirements (apply to all medium/large refactors):
+   - Perform refactors in explicit passes, in this order unless unsafe:
+       1) Stabilize current behavior and identify seams
+       2) Extract pure helpers by responsibility
+       3) Introduce typed context/result objects to reduce parameter sprawl
+       4) Simplify top-level flow to orchestration only
+       5) Fold repeated logic into collect/transform/fold helpers
+   - Keep the top-level method declarative and linear, with numbered inline comments (`Step 1`, `Step 2`, ...).
+   - Ensure each helper has one reason to change (SRP), very low cognitive complexity, and descriptive naming.
+   - Place helper declarations after the top-level return/fold where language/style allows.
+   - Prefer immutable pass-style transforms (`map`, `filter`, `reduce`, index-collection helpers) over mixed mutation-heavy loops.
+   - When passing more than 3-4 arguments repeatedly, introduce a typed context object and shared result types.
+
+Example (ideal structure)
+-------------------------
+```ts
+export function exampleMethod(input: Input) {
+   const constants = /* ... */;
+   const locals = /* ... */;
+
+   if (/* guard */) return /* fold */;
+
+   const stepOne = helperOne(input, locals, constants);
+   const stepTwo = helperTwo(stepOne, locals, constants);
+   return helperThree(stepTwo, locals, constants);
+
+   /** @param value - Input. @returns Intermediate. */
+   function helperOne(value: Input, _locals: unknown, _constants: unknown): Intermediate {
+      // Step 1: ...
+      return /* ... */;
+   }
+
+   /** @param value - Intermediate. @returns Intermediate. */
+   function helperTwo(value: Intermediate, _locals: unknown, _constants: unknown): Intermediate {
+      // Step 1: ...
+      return /* ... */;
+   }
+
+   /** @param value - Intermediate. @returns Output. */
+   function helperThree(value: Intermediate, _locals: unknown, _constants: unknown): Output {
+      // Step 1: Fold/return.
+      return /* ... */;
+   }
+}
+
+type Input = unknown;
+type Intermediate = unknown;
+type Output = unknown;
+```
+
 Automated validations to run before finalizing a suggestion
 -------------------------------------------------------
 When you modify or create files under `src/` or `test/`, run (or advise running) these quick validations. If you cannot run them, still make sure your suggestion would pass them.
@@ -130,3 +208,36 @@ When you modify or create files under `src/` or `test/`, run (or advise running)
    4. ONLY run `npm test` after all planned fixes are complete
    5. Analyze results and iterate on remaining issues
 
+
+Refactor format: large-file split (step-by-step, user-confirmed)
+---------------------------------------------------------------
+When splitting a large module into submodules, follow this exact execution format:
+
+1. Plan first
+   - Propose a file map (main orchestration file + helper/type modules).
+   - Keep exported APIs in the main file unless explicitly requested otherwise.
+   - Define boundaries clearly (types, pool, rebuild helpers, fast-path helpers, adjacency helpers).
+
+2. Create a TODO checklist
+   - Add ordered steps with one active item at a time.
+   - Track progress visibly (mark completed items as soon as each step finishes).
+
+3. Execute in strict passes (one step at a time)
+   - Step A: create empty target files (skeletons only).
+   - Step B: move one category at a time (types first, then helper groups).
+   - Step C: after moving a category, delete the original source from the main file immediately.
+   - Never batch multiple categories in one pass.
+
+4. Require user confirmation between steps
+   - After each completed step, stop and request confirmation before continuing.
+   - Do not proceed to the next step without explicit user approval.
+
+5. Keep the main file as high-level orchestration
+   - Exported functions should show step-level flow (`Step 1`, `Step 2`, ...).
+   - Avoid trivial re-export wrappers or single-helper pass-through exports.
+   - Main file may retain shared constants and orchestration-level guards.
+
+6. Validate only after all planned moves
+   - Run `npx tsc --noEmit -p tsconfig.json` after completing all migration steps.
+   - Report concise validation summary and any unresolved follow-ups.
+

package/.github/workflows/ci.yml

@@ -15,7 +15,7 @@ jobs:
       - name: Use Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: '20'
+          node-version: '22'
       - name: Install dependencies
         run: npm ci
       - name: Run tests

package/.github/workflows/deploy-pages.yml

@@ -3,12 +3,6 @@ name: Deploy docs (GitHub Pages)
 on:
   push:
     branches: [develop]
-    paths:
-      - 'docs/**'
-      - 'dist/**'
-      - 'src/**'
-      - 'package.json'
-      - '.github/workflows/deploy-pages.yml'
   workflow_dispatch:
 
 permissions:
@@ -33,7 +27,7 @@ jobs:
       - name: Setup Node
         uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 22
 
       - name: Install dependencies
         run: npm ci

package/.github/workflows/manual_release_pipeline.yml

@@ -33,7 +33,7 @@ jobs:
       - name: Setup Node
         uses: actions/setup-node@v4
         with:
-          node-version: '20'
+          node-version: '22'
 
       - name: Install dependencies
         run: npm ci

package/.github/workflows/publish.yml

@@ -59,14 +59,14 @@ jobs:
         if: ${{ env.LOOP_SKIP == 'false' }}
         uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 22
           cache: 'npm'
 
       - name: Setup Node (npmjs)
         if: ${{ env.LOOP_SKIP == 'false' }}
         uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 22
           registry-url: https://registry.npmjs.org
           always-auth: true
         env:
@@ -143,7 +143,7 @@ jobs:
         if: ${{ env.LOOP_SKIP == 'false' }}
         uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 22
           registry-url: https://npm.pkg.github.com/
           always-auth: true
         env:

package/.github/workflows/release_dispatch.yml

@@ -19,7 +19,7 @@ jobs:
       - name: Setup Node
         uses: actions/setup-node@v4
         with:
-          node-version: '20'
+          node-version: '22'
 
       - name: Install deps
         run: npm ci

package/LICENSE

@@ -1,7 +1,7 @@
 The MIT License (MIT)
 
 Copyright (c) 2024 Cesar Anton <reicek@gmail.com>
-Copyright (c) 2017 Thomas Wagenaar <wagenaartje@protonmail.com>
+Copyright (c) 2017 Thomas Wagenaar <wagenaartje@protonmail.com> (parts used from Neataptic)
 Copyright (c) 2017 Juan Cazala (parts used from Synaptic)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reicek/neataptic-ts",
-  "version": "0.1.16",
+  "version": "0.1.19",
   "description": "Architecture-free neural network library with genetic algorithm implementations",
   "main": "./dist/neataptic.js",
   "module": "./dist/neataptic.js",