semantifold 0.1.0 → 0.2.0

package/src/backends/python.js

@@ -0,0 +1,175 @@
+// @ts-check
+
+import {emitExpression} from "./shared.js"
+import {emitScalarType} from "./scalars.js"
+
+/**
+ * Emits one deterministic standalone Python program.
+ * @param {import("../semantic/types.js").SemanticModule} module - Semantic module.
+ * @param {import("./writer.js").SourceWriter} writer - Source-aware writer.
+ * @returns {void}
+ */
+export function generatePython(module, writer) {
+  module.functions.forEach((declaration, functionIndex) => {
+    if (functionIndex > 0) writer.synthetic("\n\n", "declaration separator", [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, parameterIndex) => {
+      const parameterPath = `/functions/${functionIndex}/parameters/${parameterIndex}`
+
+      if (parameterIndex > 0) writer.synthetic(", ", "parameter separator", [declaration])
+      writer.mapped(parameter.name, {mappingKind: "exact", node: parameter, path: parameterPath, role: "name"})
+      writer.synthetic(": ", "Python annotation separator", [parameter], [parameterPath])
+      writer.mapped(emitScalarType("python", parameter.type), {
+        mappingKind: "exact",
+        node: parameter.type,
+        path: `${parameterPath}/type`,
+        role: "type"
+      })
+    })
+    writer.mapped(")", {mappingKind: "anchor", node: declaration})
+    writer.synthetic(" -> ", "Python return annotation separator", [declaration])
+    writer.mapped(emitScalarType("python", declaration.returnType), {
+      mappingKind: "exact",
+      node: declaration.returnType,
+      path: `/functions/${functionIndex}/returnType`,
+      role: "type"
+    })
+    writer.mapped(":", {mappingKind: "anchor", node: declaration})
+    writer.synthetic("\n", "line break", [declaration])
+    emitBlock(writer, declaration.body, "    ", `/functions/${functionIndex}/body`)
+  })
+
+  writer.synthetic("\n\n", "entry-point separator", [module.entryPoint])
+  emitBlock(writer, module.entryPoint.body, "", "/entryPoint/body")
+}
+
+/**
+ * Emits one Python indentation block, using pass only for an empty semantic block.
+ * @param {import("./writer.js").SourceWriter} writer - Source-aware writer.
+ * @param {import("../semantic/types.js").Block} block - Semantic block.
+ * @param {string} indent - Leading indentation.
+ * @param {string} path - Exact block path.
+ * @returns {void}
+ */
+function emitBlock(writer, block, indent, path) {
+  if (block.statements.length == 0) {
+    writer.synthetic(`${indent}pass\n`, "Python empty block", [block], [path])
+    return
+  }
+
+  block.statements.forEach((statement, index) => emitStatement(writer, statement, indent, `${path}/statements/${index}`))
+}
+
+/**
+ * Emits one supported Python statement.
+ * @param {import("./writer.js").SourceWriter} writer - Source-aware writer.
+ * @param {import("../semantic/types.js").Statement} statement - Semantic statement.
+ * @param {string} indent - Leading indentation.
+ * @param {string} path - Exact statement path.
+ * @returns {void}
+ */
+function emitStatement(writer, statement, indent, path) {
+  if (statement.kind == "LocalDeclaration" || statement.kind == "AssignmentStatement") {
+    emitLocal(writer, statement, indent, path)
+    return
+  }
+  if (statement.kind == "IfStatement") {
+    emitIf(writer, statement, indent, path, "if")
+    return
+  }
+
+  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`, "python", identity)
+    writer.synthetic("\n", "line break", [statement], [path])
+    return
+  }
+
+  writer.mapped("print", {mappingKind: "anchor", node: statement, path})
+  writer.mapped("(", {mappingKind: "anchor", node: statement, path})
+  emitExpression(writer, statement.expression, `${path}/expression`, "python", identity)
+  writer.mapped(")", {mappingKind: "anchor", node: statement, path})
+  writer.synthetic("\n", "line break", [statement], [path])
+}
+
+/**
+ * Emits a Python if or elif and its optional alternative.
+ * @param {import("./writer.js").SourceWriter} writer - Source-aware writer.
+ * @param {import("../semantic/types.js").IfStatement} statement - Branch.
+ * @param {string} indent - Leading indentation.
+ * @param {string} path - Exact branch path.
+ * @param {"if" | "elif"} keyword - Branch keyword.
+ * @returns {void}
+ */
+function emitIf(writer, statement, indent, path, keyword) {
+  writer.synthetic(indent, "indentation", [statement], [path])
+  writer.mapped(keyword, {mappingKind: "anchor", node: statement, path})
+  writer.synthetic(" ", "conditional spacing", [statement], [path])
+  emitExpression(writer, statement.condition, `${path}/condition`, "python", identity)
+  writer.mapped(":", {mappingKind: "anchor", node: statement.consequent, path: `${path}/consequent`})
+  writer.synthetic("\n", "line break", [statement], [path])
+  emitBlock(writer, statement.consequent, `${indent}    `, `${path}/consequent`)
+
+  if (!statement.alternate) return
+  if (statement.alternate.statements.length == 1 && statement.alternate.statements[0].kind == "IfStatement") {
+    emitIf(writer, statement.alternate.statements[0], indent, `${path}/alternate/statements/0`, "elif")
+    return
+  }
+
+  writer.synthetic(indent, "indentation", [statement], [path])
+  writer.mapped("else", {mappingKind: "anchor", node: 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`)
+}
+
+/**
+ * Emits one annotated local declaration or plain assignment.
+ * @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} path - Exact statement path.
+ * @returns {void}
+ */
+function emitLocal(writer, statement, indent, path) {
+  if (statement.kind == "LocalDeclaration" && !statement.mutable) {
+    writer.synthetic(`${indent}# @semantifold-immutable\n`, "Python immutable local carrier", [statement], [path])
+  }
+  writer.synthetic(indent, "indentation", [statement], [path])
+
+  if (statement.kind == "AssignmentStatement") {
+    writer.mapped(statement.target.name, {mappingKind: "exact", node: statement.target, path: `${path}/target`, role: "name"})
+    writer.synthetic(" ", "assignment spacing", [statement], [path])
+    writer.mapped("=", {mappingKind: "exact", node: statement, path, role: "operator"})
+    writer.synthetic(" ", "assignment spacing", [statement], [path])
+    emitExpression(writer, statement.expression, `${path}/expression`, "python", identity)
+    writer.synthetic("\n", "line break", [statement], [path])
+    return
+  }
+
+  writer.mapped(statement.name, {mappingKind: "exact", node: statement, path, role: "name"})
+  writer.synthetic(": ", "Python annotation separator", [statement], [path])
+  writer.mapped(emitScalarType("python", statement.type), {
+    mappingKind: "exact", node: statement.type, path: `${path}/type`, role: "type"
+  })
+  writer.synthetic(" ", "assignment spacing", [statement], [path])
+  writer.mapped("=", {mappingKind: "exact", node: statement, path, role: "operator"})
+  writer.synthetic(" ", "assignment spacing", [statement], [path])
+  emitExpression(writer, statement.initializer, `${path}/initializer`, "python", identity)
+  writer.synthetic("\n", "line break", [statement], [path])
+}
+
+/**
+ * Returns one unchanged Python identifier.
+ * @param {string} name - Semantic identifier.
+ * @returns {string} Unchanged Python identifier.
+ */
+function identity(name) {
+  return name
+}

