semantifold 0.1.0

package/src/backends/writer.js

@@ -0,0 +1,224 @@
+// @ts-check
+
+import {createGenerationIndex} from "../semantic/provenance.js"
+
+/** Source-aware deterministic generated-output builder. */
+export class SourceWriter {
+  /**
+   * Creates a source-aware writer.
+   * @param {object} options - Writer options.
+   * @param {string} options.filename - Output filename.
+   * @param {import("../semantic/types.js").SemanticLanguage} options.language - Output language.
+   * @param {import("../semantic/types.js").SemanticModule} options.module - Semantic module.
+   * @param {{filename: string, content: string, language?: import("../semantic/types.js").SemanticLanguage}[]} [options.sources] - Caller-provided sources.
+   */
+  constructor({filename, language, module, sources}) {
+    const index = createGenerationIndex(module, sources)
+
+    this.filename = filename
+    this.language = language
+    this.index = index
+    /** @type {string[]} */
+    this.parts = []
+    /** @type {import("../semantic/types.js").SemantifoldMappingSpan[]} */
+    this.spans = []
+    this.offset = 0
+    this.line = 1
+    this.column = 1
+  }
+
+  /**
+   * Returns generated content so far.
+   * @returns {string} Generated content.
+   */
+  get code() {
+    return this.parts.join("")
+  }
+
+  /**
+   * Returns the current JSON Pointer for one unambiguous semantic occurrence.
+   * @param {import("../semantic/types.js").SemanticNode} node - Semantic node occurrence.
+   * @returns {string} Current occurrence path.
+   */
+  occurrencePath(node) {
+    return this.index.recordFor(node).path
+  }
+
+  /**
+   * Reports whether an exact parser-owned role range is available.
+   * @param {import("../semantic/types.js").SemanticNode} node - Semantic node occurrence.
+   * @param {string} path - JSON Pointer for a shared node occurrence.
+   * @param {string} role - Semantic token role.
+   * @returns {boolean} Whether the role has an exact source range.
+   */
+  hasRange(node, path, role) {
+    return this.index.recordFor(node, path).ranges[role] !== undefined
+  }
+
+  /**
+   * Writes text mapped to a semantic node.
+   * @param {string} text - Generated text.
+   * @param {object} annotation - Mapping annotation.
+   * @param {import("../semantic/types.js").SemanticNode} annotation.node - Semantic node.
+   * @param {"exact" | "anchor"} annotation.mappingKind - Mapping precision.
+   * @param {string} [annotation.role] - Semantic token role.
+   * @param {string} [annotation.name] - Source Map name.
+   * @param {string} [annotation.path] - JSON Pointer for a shared node occurrence.
+   * @returns {void}
+   */
+  mapped(text, {mappingKind, name, node, path, role}) {
+    if (text.length == 0) return
+
+    const record = this.index.recordFor(node, path)
+    const roleLocation = role ? record.ranges[role] : undefined
+    const origin = roleLocation ? this.#sourceOrigin(roleLocation, record.origin) : record.origin
+    const precision = mappingKind == "exact" && role && !roleLocation ? "anchor" : mappingKind
+    const symbol = record.symbolId
+      ? this.index.provenance.symbols.find((candidate) => candidate.id == record.symbolId)
+      : undefined
+
+    this.#append(text, {
+      mappingKind: precision,
+      name: name ?? symbol?.name,
+      nodeId: record.id,
+      origin,
+      role,
+      symbolId: record.symbolId
+    })
+  }
+
+  /**
+   * Writes source-free scaffolding with optional semantic context.
+   * @param {string} text - Generated text.
+   * @param {string} reason - Stable reason.
+   * @param {import("../semantic/types.js").SemanticNode[]} [relatedNodes] - Related nodes.
+   * @param {(string | undefined)[]} [relatedPaths] - Occurrence paths for shared related nodes.
+   * @returns {void}
+   */
+  synthetic(text, reason, relatedNodes = [], relatedPaths = []) {
+    if (text.length == 0) return
+
+    /** @type {Set<string>} */
+    const seen = new Set()
+    const relatedOrigins = relatedNodes.flatMap((node, index) => {
+      const record = this.index.recordFor(node, relatedPaths[index])
+
+      return relatedOriginsFor(record.origin).flatMap((related) => {
+        const contextual = {
+          ...related,
+          nodeId: related.nodeId ?? record.id,
+          role: related.role ?? "context"
+        }
+        const key = relatedOriginKey(contextual)
+
+        if (seen.has(key)) return []
+        seen.add(key)
+
+        return [contextual]
+      })
+    })
+
+    this.#append(text, {mappingKind: "synthetic", origin: {kind: "synthetic", reason, relatedOrigins}})
+  }
+
+  /**
+   * Returns the authoritative rich map for the current content.
+   * @returns {import("../semantic/types.js").SemantifoldMapping} Mapping.
+   */
+  finish() {
+    return {
+      coordinateSystem: "utf16",
+      generated: {content: this.code, filename: this.filename, language: this.language},
+      nodes: [...this.index.provenance.nodes],
+      schema: "SemantifoldMapping",
+      sources: [...this.index.provenance.sources],
+      spans: [...this.spans],
+      symbols: [...this.index.provenance.symbols],
+      version: 1
+    }
+  }
+
+  /**
+   * Appends one mapped span.
+   * @param {string} text - Generated text.
+   * @param {Omit<import("../semantic/types.js").SemantifoldMappingSpan, "generated">} annotation - Span annotation.
+   * @returns {void}
+   */
+  #append(text, annotation) {
+    if (text.includes("\r")) throw new TypeError("Generated output must use deterministic LF line endings.")
+
+    const start = {column: this.column, line: this.line, offset: this.offset}
+
+    this.parts.push(text)
+    for (let index = 0; index < text.length; index++) {
+      this.offset++
+      if (text[index] == "\n") {
+        this.line++
+        this.column = 1
+      } else this.column++
+    }
+    const compact = /** @type {Omit<import("../semantic/types.js").SemantifoldMappingSpan, "generated">} */ (
+      Object.fromEntries(Object.entries(annotation).filter(([, value]) => value !== undefined))
+    )
+
+    this.spans.push({
+      ...compact,
+      generated: {
+        end: {column: this.column, line: this.line, offset: this.offset},
+        filename: this.filename,
+        start
+      }
+    })
+  }
+
+  /**
+   * Creates a direct role origin using canonical source identities.
+   * @param {import("../semantic/types.js").SourceLocation} location - Exact role range.
+   * @param {import("../semantic/types.js").SemanticOrigin} fallback - Owning origin.
+   * @returns {import("../semantic/types.js").SemanticOrigin} Role origin.
+   */
+  #sourceOrigin(location, fallback) {
+    /** @type {string | undefined} */
+    let fallbackSourceId
+
+    if (fallback.kind == "source" && fallback.location.filename == location.filename) fallbackSourceId = fallback.sourceId
+    else if (fallback.kind == "derived") {
+      fallbackSourceId = fallback.origins.find((origin) => origin.location.filename == location.filename)?.sourceId
+    } else if (fallback.kind == "synthetic") {
+      fallbackSourceId = fallback.relatedOrigins.find((origin) => origin.location.filename == location.filename)?.sourceId
+    }
+    const source = this.index.provenance.sources.find((candidate) => candidate.id == fallbackSourceId) ??
+      this.index.provenance.sources.find((candidate) => candidate.filename == location.filename)
+
+    return source ? {kind: "source", location, sourceId: source.id} : fallback
+  }
+}
+
+/**
+ * Expands every closed provenance range in semantic order.
+ * @param {import("../semantic/types.js").SemanticOrigin} origin - Closed provenance.
+ * @returns {import("../semantic/types.js").RelatedOrigin[]} Related ranges.
+ */
+function relatedOriginsFor(origin) {
+  if (origin.kind == "source") return [{location: origin.location, sourceId: origin.sourceId}]
+  if (origin.kind == "derived") return origin.origins
+
+  return origin.relatedOrigins
+}
+
+/**
+ * Builds a deterministic identity for one contextual related origin.
+ * @param {import("../semantic/types.js").RelatedOrigin} origin - Related origin.
+ * @returns {string} Stable identity.
+ */
+function relatedOriginKey(origin) {
+  return JSON.stringify([
+    origin.sourceId,
+    origin.location.filename,
+    origin.location.start.offset,
+    origin.location.end.offset,
+    origin.nodeId ?? null,
+    origin.symbolId ?? null,
+    origin.role ?? null
+  ])
+}

