halfcode-compiler.xnl 0.1.1

package/README.md

@@ -0,0 +1,19 @@
+# halfcode-compiler.xnl
+
+The single public npm package for compiling XNL-described applications into runtime-ready skill capsules.
+
+```sh
+npm install halfcode-compiler.xnl
+```
+
+Use the package root for the high-level application assembly and skill capsule APIs:
+
+```ts
+import {
+  resolveApplicationAssembly,
+  compileResourceSkillCapsule,
+  type PageObjectResource,
+} from "halfcode-compiler.xnl"
+```
+
+Lower-level APIs are available through explicit subpaths such as `halfcode-compiler.xnl/resource-core` and `halfcode-compiler.xnl/authoring-runtime`.

package/dist/application-assembly.d.ts

@@ -0,0 +1,2 @@
+import { A as ObjectTargets, B as assertExecuteObjectOperationRequest, C as ObjectOperationDefinition, D as ObjectOperationTargetDeclaration, E as ObjectOperationOwnerKind, F as ResourceSource, G as resolveApplicationAssembly, H as assertObjectOperationCatalog, I as SkillCapsuleResource, K as resourceRefToFqn, L as TextMaterial, M as ResolveApplicationAssemblyOptions, N as ResolvedAssemblyPortBinding, O as ObjectTargetKindDefinition, P as ResourceInclude, R as TextResource, S as ObjectOperationContractError, T as ObjectOperationHandler, U as assertObjectOperationDefinition, V as assertObjectOperationCall, W as loadApplicationAssembly, _ as ObjectInvocationMode, a as AssemblyResource, b as ObjectOperationCatalog, c as BusinessObjectSopResource, d as ExecuteObjectOperationRequest, f as JsonObject, g as ObjectInvocation, h as LoadApplicationAssemblyOptions, i as AssemblyPortBinding, j as PageObjectResource, k as ObjectTargetRef, l as CodeBinding, m as JsonValue, n as ApplicationScope, o as AuthoringModuleDescriptor, p as JsonPrimitive, r as AssemblyPort, s as BusinessObjectResource, t as ApplicationAssembly, u as ContractedCallableResource, v as ObjectOperationBehavior, w as ObjectOperationEffect, x as ObjectOperationConfig, y as ObjectOperationCall, z as applicationAssemblyPackage } from "./index-FdimP_SL.js";
+export { type ApplicationAssembly, type ApplicationScope, type AssemblyPort, type AssemblyPortBinding, type AssemblyResource, type AuthoringModuleDescriptor, type BusinessObjectResource, type BusinessObjectSopResource, type CodeBinding, type ContractedCallableResource, type ExecuteObjectOperationRequest, type JsonObject, type JsonPrimitive, type JsonValue, type LoadApplicationAssemblyOptions, type ObjectInvocation, type ObjectInvocationMode, type ObjectOperationBehavior, type ObjectOperationCall, type ObjectOperationCatalog, type ObjectOperationConfig, ObjectOperationContractError, type ObjectOperationDefinition, type ObjectOperationEffect, type ObjectOperationHandler, type ObjectOperationOwnerKind, type ObjectOperationTargetDeclaration, type ObjectTargetKindDefinition, type ObjectTargetRef, type ObjectTargets, type PageObjectResource, type ResolveApplicationAssemblyOptions, type ResolvedAssemblyPortBinding, type ResourceInclude, type ResourceSource, type SkillCapsuleResource, type TextMaterial, type TextResource, applicationAssemblyPackage, assertExecuteObjectOperationRequest, assertObjectOperationCall, assertObjectOperationCatalog, assertObjectOperationDefinition, loadApplicationAssembly, resolveApplicationAssembly, resourceRefToFqn };

package/dist/application-assembly.js

@@ -0,0 +1,2 @@
+import { a as assertObjectOperationCatalog, c as resolveApplicationAssembly, i as assertObjectOperationCall, l as resourceRefToFqn, n as applicationAssemblyPackage, o as assertObjectOperationDefinition, r as assertExecuteObjectOperationRequest, s as loadApplicationAssembly, t as ObjectOperationContractError } from "./src-Dv8bfFUo.js";
+export { ObjectOperationContractError, applicationAssemblyPackage, assertExecuteObjectOperationRequest, assertObjectOperationCall, assertObjectOperationCatalog, assertObjectOperationDefinition, loadApplicationAssembly, resolveApplicationAssembly, resourceRefToFqn };

