@panagos/jojoscript 0.7.1 → 0.8.0

package/package.json

@@ -1,59 +1,50 @@
-{
-  "name": "@panagos/jojoscript",
-  "version": "0.7.1",
-  "description": "A tiny JavaScript-compatible language layer with Jojo syntax and pipelines.",
-  "license": "Unlicense",
-  "type": "module",
-
-  "bin": {
-    "jojo": "./bin/jojo.js"
-  },
-
-  "exports": {
-    ".": {
-      "import": "./src/index.js"
-    },
-    "./runtime": {
-      "import": "./src/runtime/index.js"
-    }
-  },
-
-  "files": [
-    "bin/",
-    "src/",
-    "README.md",
-    "LICENSE"
-  ],
-
-  "engines": {
-    "node": ">=18"
-  },
-
-  "scripts": {
-    "test": "node --test test/*.test.js",
-    "build:example": "npm --prefix example install && npm --prefix example run build",
-    "run:example": "npm --prefix example run start"
-  },
-
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/panagos/jojoscript.git"
-  },
-
-  "homepage": "https://github.com/panagos/jojoscript",
-
-  "bugs": {
-    "url": "https://github.com/panagos/jojoscript/issues"
-  },
-
-  "keywords": [
-    "jojoscript",
-    "javascript",
-    "language",
-    "compiler",
-    "pipeline",
-    "functional-programming",
-    "iterators",
-    "lazy-iteration"
-  ]
-}
+{
+  "name": "@panagos/jojoscript",
+  "version": "0.8.0",
+  "description": "A tiny JavaScript-compatible language layer with Jojo syntax and pipelines.",
+  "license": "Unlicense",
+  "type": "module",
+  "bin": {
+    "jojo": "./bin/jojo.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./src/index.js"
+    },
+    "./runtime": {
+      "import": "./src/runtime/index.js"
+    }
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "build:example": "npm --prefix example install && npm --prefix example run build",
+    "run:example": "npm --prefix example run start"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/panagos/jojoscript.git"
+  },
+  "homepage": "https://github.com/panagos/jojoscript",
+  "bugs": {
+    "url": "https://github.com/panagos/jojoscript/issues"
+  },
+  "keywords": [
+    "jojoscript",
+    "javascript",
+    "language",
+    "compiler",
+    "pipeline",
+    "functional-programming",
+    "iterators",
+    "lazy-iteration"
+  ]
+}

package/src/compiler.js

