semantifold 0.1.0

package/src/backends/php.js

@@ -0,0 +1,184 @@
+// @ts-check
+
+import {emitExpression} from "./shared.js"
+import {emitScalarType} from "./scalars.js"
+
+/**
+ * Emits an independently executable PHP program through the source-aware writer.
+ * @param {import("../semantic/types.js").SemanticModule} module - Semantic module.
+ * @param {import("./writer.js").SourceWriter} writer - Source-aware writer.
+ * @returns {void}
+ */
+export function generatePhp(module, writer) {
+  writer.synthetic("<?php\ndeclare(strict_types=1);\n\n", "PHP program scaffolding", [module])
+
+  module.functions.forEach((declaration, functionIndex) => {
+    if (functionIndex > 0) writer.synthetic("\n\n", "declaration separator", [declaration])
+
+    writer.mapped("function", {mappingKind: "anchor", node: declaration})
+    writer.synthetic(" ", "function spacing", [declaration])
+    writer.mapped(declaration.name, {mappingKind: "exact", node: declaration, role: "name"})
+    writer.mapped("(", {mappingKind: "anchor", node: declaration})
+    declaration.parameters.forEach((parameter, index) => {
+      const parameterPath = `/functions/${functionIndex}/parameters/${index}`
+
+      if (index > 0) writer.synthetic(", ", "parameter separator", [declaration])
+      writer.mapped(emitScalarType("php", parameter.type), {
+        mappingKind: "exact",
+        node: parameter.type,
+        path: `${parameterPath}/type`,
+        role: "type"
+      })
+      writer.synthetic(" ", "parameter spacing", [parameter], [parameterPath])
+      writer.mapped(`$${parameter.name}`, {mappingKind: "exact", node: parameter, path: parameterPath, role: "name"})
+    })
+    writer.mapped(")", {mappingKind: "anchor", node: declaration})
+    writer.synthetic(": ", "return type separator", [declaration])
+    writer.mapped(emitScalarType("php", declaration.returnType), {
+      mappingKind: "exact",
+      node: declaration.returnType,
+      path: `/functions/${functionIndex}/returnType`,
+      role: "type"
+    })
+    writer.synthetic("\n", "line break", [declaration])
+    writer.mapped("{", {mappingKind: "anchor", node: declaration})
+    writer.synthetic("\n", "line break", [declaration])
+
+    emitBlock(writer, declaration.body, "    ", `/functions/${functionIndex}/body`)
+    writer.mapped("}", {mappingKind: "anchor", node: declaration})
+  })
+
+  writer.synthetic("\n\n", "entry-point separator", [module.entryPoint])
+  emitBlock(writer, module.entryPoint.body, "", "/entryPoint/body")
+}
+
+/**
+ * Emits one ordered PHP block body.
+ * @param {import("./writer.js").SourceWriter} writer - Source-aware writer.
+ * @param {import("../semantic/types.js").Block} block - Semantic block.
+ * @param {string} indent - Indentation.
+ * @param {string} path - Exact block path.
+ * @returns {void}
+ */
+function emitBlock(writer, block, indent, path) {
+  block.statements.forEach((statement, index) => emitStatement(writer, statement, indent, `${path}/statements/${index}`))
+}
+
+/**
+ * Emits one PHP statement.
+ * @param {import("./writer.js").SourceWriter} writer - Source-aware writer.
+ * @param {import("../semantic/types.js").Statement} statement - Semantic statement.
+ * @param {string} indent - Indentation.
+ * @param {string} path - Exact statement path.
+ * @returns {void}
+ */
+function emitStatement(writer, statement, indent, path) {
+  if (statement.kind == "LocalDeclaration" || statement.kind == "AssignmentStatement") return emitLocal(writer, statement, indent, path)
+  writer.synthetic(indent, "indentation", [statement], [path])
+  if (statement.kind == "ReturnStatement") {
+    writer.mapped("return", {mappingKind: "anchor", node: statement, path})
+    writer.synthetic(" ", "return spacing", [statement], [path])
+    emitExpression(writer, statement.expression, `${path}/expression`, "php", phpIdentifier)
+    writer.mapped(";", {mappingKind: "anchor", node: statement, path})
+    writer.synthetic("\n", "line break", [statement], [path])
+    return
+  }
+  if (statement.kind == "PrintStatement") {
+    writer.mapped("echo", {mappingKind: "anchor", node: statement, path})
+    writer.synthetic(" ", "print spacing", [statement], [path])
+    emitExpression(writer, statement.expression, `${path}/expression`, "php", phpIdentifier)
+    writer.synthetic(", ", "PHP print separator", [statement], [path])
+    writer.mapped("PHP_EOL", {mappingKind: "anchor", node: statement, path})
+    writer.mapped(";", {mappingKind: "anchor", node: statement, path})
+    writer.synthetic("\n", "line break", [statement], [path])
+    return
+  }
+  writer.mapped("if", {mappingKind: "anchor", node: statement, path})
+  writer.synthetic(" ", "conditional spacing", [statement], [path])
+  writer.mapped("(", {mappingKind: "anchor", node: statement, path})
+  emitExpression(writer, statement.condition, `${path}/condition`, "php", phpIdentifier)
+  writer.mapped(")", {mappingKind: "anchor", node: statement, path})
+  writer.synthetic(" ", "conditional spacing", [statement], [path])
+  writer.mapped("{", {mappingKind: "anchor", node: statement.consequent, path: `${path}/consequent`})
+  writer.synthetic("\n", "line break", [statement], [path])
+  emitBlock(writer, statement.consequent, `${indent}    `, `${path}/consequent`)
+  writer.synthetic(indent, "indentation", [statement], [path])
+  writer.mapped("}", {mappingKind: "anchor", node: statement.consequent, path: `${path}/consequent`})
+  if (statement.alternate) {
+    writer.synthetic(" ", "conditional spacing", [statement], [path])
+    writer.mapped("else", {mappingKind: "anchor", node: statement, path})
+    writer.synthetic(" ", "conditional spacing", [statement], [path])
+    writer.mapped("{", {mappingKind: "anchor", node: statement.alternate, path: `${path}/alternate`})
+    writer.synthetic("\n", "line break", [statement], [path])
+    emitBlock(writer, statement.alternate, `${indent}    `, `${path}/alternate`)
+    writer.synthetic(indent, "indentation", [statement], [path])
+    writer.mapped("}", {mappingKind: "anchor", node: statement.alternate, path: `${path}/alternate`})
+  }
+  writer.synthetic("\n", "line break", [statement], [path])
+}
+
+/**
+ * Emits one PHP local statement with its exact Semantifold profile metadata.
+ * @param {import("./writer.js").SourceWriter} writer - Source-aware writer.
+ * @param {import("../semantic/types.js").LocalStatement} statement - Local statement.
+ * @param {string} indent - Leading indentation.
+ * @param {string} statementPath - Exact JSON Pointer for this statement occurrence.
+ * @returns {void}
+ */
+function emitLocal(writer, statement, indent, statementPath) {
+  writer.synthetic(indent, "indentation", [statement], [statementPath])
+
+  if (statement.kind == "AssignmentStatement") {
+    writer.mapped(`$${statement.target.name}`, {mappingKind: "exact", node: statement.target, path: `${statementPath}/target`, role: "name"})
+    writer.synthetic(" ", "assignment spacing", [statement], [statementPath])
+    writer.mapped("=", {mappingKind: "exact", node: statement, path: statementPath, role: "operator"})
+    writer.synthetic(" ", "assignment spacing", [statement], [statementPath])
+    emitExpression(writer, statement.expression, `${statementPath}/expression`, "php", phpIdentifier)
+    writer.mapped(";", {mappingKind: "anchor", node: statement, path: statementPath})
+    writer.synthetic("\n", "line break", [statement], [statementPath])
+    return
+  }
+
+  if (statement.mutable) {
+    writer.synthetic("/** @var ", "PHP local type scaffolding", [statement], [statementPath])
+    writer.mapped(emitScalarType("php", statement.type), {
+      mappingKind: "exact",
+      node: statement.type,
+      path: `${statementPath}/type`,
+      role: "type"
+    })
+    writer.synthetic(" ", "PHP local type scaffolding", [statement], [statementPath])
+    writer.mapped(`$${statement.name}`, {mappingKind: "exact", node: statement, path: statementPath, role: "name"})
+    writer.synthetic(" */\n", "PHP local type scaffolding", [statement], [statementPath])
+  } else {
+    writer.synthetic("/**\n", "PHP local type scaffolding", [statement], [statementPath])
+    writer.synthetic(`${indent} * @var `, "PHP local type scaffolding", [statement], [statementPath])
+    writer.mapped(emitScalarType("php", statement.type), {
+      mappingKind: "exact",
+      node: statement.type,
+      path: `${statementPath}/type`,
+      role: "type"
+    })
+    writer.synthetic(" ", "PHP local type scaffolding", [statement], [statementPath])
+    writer.mapped(`$${statement.name}`, {mappingKind: "exact", node: statement, path: statementPath, role: "name"})
+    writer.synthetic(`\n${indent} * @semantifold-immutable\n${indent} */\n`, "PHP local type scaffolding", [statement], [statementPath])
+  }
+
+  writer.synthetic(indent, "indentation", [statement], [statementPath])
+  writer.mapped(`$${statement.name}`, {mappingKind: "exact", node: statement, path: statementPath, role: "name"})
+  writer.synthetic(" ", "assignment spacing", [statement], [statementPath])
+  writer.mapped("=", {mappingKind: "exact", node: statement, path: statementPath, role: "operator"})
+  writer.synthetic(" ", "assignment spacing", [statement], [statementPath])
+  emitExpression(writer, statement.initializer, `${statementPath}/initializer`, "php", phpIdentifier)
+  writer.mapped(";", {mappingKind: "anchor", node: statement, path: statementPath})
+  writer.synthetic("\n", "line break", [statement], [statementPath])
+}
+
+/**
+ * Formats one PHP variable identifier.
+ * @param {string} name - Semantic identifier.
+ * @returns {string} PHP identifier.
+ */
+function phpIdentifier(name) {
+  return `$${name}`
+}

