@panagos/jojoscript 0.10.1 → 1.0.0

package/src/match-parser.js

@@ -20,10 +20,11 @@ import { tokenize, significantTokens } from './lexer.js'
  *     return handleUnknown();
  *   })()
  *
- * This is deliberately a value-equality match, not structural pattern
- * matching: patterns are plain expressions compared with `===`, and arms
- * are single expressions (no statement blocks). The default `_` arm is
- * required and must be last.
+ * Arms are single expressions (no statement blocks), separated by commas or
+ * newlines. Object patterns such as `{ status: "ok", value }` match
+ * structurally; any other pattern is compared with `===`. A value-equality
+ * match requires a final `_` arm, while a structural match without one
+ * throws when nothing matches.
  */
 
 function text(source, tokens) {
@@ -125,8 +126,157 @@ function findMatchBlock(source, tokens, index) {
   return { subjectTokens, braceOpen, braceClose }
 }
 
+function isNewlineBetween(source, previous, next) {
+  return source.slice(previous.end, next.start).includes('\n')
+}
+
+function hasTopLevelArrowBeforeNewline(source, tokens, start) {
+  let depth = 0
+  for (let i = start; i < tokens.length; i++) {
+    if (i > start && depth === 0 && isNewlineBetween(source, tokens[i - 1], tokens[i])) return false
+    const value = tokens[i].value
+    if (value === '(' || value === '[' || value === '{') depth++
+    else if (value === ')' || value === ']' || value === '}') depth--
+    else if (value === '=>' && depth === 0) return true
+  }
+  return false
+}
+
+/*
+ * A new line starts a new arm only once the current arm has its `=>` and the
+ * new line has its own top-level `=>`, so multi-line arm expressions still work.
+ */
+function splitArms(source, tokens) {
+  const result = []
+  let start = 0
+  let depth = 0
+  let seenArrow = false
+
+  for (let i = 0; i < tokens.length; i++) {
+    const value = tokens[i].value
+
+    if (
+      depth === 0 && seenArrow && i > start &&
+      tokens[i - 1].value !== '=>' &&
+      isNewlineBetween(source, tokens[i - 1], tokens[i]) &&
+      hasTopLevelArrowBeforeNewline(source, tokens, i)
+    ) {
+      result.push(tokens.slice(start, i))
+      start = i
+      seenArrow = false
+    }
+
+    if (value === '(' || value === '[' || value === '{') depth++
+    else if (value === ')' || value === ']' || value === '}') depth--
+    else if (value === '=>' && depth === 0) seenArrow = true
+    else if (value === ',' && depth === 0) {
+      result.push(tokens.slice(start, i))
+      start = i + 1
+      seenArrow = false
+    }
+  }
+
+  if (start < tokens.length) result.push(tokens.slice(start))
+  return result
+}
+
+const LITERAL_IDENTIFIERS = new Set(['true', 'false', 'null', 'undefined'])
+
+function isBindingName(tokens) {
+  return tokens.length === 1 &&
+    tokens[0].type === 'identifier' &&
+    !LITERAL_IDENTIFIERS.has(tokens[0].value)
+}
+
+function matchingClose(tokens, openIndex) {
+  let depth = 0
+  for (let i = openIndex; i < tokens.length; i++) {
+    const value = tokens[i].value
+    if (value === '(' || value === '[' || value === '{') depth++
+    else if (value === ')' || value === ']' || value === '}') {
+      depth--
+      if (depth === 0) return i
+    }
+  }
+  return -1
+}
+
+function isObjectPattern(tokens) {
+  return tokens[0]?.value === '{' && matchingClose(tokens, 0) === tokens.length - 1
+}
+
+function isConstructorPattern(tokens) {
+  return tokens[0]?.type === 'identifier' &&
+    /^[A-Z]/.test(tokens[0].value) &&
+    tokens[1]?.value === '(' &&
+    matchingClose(tokens, 1) === tokens.length - 1
+}
+
+function isStructuralPattern(tokens) {
+  return isObjectPattern(tokens) || isConstructorPattern(tokens)
+}
+
+// Fields bind by position through the constructor's `fields`, so values decoded from JSON still match.
+function compileConstructorPattern(source, tokens, accessor) {
+  const variant = tokens[0].value
+  const conditions = [
+    `${accessor} !== null && typeof ${accessor} === "object"`,
+    `${accessor}.tag === ${JSON.stringify(variant)}`
+  ]
+  const bindings = []
+
+  splitTopLevelCommas(tokens.slice(2, -1)).filter(group => group.length).forEach((argument, index) => {
+    const pattern = compilePattern(source, argument, `${accessor}[${variant}.fields[${index}]]`, true)
+    conditions.push(...pattern.conditions)
+    bindings.push(...pattern.bindings)
+  })
+
+  return { conditions, bindings }
+}
+
+/*
+ * Inside an object pattern a bare name binds the field, while literals and
+ * other expressions are compared with `===`.
+ */
+function compilePattern(source, tokens, accessor, nested) {
+  if (tokens.length === 1 && tokens[0].value === '_') return { conditions: [], bindings: [] }
+
+  if (isObjectPattern(tokens)) return compileObjectPattern(source, tokens, accessor)
+  if (isConstructorPattern(tokens)) return compileConstructorPattern(source, tokens, accessor)
+
+  if (nested && isBindingName(tokens)) {
+    return { conditions: [], bindings: [[tokens[0].value, accessor]] }
+  }
+
+  return { conditions: [`${accessor} === (${text(source, tokens)})`], bindings: [] }
+}
+
+function compileObjectPattern(source, tokens, accessor) {
+  const conditions = [`${accessor} !== null && typeof ${accessor} === "object"`]
+  const bindings = []
+
+  for (const field of splitTopLevelCommas(tokens.slice(1, -1)).filter(group => group.length)) {
+    const colon = field.findIndex(token => token.value === ':')
+    const keyTokens = colon === -1 ? field : field.slice(0, colon)
+    const valueTokens = colon === -1 ? field : field.slice(colon + 1)
+
+    if (keyTokens.length !== 1 || !['identifier', 'string'].includes(keyTokens[0].type) || !valueTokens.length) {
+      throw new SyntaxError(`Invalid match pattern field: ${text(source, field)}`)
+    }
+
+    const key = keyTokens[0].type === 'string' ? keyTokens[0].value : JSON.stringify(keyTokens[0].value)
+    const fieldAccessor = `${accessor}[${key}]`
+    const pattern = compilePattern(source, valueTokens, fieldAccessor, true)
+
+    conditions.push(`${key} in ${accessor}`, ...pattern.conditions)
+    bindings.push(...pattern.bindings)
+  }
+
+  return { conditions, bindings }
+}
+
 function parseArms(source, tokens) {
-  const groups = splitTopLevelCommas(tokens).filter(group => group.length)
+  const groups = splitArms(source, tokens).filter(group => group.length)
 
   if (!groups.length) {
     throw new SyntaxError('match requires at least one arm')
@@ -147,33 +297,81 @@ function parseArms(source, tokens) {
       throw new SyntaxError(`Invalid match arm, expected \`pattern => expression\`:\n${text(source, group)}`)
     }
 
-    const pattern = text(source, group.slice(0, arrowIndex)).trim()
+    const patternTokens = group.slice(0, arrowIndex)
+    const pattern = text(source, patternTokens).trim()
     const expression = text(source, group.slice(arrowIndex + 1)).trim()
 
     if (!pattern || !expression) {
       throw new SyntaxError(`Invalid match arm, expected \`pattern => expression\`:\n${text(source, group)}`)
     }
 
-    return { pattern, expression }
+    return {
+      pattern,
+      expression,
+      structural: isStructuralPattern(patternTokens),
+      variant: isConstructorPattern(patternTokens)
+        ? {
+            name: patternTokens[0].value,
+            arity: splitTopLevelCommas(patternTokens.slice(2, -1)).filter(argument => argument.length).length,
+            line: lineAt(source, patternTokens[0].start)
+          }
+        : null,
+      compiled: compilePattern(source, patternTokens, '__match', false)
+    }
   })
 }
 
