@reicek/neataptic-ts 0.1.24 → 0.1.26

package/scripts/copy-examples.ts

@@ -0,0 +1,239 @@
+/*
+ * Copies browser-viewable examples into docs/examples/* so GitHub Pages can
+ * publish them alongside the generated documentation site.
+ *
+ * The script intentionally keeps one narrow contract: copy each example's
+ * browser entrypoint into its published docs folder, then rebuild the shared
+ * examples landing page from the demos that were actually published.
+ */
+
+import { access, copyFile, mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+const DOCS_EXAMPLES_LOG_PREFIX = '[docs:examples]';
+const DOCS_EXAMPLES_DIR = path.resolve('docs', 'examples');
+const EXAMPLE_ENTRY_FILE_NAME = 'index.html';
+const DOCS_THEME_STYLESHEET_PATH = '../assets/theme.css';
+const DOCS_HOME_PATH = '../index.html';
+const EXAMPLES_HOME_PATH = './index.html';
+const GITHUB_REPOSITORY_URL = 'https://github.com/reicek/NeatapticTS';
+
+interface ExampleDefinition {
+  dirName: string;
+  label: string;
+  title: string;
+  sourceDir: string;
+}
+
+interface PublishedExample {
+  dirName: string;
+  label: string;
+  title: string;
+}
+
+const EXAMPLE_DEFINITIONS: readonly ExampleDefinition[] = [
+  {
+    dirName: 'asciiMaze',
+    label: 'asciiMaze',
+    title: 'ASCII Maze (NeatapticTS)',
+    sourceDir: path.resolve('test', 'examples', 'asciiMaze'),
+  },
+  {
+    dirName: 'flappy_bird',
+    label: 'flappy_bird',
+    title: 'Flappy Bird (NeatapticTS)',
+    sourceDir: path.resolve('test', 'examples', 'flappy_bird'),
+  },
+];
+
+/**
+ * Runs the example-copy workflow.
+ *
+ * Step 1 copies published browser entrypoints for all known examples.
+ * Step 2 rebuilds the landing page from the demos that were actually copied.
+ *
+ * @returns Promise resolved when copying and landing-page generation complete.
+ */
+async function main(): Promise<void> {
+  const publishedExamples = (
+    await Promise.all(EXAMPLE_DEFINITIONS.map(copyExampleEntryPoint))
+  ).filter(isPublishedExample);
+
+  await writeExamplesLandingPage(publishedExamples);
+}
+
+/**
+ * Copies one example entrypoint into `docs/examples/<name>/index.html`.
+ *
+ * @param exampleDefinition - Example publishing definition.
+ * @returns Published example metadata when the example entrypoint was copied,
+ * otherwise `null`.
+ */
+async function copyExampleEntryPoint(
+  exampleDefinition: ExampleDefinition,
+): Promise<PublishedExample | null> {
+  const hasSourceDirectory = await pathExists(exampleDefinition.sourceDir);
+  if (!hasSourceDirectory) {
+    console.warn(
+      `${DOCS_EXAMPLES_LOG_PREFIX} ${exampleDefinition.dirName} source directory not found, skipping`,
+    );
+    return null;
+  }
+
+  const sourceIndexPath = path.join(
+    exampleDefinition.sourceDir,
+    EXAMPLE_ENTRY_FILE_NAME,
+  );
+  const hasSourceIndex = await pathExists(sourceIndexPath);
+  if (!hasSourceIndex) {
+    console.warn(
+      `${DOCS_EXAMPLES_LOG_PREFIX} ${exampleDefinition.dirName} ${EXAMPLE_ENTRY_FILE_NAME} missing`,
+    );
+    return null;
+  }
+
+  const destinationDirectoryPath = path.join(
+    DOCS_EXAMPLES_DIR,
+    exampleDefinition.dirName,
+  );
+  const destinationIndexPath = path.join(
+    destinationDirectoryPath,
+    EXAMPLE_ENTRY_FILE_NAME,
+  );
+
+  await mkdir(destinationDirectoryPath, { recursive: true });
+  await copyFile(sourceIndexPath, destinationIndexPath);
+
+  console.log(
+    `${DOCS_EXAMPLES_LOG_PREFIX} Copied ${exampleDefinition.dirName} ${EXAMPLE_ENTRY_FILE_NAME}`,
+  );
+
+  return {
+    dirName: exampleDefinition.dirName,
+    label: exampleDefinition.label,
+    title: exampleDefinition.title,
+  };
+}
+
+/**
+ * Writes the shared docs/examples landing page.
+ *
+ * @param publishedExamples - Examples that were published in the current run.
+ * @returns Promise resolved when the landing page has been written.
+ */
+async function writeExamplesLandingPage(
+  publishedExamples: readonly PublishedExample[],
+): Promise<void> {
+  await mkdir(DOCS_EXAMPLES_DIR, { recursive: true });
+
+  const examplesLandingPageHtml =
+    buildExamplesLandingPageHtml(publishedExamples);
+  await writeFile(
+    path.join(DOCS_EXAMPLES_DIR, EXAMPLE_ENTRY_FILE_NAME),
+    examplesLandingPageHtml,
+    'utf8',
+  );
+
+  console.log(`${DOCS_EXAMPLES_LOG_PREFIX} Wrote examples landing page`);
+}
+
+/**
+ * Builds the shared examples landing page HTML.
+ *
+ * @param publishedExamples - Examples that were published in the current run.
+ * @returns Rendered landing page HTML.
+ */
+function buildExamplesLandingPageHtml(
+  publishedExamples: readonly PublishedExample[],
+): string {
+  const examplesListMarkup = buildExamplesListMarkup(publishedExamples);
+
+  return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Examples • NeatapticTS Docs</title>
+    <link rel="stylesheet" href="${DOCS_THEME_STYLESHEET_PATH}" />
+  </head>
+  <body>
+    <header class="topbar">
+      <div class="inner">
+        <div class="brand"><a href="${DOCS_HOME_PATH}">NeatapticTS</a></div>
+        <nav class="main-nav">
+          <a href="${DOCS_HOME_PATH}">Home</a>
+          <a href="${DOCS_HOME_PATH}">Docs</a>
+          <a href="${EXAMPLES_HOME_PATH}" class="active">Examples</a>
+          <a href="${GITHUB_REPOSITORY_URL}" target="_blank" rel="noopener">GitHub</a>
+        </nav>
+      </div>
+    </header>
+    <div class="layout">
+      <main class="content">
+        <h1>Examples</h1>
+        <p>Interactive browser demos built from this repository:</p>
+        ${examplesListMarkup}
+        <footer class="site-footer">Generated from source JSDoc • <a href="${GITHUB_REPOSITORY_URL}">GitHub</a></footer>
+      </main>
+    </div>
+  </body>
+</html>`;
+}
+
+/**
+ * Builds the published examples list markup.
+ *
+ * @param publishedExamples - Examples that were published in the current run.
+ * @returns HTML list markup.
+ */
+function buildExamplesListMarkup(
+  publishedExamples: readonly PublishedExample[],
+): string {
+  if (publishedExamples.length === 0) {
+    return '<p>No interactive examples were published in this run.</p>';
+  }
+
+  const listItemsMarkup = publishedExamples
+    .toSorted((leftExample, rightExample) =>
+      leftExample.title.localeCompare(rightExample.title),
+    )
+    .map(
+      (publishedExample) =>
+        `<li><a href="./${publishedExample.dirName}/${EXAMPLE_ENTRY_FILE_NAME}">${publishedExample.title}</a> <span class="demo-path">(examples/${publishedExample.label})</span></li>`,
+    )
+    .join('');
+
+  return `<ul>${listItemsMarkup}</ul>`;
+}
+
+/**
+ * Resolves whether a filesystem path exists.
+ *
+ * @param targetPath - Filesystem path to check.
+ * @returns True when the path exists.
+ */
+async function pathExists(targetPath: string): Promise<boolean> {
+  try {
+    await access(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Narrows `Promise.all` output to the published example shape.
+ *
+ * @param publishedExample - Candidate example result.
+ * @returns `true` when the example was published successfully.
+ */
+function isPublishedExample(
+  publishedExample: PublishedExample | null,
+): publishedExample is PublishedExample {
+  return publishedExample !== null;
+}
+
+main().catch((error: unknown) => {
+  console.error(`${DOCS_EXAMPLES_LOG_PREFIX} Failed:`, error);
+  process.exit(1);
+});

package/scripts/export-onnx.ts

@@ -0,0 +1,223 @@
+/**
+ * Minimal CLI to export a JSON ONNX model from a serialized network state.
+ *
+ * Usage:
+ *   npm run onnx:export -- --in network.json --out model.onnx.json [--metadata] [--batch] [--legacy] [--partial] [--mixed]
+ *
+ * This stays intentionally lightweight. For larger automation flows, prefer
+ * calling the ONNX export API directly from application code.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const PRIMARY_ONNX_MODULE_PATH = path.resolve(
+  'dist',
+  'architecture',
+  'onnx.js',
+);
+const FALLBACK_ONNX_MODULE_PATH = path.resolve(
+  'dist',
+  'architecture',
+  'network',
+  'network.onnx.js',
+);
+const NETWORK_MODULE_PATH = path.resolve('dist', 'architecture', 'network.js');
+
+interface ExportOnnxOptions {
+  includeMetadata: boolean;
+  batchDimension: boolean;
+  legacyNodeOrdering: boolean;
+  allowPartialConnectivity: boolean;
+  allowMixedActivations: boolean;
+}
+
+interface NetworkLike {
+  toJSON?: () => unknown;
+}
+
+interface NetworkFactory<TNetwork extends NetworkLike> {
+  fromJSON(raw: unknown): TNetwork;
+}
+
+interface OnnxExportModule<TNetwork extends NetworkLike> {
+  exportToONNX: (network: TNetwork, options: ExportOnnxOptions) => unknown;
+}
+
+interface DistDependencies<TNetwork extends NetworkLike> {
+  Network: NetworkFactory<TNetwork>;
+  exportToONNX: OnnxExportModule<TNetwork>['exportToONNX'];
+}
+
+interface ParsedCliOptions extends ExportOnnxOptions {
+  inputFile: string;
+  outputFile: string;
+}
+
+/**
+ * Runs the ONNX export CLI.
+ *
+ * @returns Promise resolved when export succeeds.
+ */
+async function main(): Promise<void> {
+  const rawArguments = process.argv.slice(2);
+  if (hasFlag(rawArguments, '--help') || hasFlag(rawArguments, '-h')) {
+    printUsage();
+    return;
+  }
+
+  const cliOptions = parseCliOptions(rawArguments);
+  const { Network, exportToONNX } = await loadDistDependencies<NetworkLike>();
+  const networkJson = readJsonFile(cliOptions.inputFile);
+  const network = Network.fromJSON(networkJson);
+  const onnxJson = exportToONNX(network, cliOptions);
+
+  fs.writeFileSync(
+    path.resolve(cliOptions.outputFile),
+    `${JSON.stringify(onnxJson, null, 2)}\n`,
+    'utf8',
+  );
+  console.log(`ONNX JSON written to ${cliOptions.outputFile}`);
+}
+
+/**
+ * Parses CLI options from raw process arguments.
+ *
+ * @param rawArguments - CLI arguments after the script path.
+ * @returns Parsed and validated CLI options.
+ */
+function parseCliOptions(rawArguments: readonly string[]): ParsedCliOptions {
+  const inputFile = resolveOptionValue(rawArguments, '--in');
+  const outputFile = resolveOptionValue(rawArguments, '--out');
+
+  if (!inputFile || !outputFile) {
+    printUsageAndExit('Error: --in and --out are required.');
+  }
+
+  return {
+    inputFile,
+    outputFile,
+    includeMetadata: hasFlag(rawArguments, '--metadata'),
+    batchDimension: hasFlag(rawArguments, '--batch'),
+    legacyNodeOrdering: hasFlag(rawArguments, '--legacy'),
+    allowPartialConnectivity: hasFlag(rawArguments, '--partial'),
+    allowMixedActivations: hasFlag(rawArguments, '--mixed'),
+  };
+}
+
+/**
+ * Resolves one option value from `--name value` or `--name=value` syntax.
+ *
+ * @param rawArguments - CLI arguments after the script path.
+ * @param optionName - Long option name including leading dashes.
+ * @returns Option value when present.
+ */
+function resolveOptionValue(
+  rawArguments: readonly string[],
+  optionName: string,
+): string | undefined {
+  const exactIndex = rawArguments.indexOf(optionName);
+  if (exactIndex >= 0) {
+    return rawArguments[exactIndex + 1];
+  }
+
+  const inlineArgument = rawArguments.find((argument) =>
+    argument.startsWith(`${optionName}=`),
+  );
+  return inlineArgument?.slice(optionName.length + 1);
+}
+
+/**
+ * Checks whether a boolean flag is present.
+ *
+ * @param rawArguments - CLI arguments after the script path.
+ * @param optionName - Flag name including leading dashes.
+ * @returns `true` when the flag is present.
+ */
+function hasFlag(rawArguments: readonly string[], optionName: string): boolean {
+  return rawArguments.includes(optionName);
+}
+
+/**
+ * Loads the built network and ONNX export modules from `dist/`.
+ *
+ * @returns The built network constructor and ONNX export function.
+ */
+async function loadDistDependencies<TNetwork extends NetworkLike>(): Promise<
+  DistDependencies<TNetwork>
+> {
+  const onnxModule = (await importModuleWithFallback<
+    Partial<OnnxExportModule<TNetwork>>
+  >(PRIMARY_ONNX_MODULE_PATH, FALLBACK_ONNX_MODULE_PATH)) as Partial<
+    OnnxExportModule<TNetwork>
+  >;
+  const networkModule = (await import(
+    pathToFileURL(NETWORK_MODULE_PATH).href
+  )) as { default?: NetworkFactory<TNetwork> };
+
+  if (!networkModule.default || typeof onnxModule.exportToONNX !== 'function') {
+    throw new Error(
+      'Failed to load built ONNX export dependencies from dist/.',
+    );
+  }
+
+  return {
+    Network: networkModule.default,
+    exportToONNX: onnxModule.exportToONNX,
+  };
+}
+
+/**
+ * Imports the primary built module, falling back to a secondary path when the
+ * public layout has shifted.
+ *
+ * @param primaryModulePath - Preferred built module path.
+ * @param fallbackModulePath - Fallback built module path.
+ * @returns Imported module namespace.
+ */
+async function importModuleWithFallback<TModule>(
+  primaryModulePath: string,
+  fallbackModulePath: string,
+): Promise<TModule> {
+  try {
+    return (await import(pathToFileURL(primaryModulePath).href)) as TModule;
+  } catch {
+    return (await import(pathToFileURL(fallbackModulePath).href)) as TModule;
+  }
+}
+
+/**
+ * Reads and parses one JSON file.
+ *
+ * @param filePath - Source JSON file path.
+ * @returns Parsed JSON value.
+ */
+function readJsonFile(filePath: string): unknown {
+  return JSON.parse(fs.readFileSync(path.resolve(filePath), 'utf8')) as unknown;
+}
+
+/** Prints CLI usage text. */
+function printUsage(): void {
+  console.log(
+    'Usage: npm run onnx:export -- --in network.json --out model.onnx.json [--metadata] [--batch] [--legacy] [--partial] [--mixed]',
+  );
+}
+
+/**
+ * Prints CLI usage text and exits the process with failure.
+ *
+ * @param message - Error message shown before usage text.
+ * @returns Never returns.
+ */
+function printUsageAndExit(message: string): never {
+  console.error(message);
+  printUsage();
+  process.exit(1);
+}
+
+main().catch((error: unknown) => {
+  const errorMessage = error instanceof Error ? error.message : String(error);
+  console.error('Export failed:', errorMessage);
+  process.exit(1);
+});