package/src/backends/ruby.js

@@ -0,0 +1,163 @@
+// @ts-check
+
+import {emitExpression} from "./shared.js"
+import {emitScalarType} from "./scalars.js"
+
+/**
+ * Emits an independently executable Ruby program through the source-aware writer.
+ * @param {import("../semantic/types.js").SemanticModule} module - Semantic module.
+ * @param {import("./writer.js").SourceWriter} writer - Source-aware writer.
+ * @returns {void}
+ */
+export function generateRuby(module, writer) {
+  module.functions.forEach((declaration, functionIndex) => {
+    if (functionIndex > 0) writer.synthetic("\n\n", "declaration separator", [declaration])
+
+    for (const [parameterIndex, parameter] of declaration.parameters.entries()) {
+      const parameterPath = `/functions/${functionIndex}/parameters/${parameterIndex}`
+
+      writer.synthetic("# @param ", "Ruby type scaffolding", [parameter], [parameterPath])
+      writer.mapped(parameter.name, {mappingKind: "exact", node: parameter, path: parameterPath, role: "name"})
+      writer.synthetic(" [", "Ruby type scaffolding", [parameter], [parameterPath])
+      writer.mapped(emitScalarType("ruby", parameter.type), {
+        mappingKind: "exact",
+        node: parameter.type,
+        path: `${parameterPath}/type`,
+        role: "type"
+      })
+      writer.synthetic("]\n", "Ruby type scaffolding", [parameter], [parameterPath])
+    }
+    writer.synthetic("# @return [", "Ruby type scaffolding", [declaration])
+    writer.mapped(emitScalarType("ruby", declaration.returnType), {
+      mappingKind: "exact",
+      node: declaration.returnType,
+      path: `/functions/${functionIndex}/returnType`,
+      role: "type"
+    })
+    writer.synthetic("]\n", "Ruby type scaffolding", [declaration])
+    writer.mapped("def", {mappingKind: "anchor", node: declaration})
+    writer.synthetic(" ", "function spacing", [declaration])
+    writer.mapped(declaration.name, {mappingKind: "exact", node: declaration, role: "name"})
+    writer.mapped("(", {mappingKind: "anchor", node: declaration})
+    declaration.parameters.forEach((parameter, index) => {
+      if (index > 0) writer.synthetic(", ", "parameter separator", [declaration])
+      writer.mapped(parameter.name, {
+        mappingKind: "exact",
+        node: parameter,
+        path: `/functions/${functionIndex}/parameters/${index}`,
+        role: "name"
+      })
+    })
+    writer.mapped(")", {mappingKind: "anchor", node: declaration})
+    writer.synthetic("\n", "line break", [declaration])
+
+    emitBlock(writer, declaration.body, "  ", `/functions/${functionIndex}/body`)
+    writer.mapped("end", {mappingKind: "anchor", node: declaration})
+  })
+
+  writer.synthetic("\n\n", "entry-point separator", [module.entryPoint])
+  emitBlock(writer, module.entryPoint.body, "", "/entryPoint/body")
+}
+
+/**
+ * Emits one ordered Ruby block body.
+ * @param {import("./writer.js").SourceWriter} writer - Source-aware writer.
+ * @param {import("../semantic/types.js").Block} block - Semantic block.
+ * @param {string} indent - Indentation.
+ * @param {string} path - Exact block path.
+ * @returns {void}
+ */
+function emitBlock(writer, block, indent, path) {
+  block.statements.forEach((statement, index) => emitStatement(writer, statement, indent, `${path}/statements/${index}`))
+}
+
+/**
+ * Emits one Ruby statement.
+ * @param {import("./writer.js").SourceWriter} writer - Source-aware writer.
+ * @param {import("../semantic/types.js").Statement} statement - Semantic statement.
+ * @param {string} indent - Indentation.
+ * @param {string} path - Exact statement path.
+ * @returns {void}
+ */
+function emitStatement(writer, statement, indent, path) {
+  if (statement.kind == "LocalDeclaration" || statement.kind == "AssignmentStatement") return emitLocal(writer, statement, indent, path)
+  writer.synthetic(indent, "indentation", [statement], [path])
+  if (statement.kind == "ReturnStatement") {
+    writer.mapped("return", {mappingKind: "anchor", node: statement, path})
+    writer.synthetic(" ", "return spacing", [statement], [path])
+    emitExpression(writer, statement.expression, `${path}/expression`, "ruby", identity)
+    writer.synthetic("\n", "line break", [statement], [path])
+    return
+  }
+  if (statement.kind == "PrintStatement") {
+    writer.mapped("puts", {mappingKind: "anchor", node: statement, path})
+    writer.synthetic(" ", "print spacing", [statement], [path])
+    emitExpression(writer, statement.expression, `${path}/expression`, "ruby", identity)
+    writer.synthetic("\n", "line break", [statement], [path])
+    return
+  }
+  writer.mapped("if", {mappingKind: "anchor", node: statement, path})
+  writer.synthetic(" ", "conditional spacing", [statement], [path])
+  emitExpression(writer, statement.condition, `${path}/condition`, "ruby", identity)
+  writer.synthetic("\n", "line break", [statement], [path])
+  emitBlock(writer, statement.consequent, `${indent}  `, `${path}/consequent`)
+  if (statement.alternate) {
+    writer.synthetic(indent, "indentation", [statement], [path])
+    writer.mapped("else", {mappingKind: "anchor", node: statement, path})
+    writer.synthetic("\n", "line break", [statement], [path])
+    emitBlock(writer, statement.alternate, `${indent}  `, `${path}/alternate`)
+  }
+  writer.synthetic(indent, "indentation", [statement], [path])
+  writer.mapped("end", {mappingKind: "anchor", node: statement, path})
+  writer.synthetic("\n", "line break", [statement], [path])
+}
+
+/**
+ * Emits one Ruby local statement with exact Semantifold profile metadata.
+ * @param {import("./writer.js").SourceWriter} writer - Source-aware writer.
+ * @param {import("../semantic/types.js").LocalStatement} statement - Local statement.
+ * @param {string} indent - Leading indentation.
+ * @param {string} statementPath - Exact JSON Pointer for this statement occurrence.
+ * @returns {void}
+ */
+function emitLocal(writer, statement, indent, statementPath) {
+  writer.synthetic(indent, "indentation", [statement], [statementPath])
+
+  if (statement.kind == "AssignmentStatement") {
+    writer.mapped(statement.target.name, {mappingKind: "exact", node: statement.target, path: `${statementPath}/target`, role: "name"})
+    writer.synthetic(" ", "assignment spacing", [statement], [statementPath])
+    writer.mapped("=", {mappingKind: "exact", node: statement, path: statementPath, role: "operator"})
+    writer.synthetic(" ", "assignment spacing", [statement], [statementPath])
+    emitExpression(writer, statement.expression, `${statementPath}/expression`, "ruby", identity)
+    writer.synthetic("\n", "line break", [statement], [statementPath])
+    return
+  }
+
+  writer.synthetic("# @type [", "Ruby local type scaffolding", [statement], [statementPath])
+  writer.mapped(emitScalarType("ruby", statement.type), {
+    mappingKind: "exact",
+    node: statement.type,
+    path: `${statementPath}/type`,
+    role: "type"
+  })
+  writer.synthetic("]\n", "Ruby local type scaffolding", [statement], [statementPath])
+  if (!statement.mutable) {
+    writer.synthetic(`${indent}# @semantifold-immutable\n`, "Ruby immutability scaffolding", [statement], [statementPath])
+  }
+  writer.synthetic(indent, "indentation", [statement], [statementPath])
+  writer.mapped(statement.name, {mappingKind: "exact", node: statement, path: statementPath, role: "name"})
+  writer.synthetic(" ", "assignment spacing", [statement], [statementPath])
+  writer.mapped("=", {mappingKind: "exact", node: statement, path: statementPath, role: "operator"})
+  writer.synthetic(" ", "assignment spacing", [statement], [statementPath])
+  emitExpression(writer, statement.initializer, `${statementPath}/initializer`, "ruby", identity)
+  writer.synthetic("\n", "line break", [statement], [statementPath])
+}
+
+/**
+ * Returns an unchanged Ruby identifier.
+ * @param {string} name - Identifier.
+ * @returns {string} Identifier.
+ */
+function identity(name) {
+  return name
+}