package/dist/authoring-runtime.d.ts

@@ -0,0 +1,2 @@
+import { a as createAuthoringBindings, c as logger, i as RuntimeEffects, l as runWithRuntime, n as AuthoringRuntime, o as currentRuntime, r as Logger, s as invokeEffect, t as AuthoringBindings, u as runtimeAuthoringPackage } from "./index-Dg0imcjf.js";
+export { AuthoringBindings, AuthoringRuntime, Logger, RuntimeEffects, createAuthoringBindings, currentRuntime, invokeEffect, logger, runWithRuntime, runtimeAuthoringPackage };

package/dist/authoring-runtime.js

@@ -0,0 +1,2 @@
+import { a as runWithRuntime, i as logger, n as currentRuntime, o as runtimeAuthoringPackage, r as invokeEffect, t as createAuthoringBindings } from "./src-B87eJQat.js";
+export { createAuthoringBindings, currentRuntime, invokeEffect, logger, runWithRuntime, runtimeAuthoringPackage };

package/dist/contract-schema.d.ts

@@ -0,0 +1,45 @@
+//#region ../contract-schema-compiler/src/index.d.ts
+type JsonSchema = Record<string, unknown>;
+interface ContractSideFact {
+  source: string;
+  export: string;
+  schemaId: string;
+}
+interface ContractFact {
+  kind: string;
+  fqn: string;
+  input: ContractSideFact;
+  output: ContractSideFact;
+}
+interface ContractSchemaCompilerOptions {
+  packageRoot: string;
+  sourceRoot?: string;
+  contractFactName?: string;
+  checkOnly?: boolean;
+  expectedKind?: string | readonly string[];
+  categoryCatalog?: boolean;
+}
+interface ContractSchemaCompilerReport {
+  facts: readonly ContractFactRecord[];
+  files: readonly GeneratedFile[];
+  checkOnly: boolean;
+}
+interface ContractFactRecord {
+  directory: string;
+  factPath: string;
+  category: string;
+  capabilityName: string;
+  fact: ContractFact;
+}
+interface GeneratedFile {
+  path: string;
+  content: string;
+}
+declare function compileContractSchemas(options: ContractSchemaCompilerOptions): Promise<ContractSchemaCompilerReport>;
+declare const contractSchemaCompilerPackage: {
+  readonly role: "framework";
+  readonly area: "contract-schema-compiler";
+  readonly owns: "TypeScript type-system driven contract schema projections";
+};
+//#endregion
+export { ContractFact, ContractFactRecord, ContractSchemaCompilerOptions, ContractSchemaCompilerReport, ContractSideFact, GeneratedFile, JsonSchema, compileContractSchemas, contractSchemaCompilerPackage };

package/dist/contract-schema.js

