@pipelex/mthds-ui 0.24.0 → 0.25.0

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

@@ -1,4 +1,4 @@
-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";
@@ -164,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 InputSlotParts, type MergedMethodSet, NATIVE_CONCEPT_CODES, NATIVE_DOMAIN, type ParseMthdsBundleResult, type ParsedBundle, type StaticGraphOptions, type StaticGraphResult, UNKNOWN_DOMAIN, buildStaticGraphSpec, buildStaticGraphSpecFromToml, mergeBundles, parseConceptRef, parseInputSlot, 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
@@ -1425,18 +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