@@ -1,186 +1,197 @@
-import fs from 'node:fs'
-import path from 'node:path'
-import { fileURLToPath } from 'node:url'
-
-import {
-  transformPipelines,
-  findPipelineStdlibFunctions
-} from './pipeline-parser.js'
-
-import {
-  transformMutableDeclarations,
-  transformConstDeclarations,
-  transformMultiBindingDeclarations,
-  transformDestructuringDeclarations,
-  transformFunctionDeclarations,
-  transformExpressionFunctions,
-  transformLocalImports
-} from './transforms.js'
-
-import { transformMatchExpressions } from './match-parser.js'
-import { transformTypeAnnotations } from './type-annotations.js'
-
-/*
- * The auto-generated runtime import must use whatever name this package is
- * actually installed under (e.g. a scoped fork like "@me/jojoscript"), not a
- * hardcoded literal, so it's derived from this package's own package.json
- * instead of being hardcoded.
- */
-const PACKAGE_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), '..')
-const OWN_PACKAGE_NAME = JSON.parse(
-  fs.readFileSync(path.join(PACKAGE_ROOT, 'package.json'), 'utf8')
-).name
-const JOJO_RUNTIME = `${OWN_PACKAGE_NAME}/runtime`
-
-export function compile(source) {
-  let result = source
-
-  /*
-   * Optional type annotations, stripped and re-expressed as JSDoc before
-   * anything else touches `fn` declarations.
-   */
-  result = transformTypeAnnotations(result)
-
-  /*
-   * Jojo functions.
-   */
-  result = transformExpressionFunctions(result)
-  result = transformFunctionDeclarations(result)
-
-  /*
-   * `match` expressions.
-   */
-  result = transformMatchExpressions(result)
-
-  /*
-   * Jojo declarations.
-   */
-  result = transformMultiBindingDeclarations(result)
-  result = transformDestructuringDeclarations(result)
-  result = transformMutableDeclarations(result)
-  result = transformConstDeclarations(result)
-
-  /*
-   * Remember which pipeline stages need the Jojo runtime before
-   * the pipeline syntax itself is removed.
-   */
-  const pipelineStdlibFunctions =
-    findPipelineStdlibFunctions(result)
-
-  /*
-   * Pipelines.
-   */
-  result = transformPipelines(result)
-
-  /*
-   * ES module imports.
-   */
-  result = transformLocalImports(result)
-
-  /*
-   * Generated JavaScript imports the runtime as a normal package.
-   * This makes compiled applications portable and avoids globals. If the
-   * source already has a manual `jojoscript/runtime` import (e.g. for a
-   * stdlib function that is only ever called directly, never through a
-   * pipeline stage), the auto-imported names are merged into it instead
-   * of creating a second, colliding import declaration.
-   */
-  if (pipelineStdlibFunctions.length) {
-    result = mergeRuntimeImport(result, pipelineStdlibFunctions)
-  }
-
-  return result.endsWith('\n') ? result : result + '\n'
-}
-
-const RUNTIME_IMPORT_PATTERN = new RegExp(
-  `import\\s*\\{([^}]*)\\}\\s*from\\s*(["'])${escapeRegExp(JOJO_RUNTIME)}\\2`
-)
-
-function escapeRegExp(value) {
-  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
-}
-
-function mergeRuntimeImport(source, stdlibFunctions) {
-  const existing = source.match(RUNTIME_IMPORT_PATTERN)
-
-  if (!existing) {
-    return `import { ${stdlibFunctions.join(', ')} } from "${JOJO_RUNTIME}"\n` + source
-  }
-
-  const existingNames = existing[1].split(',').map(name => name.trim()).filter(Boolean)
-  const merged = [...new Set([...existingNames, ...stdlibFunctions])]
-
-  return source.replace(
-    RUNTIME_IMPORT_PATTERN,
-    `import { ${merged.join(', ')} } from "${JOJO_RUNTIME}"`
-  )
-}
-
-export function compileFile(input, outDir = null) {
-  const src = path.resolve(input)
-  const dir = outDir
-    ? path.resolve(outDir)
-    : path.join(path.dirname(src), 'dist')
-
-  fs.mkdirSync(dir, { recursive: true })
-
-  const out = path.join(
-    dir,
-    path.basename(src, path.extname(src)) + '.js'
-  )
-
-  fs.writeFileSync(
-    out,
-    compile(fs.readFileSync(src, 'utf8')),
-    'utf8'
-  )
-
-  return { input: src, output: out }
-}
-
-export function compileDirectory(inputDir, outDir = null) {
-  const root = path.resolve(inputDir)
-  const target = outDir
-    ? path.resolve(outDir)
-    : path.join(root, 'dist')
-
-  const result = []
-
-  function walk(dir) {
-    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-      if (
-        entry.name === 'node_modules' ||
-        entry.name === 'dist' ||
-        entry.name.startsWith('.')
-      ) {
-        continue
-      }
-
-      const full = path.join(dir, entry.name)
-
-      if (entry.isDirectory()) {
-        walk(full)
-        continue
-      }
-
-      if (!entry.name.endsWith('.jojo')) continue
-
-      const rel =
-        path.relative(root, full).slice(0, -'.jojo'.length) + '.js'
-
-      const out = path.join(target, rel)
-
-      fs.mkdirSync(path.dirname(out), { recursive: true })
-      fs.writeFileSync(
-        out,
-        compile(fs.readFileSync(full, 'utf8')),
-        'utf8'
-      )
-
-      result.push({ input: full, output: out })
-    }
-  }
-
-  walk(root)
-  return result
-}
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import {
+  transformPipelines,
+  findPipelineStdlibFunctions,
+  hasPipelines
+} from './pipeline-parser.js'
+
+import {
+  transformMutableDeclarations,
+  transformConstDeclarations,
+  transformMultiBindingDeclarations,
+  transformDestructuringDeclarations,
+  transformFunctionDeclarations,
+  transformExpressionFunctions,
+  transformLocalImports
+} from './transforms.js'
+
+import { transformMatchExpressions } from './match-parser.js'
+import { transformTypeAnnotations } from './type-annotations.js'
+
+/*
+ * The auto-generated runtime import must use whatever name this package is
+ * actually installed under (e.g. a scoped fork like "@me/jojoscript"), not a
+ * hardcoded literal, so it's derived from this package's own package.json
+ * instead of being hardcoded.
+ */
+const PACKAGE_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), '..')
+const OWN_PACKAGE_NAME = JSON.parse(
+  fs.readFileSync(path.join(PACKAGE_ROOT, 'package.json'), 'utf8')
+).name
+const JOJO_RUNTIME = `${OWN_PACKAGE_NAME}/runtime`
+
+export function compile(source, options = {}) {
+  let result = source
+  const runtimeImport = options.runtimeImport ?? JOJO_RUNTIME
+
+  /*
+   * Optional type annotations, stripped and re-expressed as JSDoc before
+   * anything else touches `fn` declarations.
+   */
+  result = transformTypeAnnotations(result)
+
+  /*
+   * Jojo functions.
+   */
+  result = transformExpressionFunctions(result)
+  result = transformFunctionDeclarations(result)
+
+  /*
+   * `match` expressions.
+   */
+  result = transformMatchExpressions(result)
+
+  /*
+   * Jojo declarations.
+   */
+  result = transformMultiBindingDeclarations(result)
+  result = transformDestructuringDeclarations(result)
+  result = transformMutableDeclarations(result)
+  result = transformConstDeclarations(result)
+
+  /*
+   * Remember which pipeline stages need the Jojo runtime before
+   * the pipeline syntax itself is removed.
+   */
+  const pipelineStdlibFunctions =
+    findPipelineStdlibFunctions(result)
+
+  /*
+   * `jojo profile` compiles with `{ profile: true }`, which wraps every
+   * pipeline stage (and the initial source expression) in a call to the
+   * `traceNode` runtime helper. That helper is never written by the user,
+   * so it must be added to the auto-import list explicitly.
+   */
+  if (options.profile && hasPipelines(result) && !pipelineStdlibFunctions.includes('traceNode')) {
+    pipelineStdlibFunctions.push('traceNode')
+  }
+
+  /*
+   * Pipelines.
+   */
+  result = transformPipelines(result, options)
+
+  /*
+   * ES module imports.
+   */
+  result = transformLocalImports(result)
+
+  /*
+   * Generated JavaScript imports the runtime as a normal package.
+   * This makes compiled applications portable and avoids globals. If the
+   * source already has a manual `jojoscript/runtime` import (e.g. for a
+   * stdlib function that is only ever called directly, never through a
+   * pipeline stage), the auto-imported names are merged into it instead
+   * of creating a second, colliding import declaration.
+   */
+  if (pipelineStdlibFunctions.length) {
+    result = mergeRuntimeImport(result, pipelineStdlibFunctions, runtimeImport)
+  }
+
+  return result.endsWith('\n') ? result : result + '\n'
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+function mergeRuntimeImport(source, stdlibFunctions, runtimeImport) {
+  const pattern = new RegExp(
+    `import\\s*\\{([^}]*)\\}\\s*from\\s*(["'])([^"']+\\/runtime)\\2`
+  )
+  const existing = source.match(pattern)
+
+  if (!existing) {
+    return `import { ${stdlibFunctions.join(', ')} } from "${runtimeImport}"\n` + source
+  }
+
+  const existingNames = existing[1].split(',').map(name => name.trim()).filter(Boolean)
+  const merged = [...new Set([...existingNames, ...stdlibFunctions])]
+
+  return source.replace(
+    pattern,
+    `import { ${merged.join(', ')} } from "${runtimeImport}"`
+  )
+}
+
+export function compileFile(input, outDir = null, options = {}) {
+  const src = path.resolve(input)
+  const dir = outDir
+    ? path.resolve(outDir)
+    : path.join(path.dirname(src), 'dist')
+
+  fs.mkdirSync(dir, { recursive: true })
+
+  const out = path.join(
+    dir,
+    path.basename(src, path.extname(src)) + '.js'
+  )
+
+  fs.writeFileSync(
+    out,
+    compile(fs.readFileSync(src, 'utf8'), options),
+    'utf8'
+  )
+
+  return { input: src, output: out }
+}
+
+export function compileDirectory(inputDir, outDir = null, options = {}) {
+  const root = path.resolve(inputDir)
+  const target = outDir
+    ? path.resolve(outDir)
+    : path.join(root, 'dist')
+
+  const result = []
+
+  function walk(dir) {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (
+        entry.name === 'node_modules' ||
+        entry.name === 'dist' ||
+        entry.name.startsWith('.')
+      ) {
+        continue
+      }
+
+      const full = path.join(dir, entry.name)
+
+      if (entry.isDirectory()) {
+        walk(full)
+        continue
+      }
+
+      if (!entry.name.endsWith('.jojo')) continue
+
+      const rel =
+        path.relative(root, full).slice(0, -'.jojo'.length) + '.js'
+
+      const out = path.join(target, rel)
+
+      fs.mkdirSync(path.dirname(out), { recursive: true })
+      fs.writeFileSync(
+        out,
+        compile(fs.readFileSync(full, 'utf8'), options),
+        'utf8'
+      )
+
+      result.push({ input: full, output: out })
+    }
+  }
+
+  walk(root)
+  return result
+}

