@pipelex/mthds-ui 0.23.0 → 0.25.0

package/dist/static-graph/index.d.ts

@@ -1,8 +1,8 @@
-import { C as ConceptInfo, P as PipeBlueprintUnion, a as PresenceMarker, b as GraphSpec, V as ValidationIssue } from '../types-Cn2FttBC.js';
+import { C as ConceptInfo, P as PipeBlueprintUnion, a as PresenceMarker, b as GraphSpec, V as ValidationIssue } from '../types-Bcsh7Z0U.js';
 export { P as ParsedPipeRef, m as makePipeRef, p as parsePipeRef } from '../pipeRefs-BQJO5nh5.js';
 
 type DiagnosticSeverity = "error" | "warning";
-type DiagnosticCode = "toml-parse-error" | "missing-domain" | "invalid-bundle-shape" | "invalid-concept-entry" | "invalid-pipe-entry" | "unknown-pipe-type" | "retired-signature-tag" | "invalid-concept-ref" | "missing-pipe-output" | "invalid-sub-pipe" | "incomplete-batch-spec" | "duplicate-concept" | "duplicate-pipe" | "signature-type-mismatch" | "unresolved-pipe-ref" | "cyclic-pipe-ref" | "missing-main-pipe" | "no-entry-pipe" | "conflicting-input-concept";
+type DiagnosticCode = "toml-parse-error" | "missing-domain" | "invalid-bundle-shape" | "invalid-concept-entry" | "invalid-pipe-entry" | "unknown-pipe-type" | "retired-signature-tag" | "invalid-concept-ref" | "unknown-input-slot-key" | "missing-pipe-output" | "invalid-sub-pipe" | "incomplete-batch-spec" | "duplicate-concept" | "duplicate-pipe" | "signature-type-mismatch" | "unresolved-pipe-ref" | "cyclic-pipe-ref" | "missing-main-pipe" | "no-entry-pipe" | "conflicting-input-concept";
 /**
  * A non-fatal note collected while parsing or merging. `error` means a whole
  * unit could not be interpreted (unparseable TOML, a skipped pipe); `warning`
@@ -85,6 +85,36 @@ interface ConceptRefParts {
 }
 /** Parse a concept ref string into its parts. Returns null when the ref is not interpretable. */
 declare function parseConceptRef(raw: unknown): ConceptRefParts | null;
+interface InputSlotParts {
+    /** The slot's concept ref parts, or null when the slot is not interpretable. */
+    ref: ConceptRefParts | null;
+    /**
+     * True when an expanded slot table declares no `concept` at all. The key is
+     * required, so there is no ref for a diagnostic to be about — the caller says
+     * the key is missing rather than blaming a ref the author never wrote.
+     */
+    missingConcept: boolean;
+    /** Keys of an expanded slot table this version of the standard does not define. */
+    unknownKeys: string[];
+    /**
+     * True when the table is not a slot table at all but the wreckage of an
+     * unquoted dotted input name — see {@link looksLikeUnquotedDottedName}.
+     */
+    dottedName: boolean;
+}
+/**
+ * Read one `inputs` value, whichever form authored it.
+ *
+ * `hints` is parsed as a known key and then dropped: intent hints are
+ * presentational, and the standard routes them to renderers through the
+ * input-form descriptor, not the GraphSpec (see `docs/static-graph.md`).
+ * Their shape is not checked here for the same reason — a malformed `hints`
+ * table is content this module never reads, so it is the validator's to
+ * report, not the renderer's. An unknown key is different: it may well be
+ * where a future standard puts something that changes the slot, so it is
+ * named rather than passed over.
+ */
+declare function parseInputSlot(raw: unknown): InputSlotParts;
 
 /**
  * Parse one `.mthds` TOML string. Returns whatever could be interpreted plus
@@ -134,4 +164,82 @@ declare function buildStaticGraphSpecFromToml(tomlTexts: string | string[], opti
  */
 declare function staticDiagnosticsToValidationIssues(diagnostics: Diagnostic[]): ValidationIssue[];
 
