@reicek/neataptic-ts 0.1.25 → 0.1.26

package/scripts/run-docs.ts

@@ -0,0 +1,238 @@
+/*
+ * Orchestrates the docs pipeline with one docs-scripts build and parallelized
+ * independent steps.
+ *
+ * This keeps the user-facing `npm run docs` and `npm run docs:folders`
+ * commands simple while removing repeated `docs:build-scripts` work and
+ * parallelizing the safe parts of the pipeline.
+ */
+
+import { spawn, type ChildProcess } from 'node:child_process';
+
+const ALL_MODE = 'all';
+const FOLDERS_MODE = 'folders';
+const SUPPORTED_MODES = new Set([ALL_MODE, FOLDERS_MODE]);
+
+interface ScriptTask {
+  label: string;
+  scriptName: string;
+}
+
+interface RunningTask {
+  childProcess: ChildProcess;
+  command: string;
+}
+
+interface SpawnedCommand {
+  command: string;
+  executable: string;
+  argumentsToPass: string[];
+}
+
+async function main(): Promise<void> {
+  const requestedMode = process.argv[2] ?? ALL_MODE;
+  ensureSupportedMode(requestedMode);
+
+  if (requestedMode === FOLDERS_MODE) {
+    await runFoldersWorkflow();
+    return;
+  }
+
+  await runFullDocsWorkflow();
+}
+
+async function runFullDocsWorkflow(): Promise<void> {
+  // Step 1: Build the browser example bundles in parallel.
+  await runScriptTasksInParallel([
+    { label: 'ASCII Maze bundle', scriptName: 'build:ascii-maze' },
+    { label: 'Flappy worker bundle', scriptName: 'build:flappy-worker' },
+    { label: 'Flappy Bird bundle', scriptName: 'build:flappy-bird' },
+  ]);
+
+  // Step 2: Generate copied example assets and folder docs in parallel.
+  await runScriptTasksInParallel([
+    { label: 'Examples copy', scriptName: 'docs:examples:built' },
+    { label: 'Source folder docs', scriptName: 'docs:folders:src:built' },
+    {
+      label: 'ASCII Maze folder docs',
+      scriptName: 'docs:folders:asciiMaze:built',
+    },
+    {
+      label: 'Flappy Bird folder docs',
+      scriptName: 'docs:folders:flappy-bird:built',
+    },
+  ]);
+
+  // Step 3: Render the final HTML site after content generation finishes.
+  await runScriptTask({
+    label: 'HTML docs render',
+    scriptName: 'docs:html:built',
+  });
+}
+
+async function runFoldersWorkflow(): Promise<void> {
+  await runScriptTasksInParallel([
+    { label: 'Source folder docs', scriptName: 'docs:folders:src:built' },
+    {
+      label: 'ASCII Maze folder docs',
+      scriptName: 'docs:folders:asciiMaze:built',
+    },
+    {
+      label: 'Flappy Bird folder docs',
+      scriptName: 'docs:folders:flappy-bird:built',
+    },
+  ]);
+}
+
+function ensureSupportedMode(
+  requestedMode: string,
+): asserts requestedMode is 'all' | 'folders' {
+  if (!SUPPORTED_MODES.has(requestedMode)) {
+    throw new Error(
+      `Unsupported docs mode "${requestedMode}". Expected one of: ${[...SUPPORTED_MODES].join(', ')}`,
+    );
+  }
+}
+
+async function runScriptTasksInParallel(
+  scriptTasks: readonly ScriptTask[],
+): Promise<void> {
+  if (scriptTasks.length === 0) {
+    return;
+  }
+
+  await new Promise<void>((resolve, reject) => {
+    const runningTasks: RunningTask[] = [];
+    let completedTaskCount = 0;
+    let hasSettled = false;
+
+    for (const scriptTask of scriptTasks) {
+      const spawnedCommand = createNpmRunCommand(scriptTask.scriptName);
+      const childProcess = spawn(
+        spawnedCommand.executable,
+        spawnedCommand.argumentsToPass,
+        {
+          stdio: 'inherit',
+        },
+      );
+      runningTasks.push({ childProcess, command: spawnedCommand.command });
+
+      childProcess.once('error', (error) => {
+        if (hasSettled) {
+          return;
+        }
+
+        hasSettled = true;
+        stopSiblingProcesses(runningTasks, childProcess);
+        reject(
+          new Error(
+            `Failed to start ${scriptTask.label} (${scriptTask.scriptName}): ${error.message}`,
+            { cause: error },
+          ),
+        );
+      });
+
+      childProcess.once('exit', (exitCode, signal) => {
+        if (hasSettled) {
+          return;
+        }
+
+        if (exitCode === 0) {
+          completedTaskCount += 1;
+          if (completedTaskCount === scriptTasks.length) {
+            hasSettled = true;
+            resolve();
+          }
+
+          return;
+        }
+
+        hasSettled = true;
+        stopSiblingProcesses(runningTasks, childProcess);
+        reject(
+          new Error(
+            `${scriptTask.label} (${scriptTask.scriptName}) failed with exit code ${exitCode ?? 'null'}${signal ? ` and signal ${signal}` : ''}.`,
+          ),
+        );
+      });
+    }
+  });
+}
+
+async function runScriptTask(scriptTask: ScriptTask): Promise<void> {
+  await runScriptTasksInParallel([scriptTask]);
+}
+
+function createNpmRunCommand(scriptName: string): SpawnedCommand {
+  const npmExecutablePath = process.env.npm_execpath;
+
+  if (npmExecutablePath) {
+    const argumentsToPass = [npmExecutablePath, 'run', scriptName];
+
+    return {
+      command: `${process.execPath} ${argumentsToPass.join(' ')}`,
+      executable: process.execPath,
+      argumentsToPass,
+    };
+  }
+
+  if (process.platform === 'win32') {
+    const executable = process.env.ComSpec ?? 'cmd.exe';
+    const argumentsToPass = ['/d', '/s', '/c', 'npm.cmd', 'run', scriptName];
+
+    return {
+      command: `${executable} ${argumentsToPass.join(' ')}`,
+      executable,
+      argumentsToPass,
+    };
+  }
+
+  const executable = 'npm';
+  const argumentsToPass = ['run', scriptName];
+
+  return {
+    command: `${executable} ${argumentsToPass.join(' ')}`,
+    executable,
+    argumentsToPass,
+  };
+}
+
+function stopSiblingProcesses(
+  runningTasks: readonly RunningTask[],
+  excludedProcess: ChildProcess,
+): void {
+  for (const { childProcess } of runningTasks) {
+    if (childProcess === excludedProcess || childProcess.killed) {
+      continue;
+    }
+
+    try {
+      stopProcess(childProcess);
+    } catch {
+      // Best-effort shutdown only.
+    }
+  }
+}
+
+function stopProcess(childProcess: ChildProcess): void {
+  const processId = childProcess.pid;
+
+  if (processId === undefined) {
+    childProcess.kill();
+    return;
+  }
+
+  if (process.platform === 'win32') {
+    spawn('taskkill', ['/pid', String(processId), '/t', '/f'], {
+      stdio: 'ignore',
+    }).unref();
+    return;
+  }
+
+  childProcess.kill();
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/scripts/write-dist-docs-pkg.ts

@@ -0,0 +1,40 @@
+/*
+ * Writes a minimal package.json into dist-docs designating ESM for generated
+ * scripts.
+ *
+ * Keeping this as a tiny compiled TypeScript utility aligns the scripts folder
+ * on one file type while preserving the same post-compile behavior.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const DIST_DOCS_DIRECTORY_PATH = path.resolve('dist-docs');
+const DIST_DOCS_PACKAGE_PATH = path.join(
+  DIST_DOCS_DIRECTORY_PATH,
+  'package.json',
+);
+const DIST_DOCS_PACKAGE_JSON = {
+  type: 'module',
+};
+
+/**
+ * Writes the `dist-docs/package.json` manifest.
+ *
+ * @returns Nothing.
+ */
+function main(): void {
+  try {
+    fs.mkdirSync(DIST_DOCS_DIRECTORY_PATH, { recursive: true });
+    fs.writeFileSync(
+      DIST_DOCS_PACKAGE_PATH,
+      `${JSON.stringify(DIST_DOCS_PACKAGE_JSON, null, 2)}\n`,
+    );
+    console.log('[docs] Wrote dist-docs/package.json (type=module)');
+  } catch (error) {
+    console.error('[docs] Failed to write dist-docs/package.json', error);
+    process.exit(1);
+  }
+}
+
+main();

package/src/README.md

@@ -38,40 +38,6 @@ Recommended reading after this root chapter:
 
 ## neat.ts
 
-### NeatOptions
-
-Public configuration bag for `Neat` evolutionary runs.
-
-`NeatOptions` collects the knobs that shape how search pressure is applied.
-In practice, readers can think about the options in four teaching-friendly groups:
-
-- search size and tempo: `popsize`, `elitism`, `provenance`, `mutationRate`, `mutationAmount`
-- species formation: compatibility threshold plus the excess, disjoint, and weight-difference coefficients
-- observability: telemetry, lineage, diversity sampling, species history, Pareto archive controls
-- reproducibility: `seed`, imported RNG state, and exported run state
-
-That organization matters because most experiment tuning questions are really
-questions about pressure: how many candidates compete, how disruptive mutation
-should feel, how aggressively genomes split into species, and how much evidence
-you want to retain while the run is unfolding.
-
-```ts
-const options: NeatOptions = {
-  popsize: 150,
-  elitism: 5,
-  mutationRate: 0.6,
-  compatibilityThreshold: 3,
-  fastMode: true,
-  seed: 42,
-};
-
-const neat = new Neat(3, 1, fitness, options);
-```
-
-This alias stays intentionally permissive for compatibility with legacy callers.
-Prefer treating it as the stable front door and the narrower helper-level types in
-`src/neat/**` as implementation detail.
-
 ### DEFAULT_COMPATIBILITY_THRESHOLD
 
 Default compatibility threshold controlling speciation distance.
@@ -1189,6 +1155,40 @@ reconstructed by other means.
 
 Returns: JSON-safe metadata snapshot useful for innovation-history persistence.
 
+### NeatOptions
+
+Public configuration bag for `Neat` evolutionary runs.
+
+`NeatOptions` collects the knobs that shape how search pressure is applied.
+In practice, readers can think about the options in four teaching-friendly groups:
+
+- search size and tempo: `popsize`, `elitism`, `provenance`, `mutationRate`, `mutationAmount`
+- species formation: compatibility threshold plus the excess, disjoint, and weight-difference coefficients
+- observability: telemetry, lineage, diversity sampling, species history, Pareto archive controls
+- reproducibility: `seed`, imported RNG state, and exported run state
+
+That organization matters because most experiment tuning questions are really
+questions about pressure: how many candidates compete, how disruptive mutation
+should feel, how aggressively genomes split into species, and how much evidence
+you want to retain while the run is unfolding.
+
+```ts
+const options: NeatOptions = {
+  popsize: 150,
+  elitism: 5,
+  mutationRate: 0.6,
+  compatibilityThreshold: 3,
+  fastMode: true,
+  seed: 42,
+};
+
+const neat = new Neat(3, 1, fitness, options);
+```
+
+This alias stays intentionally permissive for compatibility with legacy callers.
+Prefer treating it as the stable front door and the narrower helper-level types in
+`src/neat/**` as implementation detail.
+
 ## config.ts
 
 Global NeatapticTS configuration contract & default instance.
@@ -1241,6 +1241,47 @@ DESIGN NOTES
 
 ## neataptic.ts
 
+### neataptic
+
+Node (Neuron)
+=============
+Fundamental computational unit: aggregates weighted inputs, applies an activation
+function (squash) and emits an activation value. Supports:
+ - Types: 'input' | 'hidden' | 'output' (affects bias initialization & error handling)
+ - Recurrent self‑connections & gated connections (for dynamic / RNN behavior)
+ - Dropout mask (`mask`), momentum terms, eligibility & extended traces (for
+   a variety of learning rules beyond simple backprop).
+
+Educational note: Traces (`eligibility` and `xtrace`) illustrate how recurrent credit
+assignment works in algorithms like RTRL / policy gradients. They are updated only when
+using the traced activation path (`activate`) vs `noTraceActivate` (inference fast path).
+
+Examples:
+
+```ts
+const encoderBlock = new Group(4);
+const decoderBlock = new Group(4);
+
+encoderBlock.connect(
+  decoderBlock,
+  methods.groupConnection.ONE_TO_ONE,
+);
+```
+
+```ts
+const source = new Node('input');
+const target = new Node('output');
+const edge = new Connection(source, target, 0.42);
+
+edge.gain = 1.5;
+edge.enabled = true;
+```
+
+```ts
+const network = Architect.perceptron(2, 4, 1);
+const output = network.activate([0, 1]);
+```
+
 ### Neat
 
 High-level NEAT controller that keeps the public workflow linear while the implementation stays chaptered.
@@ -2236,47 +2277,6 @@ reconstructed by other means.
 
 Returns: JSON-safe metadata snapshot useful for innovation-history persistence.
 
-### neataptic
-
-Node (Neuron)
-=============
-Fundamental computational unit: aggregates weighted inputs, applies an activation
-function (squash) and emits an activation value. Supports:
- - Types: 'input' | 'hidden' | 'output' (affects bias initialization & error handling)
- - Recurrent self‑connections & gated connections (for dynamic / RNN behavior)
- - Dropout mask (`mask`), momentum terms, eligibility & extended traces (for
-   a variety of learning rules beyond simple backprop).
-
-Educational note: Traces (`eligibility` and `xtrace`) illustrate how recurrent credit
-assignment works in algorithms like RTRL / policy gradients. They are updated only when
-using the traced activation path (`activate`) vs `noTraceActivate` (inference fast path).
-
-Examples:
-
-```ts
-const encoderBlock = new Group(4);
-const decoderBlock = new Group(4);
-
-encoderBlock.connect(
-  decoderBlock,
-  methods.groupConnection.ONE_TO_ONE,
-);
-```
-
-```ts
-const source = new Node('input');
-const target = new Node('output');
-const edge = new Connection(source, target, 0.42);
-
-edge.gain = 1.5;
-edge.enabled = true;
-```
-
-```ts
-const network = Architect.perceptron(2, 4, 1);
-const output = network.activate([0, 1]);
-```
-
 ### default
 
 #### _activateCore

package/src/architecture/connection/README.md

@@ -29,11 +29,6 @@ edge.enabled = true;
 
 ## architecture/connection/connection.ts
 
-### ConnectionSymbolProps
-
-Internal interface for accessing symbol-keyed properties on Connection instances.
-Used for type-safe access to dynamic symbol properties.
-
 ### Connection
 
 Connection (Synapse / Edge)
@@ -61,6 +56,11 @@ edge.gain = 1.5;
 edge.enabled = true;
 ```
 
+### ConnectionSymbolProps
+
+Internal interface for accessing symbol-keyed properties on Connection instances.
+Used for type-safe access to dynamic symbol properties.
+
 ### default
 
 #### _flags