package/src/pipeline-hash.js

@@ -0,0 +1,27 @@
+import { createHash } from 'node:crypto'
+
+/*
+ * A pipeline's identity must be a deterministic hash of its *normalized*
+ * structure (stage names + arguments, whitespace-insensitive) rather than a
+ * random id, so the same program hashes to the same pipeline id across
+ * separate process runs. This is what lets checkpoint data saved by one run
+ * be found again by a later run (`jojo resume`, `jojo replay`).
+ */
+export function computePipelineId(pipeline) {
+  const normalized = {
+    expression: normalizeText(pipeline.expression),
+    stages: pipeline.stages.map(stage => ({
+      name: stage.name,
+      args: stage.args.map(normalizeText)
+    }))
+  }
+
+  return createHash('sha256')
+    .update(JSON.stringify(normalized))
+    .digest('hex')
+    .slice(0, 16)
+}
+
+function normalizeText(text) {
+  return text.replace(/\s+/g, ' ').trim()
+}

package/src/pipeline-ir.js

@@ -0,0 +1,100 @@
+import { findAllPipelines } from './pipeline-parser.js'
+import { computePipelineId } from './pipeline-hash.js'
+
+/*
+ * Static, execution-free representation of a pipeline: SOURCE, one node per
+ * stage, RESULT, chained by `dependencies`. Used by `jojo graph` (pure
+ * text/DOT rendering, no execution) and correlated at runtime with
+ * `jojo profile`'s collected metrics via the same `node-<n>` id scheme the
+ * compiler uses when emitting code (see `pipeline-parser.js`'s
+ * `emitPipeline`).
+ */
+export function buildGraph(pipeline, pipelineId = computePipelineId(pipeline)) {
+  const nodes = []
+
+  nodes.push({
+    id: 'node-0',
+    type: 'source',
+    label: pipeline.expression.trim(),
+    args: [],
+    dependencies: [],
+    metadata: {}
+  })
+
+  pipeline.stages.forEach((stage, index) => {
+    nodes.push({
+      id: `node-${index + 1}`,
+      type: stage.name,
+      label: stage.args.length ? `${stage.name}(${stage.args.join(', ')})` : stage.name,
+      args: stage.args,
+      dependencies: [`node-${index}`],
+      metadata: {}
+    })
+  })
+
+  const resultId = `node-${pipeline.stages.length + 1}`
+  nodes.push({
+    id: resultId,
+    type: 'result',
+    label: 'RESULT',
+    args: [],
+    dependencies: [`node-${pipeline.stages.length}`],
+    metadata: {}
+  })
+
+  return { id: pipelineId, expression: pipeline.expression.trim(), nodes }
+}
+
+/*
+ * Parses every pipeline statement in `source` and returns their graphs,
+ * each with a deterministic id derived from its normalized structure.
+ */
+export function analyzePipelines(source) {
+  return findAllPipelines(source).map(pipeline => buildGraph(pipeline))
+}
+
+export function renderGraphText(graph) {
+  const lines = []
+
+  graph.nodes.forEach((node, index) => {
+    let label
+    if (node.type === 'source') {
+      label = `SOURCE ${node.label}`
+    } else if (node.type === 'result') {
+      label = 'RESULT'
+    } else {
+      label = node.args.length
+        ? `${node.type.toUpperCase()} ${node.args.join(', ')}`
+        : node.type.toUpperCase()
+    }
+
+    lines.push(label)
+
+    if (index < graph.nodes.length - 1) {
+      lines.push('      │')
+      lines.push('      ▼')
+    }
+  })
+
+  return lines.join('\n')
+}
+
+export function renderGraphDot(graph) {
+  const lines = ['digraph pipeline {']
+
+  for (const node of graph.nodes) {
+    const dotLabel = node.args.length
+      ? `${node.type}\\n${node.args.join(', ').replace(/"/g, '\\"')}`
+      : node.type
+    lines.push(`  "${node.id}" [label="${dotLabel}"];`)
+  }
+
+  for (const node of graph.nodes) {
+    for (const dependency of node.dependencies) {
+      lines.push(`  "${dependency}" -> "${node.id}";`)
+    }
+  }
+
+  lines.push('}')
+  return lines.join('\n')
+}