package/src/backends/scalars.js

@@ -5,6 +5,7 @@ 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"}),
+  python: Object.freeze({boolean: "bool", integer: "int", string: "str"}),
   ruby: Object.freeze({boolean: "bool", integer: "Integer", string: "String"}),
   typescript: Object.freeze({boolean: "boolean", integer: "number", string: "string"})
 })

package/src/backends/shared.js

@@ -7,12 +7,12 @@ import {emitStringLiteral} from "./scalars.js"
 
 /** @type {Readonly<Record<import("../semantic/types.js").SemanticUnaryOperation, string>>} */
 const unaryOperationSyntax = Object.freeze({BooleanNot: "!", IntegerNegate: "-"})
-/** @type {Readonly<Record<import("../semantic/types.js").SemanticBinaryOperation, Readonly<{default: string, php?: string, strict?: string}>>>} */
+/** @type {Readonly<Record<import("../semantic/types.js").SemanticBinaryOperation, Readonly<{default: string, php?: string, python?: string, strict?: string}>>>} */
 const binaryOperationSyntax = Object.freeze({
-  BooleanAnd: Object.freeze({default: "&&"}),
+  BooleanAnd: Object.freeze({default: "&&", python: "and"}),
   BooleanEqual: Object.freeze({default: "==", strict: "==="}),
   BooleanNotEqual: Object.freeze({default: "!=", strict: "!=="}),
-  BooleanOr: Object.freeze({default: "||"}),
+  BooleanOr: Object.freeze({default: "||", python: "or"}),
   IntegerAdd: Object.freeze({default: "+"}),
   IntegerEqual: Object.freeze({default: "==", strict: "==="}),
   IntegerGreaterThan: Object.freeze({default: ">"}),
@@ -325,7 +325,9 @@ export function emitExpression(writer, expression, path, language, emitIdentifie
     return
   }
   if (expression.kind == "BooleanLiteral") {
-    writer.mapped(expression.value ? "true" : "false", {mappingKind: "exact", node: expression, path, role: "literal"})
+    const spelling = language == "python" ? expression.value ? "True" : "False" : expression.value ? "true" : "false"
+
+    writer.mapped(spelling, {mappingKind: "exact", node: expression, path, role: "literal"})
     return
   }
   if (expression.kind == "StringLiteral") {
@@ -345,7 +347,7 @@ export function emitExpression(writer, expression, path, language, emitIdentifie
 
   if (expression.kind == "UnaryExpression") {
     writer.mapped("(", {mappingKind: "anchor", node: expression, path})
-    writer.mapped(unaryOperationSyntax[expression.operation], {
+    writer.mapped(language == "python" && expression.operation == "BooleanNot" ? "not " : unaryOperationSyntax[expression.operation], {
       mappingKind: "exact", node: expression, path, role: "operator"
     })
     emitExpression(writer, expression.operand, `${path}/operand`, language, emitIdentifier)
@@ -450,6 +452,7 @@ function binaryOperationSpelling(operation, language) {
   const syntax = binaryOperationSyntax[operation]
 
   if (language == "php" && syntax.php) return syntax.php
+  if (language == "python" && syntax.python) return syntax.python
   if ((language == "php" || language == "javascript" || language == "typescript") && syntax.strict) return syntax.strict
 
   return syntax.default

package/src/binary-mapping.js

@@ -0,0 +1,305 @@
+// @ts-check
+
+import {isDenseArray} from "./array.js"
+import {isSafeArtifactPath} from "./artifact-path.js"
+import {SemantifoldDiagnostic} from "./diagnostic.js"
+import {isSourceRangeOrdered} from "./semantic/location.js"
+
+/**
+ * Creates and validates an immutable byte-coordinate provenance map.
+ * @param {object} input - Mapping fields.
+ * @param {number} input.byteLength - Generated artifact byte length.
+ * @param {string} input.path - Generated artifact path.
+ * @param {import("./semantic/types.js").GeneratedByteRange[]} input.ranges - Ordered byte ranges.
+ * @returns {import("./semantic/types.js").SemantifoldByteMapping} Validated mapping.
+ */
+export function createByteMapping(input) {
+  if (!isPlainObject(input)) invalidByteMapping("Byte mapping construction requires an object.")
+  const {byteLength, path, ranges} = input
+
+  return finalizeByteMapping({
+    coordinateSystem: "bytes",
+    generated: {byteLength, path},
+    ranges,
+    schema: "SemantifoldByteMapping",
+    version: 1
+  })
+}
+
+/**
+ * Parses serialized byte-coordinate provenance.
+ * @param {string} serialized - JSON mapping.
+ * @returns {import("./semantic/types.js").SemantifoldByteMapping} Validated mapping.
+ */
+export function parseByteMapping(serialized) {
+  try {
+    return finalizeByteMapping(JSON.parse(serialized))
+  } catch (error) {
+    if (error instanceof SemantifoldDiagnostic && error.code == "INVALID_BYTE_MAPPING") throw error
+
+    return invalidByteMapping("Byte mapping must be valid JSON.", error)
+  }
+}
+
+/**
+ * Serializes a validated mapping with stable object-key ordering.
+ * @param {import("./semantic/types.js").SemantifoldByteMapping} mapping - Byte mapping.
+ * @returns {string} Canonical JSON with trailing LF.
+ */
+export function stringifyByteMapping(mapping) {
+  const validated = finalizeByteMapping(mapping)
+
+  return `${JSON.stringify(sortJson(validated), null, 2)}\n`
+}
+
+/**
+ * Validates an existing mapping and returns a detached immutable value.
+ * @param {unknown} candidate - Mapping candidate.
+ * @returns {import("./semantic/types.js").SemantifoldByteMapping} Validated mapping.
+ */
+export function finalizeByteMapping(candidate) {
+  try {
+    if (!isPlainObject(candidate)) invalidByteMapping("Byte mapping must be a plain object.")
+    if (candidate.schema != "SemantifoldByteMapping" || candidate.version !== 1 || candidate.coordinateSystem != "bytes") {
+      invalidByteMapping("Byte mapping requires SemantifoldByteMapping version 1 with byte coordinates.")
+    }
+    if (!isPlainObject(candidate.generated)) {
+      invalidByteMapping("Byte mapping requires a safe generated artifact path.")
+    }
+    const generatedPath = candidate.generated.path
+
+    if (!isSafeArtifactPath(generatedPath)) {
+      invalidByteMapping("Byte mapping requires a safe generated artifact path.")
+    }
+    const byteLength = candidate.generated.byteLength
+
+    if (typeof byteLength != "number" || !Number.isSafeInteger(byteLength) || byteLength < 0) {
+      invalidByteMapping("Byte mapping requires a non-negative safe byte length.")
+    }
+    if (!isDenseArray(candidate.ranges)) invalidByteMapping("Byte mapping ranges must be an ordered dense array.")
+    let previousEnd = 0
+    /** @type {import("./semantic/types.js").GeneratedByteRange[]} */
+    const ranges = []
+
+    for (let index = 0; index < candidate.ranges.length; index += 1) {
+      const range = candidate.ranges[index]
+
+      if (!isPlainObject(range) || !isPlainObject(range.generated)) invalidByteMapping(`Byte range ${index} is malformed.`)
+      const end = range.generated.end
+      const start = range.generated.start
+
+      if (typeof start != "number" || typeof end != "number" || !Number.isSafeInteger(start) || !Number.isSafeInteger(end) ||
+        start < 0 || end <= start || end > byteLength) {
+        invalidByteMapping(`Byte range ${index} must be a non-empty in-bounds half-open integer range.`)
+      }
+      if (start < previousEnd) invalidByteMapping(`Byte range ${index} is out of order or overlaps its predecessor.`)
+      previousEnd = end
+      const origin = validateOrigin(range.origin, `Byte range ${index}`)
+      const result = {
+        generated: {end, start},
+        origin,
+        ...(optionalIdentity(range.nodeId, "nodeId", index)),
+        ...(optionalIdentity(range.symbolId, "symbolId", index)),
+        ...(optionalIdentity(range.role, "role", index))
+      }
+
+      ranges.push(result)
+    }
+    const mapping = {
+      coordinateSystem: /** @type {const} */ ("bytes"),
+      generated: {byteLength, path: generatedPath},
+      ranges,
+      schema: /** @type {const} */ ("SemantifoldByteMapping"),
+      version: /** @type {const} */ (1)
+    }
+
+    return deepFreeze(mapping)
+  } catch (error) {
+    if (error instanceof SemantifoldDiagnostic && error.code == "INVALID_BYTE_MAPPING") throw error
+
+    return invalidByteMapping("Byte mapping validation failed.", error)
+  }
+}
+
+/**
+ * Validates one closed provenance origin.
+ * @param {unknown} value - Origin candidate.
+ * @param {string} label - Diagnostic range label.
+ * @returns {import("./semantic/types.js").SemanticOrigin} Detached origin.
+ */
+function validateOrigin(value, label) {
+  if (!isPlainObject(value)) invalidByteMapping(`${label} requires provenance.`)
+
+  if (value.kind == "synthetic") {
+    if (typeof value.reason != "string" || value.reason.length == 0 || !isDenseArray(value.relatedOrigins)) {
+      invalidByteMapping(`${label} synthetic provenance requires an explicit reason and related-origin array.`)
+    }
+    /** @type {import("./semantic/types.js").RelatedOrigin[]} */
+    const relatedOrigins = []
+
+    for (let index = 0; index < value.relatedOrigins.length; index += 1) {
+      relatedOrigins.push(validateRelatedOrigin(value.relatedOrigins[index], `${label} related origin ${index}`))
+    }
+
+    return {kind: "synthetic", reason: value.reason, relatedOrigins}
+  }
+  if (value.kind == "source") {
+    if (typeof value.sourceId != "string" || value.sourceId.length == 0) invalidByteMapping(`${label} source provenance requires a source ID.`)
+
+    return {kind: "source", location: validateLocation(value.location, label), sourceId: value.sourceId}
+  }
+  if (value.kind == "derived") {
+    if (!isDenseArray(value.origins) || value.origins.length == 0) invalidByteMapping(`${label} derived provenance requires origins.`)
+    /** @type {import("./semantic/types.js").RelatedOrigin[]} */
+    const origins = []
+
+    for (let index = 0; index < value.origins.length; index += 1) {
+      origins.push(validateRelatedOrigin(value.origins[index], `${label} origin ${index}`))
+    }
+
+    return {kind: "derived", origins}
+  }
+
+  return invalidByteMapping(`${label} has an unknown provenance kind.`)
+}
+
+/**
+ * Validates one related source origin.
+ * @param {unknown} value - Related-origin candidate.
+ * @param {string} label - Diagnostic range label.
+ * @returns {import("./semantic/types.js").RelatedOrigin} Detached related origin.
+ */
+function validateRelatedOrigin(value, label) {
+  if (!isPlainObject(value) || typeof value.sourceId != "string" || value.sourceId.length == 0) {
+    invalidByteMapping(`${label} requires a source ID and location.`)
+  }
+  const result = {
+    location: validateLocation(value.location, label),
+    sourceId: value.sourceId,
+    ...optionalRelated(value.nodeId, "nodeId", label),
+    ...optionalRelated(value.symbolId, "symbolId", label),
+    ...optionalRelated(value.role, "role", label)
+  }
+
+  return result
+}
+
+/**
+ * Validates a UTF-16 original source location carried by byte provenance.
+ * @param {unknown} value - Location candidate.
+ * @param {string} label - Diagnostic range label.
+ * @returns {import("./semantic/types.js").SourceLocation} Detached source location.
+ */
+function validateLocation(value, label) {
+  if (!isPlainObject(value) || typeof value.filename != "string" || value.filename.length == 0) {
+    invalidByteMapping(`${label} contains an invalid source location.`)
+  }
+  const start = snapshotPoint(value.start)
+  const end = snapshotPoint(value.end)
+
+  if (start == undefined || end == undefined || end.offset < start.offset || !isSourceRangeOrdered(start, end)) {
+    invalidByteMapping(`${label} contains an invalid source location.`)
+  }
+
+  return {
+    end,
+    filename: value.filename,
+    start
+  }
+}
+
+/**
+ * Snapshots one valid UTF-16 source point without retaining undeclared fields.
+ * @param {unknown} value - Candidate point.
+ * @returns {import("./semantic/types.js").SourcePoint | undefined} Canonical point when valid.
+ */
+function snapshotPoint(value) {
+  if (!isPlainObject(value)) return undefined
+  const line = value.line
+  const column = value.column
+  const offset = value.offset
+
+  if (typeof line != "number" || !Number.isSafeInteger(line) || line <= 0 ||
+    typeof column != "number" || !Number.isSafeInteger(column) || column <= 0 ||
+    typeof offset != "number" || !Number.isSafeInteger(offset) || offset < 0) return undefined
+
+  return {column, line, offset}
+}
+
+/**
+ * Validates an optional byte-range identity.
+ * @param {unknown} value - Candidate identity.
+ * @param {string} property - Property name.
+ * @param {number} index - Byte-range index.
+ * @returns {Record<string, string>} Present identity or an empty record.
+ */
+function optionalIdentity(value, property, index) {
+  if (value === undefined) return {}
+  if (typeof value != "string" || value.length == 0) invalidByteMapping(`Byte range ${index} has an invalid ${property}.`)
+
+  return {[property]: value}
+}
+
+/**
+ * Validates an optional related-origin identity.
+ * @param {unknown} value - Candidate identity.
+ * @param {string} property - Property name.
+ * @param {string} label - Diagnostic range label.
+ * @returns {Record<string, string>} Present identity or an empty record.
+ */
+function optionalRelated(value, property, label) {
+  if (value === undefined) return {}
+  if (typeof value != "string" || value.length == 0) invalidByteMapping(`${label} has an invalid ${property}.`)
+
+  return {[property]: value}
+}
+
+/**
+ * Throws a normalized byte-mapping diagnostic.
+ * @param {string} message - Failure detail.
+ * @param {unknown} [error] - Preserved validation cause.
+ * @returns {never} Always throws.
+ */
+function invalidByteMapping(message, error) {
+  throw new SemantifoldDiagnostic({
+    cause: error instanceof Error ? error : undefined,
+    code: "INVALID_BYTE_MAPPING",
+    language: "binary",
+    message
+  })
+}
+
+/**
+ * Checks for an ordinary string-keyed object.
+ * @param {unknown} value - Candidate value.
+ * @returns {value is Record<string, unknown>} Whether the value is a plain object.
+ */
+function isPlainObject(value) {
+  return typeof value == "object" && value != null && !Array.isArray(value) && Object.getPrototypeOf(value) == Object.prototype
+}
+
+/**
+ * Deeply freezes detached JSON mapping values.
+ * @template T
+ * @param {T} value - Detached value.
+ * @returns {T} Frozen value.
+ */
+function deepFreeze(value) {
+  if (!value || typeof value != "object" || Object.isFrozen(value)) return value
+
+  for (const nested of Object.values(value)) deepFreeze(nested)
+
+  return Object.freeze(value)
+}
+
+/**
+ * Recursively sorts JSON object keys without reordering arrays.
+ * @param {unknown} value - JSON value.
+ * @returns {unknown} Key-sorted JSON value.
+ */
+function sortJson(value) {
+  if (Array.isArray(value)) return value.map(sortJson)
+  if (!isPlainObject(value)) return value
+
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, sortJson(value[key])]))
+}

package/src/diagnostic.js

@@ -7,12 +7,20 @@ export class SemantifoldDiagnostic extends Error {
    * @param {object} options - Diagnostic fields.
    * @param {string} options.code - Stable diagnostic code.
    * @param {string} options.message - Human-readable message.
-   * @param {import("./semantic/types.js").SemanticLanguage} options.language - Related language.
+   * @param {string} options.language - Related language, target, tool, or registry identity.
    * @param {import("./semantic/types.js").SourceLocation | undefined} [options.location] - Related location.
    * @param {import("./semantic/types.js").SourceLocation | undefined} [options.generatedLocation] - Pre-remapping generated location.
    * @param {Error | undefined} [options.cause] - Preserved parser error.
+   * @param {string | undefined} [options.command] - Canonical command when tool discovery is involved.
+   * @param {string | undefined} [options.executable] - Exact resolved executable when known.
+   * @param {number | undefined} [options.exitCode] - Process exit code when available.
+   * @param {string | undefined} [options.signal] - Process termination signal when available.
+   * @param {string | undefined} [options.stage] - Acceptance stage when execution is involved.
+   * @param {string | undefined} [options.stderr] - Captured standard error when available.
+   * @param {string | undefined} [options.stdout] - Captured standard output when available.
+   * @param {string | undefined} [options.version] - Captured executable version when known.
    */
-  constructor({cause, code, generatedLocation, language, location, message}) {
+  constructor({cause, code, command, executable, exitCode, generatedLocation, language, location, message, signal, stage, stderr, stdout, version}) {
     const locationText = location ? ` at ${location.filename}:${location.start.line}:${location.start.column}` : ""
 
     super(`[${code}] ${language}${locationText}: ${message}`, cause ? {cause} : undefined)
@@ -22,6 +30,14 @@ export class SemantifoldDiagnostic extends Error {
     this.generatedLocation = generatedLocation
     this.language = language
     this.location = location
+    if (command != undefined) this.command = command
+    if (executable != undefined) this.executable = executable
+    if (exitCode != undefined) this.exitCode = exitCode
+    if (signal != undefined) this.signal = signal
+    if (stage != undefined) this.stage = stage
+    if (stderr != undefined) this.stderr = stderr
+    if (stdout != undefined) this.stdout = stdout
+    if (version != undefined) this.version = version
   }
 }
 
@@ -101,3 +117,19 @@ export function unsupportedCapability(language, capability, location) {
     message: `Backend cannot emit semantic capability '${capability}'.`
   })
 }
+
+/**
+ * Throws when a registered identity lacks one requested role.
+ * @param {string} language - Registered language or target identity.
+ * @param {string} role - Requested registry role.
+ * @param {import("./semantic/types.js").SourceLocation | undefined} [location] - Related semantic location.
+ * @returns {never} Always throws.
+ */
+export function unsupportedRole(language, role, location) {
+  throw new SemantifoldDiagnostic({
+    code: "UNSUPPORTED_ROLE",
+    language,
+    location,
+    message: `Registered language or target does not provide role '${role}'.`
+  })
+}

package/src/frontends/index.js

@@ -1,12 +1,8 @@
 // @ts-check
 
-import {SemantifoldDiagnostic} from "../diagnostic.js"
+import {languageRegistry} from "../language-registry.js"
 import {annotateParsedModule} from "../semantic/provenance.js"
 import {validateParsedModule} from "../semantic/validate.js"
-import {parseJava} from "./java.js"
-import {parseJavaScriptTypeScript} from "./javascript-typescript.js"
-import {parsePhp} from "./php.js"
-import {parseRuby} from "./ruby.js"
 
 /**
  * Parses supported source into a shared semantic module.
@@ -17,20 +13,9 @@ import {parseRuby} from "./ruby.js"
  * @returns {import("../semantic/types.js").SemanticModule} Semantic module.
  */
 export function parseSource({filename, language, source}) {
-  let module
+  const frontend = /** @type {(input: {filename: string, source: string}) => import("../semantic/types.js").SemanticModule} */ (
+    languageRegistry.resolve(language, "frontend"))
+  const module = validateParsedModule(frontend({filename, source}), language)
 
-  if (language == "php") module = validateParsedModule(parsePhp({filename, source}), language)
-  else if (language == "ruby") module = validateParsedModule(parseRuby({filename, source}), language)
-  if (language == "javascript" || language == "typescript") {
-    module = validateParsedModule(parseJavaScriptTypeScript({filename, language, source}), language)
-  }
-  else if (language == "java") module = validateParsedModule(parseJava({filename, source}), language)
-
-  if (module) return annotateParsedModule(module, {filename, language, source})
-
-  throw new SemantifoldDiagnostic({
-    code: "UNSUPPORTED_LANGUAGE",
-    language,
-    message: "No frontend adapter is registered for this language."
-  })
+  return annotateParsedModule(module, {filename, language, source})
 }