@@ -0,0 +1,297 @@
+import { mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import { dirname, join, relative, resolve } from "node:path";
+import ts from "typescript";
+//#region ../contract-schema-compiler/src/index.ts
+const defaultCompilerOptions = {
+	module: ts.ModuleKind.ESNext,
+	moduleResolution: ts.ModuleResolutionKind.Bundler,
+	target: ts.ScriptTarget.ES2022,
+	strict: true,
+	skipLibCheck: true
+};
+async function compileContractSchemas(options) {
+	const packageRoot = resolve(options.packageRoot);
+	const sourceRoot = resolve(packageRoot, options.sourceRoot ?? "src");
+	const factName = options.contractFactName ?? "contract.json";
+	const checkOnly = options.checkOnly ?? false;
+	const facts = await findContractFacts(sourceRoot, factName, options.expectedKind);
+	if (facts.length === 0) throw new Error(`No ${factName} facts found under ${relative(packageRoot, sourceRoot)}`);
+	const sourcePaths = facts.flatMap((record) => [resolve(dirname(record.factPath), normalizeFactSource(record.fact.input.source)), resolve(dirname(record.factPath), normalizeFactSource(record.fact.output.source))]);
+	const program = ts.createProgram(sourcePaths, defaultCompilerOptions);
+	assertNoProgramDiagnostics(program);
+	const files = buildGeneratedFiles({
+		packageRoot,
+		sourceRoot,
+		facts,
+		program,
+		checker: program.getTypeChecker()
+	});
+	await reconcileGeneratedFiles({
+		packageRoot,
+		files,
+		obsoletePaths: await findObsoleteGeneratedPaths(sourceRoot, files),
+		checkOnly
+	});
+	return {
+		facts,
+		files,
+		checkOnly
+	};
+}
+async function findContractFacts(sourceRoot, factName, expectedKind) {
+	const records = [];
+	await walk(sourceRoot, async (path, name) => {
+		if (name !== factName) return;
+		const fact = parseContractFact(path, await readFile(path, "utf8"), expectedKind);
+		const directory = dirname(path);
+		const segments = relative(sourceRoot, directory).split(/[\\/]/).join("/").split("/").filter(Boolean);
+		records.push({
+			directory,
+			factPath: path,
+			category: segments[0] ?? "",
+			capabilityName: segments.at(-1) ?? "",
+			fact
+		});
+	});
+	return records.sort((left, right) => left.factPath.localeCompare(right.factPath));
+}
+async function walk(dir, visit) {
+	for (const entry of await readdir(dir, { withFileTypes: true })) {
+		const full = join(dir, entry.name);
+		if (entry.isDirectory()) await walk(full, visit);
+		else if (entry.isFile()) await visit(full, entry.name);
+	}
+}
+function parseContractFact(factPath, source, expectedKind) {
+	const fact = JSON.parse(source);
+	const kinds = typeof expectedKind === "string" ? [expectedKind] : expectedKind;
+	if (typeof fact.kind !== "string" || !fact.kind.trim()) throw new Error(`${factPath} must declare a non-empty kind`);
+	if (kinds && !kinds.includes(fact.kind)) throw new Error(`${factPath} kind must be one of ${kinds.join(", ")}, received ${fact.kind}`);
+	if (typeof fact.fqn !== "string" || !fact.fqn.trim()) throw new Error(`${factPath} must declare a non-empty fqn`);
+	for (const direction of ["input", "output"]) {
+		const side = fact[direction];
+		if (!side || typeof side.source !== "string" || typeof side.export !== "string" || typeof side.schemaId !== "string") throw new Error(`${factPath} requires ${direction}.source/export/schemaId`);
+		normalizeFactSource(side.source);
+	}
+	return fact;
+}
+function normalizeFactSource(value) {
+	if (!value.trim() || value.includes("\\") || value.startsWith("/") || value.split("/").includes("..")) throw new Error(`Contract source must be a safe relative path: ${value}`);
+	return value.replace(/^\.\//, "");
+}
+function assertNoProgramDiagnostics(program) {
+	const diagnostics = ts.getPreEmitDiagnostics(program);
+	if (diagnostics.length === 0) return;
+	const message = ts.formatDiagnosticsWithColorAndContext(diagnostics, {
+		getCanonicalFileName: (fileName) => fileName,
+		getCurrentDirectory: () => process.cwd(),
+		getNewLine: () => "\n"
+	});
+	throw new Error(`TypeScript contract program has diagnostics:\n${message}`);
+}
+function buildGeneratedFiles(input) {
+	const files = [];
+	for (const record of input.facts) {
+		const inputSchema = schemaForContractSide(input.program, input.checker, record, record.fact.input);
+		const outputSchema = schemaForContractSide(input.program, input.checker, record, record.fact.output);
+		files.push({
+			path: join(record.directory, "input.schema.generated.ts"),
+			content: schemaModule("inputSchema", inputSchema)
+		});
+		files.push({
+			path: join(record.directory, "output.schema.generated.ts"),
+			content: schemaModule("outputSchema", outputSchema)
+		});
+		files.push({
+			path: join(record.directory, "index.ts"),
+			content: capabilityIndex(record.fact)
+		});
+	}
+	const byCategory = /* @__PURE__ */ new Map();
+	for (const record of input.facts) {
+		const bucket = byCategory.get(record.category) ?? [];
+		bucket.push(record);
+		byCategory.set(record.category, bucket);
+	}
+	for (const [category, records] of [...byCategory.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+		if (!category) continue;
+		files.push({
+			path: join(input.sourceRoot, category, "schema-catalog.generated.ts"),
+			content: schemaCatalog(category, records, input.sourceRoot)
+		});
+	}
+	return files.sort((left, right) => left.path.localeCompare(right.path));
+}
+function schemaForContractSide(program, checker, record, side) {
+	const sourcePath = resolve(record.directory, normalizeFactSource(side.source));
+	const sourceFile = program.getSourceFile(sourcePath);
+	if (!sourceFile) throw new Error(`Unable to read contract source ${sourcePath}`);
+	const declaration = exportedType(sourceFile, side.export);
+	return {
+		$schema: "http://json-schema.org/draft-07/schema#",
+		$id: side.schemaId,
+		title: side.export,
+		...schemaForType(checker, checker.getTypeAtLocation(declaration), /* @__PURE__ */ new Set())
+	};
+}
+function exportedType(sourceFile, name) {
+	for (const statement of sourceFile.statements) if ((ts.isInterfaceDeclaration(statement) || ts.isTypeAliasDeclaration(statement)) && statement.name.text === name && statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword)) return statement;
+	throw new Error(`Exported TypeScript type ${name} not found in ${sourceFile.fileName}`);
+}
+function schemaForType(checker, type, seen) {
+	const primitive = primitiveSchema(checker, type);
+	if (primitive) return primitive;
+	if (seen.has(type)) return {};
+	if (checker.isTupleType(type)) {
+		const elements = checker.getTypeArguments(type);
+		return {
+			type: "array",
+			prefixItems: elements.map((element) => schemaForType(checker, element, seen)),
+			minItems: elements.length,
+			maxItems: elements.length
+		};
+	}
+	if (checker.isArrayType(type)) {
+		const element = checker.getTypeArguments(type)[0];
+		return {
+			type: "array",
+			items: element ? schemaForType(checker, element, seen) : {}
+		};
+	}
+	if (type.isUnion()) {
+		const schemas = type.types.filter((member) => !(member.flags & ts.TypeFlags.Undefined)).map((member) => schemaForType(checker, member, seen));
+		if (schemas.length === 1) return schemas[0] ?? {};
+		if (schemas.every((schema) => schema.type === "string" && typeof schema.const === "string")) return {
+			type: "string",
+			enum: schemas.map((schema) => schema.const)
+		};
+		return { anyOf: schemas };
+	}
+	if (type.isIntersection()) {
+		const schemas = type.types.map((member) => schemaForType(checker, member, seen));
+		const objectSchemas = schemas.filter((schema) => schema.type === "object");
+		if (objectSchemas.length === schemas.length) return mergeObjectSchemas(objectSchemas);
+		return { allOf: schemas };
+	}
+	if (type.flags & ts.TypeFlags.Object) {
+		seen.add(type);
+		const properties = {};
+		const required = [];
+		for (const property of checker.getPropertiesOfType(type)) {
+			const declaration = property.valueDeclaration ?? property.declarations?.[0];
+			if (!declaration) continue;
+			properties[property.name] = schemaForType(checker, checker.getTypeOfSymbolAtLocation(property, declaration), seen);
+			if (!(property.flags & ts.SymbolFlags.Optional)) required.push(property.name);
+		}
+		seen.delete(type);
+		const stringIndex = checker.getIndexInfoOfType(type, ts.IndexKind.String);
+		return {
+			type: "object",
+			additionalProperties: stringIndex ? schemaForType(checker, stringIndex.type, seen) : false,
+			...Object.keys(properties).length > 0 ? {
+				properties,
+				required
+			} : {}
+		};
+	}
+	return {};
+}
+function primitiveSchema(checker, type) {
+	if (type.flags & ts.TypeFlags.StringLiteral) return {
+		type: "string",
+		const: type.value
+	};
+	if (type.flags & ts.TypeFlags.NumberLiteral) return {
+		type: "number",
+		const: type.value
+	};
+	if (type.flags & ts.TypeFlags.BooleanLiteral) return {
+		type: "boolean",
+		const: checker.typeToString(type) === "true"
+	};
+	if (type.flags & ts.TypeFlags.StringLike) return { type: "string" };
+	if (type.flags & ts.TypeFlags.NumberLike) return { type: "number" };
+	if (type.flags & ts.TypeFlags.BooleanLike) return { type: "boolean" };
+	if (type.flags & ts.TypeFlags.Null) return { type: "null" };
+	if (type.flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown)) return {};
+}
+function mergeObjectSchemas(schemas) {
+	return {
+		type: "object",
+		additionalProperties: false,
+		properties: Object.assign({}, ...schemas.map((schema) => schema.properties)),
+		required: [...new Set(schemas.flatMap((schema) => Array.isArray(schema.required) ? schema.required : []))]
+	};
+}
+function schemaModule(exportName, schema) {
+	return [
+		"/* eslint-disable */",
+		"// This file is generated by contract facts. Do not edit by hand.",
+		"",
+		`export const ${exportName} = ${JSON.stringify(schema, null, 2)} as const`,
+		""
+	].join("\n");
+}
+function capabilityIndex(fact) {
+	return [
+		"/* eslint-disable */",
+		"// This file is generated by contract facts. Do not edit by hand.",
+		"",
+		`export type { ${fact.input.export} } from ${JSON.stringify(`./${stripTsExtension(normalizeFactSource(fact.input.source))}`)}`,
+		`export type { ${fact.output.export} } from ${JSON.stringify(`./${stripTsExtension(normalizeFactSource(fact.output.source))}`)}`,
+		"export { inputSchema } from \"./input.schema.generated\"",
+		"export { outputSchema } from \"./output.schema.generated\"",
+		""
+	].join("\n");
+}
+function schemaCatalog(category, records, sourceRoot) {
+	return [
+		"/* eslint-disable */",
+		"// This file is generated by contract facts. Do not edit by hand.",
+		"",
+		...records.map((record, index) => {
+			const dir = relative(join(sourceRoot, category), record.directory).split(/[\\/]/).join("/");
+			return `import { inputSchema as input${index}, outputSchema as output${index} } from ${JSON.stringify(`./${dir}`)}`;
+		}),
+		"",
+		`export const schemaCatalog = [${records.flatMap((_, index) => [`input${index}`, `output${index}`]).join(", ")}] as const`,
+		""
+	].join("\n");
+}
+function stripTsExtension(source) {
+	return source.replace(/\.ts$/, "");
+}
+async function findObsoleteGeneratedPaths(sourceRoot, expectedFiles) {
+	const expected = new Set(expectedFiles.map((file) => resolve(file.path)));
+	const obsolete = [];
+	await walk(sourceRoot, async (path, name) => {
+		if (name === "input.schema.generated.ts" || name === "output.schema.generated.ts" || name === "schema-catalog.generated.ts") {
+			if (!expected.has(resolve(path))) obsolete.push(path);
+			return;
+		}
+		if (name !== "index.ts" || expected.has(resolve(path))) return;
+		if ((await readFile(path, "utf8")).includes("This file is generated by contract facts. Do not edit by hand.")) obsolete.push(path);
+	});
+	return obsolete.sort();
+}
+async function reconcileGeneratedFiles(input) {
+	if (input.checkOnly) {
+		const stale = [];
+		for (const file of input.files) if (await readFile(file.path, "utf8").catch(() => void 0) !== file.content) stale.push(relative(input.packageRoot, file.path));
+		for (const obsoletePath of input.obsoletePaths) if (await readFile(obsoletePath, "utf8").then(() => true).catch(() => false)) stale.push(relative(input.packageRoot, obsoletePath));
+		if (stale.length > 0) throw new Error(`Generated contract schema files are stale:\n${stale.join("\n")}`);
+		return;
+	}
+	for (const file of input.files) {
+		await mkdir(dirname(file.path), { recursive: true });
+		await writeFile(file.path, file.content, "utf8");
+	}
+	await Promise.all(input.obsoletePaths.map((path) => rm(path, { force: true })));
+}
+const contractSchemaCompilerPackage = {
+	role: "framework",
+	area: "contract-schema-compiler",
+	owns: "TypeScript type-system driven contract schema projections"
+};
+//#endregion
+export { compileContractSchemas, contractSchemaCompilerPackage };