@hypit/hypit 0.0.1 → 0.1.1

package/packages/compiler-node/src/compiler.ts

@@ -0,0 +1,207 @@
+import { randomUUID } from "node:crypto";
+
+import {
+  compileSourceClosure,
+  prepareAuthorSource,
+} from "@hypit/elaborator";
+import { link } from "@hypit/core";
+import type {
+  AuthorFrontendRegistryLike,
+  AuthorSourceDiscovery,
+  CompiledSourceClosure,
+  AuthorRecordAdmitter,
+} from "@hypit/elaborator";
+import type { SourceUnit } from "@hypit/source";
+import type { ArtifactAttachment, Workspace, WorkspaceSession } from "@hypit/workspace";
+import type { BlobRef, LinkedProgram } from "@hypit/protocol";
+import {
+  TypeValidatorRegistry,
+  createRecordAdmitter,
+} from "@hypit/validation";
+import type { TypeValidatorRegistryLike } from "@hypit/validation";
+
+import { NodeCompilerError } from "./error.js";
+import type { ModulePackageRegistryLike } from "./modules.js";
+
+type DiscoveredUnit = {
+  readonly source: SourceUnit;
+  readonly frontend: string;
+  readonly discovery: AuthorSourceDiscovery;
+};
+
+function attachmentKey(artifact: BlobRef): string {
+  return `${artifact.resource}\u0000${artifact.mediaType}`;
+}
+
+export function mergeAttachments(groups: readonly (readonly ArtifactAttachment[])[]): readonly ArtifactAttachment[] {
+  const merged = new Map<string, ArtifactAttachment>();
+  for (const item of groups.flat()) {
+    const key = attachmentKey(item.artifact);
+    const existing = merged.get(key);
+    if (existing !== undefined) {
+      if (existing.artifact.size !== item.artifact.size) {
+        throw new NodeCompilerError(
+          "SOURCE_ATTACHMENT_CONFLICT",
+          `Artifact attachment ${item.artifact.resource} carries conflicting sizes`,
+          item.artifact.resource,
+        );
+      }
+      continue;
+    }
+    merged.set(key, {
+      artifact: { ...item.artifact },
+      open: item.open,
+    });
+  }
+  return [...merged.values()]
+    .sort((left, right) => attachmentKey(left.artifact).localeCompare(attachmentKey(right.artifact)));
+}
+
+async function discoverClosure(
+  entry: SourceUnit,
+  frontends: AuthorFrontendRegistryLike,
+  workspace: WorkspaceSession,
+): Promise<readonly DiscoveredUnit[]> {
+  const units = new Map<string, DiscoveredUnit>();
+  const visiting = new Set<string>();
+  const visit = async (source: SourceUnit): Promise<void> => {
+    const prepared = prepareAuthorSource(source);
+    const selectedFrontend = prepared.header.using;
+    const key = `${source.id}\u0000${selectedFrontend}`;
+    if (units.has(key)) return;
+    if (visiting.has(key)) {
+      throw new NodeCompilerError("SOURCE_IMPORT_CYCLE", `Source imports cycle through ${source.name}`, source.id);
+    }
+    const frontend = frontends.resolve(selectedFrontend);
+    if (frontend === undefined) {
+      throw new NodeCompilerError("UNKNOWN_FRONTEND", `Frontend ${selectedFrontend} is not registered`, selectedFrontend);
+    }
+    visiting.add(key);
+    const discovery = await frontend.discover(prepared);
+    for (const request of discovery.sources) {
+      await visit(await workspace.resolveSource(source, request));
+    }
+    visiting.delete(key);
+    units.set(key, { source, frontend: selectedFrontend, discovery });
+  };
+  await visit(entry);
+  return [...units.values()];
+}
+
+export type NodeCompilerOptions = {
+  readonly modules: ModulePackageRegistryLike;
+  readonly frontends: AuthorFrontendRegistryLike;
+  /** Explicit definition environment selected by the Host. */
+  readonly workspace: Workspace;
+  /** Trusted Type-owner validators used to admit authored Records before linking. */
+  readonly validators?: TypeValidatorRegistryLike;
+};
+
+export type NodeCompiledSourceClosure = CompiledSourceClosure & {
+  /** Host-side transfer bundle; bytes are not serialized into Core BuildState. */
+  readonly attachments: readonly ArtifactAttachment[];
+};
+
+/** Domain-neutral Node facade from a real Author Source to a verified Source Closure and Graph. */
+export class NodeCompiler {
+  readonly #options: NodeCompilerOptions;
+  readonly #admitRecord: AuthorRecordAdmitter;
+
+  constructor(options: NodeCompilerOptions) {
+    this.#options = options;
+    this.#admitRecord = createRecordAdmitter(options.validators ?? new TypeValidatorRegistry());
+  }
+
+  supportsFrontend(id: string): boolean {
+    return this.#options.frontends.resolve(id) !== undefined;
+  }
+
+  /** Open one read-once Workspace session so a Host can inspect the Source Header and compile it once. */
+  async openFile(file: string): Promise<WorkspaceSession> {
+    return await this.#options.workspace.open(file);
+  }
+
+  async compileFile(file: string): Promise<NodeCompiledSourceClosure> {
+    const workspace = await this.openFile(file);
+    return await this.compileSource(workspace.entry, workspace);
+  }
+
+  /** Compile an explicitly resolved self-describing SourceUnit inside one already isolated Workspace. */
+  async compileSource(entry: SourceUnit, workspace: WorkspaceSession): Promise<NodeCompiledSourceClosure> {
+    const embeddedAttachments = new Map<string, ArtifactAttachment>();
+    const discovered = await discoverClosure(
+      entry,
+      this.#options.frontends,
+      workspace,
+    );
+    const closure = this.#options.modules.createClosure(
+      discovered.flatMap((unit) => unit.discovery.modules),
+    );
+    const discoveries = new Map(discovered.map((unit) => [
+      `${unit.source.id}\u0000${unit.frontend}`,
+      unit.discovery,
+    ]));
+    const compilation = await compileSourceClosure({
+      entry,
+      closure,
+      frontends: this.#options.frontends,
+      discover(source, frontend) {
+        const discovery = discoveries.get(`${source.id}\u0000${frontend.id}`);
+        if (discovery === undefined) {
+          throw new NodeCompilerError(
+            "SOURCE_DISCOVERY_MISSING",
+            `Source ${source.name} was not present in the frozen discovery closure`,
+            source.id,
+          );
+        }
+        return discovery;
+      },
+      resolveSource: workspace.resolveSource,
+      async resolveAsset(importer, request) {
+        if (request.bytes === undefined) return await workspace.resolveAsset(importer, request);
+        const bytes = Uint8Array.from(request.bytes);
+        const artifact: BlobRef = {
+          kind: "blob",
+          resource: `res_${randomUUID()}`,
+          size: bytes.byteLength,
+          mediaType: request.mediaType,
+        };
+        const key = attachmentKey(artifact);
+        const existing = embeddedAttachments.get(key);
+        if (existing !== undefined && existing.artifact.size !== bytes.byteLength) {
+          throw new NodeCompilerError(
+            "SOURCE_ATTACHMENT_CONFLICT",
+            `Embedded asset ${request.from} conflicts with ${artifact.resource}`,
+            request.from,
+          );
+        }
+        embeddedAttachments.set(key, {
+          artifact,
+          open: async () => (async function* () { yield Uint8Array.from(bytes); })(),
+        });
+        return { artifact: { ...artifact } };
+      },
+      admitRecord: this.#admitRecord,
+    });
+    return {
+      ...compilation,
+      attachments: mergeAttachments([await workspace.attachments(), [...embeddedAttachments.values()]]),
+    };
+  }
+
+  /**
+   * Add modules used only by Run implementations. Author records stay unchanged.
+   */
+  extendExecutionProgram(program: LinkedProgram, requests: readonly string[]): LinkedProgram {
+    const existing = program.closure.modules.map((item) => `${item.manifest.name}@${item.manifest.version}`);
+    if (requests.every((request) => existing.includes(request))) return program;
+    const closure = this.#options.modules.createClosure([...existing, ...requests]);
+    return link(closure, program.records);
+  }
+
+  /** Admit one selected Run value through the same Type-owner boundary as authored Records. */
+  async admitRecord(program: LinkedProgram, record: import("@hypit/protocol").TypedRecord): Promise<void> {
+    await this.#admitRecord(program.closure, record);
+  }
+
+}

