semantifold 0.1.1 → 0.3.0

package/src/semantic/types.js

@@ -1,11 +1,45 @@
 // @ts-check
 
-/** @typedef {"php" | "ruby" | "javascript" | "typescript" | "java"} SemanticLanguage */
+/** @typedef {"php" | "ruby" | "javascript" | "typescript" | "java" | "python" | "csharp" | "go" | "c" | "cpp"} SemanticLanguage */
 /** @typedef {"integer" | "boolean" | "string"} SemanticTypeName */
 /** @typedef {"IntegerNegate" | "BooleanNot"} SemanticUnaryOperation */
 /** @typedef {"IntegerAdd" | "IntegerSubtract" | "IntegerMultiply" | "BooleanAnd" | "BooleanOr" | "IntegerEqual" | "IntegerNotEqual" | "BooleanEqual" | "BooleanNotEqual" | "StringEqual" | "StringNotEqual" | "IntegerLessThan" | "IntegerLessThanOrEqual" | "IntegerGreaterThan" | "IntegerGreaterThanOrEqual" | "StringConcat"} SemanticBinaryOperation */
 /** @typedef {"function" | "parameter" | "local"} SemanticSymbolKind */
 /** @typedef {"declaration" | "read" | "write" | "call"} SemanticSymbolRole */
+/** @typedef {"parse" | "generate" | "restore" | "compile" | "link" | "validate" | "instantiate" | "execute"} AcceptanceStage */
+/** @typedef {"entry" | "source" | "manifest" | "support" | "mapping" | "resource" | "loader"} GeneratedArtifactRole */
+
+/**
+ * @typedef LanguageRoleCapabilities
+ * @property {boolean} frontend - Parser adapter availability.
+ * @property {boolean} textBackend - Single- or multi-file text backend availability.
+ * @property {boolean} binaryBackend - Binary backend availability.
+ * @property {boolean} applicationBackend - Application-artifact backend availability.
+ * @property {boolean} interoperability - Interoperability bridge availability.
+ */
+
+/**
+ * @typedef LanguageMappingCapabilities
+ * @property {boolean} richText - Authoritative rich text mappings.
+ * @property {boolean} sourceMapV3 - Source Map v3 projection.
+ * @property {boolean} binaryRanges - Byte-coordinate binary/resource mappings.
+ */
+
+/**
+ * @typedef LanguageAcceptanceCapabilities
+ * @property {readonly AcceptanceStage[]} stages - Applicable ordered acceptance stages.
+ * @property {readonly string[]} toolchains - Required canonical toolchain IDs.
+ */
+
+/**
+ * @typedef LanguageCapabilities
+ * @property {string} id - Stable registry identity.
+ * @property {Readonly<LanguageRoleCapabilities>} roles - Independently registered roles.
+ * @property {"single" | "multiple"} artifactMultiplicity - Target artifact multiplicity.
+ * @property {boolean} roundTrip - Whether frontend/backend round-trip acceptance is declared.
+ * @property {Readonly<LanguageMappingCapabilities>} mapping - Mapping forms.
+ * @property {Readonly<LanguageAcceptanceCapabilities>} acceptance - Stages and toolchains.
+ */
 
 /**
  * @typedef SourcePoint
@@ -60,6 +94,24 @@
 
 /** @typedef {SourceOrigin | DerivedOrigin | SyntheticOrigin} SemanticOrigin */
 
+/**
+ * @typedef GeneratedByteRange
+ * @property {{start: number, end: number}} generated - Half-open generated byte offsets.
+ * @property {SemanticOrigin} origin - Semantic or explicit synthetic provenance.
+ * @property {string} [nodeId] - Originating semantic node identity.
+ * @property {string} [symbolId] - Originating semantic symbol identity.
+ * @property {string} [role] - Semantic or binary-region role.
+ */
+
+/**
+ * @typedef SemantifoldByteMapping
+ * @property {"SemantifoldByteMapping"} schema - Schema discriminator.
+ * @property {1} version - Schema version.
+ * @property {"bytes"} coordinateSystem - Generated offsets are bytes, never text columns.
+ * @property {{path: string, byteLength: number}} generated - Generated artifact identity.
+ * @property {readonly GeneratedByteRange[]} ranges - Ordered non-overlapping ranges.
+ */
+
 /**
  * @typedef SemanticNodeSourceProvenance
  * @property {"SemantifoldNodeProvenance"} schema - Association discriminator.
@@ -147,6 +199,77 @@
  * @property {string} sourceMapFilename - Default external Source Map filename.
  */
 
