semantifold 0.8.0 → 0.10.0

package/src/project-build.js

@@ -0,0 +1,353 @@
+// @ts-check
+
+import {randomUUID} from "node:crypto"
+import {generateProgramArtifacts} from "./backends/program.js"
+import {SemantifoldDiagnostic} from "./diagnostic.js"
+import {parseProgramSource} from "./frontends/program.js"
+import {ProjectManifestLoader} from "./project-manifest.js"
+import {ProjectSnapshotBuilder} from "./project-snapshot.js"
+import {GeneratedArtifactPublisher, guardNextPublicationCommit} from "./publication.js"
+import {languageRegistry} from "./language-registry.js"
+import {createTargetCheckPlan, TargetCheckRunner} from "./target-check.js"
+import {canonicalToolchains, discoverCanonicalToolchain} from "./toolchains.js"
+
+/** @type {WeakMap<ProjectBuilder, (operation: string) => void>} */
+const projectBuildObservers = new WeakMap()
+/** @type {WeakMap<ProjectBuilder, ProjectWatchBuildControls[]>} */
+const projectWatchBuildControls = new WeakMap()
+
+/**
+ * Installs an internal synchronous orchestration observer for focused specs.
+ * This helper is intentionally not part of the package root API.
+ * @param {ProjectBuilder} builder - Project builder instance.
+ * @param {(operation: string) => void} observer - Ordered operation observer.
+ * @returns {void}
+ */
+export function observeProjectBuild(builder, observer) {
+  if (!(builder instanceof ProjectBuilder) || typeof observer != "function") {
+    throw new TypeError("Invalid project build observer.")
+  }
+  projectBuildObservers.set(builder, observer)
+}
+
+/**
+ * Runs one builder invocation with the narrow snapshot-currentness controls owned by the watch coordinator.
+ * This helper is intentionally not part of the package root API.
+ * @param {ProjectBuilder} builder - Project builder instance.
+ * @param {string} projectPath - Exact project manifest path.
+ * @param {ProjectBuildReporterLike} reporter - Watch-cycle reporter.
+ * @param {ProjectWatchBuildOptions} options - Checked-cycle and currentness controls.
+ * @returns {Promise<Readonly<ProjectBuildSuccess>>} Committed build result.
+ */
+export function buildWatchedProject(builder, projectPath, reporter, options) {
+  if (!(builder instanceof ProjectBuilder) || typeof projectPath != "string" || projectPath.length == 0 ||
+    !isPlainObject(options) || Object.keys(options).some(key =>
+      !["check", "expectedSnapshotHash", "publicationSignal", "signal", "validateCurrentSnapshot"].includes(key)) ||
+    typeof options.check != "boolean" || typeof options.expectedSnapshotHash != "string" ||
+    !/^[a-f0-9]{64}$/u.test(options.expectedSnapshotHash) || !(options.publicationSignal instanceof AbortSignal) ||
+    !(options.signal instanceof AbortSignal) || typeof options.validateCurrentSnapshot != "function") {
+    throw new TypeError("Invalid watched project build controls.")
+  }
+  const queued = projectWatchBuildControls.get(builder) ?? []
+
+  queued.push({
+    expectedSnapshotHash: options.expectedSnapshotHash,
+    publicationSignal: options.publicationSignal,
+    validateCurrentSnapshot: options.validateCurrentSnapshot
+  })
+  projectWatchBuildControls.set(builder, queued)
+
+  return builder.build(projectPath, reporter, {check: options.check, signal: options.signal})
+}
+
+/**
+ * Orchestrates one complete immutable project build and one transactional publication.
+ */
+export class ProjectBuilder {
+  /** @type {ProjectManifestLoader} */
+  #manifestLoader
+  /** @type {ProjectSnapshotBuilder} */
+  #snapshotBuilder
+  /** @type {TargetCheckRunner} */
+  #checkRunner
+  /** @type {Readonly<Record<string, string | undefined>> | undefined} */
+  #environment
+
+  /**
+   * Creates a one-shot project builder.
+   * @param {{checkRunner?: TargetCheckRunner, environment?: Readonly<Record<string, string | undefined>>, manifestLoader?: ProjectManifestLoader, snapshotBuilder?: ProjectSnapshotBuilder}} [options] - Lifecycle collaborators.
+   */
+  constructor(options = {}) {
+    if (options.checkRunner !== undefined && !(options.checkRunner instanceof TargetCheckRunner)) {
+      throw new TypeError("Project builder check runner must be a TargetCheckRunner.")
+    }
+    this.#manifestLoader = options.manifestLoader ?? new ProjectManifestLoader()
+    this.#snapshotBuilder = options.snapshotBuilder ?? new ProjectSnapshotBuilder()
+    this.#checkRunner = options.checkRunner ?? new TargetCheckRunner()
+    this.#environment = options.environment === undefined ? undefined : snapshotEnvironment(options.environment)
+  }
+
+  /**
+   * Builds and atomically publishes one project generation.
+   * @param {string} [projectPath] - Project manifest path.
+   * @param {ProjectBuildReporterLike} [reporter] - Optional state reporter.
+   * @param {ProjectBuildOptions} [options] - Optional developer-check and publication lifecycle.
+   * @returns {Promise<Readonly<ProjectBuildSuccess>>} Committed build result.
+   */
+  async build(projectPath = "./semantifold.json", reporter, options = {}) {
+    const queuedWatchControls = projectWatchBuildControls.get(this)
+    const watchControls = queuedWatchControls?.shift()
+
+    if (queuedWatchControls?.length == 0) projectWatchBuildControls.delete(this)
+    if (typeof options != "object" || options == null || Array.isArray(options) || Object.getPrototypeOf(options) != Object.prototype ||
+      Object.keys(options).some(key => !["check", "signal", "timeoutMs"].includes(key)) ||
+      options.check !== undefined && typeof options.check != "boolean" ||
+      options.signal !== undefined && !(options.signal instanceof AbortSignal) ||
+      options.timeoutMs !== undefined && (typeof options.timeoutMs != "number" || !Number.isInteger(options.timeoutMs))) {
+      throw new SemantifoldDiagnostic({
+        code: "INVALID_PROJECT_BUILD",
+        language: "project",
+        message: "Project build options require valid check, snapshot-currentness, cancellation, and timeout controls."
+      })
+    }
+    const check = options.check === true
+    const signal = options.signal
+    const project = await this.#manifestLoader.load(projectPath)
+
+    reporter?.projectLoaded(project.id)
+    const snapshot = await this.#snapshotBuilder.build(project)
+
+    if (watchControls !== undefined && snapshot.hash != watchControls.expectedSnapshotHash) {
+      throw new SemantifoldDiagnostic({
+        code: "WATCH_SNAPSHOT_CHANGED",
+        language: project.id,
+        message: "The complete project snapshot changed before its watch cycle began."
+      })
+    }
+
+    reporter?.snapshotLoaded(snapshot.hash)
+    projectBuildObservers.get(this)?.("snapshot")
+    const program = parseProgramSource({
+      entryModule: project.entryModule,
+      sources: snapshot.sources.map(source => ({
+        filename: source.path,
+        id: source.id,
+        language: source.language,
+        source: source.source
+      }))
+    })
+
+    projectBuildObservers.get(this)?.("parse")
+    /** @type {import("./semantic/types.js").PublicationTargetInput[]} */
+    const publicationTargets = []
+    /** @type {ProjectBuildTargetResult[]} */
+    const targetResults = []
+    /** @type {Map<string, import("./semantic/types.js").TargetCheckResult>} */
+    const checkResults = new Map()
+
+    for (const target of project.targets) {
+      if (target.role == "binary") {
+        throw new SemantifoldDiagnostic({
+          code: "UNSUPPORTED_PROJECT_TARGET",
+          language: target.language,
+          message: "Complete semantic programs do not support binary project generation."
+        })
+      }
+      const artifactSet = generateProgramArtifacts({
+        language: target.language,
+        program,
+        role: target.role
+      })
+      const checkCapability = languageRegistry.record(target.language).check
+
+      if (check && !checkCapability.supported) {
+        throw new SemantifoldDiagnostic({
+          code: "UNSUPPORTED_TARGET_CHECK",
+          language: target.language,
+          message: `Project target '${target.id}' does not provide a developer check plan.`
+        })
+      }
+      /**
+       * Ordered candidate validators when checking is enabled.
+       * @type {import("./semantic/types.js").PublicationValidator[] | undefined}
+       */
+      const validators = check ? [async ({buildPath, sourcePath, targetId}) => {
+        /** @type {import("./semantic/types.js").DiscoveredToolchain[]} */
+        const tools = []
+
+        for (const toolchain of checkCapability.toolchains) {
+          tools.push(await discoverCanonicalToolchain(/** @type {keyof typeof canonicalToolchains} */ (toolchain), {
+            ...(this.#environment === undefined ? {} : {environment: this.#environment})
+          }))
+        }
+        const plan = createTargetCheckPlan({
+          artifacts: artifactSet,
+          buildPath,
+          projectId: project.id,
+          sourcePath,
+          targetId,
+          tools: Object.freeze(tools)
+        })
+        const result = await this.#checkRunner.run(plan, {
+          onStage: stage => {
+            reporter?.targetChecked({id: target.id, language: target.language, stage})
+            projectBuildObservers.get(this)?.(`check:${target.id}:${stage.stage}`)
+          },
+          ...(signal === undefined ? {} : {signal}),
+          ...(options.timeoutMs === undefined ? {} : {timeoutMs: options.timeoutMs})
+        })
+
+        checkResults.set(target.id, result)
+
+        return [...result.outputs]
+      }] : undefined
+
+      publicationTargets.push({
+        artifactSet,
+        buildProjection: target.buildProjection,
+        id: target.id,
+        role: target.role,
+        sourceProjection: target.sourceProjection,
+        ...(validators === undefined ? {} : {validators})
+      })
+      targetResults.push(Object.freeze({
+        artifactCount: artifactSet.artifacts.length,
+        id: target.id,
+        language: target.language,
+        role: target.role
+      }))
+      reporter?.targetGenerated(targetResults[targetResults.length - 1])
+      projectBuildObservers.get(this)?.(`target:${target.id}`)
+    }
+    const publisher = new GeneratedArtifactPublisher({
+      projectId: project.id,
+      projectRoot: project.projectRoot,
+      publicationRoot: project.publicationRoot,
+      sourceFiles: project.sources.map(({absolutePath}) => absolutePath)
+    })
+    const generationId = check
+      ? `g-${snapshot.hash}-checked-${randomUUID()}`
+      : `g-${snapshot.hash}`
+    if (watchControls !== undefined) {
+      guardNextPublicationCommit(publisher, watchControls.validateCurrentSnapshot)
+    }
+    const publicationSignal = signal === undefined
+      ? watchControls?.publicationSignal
+      : watchControls === undefined
+        ? signal
+        : AbortSignal.any([signal, watchControls.publicationSignal])
+    const generation = await publisher.publish({generationId, targets: publicationTargets}, {
+      ...(publicationSignal === undefined ? {} : {signal: publicationSignal})
+    })
+
+    projectBuildObservers.get(this)?.("publish")
+
+    return Object.freeze({
+      generation,
+      generationId,
+      checked: check,
+      projectId: project.id,
+      snapshotHash: snapshot.hash,
+      status: /** @type {const} */ ("succeeded"),
+      targets: Object.freeze(targetResults.map(target => {
+        const result = checkResults.get(target.id)
+
+        return Object.freeze({
+          ...target,
+          ...(result === undefined ? {} : {check: Object.freeze({stages: result.stages})})
+        })
+      }))
+    })
+  }
+}
+
+/**
+ * @typedef ProjectBuildOptions
+ * @property {boolean} [check] - Whether every target must run its developer check.
+ * @property {AbortSignal} [signal] - Active check and publication cancellation authority.
+ * @property {number} [timeoutMs] - Per-check-stage deadline.
+ */
+
+/**
+ * @typedef ProjectWatchBuildOptions
+ * @property {boolean} check - Whether every target must run its developer check.
+ * @property {string} expectedSnapshotHash - Coordinator-reconciled complete graph hash.
+ * @property {AbortSignal} publicationSignal - Publication-only cancellation authority.
+ * @property {AbortSignal} signal - Active check and publication cancellation authority.
+ * @property {() => Promise<void> | void} validateCurrentSnapshot - Complete graph guard at the pointer boundary.
+ */
+
+/**
+ * @typedef ProjectWatchBuildControls
+ * @property {string} expectedSnapshotHash - Coordinator-reconciled complete graph hash.
+ * @property {AbortSignal} publicationSignal - Publication-only cancellation authority.
+ * @property {() => Promise<void> | void} validateCurrentSnapshot - Complete graph guard at the pointer boundary.
+ */
+
+/**
+ * @typedef ProjectBuildReporterLike
+ * @property {(projectId: string) => void} projectLoaded - Reports validated configuration.
+ * @property {(snapshotHash: string) => void} snapshotLoaded - Reports a complete snapshot.
+ * @property {(target: ProjectBuildTargetResult) => void} targetGenerated - Reports generated target output.
+ * @property {(checked: {id: string, language: string, stage: import("./semantic/types.js").TargetCheckStageResult}) => void} targetChecked - Reports a successful check stage.
+ */
+
+/**
+ * @typedef ProjectBuildTargetResult
+ * @property {number} artifactCount - Generated artifact count.
+ * @property {string} id - Project target identity.
+ * @property {import("./semantic/types.js").BackendLanguage} language - Backend target identity.
+ * @property {import("./semantic/types.js").PublicationTargetRole} role - Explicit target role.
+ * @property {Readonly<{stages: readonly import("./semantic/types.js").TargetCheckStageResult[]}>} [check] - Successful developer-check evidence.
+ */
+
+/**
+ * @typedef ProjectBuildSuccess
+ * @property {"succeeded"} status - Terminal success state.
+ * @property {string} projectId - Stable project identity.
+ * @property {string} snapshotHash - Complete ordered input hash.
+ * @property {string} generationId - Deterministic immutable generation identity.
+ * @property {boolean} checked - Whether developer checks completed for every target.
+ * @property {readonly ProjectBuildTargetResult[]} targets - Ordered generated target results.
+ * @property {import("./semantic/types.js").PublishedGeneration} generation - Committed publisher snapshot.
+ */
+
+/**
+ * Detaches explicit tool discovery configuration from caller mutation.
+ * @param {unknown} candidate - Candidate environment.
+ * @returns {Readonly<Record<string, string | undefined>>} Immutable snapshot.
+ */
+function snapshotEnvironment(candidate) {
+  if (typeof candidate != "object" || candidate == null || Array.isArray(candidate)) {
+    throw new TypeError("Project builder environment must be a plain string record.")
+  }
+  const prototype = Object.getPrototypeOf(candidate)
+
+  if (prototype !== Object.prototype && prototype !== null) {
+    throw new TypeError("Project builder environment must be a plain string record.")
+  }
+  /** @type {Record<string, string | undefined>} */
+  const snapshot = Object.create(null)
+
+  for (const key of Reflect.ownKeys(candidate)) {
+    if (typeof key != "string") throw new TypeError("Project builder environment must use string keys.")
+    const descriptor = Object.getOwnPropertyDescriptor(candidate, key)
+
+    if (descriptor == undefined || !descriptor.enumerable || !("value" in descriptor) ||
+      descriptor.value !== undefined && typeof descriptor.value != "string") {
+      throw new TypeError("Project builder environment must contain string or undefined data values.")
+    }
+    snapshot[key] = descriptor.value
+  }
+
+  return Object.freeze(snapshot)
+}
+
+/**
+ * Checks for an ordinary object-prototype record.
+ * @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
+}

package/src/project-cli.js

@@ -0,0 +1,155 @@
+// @ts-check
+
+import {SemantifoldDiagnostic} from "./diagnostic.js"
+import {ProjectBuilder} from "./project-build.js"
+import {ProjectBuildReporter} from "./project-reporter.js"
+import {ProjectWatchCoordinator} from "./project-watch.js"
+import {ProjectWatchReporter} from "./project-watch-reporter.js"
+
+/**
+ * Owns one strict command invocation while delegating durable build behavior.
+ */
+export class SemantifoldCli {
+  /** @type {ProjectBuilder} */
+  #builder
+  /** @type {ProjectWatchCoordinator} */
+  #coordinator
+  /** @type {import("./project-reporter.js").WritableOutput} */
+  #stdout
+  /** @type {import("./project-reporter.js").WritableOutput} */
+  #stderr
+
+  /**
+   * Creates an importable CLI lifecycle.
+   * @param {{builder?: ProjectBuilder, coordinator?: ProjectWatchCoordinator, stderr?: import("./project-reporter.js").WritableOutput, stdout?: import("./project-reporter.js").WritableOutput}} [options] - Collaborators and sinks.
+   */
+  constructor(options = {}) {
+    this.#builder = options.builder ?? new ProjectBuilder()
+    this.#coordinator = options.coordinator ?? new ProjectWatchCoordinator({builder: this.#builder})
+    this.#stdout = options.stdout ?? process.stdout
+    this.#stderr = options.stderr ?? process.stderr
+  }
+
+  /**
+   * Runs one command without mutating process exit state.
+   * @param {readonly string[]} arguments_ - Arguments after the executable name.
+   * @returns {Promise<0 | 1>} Exact process status.
+   */
+  async run(arguments_) {
+    const hintedFormat = arguments_.includes("--ndjson") ? "ndjson" : "human"
+    const watchHint = arguments_[0] == "watch"
+    let reporter = watchHint
+      ? new ProjectWatchReporter({format: hintedFormat, stderr: this.#stderr, stdout: this.#stdout})
+      : new ProjectBuildReporter({format: hintedFormat, stderr: this.#stderr, stdout: this.#stdout})
+
+    try {
+      const options = parseSemantifoldCliArguments(arguments_)
+      const command = "command" in options ? options.command : "build"
+
+      if (options.format != hintedFormat) {
+        reporter = command == "watch"
+          ? new ProjectWatchReporter({format: options.format, stderr: this.#stderr, stdout: this.#stdout})
+          : new ProjectBuildReporter({format: options.format, stderr: this.#stderr, stdout: this.#stdout})
+      }
+      if (command == "watch") {
+        const result = await this.#coordinator.run(options.projectPath, /** @type {ProjectWatchReporter} */ (reporter), {
+          check: options.check
+        })
+
+        return result.status == "stopped" ? 0 : 1
+      }
+      const controller = new AbortController()
+      const forwardSignal = () => controller.abort("Semantifold CLI received a termination signal.")
+
+      if (options.check) {
+        process.once("SIGINT", forwardSignal)
+        process.once("SIGTERM", forwardSignal)
+      }
+      let result
+
+      try {
+        result = await this.#builder.build(options.projectPath, /** @type {ProjectBuildReporter} */ (reporter), {
+          check: options.check,
+          ...(options.check ? {signal: controller.signal} : {})
+        })
+      } finally {
+        if (options.check) {
+          process.removeListener("SIGINT", forwardSignal)
+          process.removeListener("SIGTERM", forwardSignal)
+        }
+      }
+
+      /** @type {ProjectBuildReporter} */ (reporter).succeeded(result)
+
+      return 0
+    } catch (error) {
+      if (reporter instanceof ProjectWatchReporter) reporter.watchFailed(error)
+      else reporter.failed(error)
+
+      return 1
+    }
+  }
+}
+
+/**
+ * Parses the intentionally narrow one-shot CLI grammar.
+ * @param {readonly string[]} arguments_ - Arguments after the executable name.
+ * @returns {Readonly<{check: boolean, format: "human" | "ndjson", projectPath: string}> | Readonly<{command: "watch", check: boolean, format: "human" | "ndjson", projectPath: string}>} Validated command options.
+ */
+export function parseSemantifoldCliArguments(arguments_) {
+  if (!Array.isArray(arguments_) || arguments_.length == 0 || arguments_[0] != "build" && arguments_[0] != "watch") {
+    invalidArguments("Expected the command 'semantifold build' or 'semantifold watch'.")
+  }
+  const command = /** @type {"build" | "watch"} */ (arguments_[0])
+  let format = /** @type {"human" | "ndjson"} */ ("human")
+  let projectPath = "./semantifold.json"
+  let projectSeen = false
+  let ndjsonSeen = false
+  let checkSeen = false
+
+  for (let index = 1; index < arguments_.length; index += 1) {
+    const argument = arguments_[index]
+
+    if (argument == "--check") {
+      if (checkSeen) invalidArguments("Option '--check' may be supplied only once.")
+      checkSeen = true
+      continue
+    }
+    if (argument == "--ndjson") {
+      if (ndjsonSeen) invalidArguments("Option '--ndjson' may be supplied only once.")
+      ndjsonSeen = true
+      format = "ndjson"
+      continue
+    }
+    if (argument == "--project") {
+      if (projectSeen) invalidArguments("Option '--project' may be supplied only once.")
+      const value = arguments_[index + 1]
+
+      if (typeof value != "string" || value.length == 0 || value.startsWith("--")) {
+        invalidArguments("Option '--project' requires one path value.")
+      }
+      projectSeen = true
+      projectPath = value
+      index += 1
+      continue
+    }
+    invalidArguments(`Unknown command argument '${argument}'.`)
+  }
+
+  return command == "watch"
+    ? Object.freeze({command, check: checkSeen, format, projectPath})
+    : Object.freeze({check: checkSeen, format, projectPath})
+}
+
+/**
+ * Throws one stable CLI grammar diagnostic.
+ * @param {string} message - Failure detail.
+ * @returns {never} Always throws.
+ */
+function invalidArguments(message) {
+  throw new SemantifoldDiagnostic({
+    code: "INVALID_CLI_ARGUMENTS",
+    language: "cli",
+    message
+  })
+}