-export { type ConceptRefParts, type Diagnostic, type DiagnosticCode, type DiagnosticSeverity, type DomainNamespace, type MergedMethodSet, NATIVE_CONCEPT_CODES, NATIVE_DOMAIN, type ParseMthdsBundleResult, type ParsedBundle, type StaticGraphOptions, type StaticGraphResult, UNKNOWN_DOMAIN, buildStaticGraphSpec, buildStaticGraphSpecFromToml, mergeBundles, parseConceptRef, parseMthdsBundle, staticDiagnosticsToValidationIssues };
+/**
+ * One `.mthds` file of a method: the name it goes by and its TOML text. The
+ * same shape as an `mthds_sources[]` entry on the hosted API, so a host holding
+ * one can pass it straight through.
+ */
+interface MthdsSource {
+    /**
+     * File name, or a path ending in one. The whole string is the file's
+     * identity: a `preferred` file is matched against it exactly, and an embed
+     * lists each name once. Only the `bundle.mthds` tie-break reads the last
+     * segment alone.
+     */
+    name: string;
+    /** The file's `.mthds` TOML text. */
+    content: string;
+}
+/** The file name that breaks a tie when several files declare `main_pipe`. */
+declare const DEFAULT_BUNDLE_FILE_NAME = "bundle.mthds";
+/**
+ * Whether a file declares `main_pipe` at the top level, before its first table.
+ *
+ * A line scan rather than a TOML parse, on purpose: an editor asks this about
+ * a file the author is in the middle of writing, and a syntax error further
+ * down must not demote the file that plainly declares the entry point. The
+ * scan stops at the first table header, because a `main_pipe` key inside a
+ * table is not the bundle's.
+ */
+declare function hasTopLevelMainPipe(content: string): boolean;
+/**
+ * The file a method's graph is anchored on.
+ *
+ * `preferred` is the file the host is looking at, such as the one open in an
+ * editor; it leads whenever it declares `main_pipe` itself. Otherwise the file
+ * declaring a top-level `main_pipe` leads, `bundle.mthds` when several do and
+ * the first of them in the given order when none is named so. When no file
+ * declares one, `preferred` leads, or else the first file. Returns `undefined`
+ * only for an empty list.
+ *
+ * `preferred` is matched against `sources` by `name`, and the listed entry is
+ * what is read and returned, so a host may pass its own object for the open
+ * file rather than the list's: the result is always a member of `sources`,
+ * because the merge reads the list and not `preferred`. That is also why
+ * `preferred` is a plain `MthdsSource`: it cannot narrow the result's type and
+ * strip the fields a host's own list entries carry. A `preferred` whose
+ * name is not listed is ignored: it cannot lead a list it is not in, and the
+ * answer is then the one given no `preferred` at all.
+ */
+declare function selectPrimaryMthdsSource<T extends MthdsSource>(sources: readonly T[], preferred?: MthdsSource): T | undefined;
+/**
+ * The files in the order the static builder should merge them: the primary
+ * file (see {@link selectPrimaryMthdsSource}, which also says how `preferred`
+ * is matched) first, then the rest in the order given. The rest keep their
+ * order so a host that wants a deterministic merge only has to list its files
+ * deterministically. Returns a new array.
+ */
+declare function orderMthdsSources<T extends MthdsSource>(sources: readonly T[], preferred?: MthdsSource): T[];
+
+/** The id of the `<script type="application/json">` element carrying the files. */
+declare const MTHDS_SOURCES_EMBED_ID = "mthds-sources";
+/**
+ * The text a host places inside `<script type="application/json"
+ * id="mthds-sources">`: the files as a JSON array of `{ name, content }`,
+ * checked against the embed contract, with every `<` written as `\u003c`.
+ *
+ * The escape is what makes the text safe inside the element. `JSON.parse`
+ * reads it back as `<`, while the HTML parser never meets one, so no method
+ * text can end the element early, whichever spelling of `</script` it uses, or
+ * switch the element into the states a `<!--` opens. A prompt quoting a line of
+ * HTML is enough to need it. Neither `JSON.stringify` nor any platform API has
+ * an HTML-safe mode, which is why this function exists.
+ *
+ * Only `name` and `content` are written, whatever else a host's objects carry,
+ * and the files keep the order given, because the bundle puts them in merge
+ * order itself. Throws on a list the bundle would refuse, naming the entry at
+ * fault.
+ */
+declare function serializeMthdsSourcesEmbed(sources: readonly MthdsSource[]): string;
+
+export { type ConceptRefParts, DEFAULT_BUNDLE_FILE_NAME, type Diagnostic, type DiagnosticCode, type DiagnosticSeverity, type DomainNamespace, type InputSlotParts, MTHDS_SOURCES_EMBED_ID, type MergedMethodSet, type MthdsSource, NATIVE_CONCEPT_CODES, NATIVE_DOMAIN, type ParseMthdsBundleResult, type ParsedBundle, type StaticGraphOptions, type StaticGraphResult, UNKNOWN_DOMAIN, buildStaticGraphSpec, buildStaticGraphSpecFromToml, hasTopLevelMainPipe, mergeBundles, orderMthdsSources, parseConceptRef, parseInputSlot, parseMthdsBundle, selectPrimaryMthdsSource, serializeMthdsSourcesEmbed, staticDiagnosticsToValidationIssues };