+/**
+ * @typedef TextArtifactProvenance
+ * @property {"text"} kind - Rich text provenance discriminator.
+ * @property {SemantifoldMapping} mapping - Authoritative range mapping.
+ * @property {import("@jridgewell/gen-mapping").EncodedSourceMap} sourceMap - Interoperable projection.
+ * @property {string} [sourceMapFilename] - Logical Source Map sidecar path.
+ */
+
+/**
+ * @typedef ByteArtifactProvenance
+ * @property {"bytes"} kind - Byte provenance discriminator.
+ * @property {SemantifoldByteMapping} mapping - Authoritative byte ranges.
+ */
+
+/**
+ * @typedef ArtifactSyntheticProvenance
+ * @property {"synthetic"} kind - Synthetic artifact discriminator.
+ * @property {string} reason - Explicit target-scaffolding reason.
+ * @property {readonly RelatedOrigin[]} relatedOrigins - Related semantic source ranges.
+ */
+
+/** @typedef {TextArtifactProvenance | ByteArtifactProvenance | ArtifactSyntheticProvenance} ArtifactProvenance */
+
+/**
+ * @typedef GeneratedSetArtifact
+ * @property {string} path - Unique safe relative POSIX path.
+ * @property {"text" | "binary"} contentKind - Content representation.
+ * @property {string | Uint8Array} content - Text or a detached copy of the exact generated bytes on every binary read.
+ * @property {string} mediaType - Artifact media type.
+ * @property {GeneratedArtifactRole} role - Artifact role; exactly one set artifact is entry.
+ * @property {"generated"} ownership - Task-015 ownership contract.
+ * @property {ArtifactProvenance} provenance - Text, byte-range, or synthetic provenance.
+ */
+
+/**
+ * @typedef GeneratedArtifactSet
+ * @property {"GeneratedArtifactSet"} schema - Schema discriminator.
+ * @property {1} version - Schema version.
+ * @property {string} target - Stable language or target ID.
+ * @property {string} entry - Path of the sole declared entry artifact.
+ * @property {readonly GeneratedSetArtifact[]} artifacts - Deterministic artifact order.
+ */
+
+/**
+ * @typedef DiscoveredToolchain
+ * @property {string} id - Toolchain ID.
+ * @property {string} command - Documented canonical command.
+ * @property {string} executable - Exact absolute executable path.
+ * @property {"override" | "canonical"} source - Resolution route.
+ * @property {string} version - First captured version line.
+ * @property {string} versionOutput - Complete captured version output.
+ * @property {readonly string[]} versionArguments - Exact version argument array.
+ */
+
+/**
+ * @typedef AcceptanceStageResult
+ * @property {AcceptanceStage} stage - Completed stage.
+ * @property {string} executable - Exact executable used.
+ * @property {readonly string[]} arguments - Exact argument array used.
+ * @property {string} version - Discovered tool version.
+ * @property {string} stdout - Captured standard output.
+ * @property {string} stderr - Captured standard error.
+ */
+
+/**
+ * @typedef AcceptanceResult
+ * @property {string} target - Target identity.
+ * @property {string} directory - Removed isolated project directory identity.
+ * @property {readonly AcceptanceStageResult[]} stages - Ordered completed stages.
+ */
+
 /**
  * @typedef TypeReference
  * @property {"TypeReference"} kind - Node discriminator.

package/src/subprocess.js

@@ -0,0 +1,232 @@
+// @ts-check
+
+import {spawn} from "node:child_process"
+import {StringDecoder} from "node:string_decoder"
+
+const forcedTerminationGraceMs = 250
+const retainedPipeGraceMs = 250
+const deadlineFailures = new WeakSet()
+
+/**
+ * Executes one exact file while owning its complete bounded lifecycle.
+ * @param {object} input - Process request.
+ * @param {readonly string[]} input.arguments - Exact argument array.
+ * @param {string} [input.cwd] - Working directory.
+ * @param {Readonly<Record<string, string>>} input.environment - Exact environment.
+ * @param {string} input.executable - Exact executable path.
+ * @param {number} input.maxBuffer - Maximum bytes captured per output stream.
+ * @param {number} input.timeoutMs - Deadline before termination begins.
+ * @returns {Promise<{stderr: string, stdout: string}>} Output after the owned process group closes.
+ */
+export function executeFileWithDeadline(input) {
+  return executeFileWithDeadlineUsing(input, registerChildSpawn)
+}
+
+/**
+ * Creates an executor whose spawn observation belongs only to that executor instance.
+ * @param {object} dependencies - Internal lifecycle dependencies.
+ * @param {(child: import("node:child_process").ChildProcess, listener: () => void) => void} dependencies.registerSpawnListener - Registers deadline initialization.
+ * @returns {typeof executeFileWithDeadline} Owned subprocess executor.
+ */
+export function createExecuteFileWithDeadline({registerSpawnListener}) {
+  return (input) => executeFileWithDeadlineUsing(input, registerSpawnListener)
+}
+
+/**
+ * Executes with exact instance-owned spawn observation.
+ * @param {Parameters<typeof executeFileWithDeadline>[0]} input - Process request.
+ * @param {(child: import("node:child_process").ChildProcess, listener: () => void) => void} registerSpawnListener - Registers deadline initialization.
+ * @returns {Promise<{stderr: string, stdout: string}>} Output after the owned process group closes.
+ */
+function executeFileWithDeadlineUsing({arguments: processArguments, cwd, environment, executable, maxBuffer, timeoutMs}, registerSpawnListener) {
+  if (process.platform == "win32") {
+    return Promise.reject(Object.assign(new Error("Owned process-tree termination is unavailable on this platform."), {
+      code: "ENOTSUP",
+      stderr: "",
+      stdout: ""
+    }))
+  }
+
+  return new Promise((resolve, reject) => {
+    /** @type {ReturnType<typeof setTimeout> | undefined} */
+    let deadlineTimer
+    /** @type {ReturnType<typeof setTimeout> | undefined} */
+    let forceTimer
+    /** @type {ReturnType<typeof setTimeout> | undefined} */
+    let pipeTimer
+    /** @type {Error | undefined} */
+    let launchError
+    let deadlineExceeded = false
+    let outputExceeded = false
+    let settled = false
+    const stderr = outputCapture(maxBuffer, () => terminateForOutputLimit())
+    const stdout = outputCapture(maxBuffer, () => terminateForOutputLimit())
+    const child = spawn(executable, [...processArguments], {
+      cwd,
+      detached: true,
+      env: environment,
+      stdio: ["ignore", "pipe", "pipe"]
+    })
+    const processGroupId = child.pid
+
+    child.stderr.on("data", stderr.receive)
+    child.stdout.on("data", stdout.receive)
+    child.once("error", (error) => {
+      launchError = error
+    })
+    registerSpawnListener(child, () => {
+      if (processGroupId == undefined || !verifyOwnedProcessGroup(processGroupId)) {
+        launchError = Object.assign(new Error("Spawned subprocess did not establish its required process group."), {code: "ENOTSUP"})
+        child.kill("SIGKILL")
+        return
+      }
+
+      deadlineTimer = setTimeout(() => {
+        if (settled) return
+        deadlineExceeded = true
+        beginTermination(processGroupId)
+      }, timeoutMs)
+    })
+    child.once("close", (code, signal) => {
+      settled = true
+      if (deadlineTimer != undefined) clearTimeout(deadlineTimer)
+      if (forceTimer != undefined) clearTimeout(forceTimer)
+      if (pipeTimer != undefined) clearTimeout(pipeTimer)
+      const capturedStderr = stderr.finish()
+      const capturedStdout = stdout.finish()
+
+      if (launchError) {
+        reject(Object.assign(launchError, {stderr: capturedStderr, stdout: capturedStdout}))
+      } else if (outputExceeded) {
+        reject(Object.assign(new Error(`Subprocess exceeded its ${maxBuffer}-byte output capture limit.`), {
+          code: "ERR_CHILD_PROCESS_STDIO_MAXBUFFER",
+          signal,
+          stderr: capturedStderr,
+          stdout: capturedStdout
+        }))
+      } else if (deadlineExceeded) {
+        const timeoutError = Object.assign(new Error("Subprocess exceeded its owned deadline."), {
+          code,
+          signal,
+          stderr: capturedStderr,
+          stdout: capturedStdout
+        })
+
+        deadlineFailures.add(timeoutError)
+        reject(timeoutError)
+      } else if (code != 0 || signal != null) {
+        reject(Object.assign(new Error("Subprocess failed after launch."), {
+          code,
+          signal,
+          stderr: capturedStderr,
+          stdout: capturedStdout
+        }))
+      } else resolve({stderr: capturedStderr, stdout: capturedStdout})
+    })
+
+    /** Begins bounded termination after output capture crosses its limit. */
+    function terminateForOutputLimit() {
+      if (outputExceeded || settled) return
+      outputExceeded = true
+      if (processGroupId != undefined) beginTermination(processGroupId)
+    }
+
+    /**
+     * Signals the owned group now and escalates if its inherited pipes remain open.
+     * @param {number} ownedGroupId - Spawn-verified process-group identity.
+     */
+    function beginTermination(ownedGroupId) {
+      signalOwnedProcessGroup(ownedGroupId, "SIGTERM")
+      if (!settled && forceTimer == undefined) {
+        forceTimer = setTimeout(() => {
+          if (settled) return
+          signalOwnedProcessGroup(ownedGroupId, "SIGKILL")
+          pipeTimer = setTimeout(() => {
+            if (settled) return
+            child.stdout.destroy()
+            child.stderr.destroy()
+          }, retainedPipeGraceMs)
+        }, forcedTerminationGraceMs)
+      }
+    }
+  })
+}
+
+/**
+ * Registers production deadline initialization on the child's real spawn event.
+ * @param {import("node:child_process").ChildProcess} child - Exact spawned child.
+ * @param {() => void} listener - Deadline initialization.
+ */
+function registerChildSpawn(child, listener) {
+  child.once("spawn", listener)
+}
+
+/**
+ * Creates one byte-bounded UTF-8 stream capture.
+ * @param {number} maximumBytes - Maximum captured bytes.
+ * @param {() => void} onExceeded - First-overflow callback.
+ * @returns {{finish: () => string, receive: (chunk: Buffer) => void}} Capture callbacks.
+ */
+function outputCapture(maximumBytes, onExceeded) {
+  const decoder = new StringDecoder("utf8")
+  let byteLength = 0
+  let content = ""
+  let exceeded = false
+
+  return {
+    finish() {
+      return content + decoder.end()
+    },
+    receive(chunk) {
+      if (exceeded) return
+      const remaining = maximumBytes - byteLength
+
+      if (chunk.length > remaining) {
+        if (remaining > 0) content += decoder.write(chunk.subarray(0, remaining))
+        exceeded = true
+        onExceeded()
+        return
+      }
+      byteLength += chunk.length
+      content += decoder.write(chunk)
+    }
+  }
+}
+
+/**
+ * Verifies that the spawned child is the live leader of its distinct POSIX group.
+ * @param {number} processGroupId - Spawn-returned child PID and required group ID.
+ * @returns {boolean} Whether the owned group exists.
+ */
+function verifyOwnedProcessGroup(processGroupId) {
+  try {
+    process.kill(-processGroupId, 0)
+    return true
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code == "ESRCH") return false
+    throw error
+  }
+}
+
+/**
+ * Signals only the verified process group created for the exact spawned child.
+ * @param {number} processGroupId - Spawn-returned child PID and POSIX process-group ID.
+ * @param {"SIGKILL" | "SIGTERM"} signal - Lifecycle signal.
+ * @returns {void}
+ */
+function signalOwnedProcessGroup(processGroupId, signal) {
+  try {
+    process.kill(-processGroupId, signal)
+  } catch (error) {
+    if (!(error instanceof Error && "code" in error && error.code == "ESRCH")) throw error
+  }
+}
+
+/**
+ * Reports whether this module's deadline timer initiated termination.
+ * @param {unknown} error - Subprocess failure.
+ * @returns {boolean} Whether the failure belongs to an owned deadline.
+ */
+export function exceededOwnedDeadline(error) {
+  return typeof error == "object" && error != null && deadlineFailures.has(error)
+}

package/src/timeout.js

@@ -0,0 +1,12 @@
+// @ts-check
+
+export const maximumTimeoutMs = 2_147_483_647
+
+/**
+ * Checks whether a public subprocess timeout fits one exact Node timer.
+ * @param {unknown} value - Candidate timeout.
+ * @returns {value is number} Whether the timeout is a supported positive integer.
+ */
+export function isSupportedTimeoutMs(value) {
+  return typeof value == "number" && Number.isSafeInteger(value) && value > 0 && value <= maximumTimeoutMs
+}