package/packages/compiler-node/src/error.ts

@@ -0,0 +1,11 @@
+export class NodeCompilerError extends Error {
+  readonly code: string;
+  readonly subject: string | undefined;
+
+  constructor(code: string, message: string, subject?: string) {
+    super(message);
+    this.name = "NodeCompilerError";
+    this.code = code;
+    this.subject = subject;
+  }
+}

package/packages/compiler-node/src/graph-query.ts

@@ -0,0 +1,51 @@
+import {
+  resolveCandidate,
+  resolveLogicalOutput,
+  resolveOperation,
+} from "@hypit/core";
+import type {
+  Candidate,
+  CompiledGraph,
+  GraphValueRef,
+  LogicalOutput,
+  OperationNode,
+  ProducerRef,
+} from "@hypit/protocol";
+
+/** Read-only Graph helpers shared by preview and other host tooling. */
+
+export function findLogicalOutput(graph: CompiledGraph, outputId: string): LogicalOutput | undefined {
+  try { return resolveLogicalOutput(graph, outputId); } catch { return undefined; }
+}
+
+export function findCandidate(graph: CompiledGraph, candidateId: string): Candidate | undefined {
+  try { return resolveCandidate(graph, candidateId); } catch { return undefined; }
+}
+
+export function findOperation(graph: CompiledGraph, operationId: string): OperationNode | undefined {
+  try { return resolveOperation(graph, operationId); } catch { return undefined; }
+}
+
+export function findOperationsByProducer(graph: CompiledGraph, producer: ProducerRef): readonly OperationNode[] {
+  return graph.operations.filter((operation) =>
+    operation.producer.module.name === producer.module.name
+    && operation.producer.module.version === producer.module.version
+    && operation.producer.name === producer.name,
+  );
+}
+
+/** Walk operation inputs in dependency order, excluding authored Records and Logical Outputs. */
+export function walkOperationInputs(graph: CompiledGraph, operationId: string): readonly OperationNode[] {
+  const result: OperationNode[] = [];
+  const visited = new Set<string>();
+  const visitRef = (ref: GraphValueRef): void => {
+    if (ref.kind !== "operation-result" || visited.has(ref.operation)) return;
+    const operation = findOperation(graph, ref.operation);
+    if (operation === undefined) return;
+    visited.add(ref.operation);
+    for (const input of Object.values(operation.inputs)) visitRef(input);
+    result.push(operation);
+  };
+  visitRef({ kind: "operation-result", operation: operationId });
+  return result;
+}