package/dist/static-graph/index.js

@@ -4,7 +4,7 @@ import {
 } from "../chunk-2N65P32H.js";
 import {
   KNOWN_PIPE_TYPES
-} from "../chunk-RJVEDP7M.js";
+} from "../chunk-F3GBNU2I.js";
 import {
   __spreadProps,
   __spreadValues
@@ -17,6 +17,9 @@ function isPlainObject(value) {
   const proto = Object.getPrototypeOf(value);
   return proto === Object.prototype || proto === null;
 }
+function authoredRecord() {
+  return /* @__PURE__ */ Object.create(null);
+}
 function strOrNull(value) {
   return typeof value === "string" && value.length > 0 ? value : null;
 }
@@ -70,6 +73,32 @@ function parseConceptRef(raw) {
     presence: presenceFromSymbol(presence)
   };
 }
+var INPUT_SLOT_KEYS = /* @__PURE__ */ new Set(["concept", "hints"]);
+var CONCEPT_CODE_RE = /^[A-Z][A-Za-z0-9]*$/;
+function looksLikeUnquotedDottedName(raw, unknownKeys) {
+  if (raw.concept !== void 0 || unknownKeys.length === 0) return false;
+  return unknownKeys.every((key) => {
+    const parts = parseConceptRef(raw[key]);
+    return parts !== null && CONCEPT_CODE_RE.test(parts.code);
+  });
+}
+function parseInputSlot(raw) {
+  if (!isPlainObject(raw)) {
+    return {
+      ref: parseConceptRef(raw),
+      missingConcept: false,
+      unknownKeys: [],
+      dottedName: false
+    };
+  }
+  const unknownKeys = Object.keys(raw).filter((key) => !INPUT_SLOT_KEYS.has(key));
+  return {
+    ref: parseConceptRef(raw.concept),
+    missingConcept: raw.concept === void 0,
+    unknownKeys,
+    dottedName: looksLikeUnquotedDottedName(raw, unknownKeys)
+  };
+}
 function qualifiedStructureClassName(domain, code) {
   return `${domain.replaceAll(".", "\xB7")}__${code}`;
 }
@@ -98,22 +127,32 @@ function resolveConceptInfo(parts, currentDomain, localConcepts) {
   if (parts.domain !== null && parts.domain !== currentDomain) {
     return stubConceptInfo(parts.code, parts.domain);
   }
-  const local = localConcepts[parts.code];
-  if (local) return local;
+  if (Object.hasOwn(localConcepts, parts.code)) return localConcepts[parts.code];
   if (parts.domain === null && isNativeConceptCode(parts.code)) {
     return nativeConceptInfo(parts.code);
   }
   return stubConceptInfo(parts.code, currentDomain);
 }
