@panagos/jojoscript 0.10.1 → 1.0.0

package/src/compiler.js

@@ -20,6 +20,10 @@ import {
 
 import { transformMatchExpressions } from './match-parser.js'
 import { transformTypeAnnotations } from './type-annotations.js'
+import { transformPurityModifiers } from './purity.js'
+import { transformNamedPipelines } from './named-pipelines.js'
+import { transformContracts, findContracts } from './contracts.js'
+import { transformTypeDeclarations, findTypeDeclarations } from './type-declarations.js'
 import {
   transformEffectDeclarations,
   transformHandleBlocks,
@@ -47,8 +51,16 @@ export function compile(source, options = {}) {
    * Optional type annotations, stripped and re-expressed as JSDoc before
    * anything else touches `fn` declarations.
    */
+  result = transformNamedPipelines(result)
+  result = transformPurityModifiers(result)
+
+  const usesContracts = findContracts(result).length > 0
+  result = transformContracts(result)
   result = transformTypeAnnotations(result)
 
+  const usesTypeDeclarations = findTypeDeclarations(result).length > 0
+  result = transformTypeDeclarations(result)
+
   /*
    * Jojo functions.
    */
@@ -98,6 +110,12 @@ export function compile(source, options = {}) {
   if (usesHandleBlocks && !pipelineStdlibFunctions.includes('withHandlers')) {
     pipelineStdlibFunctions.push('withHandlers')
   }
+  if (usesContracts && !pipelineStdlibFunctions.includes('ContractError')) {
+    pipelineStdlibFunctions.push('ContractError')
+  }
+  if (usesTypeDeclarations && !pipelineStdlibFunctions.includes('defineType')) {
+    pipelineStdlibFunctions.push('defineType')
+  }
 
   /*
    * `jojo profile` compiles with `{ profile: true }`, which wraps every
@@ -127,17 +145,13 @@ export function compile(source, options = {}) {
    * pipeline stage), the auto-imported names are merged into it instead
    * of creating a second, colliding import declaration.
    */
-  if (pipelineStdlibFunctions.length) {
+  if (pipelineStdlibFunctions.length || options.runtimeImport) {
     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`
@@ -145,6 +159,7 @@ function mergeRuntimeImport(source, stdlibFunctions, runtimeImport) {
   const existing = source.match(pattern)
 
   if (!existing) {
+    if (!stdlibFunctions.length) return source
     return `import { ${stdlibFunctions.join(', ')} } from "${runtimeImport}"\n` + source
   }
 
@@ -185,43 +200,27 @@ export function compileDirectory(inputDir, outDir = null, options = {}) {
     ? 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)
+  return findJojoFiles(root).map(full => {
+    const rel = path.relative(root, full).slice(0, -'.jojo'.length) + '.js'
+    const out = path.join(target, rel)
 
-      if (entry.isDirectory()) {
-        walk(full)
-        continue
-      }
+    fs.mkdirSync(path.dirname(out), { recursive: true })
+    fs.writeFileSync(out, compile(fs.readFileSync(full, 'utf8'), options), 'utf8')
 
-      if (!entry.name.endsWith('.jojo')) continue
-
-      const rel =
-        path.relative(root, full).slice(0, -'.jojo'.length) + '.js'
+    return { input: full, output: out }
+  })
+}
 
-      const out = path.join(target, rel)
+export function findJojoFiles(root) {
+  const files = []
 
-      fs.mkdirSync(path.dirname(out), { recursive: true })
-      fs.writeFileSync(
-        out,
-        compile(fs.readFileSync(full, 'utf8'), options),
-        'utf8'
-      )
+  for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+    if (entry.name === 'node_modules' || entry.name === 'dist' || entry.name.startsWith('.')) continue
 
-      result.push({ input: full, output: out })
-    }
+    const full = path.join(root, entry.name)
+    if (entry.isDirectory()) files.push(...findJojoFiles(full))
+    else if (entry.name.endsWith('.jojo')) files.push(full)
   }
 
-  walk(root)
-  return result
+  return files
 }

package/src/contracts.js

@@ -0,0 +1,124 @@
+import { maskNonCode } from './lexer.js'
+
+const FUNCTION_HEAD = /^[ \t]*(?:export[ \t]+)?(?:(?:pure|effectful)[ \t]+)?(async[ \t]+)?(?:(?:pure|effectful)[ \t]+)?fn[ \t]+([A-Za-z_$][\w$]*)[ \t]*\(/gm
+const CLAUSE = /^([ \t]*)(requires|ensures)[ \t]+(.+?)[ \t]*$/
+
+function lineAt(source, offset) {
+  return source.slice(0, offset).split('\n').length
+}
+
+function matchingClose(code, openIndex, open, close) {
+  let depth = 0
+  for (let i = openIndex; i < code.length; i++) {
+    if (code[i] === open) depth++
+    else if (code[i] === close && --depth === 0) return i
+  }
+  return -1
+}
+
+function parameterNames(params) {
+  return params.split(',')
+    .map(param => param.trim().match(/^(?:\.\.\.)?([A-Za-z_$][\w$]*)/)?.[1])
+    .filter(Boolean)
+}
+
+/*
+ * Contract clauses sit on their own lines between a block function's
+ * parameter list and its opening `{`:
+ *
+ *   fn divide(a, b)
+ *     requires b != 0
+ *     ensures result * b == a
+ *   {
+ */
+export function findContracts(source) {
+  const code = maskNonCode(source)
+  const regex = new RegExp(FUNCTION_HEAD.source, FUNCTION_HEAD.flags)
+  const contracts = []
+  let match
+
+  while ((match = regex.exec(code))) {
+    const paramsOpen = match.index + match[0].length - 1
+    const paramsClose = matchingClose(code, paramsOpen, '(', ')')
+    if (paramsClose === -1) continue
+
+    const headEnd = code.indexOf('\n', paramsClose)
+    if (headEnd === -1 || /[{=]/.test(code.slice(paramsClose + 1, headEnd))) continue
+
+    const clauses = []
+    let position = headEnd + 1
+    let bodyOpen = -1
+
+    while (position < code.length) {
+      const lineEnd = code.indexOf('\n', position) === -1 ? code.length : code.indexOf('\n', position)
+      const line = source.slice(position, lineEnd)
+      const clause = code.slice(position, lineEnd).match(CLAUSE)
+
+      if (clause) {
+        clauses.push({
+          kind: clause[2],
+          condition: line.slice(clause[1].length + clause[2].length).trim(),
+          line: lineAt(source, position),
+          start: position,
+          end: lineEnd
+        })
+      } else if (line.trim().startsWith('{')) {
+        bodyOpen = position + line.indexOf('{')
+        break
+      } else {
+        break
+      }
+      position = lineEnd + 1
+    }
+
+    if (!clauses.length || bodyOpen === -1) continue
+
+    const toEntry = ({ condition, line }) => ({ condition, line })
+    contracts.push({
+      name: match[2],
+      async: Boolean(match[1]),
+      params: parameterNames(source.slice(paramsOpen + 1, paramsClose)),
+      line: lineAt(source, match.index + match[0].search(/\S/)),
+      requires: clauses.filter(clause => clause.kind === 'requires').map(toEntry),
+      ensures: clauses.filter(clause => clause.kind === 'ensures').map(toEntry),
+      clauses,
+      bodyOpen,
+      bodyClose: matchingClose(code, bodyOpen, '{', '}')
+    })
+  }
+
+  return contracts
+}
+
+function check(contract, { kind, condition }) {
+  const error = `new ContractError(${JSON.stringify(contract.name)}, "${kind}", ${JSON.stringify(condition)})`
+  return `if (!(${condition})) throw ${error};`
+}
+
+/*
+ * The body runs inside an arrow function so `ensures` can inspect `result`
+ * while `this` and `arguments` still refer to the declared function.
+ */
+export function transformContracts(source) {
+  let result = source
+
+  for (const contract of findContracts(source).reverse()) {
+    const requires = contract.clauses.filter(clause => clause.kind === 'requires').map(clause => check(contract, clause))
+    const ensures = contract.clauses.filter(clause => clause.kind === 'ensures').map(clause => check(contract, clause))
+
+    let open = `{ ${requires.join(' ')}`
+    let close = '}'
+    if (ensures.length) {
+      open += contract.async ? ' const result = await (async () => {' : ' const result = (() => {'
+      close = `})(); ${ensures.join(' ')} return result }`
+    }
+
+    result = result.slice(0, contract.bodyClose) + close + result.slice(contract.bodyClose + 1)
+    result = result.slice(0, contract.bodyOpen) + open.trimEnd() + result.slice(contract.bodyOpen + 1)
+    for (const clause of [...contract.clauses].reverse()) {
+      result = result.slice(0, clause.start) + result.slice(clause.end)
+    }
+  }
+
+  return result
+}

package/src/describe.js

@@ -0,0 +1,63 @@
+import { explainPipelines } from './pipeline-explain.js'
+import { planPipelines } from './pipeline-plan.js'
+import { findEffectDeclarations, findHandleBlocks } from './effect-parser.js'
+import { findPurityDeclarations } from './purity.js'
+import { findContracts } from './contracts.js'
+import { findTypeDeclarations } from './type-declarations.js'
+
+const DESCRIPTION_VERSION = '1'
+
+/*
+ * One self-describing JSON document for a source file, assembled from the
+ * same analyses as `explain`, `plan`, and `check` so they never disagree.
+ */
+export function describeSource(source) {
+  const plans = planPipelines(source).pipelines
+
+  return {
+    language: 'jojo',
+    version: DESCRIPTION_VERSION,
+    pipelines: explainPipelines(source).map((explanation, index) => describePipeline(explanation, plans[index])),
+    effects: describeEffects(source),
+    functions: describeFunctions(source),
+    types: findTypeDeclarations(source).map(({ name, variants }) => ({ name, variants }))
+  }
+}
+
+function describePipeline(explanation, plan) {
+  const [source, ...stages] = explanation.stages
+  const effects = stages.flatMap(stage => [...stage.effects, ...stage.effectfulFunctions])
+
+  return {
+    name: explanation.name,
+    inputs: /^[A-Za-z_$][\w$]*$/.test(source.detail) ? [source.detail] : [],
+    effects: [...new Set(effects)],
+    stages: stages.map((stage, index) => {
+      const { type, id, ...fields } = plan.stages[index + 1]
+      return { id: stage.id ?? `node-${stage.index - 1}`, operation: type, ...fields }
+    }),
+    properties: explanation.properties
+  }
+}
+
+function describeEffects(source) {
+  const handled = new Set(findHandleBlocks(source).flatMap(block => block.handlerNames))
+  return findEffectDeclarations(source).map(({ name, params }) => ({ name, params, handled: handled.has(name) }))
+}
+
+function describeFunctions(source) {
+  const functions = new Map()
+  const entry = (name, line) => {
+    if (!functions.has(name)) functions.set(name, { name, line, purity: null, requires: [], ensures: [] })
+    return functions.get(name)
+  }
+
+  for (const { name, line, purity } of findPurityDeclarations(source)) entry(name, line).purity = purity
+  for (const { name, line, requires, ensures } of findContracts(source)) {
+    const described = entry(name, line)
+    described.requires = requires.map(clause => clause.condition)
+    described.ensures = ensures.map(clause => clause.condition)
+  }
+
+  return [...functions.values()].sort((a, b) => a.line - b.line)
+}

package/src/effect-parser.js

@@ -211,11 +211,13 @@ export function transformHandleBlocks(source) {
 
     const handlerText = text(result, tokens.slice(target.handlerOpen, target.handlerClose + 1))
     const bodyText = text(result, tokens.slice(target.bodyOpen, target.bodyClose + 1))
-    const replacement = `(await withHandlers(${handlerText}, async () => ${bodyText}))`
-
     const start = tokens[target.keywordIndex].start
     const end = tokens[target.bodyClose].end
 
+    // A statement starting with `(` would otherwise be parsed as a call on the previous line.
+    const startsStatement = /(^|\n)[ \t]*$/.test(result.slice(0, start))
+    const replacement = `${startsStatement ? ';' : ''}(await withHandlers(${handlerText}, async () => ${bodyText}))`
+
     result = result.slice(0, start) + replacement + result.slice(end)
   }
 

package/src/formatter.js

@@ -0,0 +1,105 @@
+/*
+ * A line-based reindenter, matching the compiler's no-AST design: it only
+ * normalizes indentation and whitespace and never rewrites expressions.
+ * The VS Code extension ships an identical copy (editors/vscode/src/formatter.mjs).
+ *
+ * Every open bracket remembers the indent level of the line that opened it,
+ * so a line opening several brackets (`reduce((a, b) => {`) indents its
+ * contents once. Block comments and template literal text are left
+ * untouched. Like the compiler, it is not regex-literal aware.
+ */
+const PIPELINE_BLOCK = /^(?:export\s+)?pipeline\s+[A-Za-z_$][\w$]*\s*\{$/
+
+function continuationLevels(trimmed, insidePipelineBlock) {
+  if (trimmed.startsWith('|>')) return insidePipelineBlock ? 0 : 1
+  if (/^(requires|ensures)\b/.test(trimmed)) return 1
+  if (/^\|(?![|>])/.test(trimmed)) return 1
+  if (/^[?:](?![?:.])/.test(trimmed)) return 1
+  if (/^\.(?!\.)/.test(trimmed)) return 1
+  return 0
+}
+
+export function formatSource(text, options = {}) {
+  const indentUnit = options.indent ?? '  '
+  const stack = []
+  const output = []
+  let inBlockComment = false
+  let hangingDepth = null
+
+  const openBrackets = () => stack.filter(entry => entry.ch !== 'TPL')
+
+  function scanLine(line, level) {
+    let i = 0
+    while (i < line.length) {
+      if (inBlockComment) {
+        const end = line.indexOf('*/', i)
+        if (end === -1) return
+        inBlockComment = false
+        i = end + 2
+        continue
+      }
+
+      const ch = line[i]
+      if (stack.at(-1)?.ch === 'TPL') {
+        if (ch === '\\') i += 2
+        else if (ch === '`') { stack.pop(); i++ }
+        else if (ch === '$' && line[i + 1] === '{') { stack.push({ ch: '{', level }); i += 2 }
+        else i++
+        continue
+      }
+
+      const two = line.slice(i, i + 2)
+      if (two === '//') return
+      if (two === '/*') { inBlockComment = true; i += 2; continue }
+      if (ch === '`') { stack.push({ ch: 'TPL' }); i++; continue }
+
+      if (ch === '"' || ch === "'") {
+        i++
+        while (i < line.length && line[i] !== ch) i += line[i] === '\\' ? 2 : 1
+        i++
+        continue
+      }
+
+      if ('{[('.includes(ch)) stack.push({ ch, level, pipeline: ch === '{' && PIPELINE_BLOCK.test(line.trim()) })
+      else if ('}])'.includes(ch) && stack.length && stack.at(-1).ch !== 'TPL') stack.pop()
+      i++
+    }
+  }
+
+  for (const rawLine of text.split(/\r\n|\r|\n/)) {
+    const trimmed = rawLine.trim()
+
+    if (trimmed === '') {
+      output.push('')
+      hangingDepth = null
+      continue
+    }
+
+    if (inBlockComment || stack.at(-1)?.ch === 'TPL') {
+      output.push(rawLine)
+      scanLine(rawLine, 0)
+      continue
+    }
+
+    const open = openBrackets()
+    const innermost = open.at(-1)
+    const startsWithCloser = /^[}\])]/.test(trimmed)
+
+    let level = innermost ? innermost.level + (startsWithCloser ? 0 : 1) : 0
+    if (!startsWithCloser) level += continuationLevels(trimmed, innermost?.pipeline)
+    if (hangingDepth === open.length && !startsWithCloser) level += 1
+
+    output.push(indentUnit.repeat(level) + trimmed)
+
+    if (startsWithCloser || /\{$/.test(trimmed)) hangingDepth = null
+    if (/(:=|=>)$/.test(trimmed)) hangingDepth = open.length
+
+    scanLine(rawLine, level)
+  }
+
+  const collapsed = output.filter((line, index) => line !== '' || output[index - 1] !== '')
+  while (collapsed[0] === '') collapsed.shift()
+  while (collapsed.at(-1) === '') collapsed.pop()
+
+  return collapsed.join('\n') + '\n'
+}

package/src/index.js

@@ -25,9 +25,40 @@ export {
   renderGraphDot
 } from './pipeline-ir.js'
 
+export {
+  explainPipelines,
+  renderExplanationText
+} from './pipeline-explain.js'
+
+export {
+  planPipelines,
+  planToJojo
+} from './pipeline-plan.js'
+
 export {
   transformEffectDeclarations,
   transformHandleBlocks,
   findEffectDeclarations,
   findHandleBlocks
 } from './effect-parser.js'
+
+export {
+  checkSource,
+  checkPlan
+} from './check.js'
+
+export { describeSource } from './describe.js'
+
+export {
+  simulatePipelines,
+  renderSimulationText
+} from './simulate.js'
+
+export {
+  whyPipelines,
+  renderWhyText
+} from './why.js'
+
+export { formatSource } from './formatter.js'
+
+export { parseSource } from './parse.js'