package/packages/compiler-node/src/index.ts

@@ -0,0 +1,27 @@
+export { NodeCompilerError } from "./error.js";
+export {
+  ModulePackageRegistry,
+} from "./modules.js";
+export type {
+  ModulePackageRegistryLike,
+  RegisteredModulePackage,
+} from "./modules.js";
+export { NodeCompiler } from "./compiler.js";
+export { NodeRunCompiler } from "./run.js";
+export type {
+  NodeCompilerOptions,
+  NodeCompiledSourceClosure,
+} from "./compiler.js";
+export type {
+  NodeCheckedRun,
+  NodeCompiledRun,
+  NodeRunCompilerOptions,
+  PlannedBuild,
+} from "./run.js";
+export {
+  findCandidate,
+  findLogicalOutput,
+  findOperation,
+  findOperationsByProducer,
+  walkOperationInputs,
+} from "./graph-query.js";

package/packages/compiler-node/src/modules.ts

@@ -0,0 +1,107 @@
+import { createResolvedClosure } from "@hypit/core";
+import type {
+  ModuleManifest,
+  ModuleRef,
+  ResolvedModuleClosure,
+} from "@hypit/protocol";
+
+import { NodeCompilerError } from "./error.js";
+
+function moduleKey(ref: ModuleRef): string {
+  return `${ref.name}@${ref.version}`;
+}
+
+function manifestRef(manifest: ModuleManifest): ModuleRef {
+  return { name: manifest.name, version: manifest.version };
+}
+
+export type RegisteredModulePackage = {
+  readonly manifest: ModuleManifest;
+  /** Additional author import spellings resolved to this exact manifest. */
+  readonly specifiers?: readonly string[];
+};
+
+export interface ModulePackageRegistryLike {
+  resolve(request: string): ModuleRef | undefined;
+  createClosure(requests: readonly string[]): ResolvedModuleClosure;
+}
+
+/**
+ * Deterministic registry of already trusted/installed module manifests.
+ *
+ * This is intentionally not an npm loader: locating and trusting executable package code belongs
+ * to the embedding Host. The registry only resolves an author import spelling to one immutable
+ * manifest and closes that manifest's declared dependencies.
+ */
+export class ModulePackageRegistry implements ModulePackageRegistryLike {
+  readonly #manifests = new Map<string, ModuleManifest>();
+  readonly #specifiers = new Map<string, string>();
+
+  register(value: RegisteredModulePackage): void {
+    const ref = manifestRef(value.manifest);
+    const key = moduleKey(ref);
+    const existing = this.#manifests.get(key);
+    if (existing !== undefined) {
+      throw new NodeCompilerError("DUPLICATE_MODULE_PACKAGE", `Module package ${key} is already registered`, key);
+    }
+    const specifiers = new Set([key, ...(value.specifiers ?? [])]);
+    for (const specifier of specifiers) {
+      if (specifier.length === 0) {
+        throw new NodeCompilerError("EMPTY_MODULE_SPECIFIER", `${key} declares an empty import specifier`, key);
+      }
+      const owner = this.#specifiers.get(specifier);
+      if (owner !== undefined) {
+        throw new NodeCompilerError(
+          "DUPLICATE_MODULE_SPECIFIER",
+          `Import ${specifier} is already bound to ${owner}`,
+          specifier,
+        );
+      }
+    }
+    this.#manifests.set(key, value.manifest);
+    for (const specifier of specifiers) this.#specifiers.set(specifier, key);
+  }
+
+  resolve(request: string): ModuleRef | undefined {
+    const key = this.#specifiers.get(request);
+    const manifest = key === undefined ? undefined : this.#manifests.get(key);
+    return manifest === undefined ? undefined : manifestRef(manifest);
+  }
+
+  createClosure(requests: readonly string[]): ResolvedModuleClosure {
+    const included = new Map<string, ModuleManifest>();
+    const visit = (key: string): void => {
+      if (included.has(key)) return;
+      const manifest = this.#manifests.get(key);
+      if (manifest === undefined) {
+        throw new NodeCompilerError("MISSING_MODULE_DEPENDENCY", `Module dependency ${key} is not registered`, key);
+      }
+      included.set(key, manifest);
+      for (const dependency of manifest.dependencies) {
+        const dependencyKey = moduleKey(dependency.module);
+        const resolved = this.#manifests.get(dependencyKey);
+        if (resolved === undefined) {
+          throw new NodeCompilerError(
+            "MISSING_MODULE_DEPENDENCY",
+            `${key} requires unregistered module ${dependencyKey}`,
+            dependencyKey,
+          );
+        }
+        visit(dependencyKey);
+      }
+    };
+
+    for (const request of [...new Set(requests)].sort()) {
+      const key = this.#specifiers.get(request);
+      if (key === undefined) {
+        throw new NodeCompilerError("UNKNOWN_MODULE_IMPORT", `No registered module satisfies ${request}`, request);
+      }
+      visit(key);
+    }
+    return createResolvedClosure(
+      [...included.values()].sort((left, right) =>
+        moduleKey(manifestRef(left)).localeCompare(moduleKey(manifestRef(right))),
+      ),
+    );
+  }
+}