-function resolveStuffSpec(raw, currentDomain, localConcepts) {
-  const parts = parseConceptRef(raw);
-  if (parts === null) return null;
+function stuffSpecFromParts(parts, currentDomain, localConcepts) {
   return {
     concept: resolveConceptInfo(parts, currentDomain, localConcepts),
     multiplicity: parts.multiplicity,
     presence: parts.presence
   };
 }
+function resolveStuffSpec(raw, currentDomain, localConcepts) {
+  const parts = parseConceptRef(raw);
+  return parts === null ? null : stuffSpecFromParts(parts, currentDomain, localConcepts);
+}
+function resolveInputSlot(raw, currentDomain, localConcepts) {
+  const { ref, missingConcept, unknownKeys, dottedName } = parseInputSlot(raw);
+  return {
+    spec: ref === null ? null : stuffSpecFromParts(ref, currentDomain, localConcepts),
+    missingConcept,
+    unknownKeys,
+    dottedName
+  };
+}
 
 // src/static-graph/parseMthdsBundle.ts
 import { parse as parseToml } from "smol-toml";
@@ -135,7 +174,7 @@ function stringArrayOrNull(value) {
   return value.filter((item) => typeof item === "string");
 }
 function normalizeInputs(raw, pipeCode, ctx) {
-  const inputs = {};
+  const inputs = authoredRecord();
   if (raw === void 0 || raw === null) return inputs;
   if (!isPlainObject(raw)) {
     ctx.diagnostics.push({
@@ -146,13 +185,34 @@ function normalizeInputs(raw, pipeCode, ctx) {
     });
     return inputs;
   }
-  for (const [name, ref] of Object.entries(raw)) {
-    const spec = resolveStuffSpec(ref, ctx.domain, ctx.concepts);
+  for (const [name, slot] of Object.entries(raw)) {
+    const { spec, missingConcept, unknownKeys, dottedName } = resolveInputSlot(
+      slot,
+      ctx.domain,
+      ctx.concepts
+    );
+    if (dottedName) {
+      ctx.diagnostics.push({
+        severity: "warning",
+        code: "invalid-concept-ref",
+        message: `pipe "${pipeCode}": input "${name}" reads as a slot table but looks like an unquoted dotted input name \u2014 write it as one quoted key ("${name}.${unknownKeys.join(".")}" = \u2026) \u2014 skipped`,
+        path: `pipe.${pipeCode}.inputs.${name}`
+      });
+      continue;
+    }
+    if (unknownKeys.length > 0) {
+      ctx.diagnostics.push({
+        severity: "warning",
+        code: "unknown-input-slot-key",
+        message: `pipe "${pipeCode}": input "${name}" declares ${unknownKeys.map((key) => `"${key}"`).join(", ")}, which the input slot form does not define \u2014 ignored here, and the runtime refuses the bundle`,
+        path: `pipe.${pipeCode}.inputs.${name}`
+      });
+    }
     if (spec === null) {
       ctx.diagnostics.push({
         severity: "warning",
         code: "invalid-concept-ref",
-        message: `pipe "${pipeCode}": input "${name}" has an uninterpretable concept ref \u2014 skipped`,
+        message: missingConcept ? `pipe "${pipeCode}": input "${name}" is a slot table with no "concept" \u2014 the key is required \u2014 skipped` : `pipe "${pipeCode}": input "${name}" has an uninterpretable concept ref \u2014 skipped`,
         path: `pipe.${pipeCode}.inputs.${name}`
       });
       continue;
@@ -514,7 +574,7 @@ function fieldSchema(spec) {
 }
 function deriveJsonSchema(structure, title, description) {
   if (!isPlainObject(structure)) return void 0;
-  const properties = {};
+  const properties = authoredRecord();
   const required = [];
   for (const [name, spec] of Object.entries(structure)) {
     if (typeof spec === "string") {
@@ -552,7 +612,7 @@ function qualifyRefines(raw, domain, declaredCodes, conceptCode, diagnostics) {
 }
 function parseConcepts(raw, domain, diagnostics) {
   var _a, _b;
-  const concepts = {};
+  const concepts = authoredRecord();
   if (raw === void 0) return concepts;
   if (!isPlainObject(raw)) {
     diagnostics.push({
@@ -603,8 +663,8 @@ function emptyBundle() {
     description: null,
     main_pipe: null,
     system_prompt: null,
-    concepts: {},
-    pipes: {}
+    concepts: authoredRecord(),
+    pipes: authoredRecord()
   };
 }
 function parseMthdsBundle(tomlText) {
@@ -675,7 +735,7 @@ function enrichPipeConcepts(pipe, domains) {
     const declared = (_a = domains[spec.concept.domain_code]) == null ? void 0 : _a.concepts[spec.concept.code];
     return declared !== void 0 && declared !== spec.concept ? __spreadProps(__spreadValues({}, spec), { concept: declared }) : spec;
   };
-  const inputs = {};
+  const inputs = authoredRecord();
   for (const [name, spec] of Object.entries(pipe.inputs)) {
     inputs[name] = enrichSpec(spec);
   }
@@ -684,13 +744,17 @@ function enrichPipeConcepts(pipe, domains) {
 function mergeBundles(bundles) {
   var _a, _b, _c;
   const diagnostics = [];
-  const domains = {};
+  const domains = authoredRecord();
   let mainDomain = null;
   let mainPipe = null;
   let description = null;
   for (const bundle of bundles) {
     const domain = (_a = bundle.domain) != null ? _a : UNKNOWN_DOMAIN;
-    const namespace = (_b = domains[domain]) != null ? _b : domains[domain] = { domain, concepts: {}, pipes: {} };
+    const namespace = (_b = domains[domain]) != null ? _b : domains[domain] = {
+      domain,
+      concepts: authoredRecord(),
+      pipes: authoredRecord()
+    };
     if (mainDomain === null && bundle.domain !== null) mainDomain = bundle.domain;
     if (mainPipe === null && bundle.main_pipe !== null) {
       mainPipe = bundle.main_pipe;
@@ -1361,17 +1425,90 @@ function staticDiagnosticsToValidationIssues(diagnostics) {
     origin: "static"
   }, targetFromPath(diagnostic.path, diagnostic.domain_code)));
 }
+
+// src/static-graph/sourceOrder.ts
+var DEFAULT_BUNDLE_FILE_NAME = "bundle.mthds";
+var MAIN_PIPE_LINE = /^\s*main_pipe\s*=\s*(["'])[^"']+\1\s*(?:#.*)?$/;
+var TABLE_HEADER_LINE = /^\s*\[/;
+function hasTopLevelMainPipe(content) {
+  for (const line of content.split(/\r\n|\r|\n/)) {
+    if (TABLE_HEADER_LINE.test(line)) return false;
+    if (MAIN_PIPE_LINE.test(line)) return true;
+  }
+  return false;
+}
+function isDefaultBundle(source) {
+  const baseName = source.name.replace(/^.*[\\/]/, "");
+  return baseName.toLowerCase() === DEFAULT_BUNDLE_FILE_NAME;
+}
+function selectPrimaryMthdsSource(sources, preferred) {
+  var _a, _b, _c;
+  const listed = preferred === void 0 ? void 0 : sources.find((source) => source.name === preferred.name);
+  if (listed !== void 0 && hasTopLevelMainPipe(listed.content)) return listed;
+  const withMainPipe = sources.filter((source) => hasTopLevelMainPipe(source.content));
+  return (_c = (_b = (_a = withMainPipe.find(isDefaultBundle)) != null ? _a : withMainPipe[0]) != null ? _b : listed) != null ? _c : sources[0];
+}
+function orderMthdsSources(sources, preferred) {
+  const primary = selectPrimaryMthdsSource(sources, preferred);
+  const index = primary === void 0 ? -1 : sources.indexOf(primary);
+  if (index <= 0) return [...sources];
+  return [sources[index], ...sources.slice(0, index), ...sources.slice(index + 1)];
+}
+
+// src/static-graph/mthdsSourcesEmbed.ts
+var MTHDS_SOURCES_EMBED_ID = "mthds-sources";
+function describeEntry(index) {
+  return `<script id="${MTHDS_SOURCES_EMBED_ID}"> entry ${index}`;
+}
+function parseMthdsSourcesEmbed(raw) {
+  if (!Array.isArray(raw)) {
+    throw new Error(
+      `<script id="${MTHDS_SOURCES_EMBED_ID}"> must hold a JSON array of { "name", "content" } objects, one per .mthds file.`
+    );
+  }
+  if (raw.length === 0) {
+    throw new Error(`<script id="${MTHDS_SOURCES_EMBED_ID}"> lists no .mthds file.`);
+  }
+  const seen = /* @__PURE__ */ new Set();
+  return raw.map((entry, index) => {
+    if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
+      throw new Error(`${describeEntry(index)} is not a { "name", "content" } object.`);
+    }
+    const { name, content } = entry;
+    if (typeof name !== "string" || name.trim() === "") {
+      throw new Error(`${describeEntry(index)} has no "name" string.`);
+    }
+    if (typeof content !== "string") {
+      throw new Error(`${describeEntry(index)} ("${name}") has no "content" string.`);
+    }
+    if (seen.has(name)) {
+      throw new Error(`${describeEntry(index)} repeats the name "${name}".`);
+    }
+    seen.add(name);
+    return { name, content };
+  });
+}
+function serializeMthdsSourcesEmbed(sources) {
+  return JSON.stringify(parseMthdsSourcesEmbed(sources)).replace(/</g, "\\u003c");
+}
 export {
+  DEFAULT_BUNDLE_FILE_NAME,
+  MTHDS_SOURCES_EMBED_ID,
   NATIVE_CONCEPT_CODES,
   NATIVE_DOMAIN,
   UNKNOWN_DOMAIN,
   buildStaticGraphSpec,
   buildStaticGraphSpecFromToml,
+  hasTopLevelMainPipe,
   makePipeRef,
   mergeBundles,
+  orderMthdsSources,
   parseConceptRef,
+  parseInputSlot,
   parseMthdsBundle,
   parsePipeRef,
+  selectPrimaryMthdsSource,
+  serializeMthdsSourcesEmbed,
   staticDiagnosticsToValidationIssues
 };
 //# sourceMappingURL=index.js.map