+function lineAt(source, offset) {
+  return source.slice(0, offset).split('\n').length
+}
+
+// Static view of every match expression, used by `jojo check` for exhaustiveness.
+export function findMatchExpressions(source) {
+  const tokens = significantTokens(tokenize(source))
+  const matches = []
+
+  for (let i = 0; i < tokens.length; i++) {
+    if (!isMatchKeyword(tokens, i)) continue
+    const block = findMatchBlock(source, tokens, i)
+    if (!block) continue
+
+    const arms = parseArms(source, tokens.slice(block.braceOpen + 1, block.braceClose))
+    matches.push({
+      line: lineAt(source, tokens[i].start),
+      hasDefault: arms.some(arm => arm.pattern === '_'),
+      arms: arms.map(({ pattern, variant }) => ({ pattern, variant }))
+    })
+  }
+
+  return matches
+}
+
+function emitArm({ pattern, expression, compiled: { conditions, bindings } }) {
+  if (pattern === '_') return `  return ${expression};`
+
+  const condition = conditions.map(item => conditions.length > 1 ? `(${item})` : item).join(' && ')
+  if (!bindings.length) return `  if (${condition}) return ${expression};`
+
+  const declarations = bindings.map(([name, accessor]) => `${name} = ${accessor}`).join(', ')
+  return `  if (${condition}) { const ${declarations}; return ${expression}; }`
+}
+
 function emitMatch(subject, arms) {
   const defaultIndex = arms.findIndex(arm => arm.pattern === '_')
+  const structural = arms.some(arm => arm.structural)
 
-  if (defaultIndex === -1) {
+  if (defaultIndex === -1 && !structural) {
     throw new SyntaxError('match requires a default `_` arm')
   }
 
-  if (defaultIndex !== arms.length - 1) {
+  if (defaultIndex !== -1 && defaultIndex !== arms.length - 1) {
     throw new SyntaxError('the default `_` arm must be the last arm in match')
   }
 
-  const lines = arms.map(arm =>
-    arm.pattern === '_'
-      ? `  return ${arm.expression};`
-      : `  if (__match === (${arm.pattern})) return ${arm.expression};`
-  )
+  const lines = arms.map(emitArm)
+  if (defaultIndex === -1) {
+    lines.push("  throw new TypeError('No match arm matched the value');")
+  }
 
   return `(() => {\n  const __match = ${subject};\n${lines.join('\n')}\n})()`
 }

package/src/named-pipelines.js

@@ -0,0 +1,87 @@
+import { maskNonCode } from './lexer.js'
+
+const PIPELINE_HEAD = /^([ \t]*)(export[ \t]+)?pipeline[ \t]+([A-Za-z_$][\w$]*)[ \t]*\{/gm
+const SOURCE_LINE = /^([ \t]*)source[ \t]+(.+?)[ \t]*$/
+
+function lineAt(source, offset) {
+  return source.slice(0, offset).split('\n').length
+}
+
+function matchingBrace(code, openIndex) {
+  let depth = 0
+  for (let i = openIndex; i < code.length; i++) {
+    if (code[i] === '{') depth++
+    else if (code[i] === '}' && --depth === 0) return i
+  }
+  throw new SyntaxError('Unclosed pipeline block')
+}
+
+/*
+ * `pipeline name { source input |> stages }` is a named, reusable pipeline.
+ * An identifier source becomes the function's single input parameter.
+ */
+export function findNamedPipelines(source) {
+  const code = maskNonCode(source)
+  const regex = new RegExp(PIPELINE_HEAD.source, PIPELINE_HEAD.flags)
+  const pipelines = []
+  let match
+
+  while ((match = regex.exec(code))) {
+    const [head, indent, exportPart, name] = match
+    const bodyOpen = match.index + head.length - 1
+    const bodyClose = matchingBrace(code, bodyOpen)
+    const lines = source.slice(bodyOpen + 1, bodyClose).split('\n')
+
+    const sourceIndex = lines.findIndex(line => line.trim())
+    const sourceLine = sourceIndex === -1 ? null : lines[sourceIndex].match(SOURCE_LINE)
+    if (!sourceLine) throw new SyntaxError(`pipeline "${name}" must start with "source <expression>"`)
+
+    const stageLines = lines.slice(sourceIndex + 1).filter(line => line.trim())
+    if (!stageLines.length) throw new SyntaxError(`pipeline "${name}" has no stages`)
+
+    const expression = sourceLine[2]
+    pipelines.push({
+      name,
+      inputs: /^[A-Za-z_$][\w$]*$/.test(expression) ? [expression] : [],
+      expression,
+      exported: Boolean(exportPart),
+      // Only a top-level `|> await` or an awaited source needs an async function; awaits inside stage callbacks do not.
+      async: /\bawait\b/.test(expression) || stageLines.some(line => /^\s*\|>\s*await\b/.test(line)),
+      line: lineAt(source, match.index + indent.length),
+      indent,
+      sourceIndent: sourceLine[1],
+      stageLines,
+      // The first and last entries are the rest of the `{` line and the start of the `}` line.
+      blankLines: Math.max(0, lines.length - 3 - stageLines.length),
+      start: match.index,
+      end: bodyClose + 1
+    })
+  }
+
+  return pipelines
+}
+
+/*
+ * Blank lines would split the returned pipeline into separate statements, so
+ * they move to the end of the block, which keeps its total line count.
+ */
+export function transformNamedPipelines(source) {
+  let result = source
+
+  for (const pipeline of findNamedPipelines(source).reverse()) {
+    const exportPart = pipeline.exported ? 'export ' : ''
+    const asyncPart = pipeline.async ? 'async ' : ''
+    const body = [
+      `${pipeline.sourceIndent}return ${pipeline.expression}`,
+      ...pipeline.stageLines,
+      ...Array(pipeline.blankLines).fill('')
+    ].join('\n')
+
+    const replacement =
+      `${pipeline.indent}${exportPart}${asyncPart}fn ${pipeline.name}(${pipeline.inputs.join(', ')}) {\n${body}\n${pipeline.indent}}`
+
+    result = result.slice(0, pipeline.start) + replacement + result.slice(pipeline.end)
+  }
+
+  return result
+}

package/src/parse.js

@@ -0,0 +1,124 @@
+import { maskNonCode } from './lexer.js'
+import { findAllPipelines } from './pipeline-parser.js'
+import { inferPipelineName } from './pipeline-explain.js'
+import { findNamedPipelines, transformNamedPipelines } from './named-pipelines.js'
+import { findEffectDeclarations, findHandleBlocks } from './effect-parser.js'
+import { findTypeDeclarations } from './type-declarations.js'
+import { findContracts } from './contracts.js'
+import { findMatchExpressions } from './match-parser.js'
+
+const PARSE_VERSION = '1'
+const IMPORT = /^[ \t]*import\s+([^'"]+?)\s+from\s+(["'])([^"']+)\2/gm
+const FUNCTION = /^[ \t]*(export[ \t]+)?(?:(async)[ \t]+)?(?:(pure|effectful)[ \t]+)?(?:(async)[ \t]+)?fn[ \t]+([A-Za-z_$][\w$]*)[ \t]*\(/gm
+
+function lineAt(source, offset) {
+  return source.slice(0, offset).split('\n').length
+}
+
+function splitTopLevel(text) {
+  const parts = []
+  let depth = 0
+  let start = 0
+  for (let i = 0; i < text.length; i++) {
+    if ('([{'.includes(text[i])) depth++
+    else if (')]}'.includes(text[i])) depth--
+    else if (text[i] === ',' && depth === 0) {
+      parts.push(text.slice(start, i).trim())
+      start = i + 1
+    }
+  }
+  if (text.trim()) parts.push(text.slice(start).trim())
+  return parts
+}
+
+function matchingParen(code, open) {
+  let depth = 0
+  for (let i = open; i < code.length; i++) {
+    if (code[i] === '(') depth++
+    else if (code[i] === ')' && --depth === 0) return i
+  }
+  return code.length
+}
+
+function parseImports(source, code) {
+  return [...source.matchAll(IMPORT)]
+    .filter(match => code.startsWith('import', match.index + match[0].search(/import/)))
+    .map(match => ({
+      kind: 'import',
+      line: lineAt(source, match.index),
+      from: match[3],
+      names: splitTopLevel(match[1].replace(/[{}]/g, ',')).filter(Boolean)
+    }))
+}
+
+function parseFunctions(source, code) {
+  const contracts = findContracts(source)
+
+  return [...code.matchAll(FUNCTION)].map(match => {
+    const [head, exportPart, asyncBefore, purity, asyncAfter, name] = match
+    const open = match.index + head.length - 1
+    const close = matchingParen(code, open)
+    const restOfLine = code.slice(close + 1).split('\n')[0]
+    const line = lineAt(source, match.index + head.search(/\S/))
+    const contract = contracts.find(item => item.name === name && item.line === line)
+
+    return {
+      kind: 'function',
+      line,
+      name,
+      params: splitTopLevel(source.slice(open + 1, close)),
+      exported: Boolean(exportPart),
+      async: Boolean(asyncBefore || asyncAfter),
+      purity: purity ?? null,
+      body: /^\s*(?::[^={]*)?=(?![=>])/.test(restOfLine) ? 'expression' : 'block',
+      requires: contract?.requires.map(clause => clause.condition) ?? [],
+      ensures: contract?.ensures.map(clause => clause.condition) ?? []
+    }
+  })
+}
+
+/*
+ * Named pipeline blocks are analyzed through their compiled `fn` form, which
+ * keeps every line in place, so their nodes report the `pipeline` line.
+ */
+function parsePipelines(rawSource) {
+  const source = transformNamedPipelines(rawSource)
+  const declared = findNamedPipelines(rawSource)
+
+  return findAllPipelines(source).map(pipeline => {
+    const name = inferPipelineName(source, pipeline)
+    const startLine = lineAt(source, pipeline.start)
+    const block = declared.find(item => item.name === name && item.line < startLine)
+
+    return {
+      kind: 'pipeline',
+      line: block ? block.line : startLine,
+      name,
+      declared: Boolean(block),
+      source: pipeline.expression,
+      stages: pipeline.stages.map(stage => ({ type: stage.name, args: stage.args, id: stage.id ?? null }))
+    }
+  })
+}
+
+export function parseSource(source) {
+  const code = maskNonCode(source)
+
+  const nodes = [
+    ...parseImports(source, code),
+    ...findEffectDeclarations(source).map(effect => ({ kind: 'effect', line: lineAt(source, effect.start), name: effect.name, params: effect.params })),
+    ...findTypeDeclarations(source).map(type => ({
+      kind: 'type',
+      line: lineAt(source, type.start + type.indent.length),
+      name: type.name,
+      exported: type.exported,
+      variants: type.variants
+    })),
+    ...parseFunctions(source, code),
+    ...parsePipelines(source),
+    ...findHandleBlocks(source).map(block => ({ kind: 'handle', line: lineAt(source, block.start), handlers: block.handlerNames })),
+    ...findMatchExpressions(source).map(match => ({ kind: 'match', line: match.line, patterns: match.arms.map(arm => arm.pattern) }))
+  ]
+
+  return { language: 'jojo', version: PARSE_VERSION, nodes: nodes.sort((a, b) => a.line - b.line) }
+}

package/src/pipeline-explain.js

@@ -0,0 +1,132 @@
+import { maskNonCode } from './lexer.js'
+import { findAllPipelines } from './pipeline-parser.js'
+import { analyzePipelines, namesReferencedByStage } from './pipeline-ir.js'
+import { findPurityDeclarations } from './purity.js'
+import { transformNamedPipelines } from './named-pipelines.js'
+
+const CONTROL_STAGES = new Set(['await', 'catch', 'orElse', 'pass'])
+const MATERIALIZING_STAGES = new Set(['sort', 'sortBy', 'groupBy', 'partition'])
+
+const ASSIGNED_NAME = /(?:^|[^\w$.])([A-Za-z_$][\w$]*)\s*(?::=|=|:)$/
+const EXPRESSION_FUNCTION_NAME = /\bfn\s+([A-Za-z_$][\w$]*)\s*\([^()]*\)\s*=$/
+const FUNCTION_NAME = /\b(?:fn|function)\s+([A-Za-z_$][\w$]*)\s*\(/g
+
+/*
+ * A static, execution-free description of what each pipeline in `source`
+ * means, built on the same graph as `jojo graph`. Purity and determinism
+ * only reflect references to declared effects; ordinary JavaScript calls
+ * inside a stage are not analyzed.
+ */
+export function explainPipelines(jojoSource) {
+  const source = transformNamedPipelines(jojoSource)
+  const pipelines = findAllPipelines(source)
+  const effectfulFunctionNames = findPurityDeclarations(source)
+    .filter(declaration => declaration.purity === 'effectful')
+    .map(declaration => declaration.name)
+
+  return analyzePipelines(source).map((graph, index) => {
+    const stages = graph.nodes
+      .filter(node => node.type !== 'result')
+      .map((node, position) => describeStage(node, position + 1, effectfulFunctionNames))
+
+    return {
+      name: inferPipelineName(source, pipelines[index]) ?? `pipeline-${index + 1}`,
+      id: graph.id,
+      stages,
+      effects: uniqueEffects(graph.effects),
+      properties: {
+        lazy: !stages.some(stage => MATERIALIZING_STAGES.has(stage.type)),
+        parallel: stages.some(stage => stage.type === 'parallel'),
+        resumable: stages.some(stage => stage.type === 'checkpoint'),
+        deterministic: stages.every(stage => !stage.effects.length && !stage.effectfulFunctions.length)
+      }
+    }
+  })
+}
+
+function describeStage(node, index, effectfulFunctionNames) {
+  const effects = node.metadata.effects ?? []
+  const effectfulFunctions = node.type === 'source'
+    ? []
+    : namesReferencedByStage({ name: node.type, args: node.args }, effectfulFunctionNames)
+
+  return {
+    index,
+    id: node.type === 'source' || /^node-\d+$/.test(node.id) ? null : node.id,
+    type: node.type,
+    detail: stageDetail(node, [...effects, ...effectfulFunctions]),
+    args: node.args,
+    effects,
+    effectfulFunctions
+  }
+}
+
+function stageDetail(node, effects) {
+  if (node.type === 'source') return node.label
+  if (CONTROL_STAGES.has(node.type)) return 'control'
+  if (node.type === 'parallel') return `concurrency=${node.args[0]}`
+  if (node.type === 'batch') return `size=${node.args[0]}`
+  if (node.type === 'checkpoint') return node.args[0].replace(/^(["'`])(.*)\1$/, '$2')
+  return effects.length ? `effectful: ${effects.join(', ')}` : 'pure'
+}
+
+function uniqueEffects(effects) {
+  const byName = new Map()
+  for (const { name, staticallyHandled } of effects) {
+    if (!byName.has(name)) byName.set(name, { name, staticallyHandled })
+  }
+  return [...byName.values()]
+}
+
+export function inferPipelineName(source, pipeline) {
+  const lead = (source.slice(0, pipeline.start) + pipeline.prefix).trimEnd()
+
+  const expressionFunction = lead.match(EXPRESSION_FUNCTION_NAME)
+  if (expressionFunction) return expressionFunction[1]
+
+  if (pipeline.prefix === 'return') return enclosingFunctionName(source, pipeline.start)
+
+  return lead.match(ASSIGNED_NAME)?.[1] ?? null
+}
+
+function enclosingFunctionName(source, position) {
+  const code = maskNonCode(source).slice(0, position)
+  const candidates = [...code.matchAll(FUNCTION_NAME)].reverse()
+
+  const enclosing = candidates.find(match => !bodyClosesWithin(code, match.index))
+  return enclosing?.[1] ?? null
+}
+
+function bodyClosesWithin(code, functionStart) {
+  const bodyStart = code.indexOf('{', functionStart)
+  if (bodyStart === -1) return true
+
+  let depth = 0
+  for (let i = bodyStart; i < code.length; i++) {
+    if (code[i] === '{') depth++
+    else if (code[i] === '}' && --depth === 0) return true
+  }
+  return false
+}
+
+export function renderExplanationText(explanation) {
+  const width = Math.max(...explanation.stages.map(stage => stage.type.length))
+  const effects = explanation.effects.length
+    ? explanation.effects.map(effect =>
+      `  ${effect.name} (${effect.staticallyHandled ? 'handler declared' : 'no handler in file'})`)
+    : ['  none']
+
+  return [
+    `PIPELINE ${explanation.name}`,
+    '',
+    'STAGES',
+    ...explanation.stages.map(stage =>
+      `  ${stage.index} ${stage.type.padEnd(width)} ${stage.detail}${stage.id ? ` @${stage.id}` : ''}`),
+    '',
+    'EFFECTS',
+    ...effects,
+    '',
+    'PROPERTIES',
+    ...Object.entries(explanation.properties).map(([name, value]) => `  ${name}: ${value}`)
+  ].join('\n')
+}

package/src/pipeline-ir.js

@@ -1,6 +1,7 @@
 import { findAllPipelines } from './pipeline-parser.js'
 import { computePipelineId } from './pipeline-hash.js'
-import { findEffectDeclarations, findHandleBlocks } from './effect-parser.js'
+import { findEffectDeclarations, findHandleBlocks } from './effect-parser.js'
+import { transformNamedPipelines } from './named-pipelines.js'
 
 /*
  * Best-effort, purely textual check for whether `effectName` is referenced
@@ -10,7 +11,7 @@ import { findEffectDeclarations, findHandleBlocks } from './effect-parser.js'
  * whether the reference is actually reachable/called, only that the name
  * appears with word boundaries.
  */
-function effectsUsedByStage(stage, effectNames) {
+export function namesReferencedByStage(stage, effectNames) {
   if (!effectNames.length) return []
   const haystack = stage.args.length ? `${stage.name} ${stage.args.join(' ')}` : stage.name
   return effectNames.filter(name => new RegExp(`\\b${name}\\b`).test(haystack))
@@ -44,14 +45,14 @@ export function buildGraph(pipeline, pipelineId = computePipelineId(pipeline), o
   })
 
   pipeline.stages.forEach((stage, index) => {
-    const effects = effectsUsedByStage(stage, effectNames)
+    const effects = namesReferencedByStage(stage, effectNames)
 
     nodes.push({
-      id: `node-${index + 1}`,
+      id: stage.id ?? `node-${index + 1}`,
       type: stage.name,
       label: stage.args.length ? `${stage.name}(${stage.args.join(', ')})` : stage.name,
       args: stage.args,
-      dependencies: [`node-${index}`],
+      dependencies: [nodes[index].id],
       metadata: effects.length ? { effects } : {}
     })
   })
@@ -62,7 +63,7 @@ export function buildGraph(pipeline, pipelineId = computePipelineId(pipeline), o
     type: 'result',
     label: 'RESULT',
     args: [],
-    dependencies: [`node-${pipeline.stages.length}`],
+    dependencies: [nodes[nodes.length - 1].id],
     metadata: {}
   })
 
@@ -92,7 +93,8 @@ export function buildGraph(pipeline, pipelineId = computePipelineId(pipeline), o
  * handler-map keys, so returned graphs can expose which effects each
  * pipeline uses and whether a handler for them is statically visible.
  */
-export function analyzePipelines(source) {
+export function analyzePipelines(jojoSource) {
+  const source = transformNamedPipelines(jojoSource)
   const effectNames = findEffectDeclarations(source).map(declaration => declaration.name)
   const handledEffectNames = findHandleBlocks(source).flatMap(block => block.handlerNames)