package/src/backends/scalars.js

@@ -0,0 +1,120 @@
+// @ts-check
+
+/** @type {Readonly<Record<import("../semantic/types.js").SemanticLanguage, Readonly<Record<import("../semantic/types.js").SemanticTypeName, string>>>>} */
+const targetScalarTypes = Object.freeze({
+  java: Object.freeze({boolean: "boolean", integer: "int", string: "String"}),
+  javascript: Object.freeze({boolean: "boolean", integer: "number", string: "string"}),
+  php: Object.freeze({boolean: "bool", integer: "int", string: "string"}),
+  ruby: Object.freeze({boolean: "bool", integer: "Integer", string: "String"}),
+  typescript: Object.freeze({boolean: "boolean", integer: "number", string: "string"})
+})
+
+/**
+ * Emits one target-language scalar type spelling.
+ * @param {import("../semantic/types.js").SemanticLanguage} language - Target language.
+ * @param {import("../semantic/types.js").TypeReference} type - Semantic scalar type.
+ * @returns {string} Target type spelling.
+ */
+export function emitScalarType(language, type) {
+  return targetScalarTypes[language][type.name]
+}
+
+/**
+ * Emits a safely escaped target-language string literal.
+ * @param {import("../semantic/types.js").SemanticLanguage} language - Target language.
+ * @param {string} value - Valid Unicode scalar string.
+ * @returns {string} Target string literal.
+ */
+export function emitStringLiteral(language, value) {
+  if (language == "php") return emitPhpString(value)
+  if (language == "ruby") return emitRubyString(value)
+  if (language == "java") return emitJavaString(value)
+
+  const literal = JSON.stringify(value)
+
+  if (typeof literal != "string") throw new TypeError("A validated semantic string did not serialize.")
+
+  return literal.replaceAll("\u2028", "\\u2028").replaceAll("\u2029", "\\u2029")
+}
+
+/**
+ * Emits a PHP double-quoted string while preventing interpolation.
+ * @param {string} value - Valid Unicode scalar string.
+ * @returns {string} PHP string literal.
+ */
+function emitPhpString(value) {
+  let emitted = "\""
+
+  for (const character of value) {
+    const codePoint = character.codePointAt(0)
+
+    if (character == "\"") emitted += "\\\""
+    else if (character == "\\") emitted += "\\\\"
+    else if (character == "$") emitted += "\\$"
+    else if (character == "\n") emitted += "\\n"
+    else if (character == "\r") emitted += "\\r"
+    else if (character == "\t") emitted += "\\t"
+    else if (character == "\f") emitted += "\\f"
+    else if (character == "\v") emitted += "\\v"
+    else if (codePoint == 27) emitted += "\\e"
+    else if (codePoint !== undefined && (codePoint < 32 || codePoint == 127)) {
+      emitted += `\\x${codePoint.toString(16).padStart(2, "0")}`
+    } else emitted += character
+  }
+
+  return `${emitted}"`
+}
+
+/**
+ * Emits a Ruby double-quoted string while preventing interpolation.
+ * @param {string} value - Valid Unicode scalar string.
+ * @returns {string} Ruby string literal.
+ */
+function emitRubyString(value) {
+  let emitted = "\""
+
+  for (const character of value) {
+    const codePoint = character.codePointAt(0)
+
+    if (character == "\"") emitted += "\\\""
+    else if (character == "\\") emitted += "\\\\"
+    else if (character == "#") emitted += "\\#"
+    else if (character == "\n") emitted += "\\n"
+    else if (character == "\r") emitted += "\\r"
+    else if (character == "\t") emitted += "\\t"
+    else if (character == "\f") emitted += "\\f"
+    else if (character == "\v") emitted += "\\v"
+    else if (codePoint == 27) emitted += "\\e"
+    else if (codePoint !== undefined && (codePoint < 32 || codePoint == 127)) {
+      emitted += `\\u{${codePoint.toString(16)}}`
+    } else emitted += character
+  }
+
+  return `${emitted}"`
+}
+
+/**
+ * Emits a Java string using standard or fixed-width octal control escapes.
+ * @param {string} value - Valid Unicode scalar string.
+ * @returns {string} Java string literal.
+ */
+function emitJavaString(value) {
+  let emitted = "\""
+
+  for (const character of value) {
+    const codePoint = character.codePointAt(0)
+
+    if (character == "\"") emitted += "\\\""
+    else if (character == "\\") emitted += "\\\\"
+    else if (character == "\b") emitted += "\\b"
+    else if (character == "\t") emitted += "\\t"
+    else if (character == "\n") emitted += "\\n"
+    else if (character == "\f") emitted += "\\f"
+    else if (character == "\r") emitted += "\\r"
+    else if (codePoint !== undefined && (codePoint < 32 || codePoint == 127)) {
+      emitted += `\\${codePoint.toString(8).padStart(3, "0")}`
+    } else emitted += character
+  }
+
+  return `${emitted}"`
+}