@pipelex/mthds-ui 0.12.0 → 0.13.0

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

@@ -0,0 +1,118 @@
+import { C as ConceptInfo, P as PipeBlueprintUnion, G as GraphSpec, V as ValidationIssue } from '../types-Cm4147S5.js';
+
+type DiagnosticSeverity = "error" | "warning";
+type DiagnosticCode = "toml-parse-error" | "missing-domain" | "invalid-bundle-shape" | "invalid-concept-entry" | "invalid-pipe-entry" | "unknown-pipe-type" | "invalid-concept-ref" | "missing-pipe-output" | "invalid-sub-pipe" | "incomplete-batch-spec" | "duplicate-concept" | "duplicate-pipe" | "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`
+ * means something was tolerated with a fallback (missing output, bad ref).
+ */
+interface Diagnostic {
+    severity: DiagnosticSeverity;
+    code: DiagnosticCode;
+    message: string;
+    /** TOML-style locator for the offending entry, e.g. `pipe.analyze_candidate.output`. */
+    path?: string;
+}
+/**
+ * One `.mthds` file, parsed and normalized. Pipes are narrowed to the same
+ * `PipeBlueprintUnion` shapes the pipelex runtime serializes into GraphSpec
+ * `pipe_registry`, and concepts to `ConceptInfo` — no parallel type universe.
+ * Field names mirror the TOML bundle header keys.
+ */
+interface ParsedBundle {
+    domain: string | null;
+    description: string | null;
+    main_pipe: string | null;
+    system_prompt: string | null;
+    /** Concepts declared in this bundle, keyed by bare concept code. */
+    concepts: Record<string, ConceptInfo>;
+    /** Pipes declared in this bundle, keyed by bare pipe code. */
+    pipes: Record<string, PipeBlueprintUnion>;
+}
+interface ParseMthdsBundleResult {
+    bundle: ParsedBundle;
+    diagnostics: Diagnostic[];
+}
+/** Namespace of one domain after merging bundles: concepts and pipes by bare code. */
+interface DomainNamespace {
+    domain: string;
+    concepts: Record<string, ConceptInfo>;
+    pipes: Record<string, PipeBlueprintUnion>;
+}
+/**
+ * The merged namespace of a method package: every parsed bundle grouped by
+ * domain, with duplicate codes resolved keep-first (plus a diagnostic).
+ * `mainDomain` / `mainPipe` come as a pair from the first bundle declaring
+ * `main_pipe` (falling back to the first domained bundle when none does) —
+ * the walk entry point for the static graph builder. `description` comes from
+ * the first bundle that declares it.
+ */
+interface MergedMethodSet {
+    domains: Record<string, DomainNamespace>;
+    mainDomain: string | null;
+    mainPipe: string | null;
+    description: string | null;
+    diagnostics: Diagnostic[];
+}
+/** Namespace used for bundles that declare no `domain` (a legal WIP state). */
+declare const UNKNOWN_DOMAIN = "unknown";
+
+declare const NATIVE_DOMAIN = "native";
+declare const NATIVE_CONCEPT_CODES: ReadonlySet<string>;
+interface ConceptRefParts {
+    /** Explicit domain qualifier (`recruitment` in `recruitment.Profile`), or null for bare refs. */
+    domain: string | null;
+    code: string;
+    /** `[]` → true (many), `[N]` → N, no suffix → null (single). */
+    multiplicity: number | boolean | null;
+}
+/** Parse a concept ref string into its parts. Returns null when the ref is not interpretable. */
+declare function parseConceptRef(raw: unknown): ConceptRefParts | null;
+
+/**
+ * Parse one `.mthds` TOML string. Returns whatever could be interpreted plus
+ * the diagnostics collected along the way — never throws.
+ */
+declare function parseMthdsBundle(tomlText: string): ParseMthdsBundleResult;
+
+/**
+ * Merge parsed bundles into one namespace per domain. Order matters: on
+ * duplicate codes the first bundle wins. `mainDomain` and `mainPipe` are taken
+ * together from the first bundle declaring `main_pipe`, so a bare entry ref
+ * always resolves in its declaring bundle's namespace; when no bundle declares
+ * one, `mainDomain` falls back to the first domained bundle. `description`
+ * comes from the first bundle that declares it.
+ */
+declare function mergeBundles(bundles: ParsedBundle[]): MergedMethodSet;
+
+interface StaticGraphOptions {
+    /**
+     * Pipe ref to walk from (`code` or `domain.code`). Defaults to the merged
+     * set's `main_pipe`, falling back to a root heuristic (first pipe no other
+     * pipe references) when none is declared.
+     */
+    entryPipe?: string;
+}
+interface StaticGraphResult {
+    spec: GraphSpec;
+    diagnostics: Diagnostic[];
+}
+/** Build a static GraphSpec from an already-parsed, merged method set. */
+declare function buildStaticGraphSpec(set: MergedMethodSet, options?: StaticGraphOptions): StaticGraphResult;
+/**
+ * Convenience wrapper: parse one or more `.mthds` TOML strings, merge them,
+ * and build the static GraphSpec. Diagnostics from all three stages are
+ * concatenated in order (parse, merge, build).
+ */
+declare function buildStaticGraphSpecFromToml(tomlTexts: string | string[], options?: StaticGraphOptions): StaticGraphResult;
+
+/**
+ * Project static-graph {@link Diagnostic}s onto the viewer's presentation shape
+ * so a host can feed them straight into `GraphViewer`'s `validationIssues`.
+ * The TOML-style `path` becomes the locator chip; `origin: "static"` lets the
+ * panel (and the host's issue policy) distinguish them from validator verdicts.
+ */
+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 };