package/src/diagnostic.js

@@ -0,0 +1,103 @@
+// @ts-check
+
+/** A clear parser, semantic, or backend capability diagnostic. */
+export class SemantifoldDiagnostic extends Error {
+  /**
+   * Creates a diagnostic.
+   * @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 {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.
+   */
+  constructor({cause, code, generatedLocation, language, location, message}) {
+    const locationText = location ? ` at ${location.filename}:${location.start.line}:${location.start.column}` : ""
+
+    super(`[${code}] ${language}${locationText}: ${message}`, cause ? {cause} : undefined)
+    this.name = "SemantifoldDiagnostic"
+    this.code = code
+    this.detail = message
+    this.generatedLocation = generatedLocation
+    this.language = language
+    this.location = location
+  }
+}
+
+/**
+ * Throws a normalized parser diagnostic while preserving the parser error.
+ * @param {import("./semantic/types.js").SemanticLanguage} language - Frontend language.
+ * @param {unknown} error - Opaque parser error, narrowed immediately.
+ * @returns {never} Always throws.
+ */
+export function parseFailure(language, error) {
+  const cause = error instanceof Error ? error : new Error(String(error))
+
+  throw new SemantifoldDiagnostic({
+    cause,
+    code: "PARSE_ERROR",
+    language,
+    message: cause.message
+  })
+}
+
+/**
+ * Throws an unsupported-syntax diagnostic.
+ * @param {import("./semantic/types.js").SemanticLanguage} language - Frontend language.
+ * @param {string} syntax - Parser syntax kind.
+ * @param {import("./semantic/types.js").SourceLocation | undefined} location - Source location.
+ * @returns {never} Always throws.
+ */
+export function unsupportedSyntax(language, syntax, location) {
+  throw new SemantifoldDiagnostic({
+    code: "UNSUPPORTED_SYNTAX",
+    language,
+    location,
+    message: `Syntax '${syntax}' is outside the implemented semantic subset.`
+  })
+}
+
+/**
+ * Throws a missing-type diagnostic.
+ * @param {import("./semantic/types.js").SemanticLanguage} language - Frontend language.
+ * @param {string} subject - Untyped subject.
+ * @param {import("./semantic/types.js").SourceLocation | undefined} location - Source location.
+ * @returns {never} Always throws.
+ */
+export function missingType(language, subject, location) {
+  throw new SemantifoldDiagnostic({
+    code: "MISSING_TYPE",
+    language,
+    location,
+    message: `${subject} requires an explicit supported scalar type: integer, boolean, or string.`
+  })
+}
+
+/**
+ * Throws a language-neutral semantic diagnostic discovered after adaptation.
+ * @param {import("./semantic/types.js").SemanticLanguage} language - Source language.
+ * @param {string} code - Stable semantic diagnostic code.
+ * @param {string} detail - Human-readable semantic failure.
+ * @param {import("./semantic/types.js").SourceLocation | undefined} location - Source location.
+ * @returns {never} Always throws.
+ */
+export function semanticFailure(language, code, detail, location) {
+  throw new SemantifoldDiagnostic({code, language, location, message: detail})
+}
+
+/**
+ * Throws an unsupported backend-capability diagnostic.
+ * @param {import("./semantic/types.js").SemanticLanguage} language - Backend language.
+ * @param {string} capability - Unsupported semantic capability.
+ * @param {import("./semantic/types.js").SourceLocation | undefined} location - Semantic source location.
+ * @returns {never} Always throws.
+ */
+export function unsupportedCapability(language, capability, location) {
+  throw new SemantifoldDiagnostic({
+    code: "UNSUPPORTED_CAPABILITY",
+    language,
+    location,
+    message: `Backend cannot emit semantic capability '${capability}'.`
+  })
+}

package/src/frontends/index.js

@@ -0,0 +1,36 @@
+// @ts-check
+
+import {SemantifoldDiagnostic} from "../diagnostic.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.
+ * @param {object} input - Parse request.
+ * @param {string} input.filename - Source filename used in diagnostics.
+ * @param {import("../semantic/types.js").SemanticLanguage} input.language - Source language.
+ * @param {string} input.source - Source text.
+ * @returns {import("../semantic/types.js").SemanticModule} Semantic module.
+ */
+export function parseSource({filename, language, source}) {
+  let module
+
+  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."
+  })
+}