@ryanstark24/sfgraph-core 1.1.0

package/dist/parsers/rules/_engine.ts

@@ -0,0 +1,171 @@
+import { createHash } from "node:crypto";
+import { XMLParser } from "fast-xml-parser";
+import {
+  type EdgeFact,
+  METADATA_CATEGORY,
+  type MetadataCategory,
+  type NodeFact,
+  type RelType,
+} from "../../domain/index.js";
+import { makeEdge, makeNode } from "../common.js";
+import type { ParseContext, ParseResult, Parser } from "../contract.js";
+import type { EdgeRule, NodeRule, Rule } from "./_schema.js";
+import { type EvalCtx, evaluatePredicate, evaluateRaw, evaluateString } from "./_selectors.js";
+
+const xmlParser = new XMLParser({ ignoreAttributes: false, attributeNamePrefix: "@_" });
+
+function sha256(s: string): string {
+  return createHash("sha256").update(s).digest("hex");
+}
+
+function toArr<T>(v: T | T[] | undefined | null): T[] {
+  if (v === undefined || v === null) return [];
+  return Array.isArray(v) ? v : [v];
+}
+
+export class RuleBasedParser implements Parser<unknown> {
+  constructor(private readonly rule: Rule) {}
+
+  get type(): string {
+    return this.rule.type;
+  }
+
+  get category(): MetadataCategory {
+    // The rule files use the same string constants as METADATA_CATEGORY values.
+    return this.rule.category as MetadataCategory;
+  }
+
+  async parse(input: unknown, ctx: ParseContext): Promise<ParseResult> {
+    const record = this.coerceInput(input);
+    const caps = (ctx as unknown as { caps?: Record<string, unknown> }).caps ?? {};
+    const evalCtx: EvalCtx = {
+      record,
+      item: null,
+      ns: ctx.namespace,
+      caps,
+    };
+
+    const nodes: NodeFact[] = [];
+    const edges: EdgeFact[] = [];
+    // Source hash derived from input string when available (parity with old parsers).
+    const sourceHashSeed = this.deriveSourceText(input);
+    const hashBase = sourceHashSeed ? sha256(sourceHashSeed) : "";
+
+    for (const n of this.rule.nodes) {
+      this.emitNode(n, evalCtx, ctx, hashBase, nodes);
+    }
+    for (const e of this.rule.edges) {
+      this.emitEdge(e, evalCtx, ctx, edges);
+    }
+
+    return { nodes, edges };
+  }
+
+  private emitNode(
+    n: NodeRule,
+    evalCtx: EvalCtx,
+    ctx: ParseContext,
+    hashBase: string,
+    out: NodeFact[],
+  ): void {
+    const items: unknown[] = n.iterate ? toArr(evaluateRaw(n.iterate, evalCtx)) : [null];
+    for (const item of items) {
+      const subCtx: EvalCtx = { ...evalCtx, item };
+      if (n.when && !evaluatePredicate(n.when, subCtx)) continue;
+      const qnameVal = evaluateString(n.qname, subCtx);
+      if (qnameVal === undefined || qnameVal === null || qnameVal === "") continue;
+      const qname = String(qnameVal);
+      const props = this.materializeProps(n.props, subCtx);
+      out.push(makeNode(ctx, n.label, qname, props, hashBase));
+    }
+  }
+
+  private emitEdge(e: EdgeRule, evalCtx: EvalCtx, ctx: ParseContext, out: EdgeFact[]): void {
+    const items: unknown[] = e.iterate ? toArr(evaluateRaw(e.iterate, evalCtx)) : [null];
+    for (const item of items) {
+      const subCtx: EvalCtx = { ...evalCtx, item };
+      if (e.when && !evaluatePredicate(e.when, subCtx)) continue;
+      const src = evaluateString(e.src, subCtx);
+      const dst = evaluateString(e.dst, subCtx);
+      if (!src || !dst) continue;
+      const props = this.materializeProps(e.props, subCtx);
+      // relType is a string union at runtime; rule authors must use canonical names.
+      out.push(makeEdge(ctx, String(src), e.relType as RelType, String(dst), props));
+    }
+  }
+
+  private materializeProps(
+    props: Record<string, unknown> | undefined,
+    evalCtx: EvalCtx,
+  ): Record<string, unknown> {
+    if (!props) return {};
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(props)) {
+      if (typeof v === "string") {
+        const evaluated = evaluateString(v, evalCtx);
+        out[k] = evaluated === undefined ? null : evaluated;
+      } else {
+        out[k] = v;
+      }
+    }
+    return out;
+  }
+
+  private coerceInput(input: unknown): unknown {
+    if (this.rule.input === "object") return input;
+    if (this.rule.input === "json") {
+      return typeof input === "string" ? JSON.parse(input) : input;
+    }
+    if (this.rule.input === "xml-string") {
+      // Inputs in this codebase pass `{ name, xml }` objects (or similar).
+      // Parse the xml field and merge any sibling keys into the record so
+      // they're addressable as ${record.<key>}.
+      const obj = input as Record<string, unknown> | null;
+      const xml = typeof obj?.xml === "string" ? (obj.xml as string) : "";
+      let parsed: unknown = {};
+      if (xml) parsed = xmlParser.parse(xml);
+      const rootKey = this.rule.root;
+      const root = rootKey ? ((parsed as Record<string, unknown>)?.[rootKey] ?? {}) : parsed;
+      const merged: Record<string, unknown> = {
+        ...(typeof root === "object" && root !== null ? (root as Record<string, unknown>) : {}),
+      };
+      // Promote sibling keys (name, object, body, etc.) into the record.
+      if (obj && typeof obj === "object") {
+        for (const [k, v] of Object.entries(obj)) {
+          if (k === "xml") continue;
+          merged[k] = v;
+        }
+      }
+      return merged;
+    }
+    return input;
+  }
+
+  private deriveSourceText(input: unknown): string {
+    if (typeof input === "string") return input;
+    if (input && typeof input === "object") {
+      const obj = input as Record<string, unknown>;
+      if (typeof obj.xml === "string") return obj.xml;
+      if (typeof obj.body === "string") return obj.body;
+    }
+    return "";
+  }
+}
+
+export function appliesTo(rule: Rule, caps: Record<string, unknown>): boolean {
+  return matchWhen(rule.applies_when, caps);
+}
+
+function matchWhen(w: unknown, caps: Record<string, unknown>): boolean {
+  if (!w || typeof w !== "object") return false;
+  const obj = w as Record<string, unknown>;
+  if ("always" in obj) return true;
+  if ("capability" in obj) return Boolean(caps[obj.capability as string]);
+  if ("not" in obj) return !matchWhen(obj.not, caps);
+  if ("any_of" in obj) return (obj.any_of as unknown[]).some((x) => matchWhen(x, caps));
+  if ("all_of" in obj) return (obj.all_of as unknown[]).every((x) => matchWhen(x, caps));
+  return false;
+}
+
+// Re-export METADATA_CATEGORY for rule author convenience (unused but stable).
+export { METADATA_CATEGORY };

package/dist/parsers/rules/_generic-opaque.d.ts

@@ -0,0 +1,13 @@
+import type { ParseContext, ParseResult, Parser } from "../contract.js";
+/**
+ * Fallback rule-style parser that emits one opaque NodeFact for any unknown type.
+ * Thin wrapper around the existing OpaqueNodeParser, exported so callers can
+ * locate the fallback alongside the rule engine.
+ */
+export declare class GenericOpaqueParser implements Parser<unknown> {
+    private readonly inner;
+    readonly category: "OpaqueMetadata";
+    readonly type = "OpaqueMetadata";
+    parse(input: unknown, ctx: ParseContext): Promise<ParseResult>;
+}
+//# sourceMappingURL=_generic-opaque.d.ts.map

package/dist/parsers/rules/_generic-opaque.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_generic-opaque.d.ts","sourceRoot":"","sources":["../../../src/parsers/rules/_generic-opaque.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAGxE;;;;GAIG;AACH,qBAAa,mBAAoB,YAAW,MAAM,CAAC,OAAO,CAAC;IACzD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA0B;IAChD,QAAQ,CAAC,QAAQ,mBAAuB;IACxC,QAAQ,CAAC,IAAI,oBAAoB;IACjC,KAAK,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC;CAG/D"}

package/dist/parsers/rules/_generic-opaque.js

@@ -0,0 +1,15 @@
+import { OpaqueNodeParser } from "../generic/opaque-node-parser.js";
+/**
+ * Fallback rule-style parser that emits one opaque NodeFact for any unknown type.
+ * Thin wrapper around the existing OpaqueNodeParser, exported so callers can
+ * locate the fallback alongside the rule engine.
+ */
+export class GenericOpaqueParser {
+    inner = new OpaqueNodeParser();
+    category = this.inner.category;
+    type = "OpaqueMetadata";
+    parse(input, ctx) {
+        return this.inner.parse(input, ctx);
+    }
+}
+//# sourceMappingURL=_generic-opaque.js.map

package/dist/parsers/rules/_generic-opaque.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_generic-opaque.js","sourceRoot":"","sources":["../../../src/parsers/rules/_generic-opaque.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AAEpE;;;;GAIG;AACH,MAAM,OAAO,mBAAmB;IACb,KAAK,GAAG,IAAI,gBAAgB,EAAE,CAAC;IACvC,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC;IAC/B,IAAI,GAAG,gBAAgB,CAAC;IACjC,KAAK,CAAC,KAAc,EAAE,GAAiB;QACrC,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,KAA4D,EAAE,GAAG,CAAC,CAAC;IAC7F,CAAC;CACF"}

package/dist/parsers/rules/_generic-opaque.ts

@@ -0,0 +1,16 @@
+import type { ParseContext, ParseResult, Parser } from "../contract.js";
+import { OpaqueNodeParser } from "../generic/opaque-node-parser.js";
+
+/**
+ * Fallback rule-style parser that emits one opaque NodeFact for any unknown type.
+ * Thin wrapper around the existing OpaqueNodeParser, exported so callers can
+ * locate the fallback alongside the rule engine.
+ */
+export class GenericOpaqueParser implements Parser<unknown> {
+  private readonly inner = new OpaqueNodeParser();
+  readonly category = this.inner.category;
+  readonly type = "OpaqueMetadata";
+  parse(input: unknown, ctx: ParseContext): Promise<ParseResult> {
+    return this.inner.parse(input as { metadataType: string; name: string; raw: string }, ctx);
+  }
+}

package/dist/parsers/rules/_loader.d.ts

@@ -0,0 +1,17 @@
+import { RuleBasedParser } from "./_engine.js";
+export interface LoadResult {
+    loaded: string[];
+    parsers: RuleBasedParser[];
+}
+/**
+ * Load all rule YAML files from the given directory (defaults to this module's dir)
+ * and register each with the parser registry.
+ *
+ * Files prefixed with `_` are treated as engine internals and skipped.
+ */
+export declare function loadAllRules(opts?: {
+    dir?: string;
+    /** When true, do not register globally — return parsers only. */
+    skipRegister?: boolean;
+}): Promise<LoadResult>;
+//# sourceMappingURL=_loader.d.ts.map

package/dist/parsers/rules/_loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_loader.d.ts","sourceRoot":"","sources":["../../../src/parsers/rules/_loader.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAG/C,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,OAAO,EAAE,eAAe,EAAE,CAAC;CAC5B;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,IAAI,CAAC,EAAE;IACxC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB,GAAG,OAAO,CAAC,UAAU,CAAC,CAyCtB"}

package/dist/parsers/rules/_loader.js

@@ -0,0 +1,58 @@
+import { readFile, readdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parse as parseYaml } from "yaml";
+import { parserRegistry } from "../registry.js";
+import { RuleBasedParser } from "./_engine.js";
+import { RuleSchema } from "./_schema.js";
+/**
+ * Load all rule YAML files from the given directory (defaults to this module's dir)
+ * and register each with the parser registry.
+ *
+ * Files prefixed with `_` are treated as engine internals and skipped.
+ */
+export async function loadAllRules(opts) {
+    const here = opts?.dir ?? dirname(fileURLToPath(import.meta.url));
+    const entries = await readdir(here, { withFileTypes: true }).catch(() => []);
+    const loaded = [];
+    const parsers = [];
+    const seenTypes = new Map();
+    for (const ent of entries) {
+        if (!ent.isFile())
+            continue;
+        if (!ent.name.endsWith(".yml") && !ent.name.endsWith(".yaml"))
+            continue;
+        if (ent.name.startsWith("_"))
+            continue;
+        const fp = join(here, ent.name);
+        const text = await readFile(fp, "utf8");
+        let raw;
+        try {
+            raw = parseYaml(text);
+        }
+        catch (err) {
+            throw new Error(`Invalid YAML in rule file ${ent.name}: ${err.message}`);
+        }
+        const parsed = RuleSchema.safeParse(raw);
+        if (!parsed.success) {
+            throw new Error(`Invalid rule file ${ent.name}: ${parsed.error.message}`);
+        }
+        const rule = parsed.data;
+        const prior = seenTypes.get(rule.type);
+        if (prior) {
+            throw new Error(`Duplicate parser type "${rule.type}" in ${ent.name} (already registered by ${prior})`);
+        }
+        seenTypes.set(rule.type, ent.name);
+        const parser = new RuleBasedParser(rule);
+        if (!opts?.skipRegister) {
+            // Tolerate already-registered (idempotent re-load in tests).
+            if (!parserRegistry.for(rule.type)) {
+                parserRegistry.register(parser);
+            }
+        }
+        loaded.push(ent.name);
+        parsers.push(parser);
+    }
+    return { loaded, parsers };
+}
+//# sourceMappingURL=_loader.js.map

package/dist/parsers/rules/_loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_loader.js","sourceRoot":"","sources":["../../../src/parsers/rules/_loader.ts"],"names":[],"mappings":"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"}

package/dist/parsers/rules/_loader.ts

@@ -0,0 +1,65 @@
+import { readFile, readdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parse as parseYaml } from "yaml";
+import { parserRegistry } from "../registry.js";
+import { RuleBasedParser } from "./_engine.js";
+import { type Rule, RuleSchema } from "./_schema.js";
+
+export interface LoadResult {
+  loaded: string[];
+  parsers: RuleBasedParser[];
+}
+
+/**
+ * Load all rule YAML files from the given directory (defaults to this module's dir)
+ * and register each with the parser registry.
+ *
+ * Files prefixed with `_` are treated as engine internals and skipped.
+ */
+export async function loadAllRules(opts?: {
+  dir?: string;
+  /** When true, do not register globally — return parsers only. */
+  skipRegister?: boolean;
+}): Promise<LoadResult> {
+  const here = opts?.dir ?? dirname(fileURLToPath(import.meta.url));
+  const entries = await readdir(here, { withFileTypes: true }).catch(() => []);
+  const loaded: string[] = [];
+  const parsers: RuleBasedParser[] = [];
+  const seenTypes = new Map<string, string>();
+  for (const ent of entries) {
+    if (!ent.isFile()) continue;
+    if (!ent.name.endsWith(".yml") && !ent.name.endsWith(".yaml")) continue;
+    if (ent.name.startsWith("_")) continue;
+    const fp = join(here, ent.name);
+    const text = await readFile(fp, "utf8");
+    let raw: unknown;
+    try {
+      raw = parseYaml(text);
+    } catch (err) {
+      throw new Error(`Invalid YAML in rule file ${ent.name}: ${(err as Error).message}`);
+    }
+    const parsed = RuleSchema.safeParse(raw);
+    if (!parsed.success) {
+      throw new Error(`Invalid rule file ${ent.name}: ${parsed.error.message}`);
+    }
+    const rule: Rule = parsed.data;
+    const prior = seenTypes.get(rule.type);
+    if (prior) {
+      throw new Error(
+        `Duplicate parser type "${rule.type}" in ${ent.name} (already registered by ${prior})`,
+      );
+    }
+    seenTypes.set(rule.type, ent.name);
+    const parser = new RuleBasedParser(rule);
+    if (!opts?.skipRegister) {
+      // Tolerate already-registered (idempotent re-load in tests).
+      if (!parserRegistry.for(rule.type)) {
+        parserRegistry.register(parser);
+      }
+    }
+    loaded.push(ent.name);
+    parsers.push(parser);
+  }
+  return { loaded, parsers };
+}

package/dist/parsers/rules/_schema.d.ts

@@ -0,0 +1,143 @@
+import { z } from "zod";
+export declare const WhenSchema: z.ZodType<unknown>;
+declare const NodeRuleSchema: z.ZodObject<{
+    label: z.ZodString;
+    qname: z.ZodString;
+    props: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodBoolean, z.ZodNumber, z.ZodNull]>>>;
+    /** When set, repeats the node per element of the iterated array. */
+    iterate: z.ZodOptional<z.ZodString>;
+    /** Conditional emit; evaluated against ctx (item bound when iterating). */
+    when: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    label: string;
+    qname: string;
+    props?: Record<string, string | number | boolean | null> | undefined;
+    iterate?: string | undefined;
+    when?: string | undefined;
+}, {
+    label: string;
+    qname: string;
+    props?: Record<string, string | number | boolean | null> | undefined;
+    iterate?: string | undefined;
+    when?: string | undefined;
+}>;
+declare const EdgeRuleSchema: z.ZodObject<{
+    relType: z.ZodString;
+    iterate: z.ZodOptional<z.ZodString>;
+    when: z.ZodOptional<z.ZodString>;
+    src: z.ZodString;
+    dst: z.ZodString;
+    props: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodBoolean, z.ZodNumber, z.ZodNull]>>>;
+}, "strict", z.ZodTypeAny, {
+    relType: string;
+    src: string;
+    dst: string;
+    props?: Record<string, string | number | boolean | null> | undefined;
+    iterate?: string | undefined;
+    when?: string | undefined;
+}, {
+    relType: string;
+    src: string;
+    dst: string;
+    props?: Record<string, string | number | boolean | null> | undefined;
+    iterate?: string | undefined;
+    when?: string | undefined;
+}>;
+export declare const RuleSchema: z.ZodObject<{
+    type: z.ZodString;
+    category: z.ZodString;
+    input: z.ZodEnum<["object", "json", "xml-string"]>;
+    /** Optional dot-path to the root element after XML parsing (e.g. "Profile"). */
+    root: z.ZodOptional<z.ZodString>;
+    applies_when: z.ZodDefault<z.ZodType<unknown, z.ZodTypeDef, unknown>>;
+    nodes: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        qname: z.ZodString;
+        props: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodBoolean, z.ZodNumber, z.ZodNull]>>>;
+        /** When set, repeats the node per element of the iterated array. */
+        iterate: z.ZodOptional<z.ZodString>;
+        /** Conditional emit; evaluated against ctx (item bound when iterating). */
+        when: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        label: string;
+        qname: string;
+        props?: Record<string, string | number | boolean | null> | undefined;
+        iterate?: string | undefined;
+        when?: string | undefined;
+    }, {
+        label: string;
+        qname: string;
+        props?: Record<string, string | number | boolean | null> | undefined;
+        iterate?: string | undefined;
+        when?: string | undefined;
+    }>, "many">>;
+    edges: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        relType: z.ZodString;
+        iterate: z.ZodOptional<z.ZodString>;
+        when: z.ZodOptional<z.ZodString>;
+        src: z.ZodString;
+        dst: z.ZodString;
+        props: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodBoolean, z.ZodNumber, z.ZodNull]>>>;
+    }, "strict", z.ZodTypeAny, {
+        relType: string;
+        src: string;
+        dst: string;
+        props?: Record<string, string | number | boolean | null> | undefined;
+        iterate?: string | undefined;
+        when?: string | undefined;
+    }, {
+        relType: string;
+        src: string;
+        dst: string;
+        props?: Record<string, string | number | boolean | null> | undefined;
+        iterate?: string | undefined;
+        when?: string | undefined;
+    }>, "many">>;
+}, "strict", z.ZodTypeAny, {
+    category: string;
+    type: string;
+    nodes: {
+        label: string;
+        qname: string;
+        props?: Record<string, string | number | boolean | null> | undefined;
+        iterate?: string | undefined;
+        when?: string | undefined;
+    }[];
+    edges: {
+        relType: string;
+        src: string;
+        dst: string;
+        props?: Record<string, string | number | boolean | null> | undefined;
+        iterate?: string | undefined;
+        when?: string | undefined;
+    }[];
+    input: "object" | "json" | "xml-string";
+    root?: string | undefined;
+    applies_when?: unknown;
+}, {
+    category: string;
+    type: string;
+    input: "object" | "json" | "xml-string";
+    nodes?: {
+        label: string;
+        qname: string;
+        props?: Record<string, string | number | boolean | null> | undefined;
+        iterate?: string | undefined;
+        when?: string | undefined;
+    }[] | undefined;
+    edges?: {
+        relType: string;
+        src: string;
+        dst: string;
+        props?: Record<string, string | number | boolean | null> | undefined;
+        iterate?: string | undefined;
+        when?: string | undefined;
+    }[] | undefined;
+    root?: string | undefined;
+    applies_when?: unknown;
+}>;
+export type Rule = z.infer<typeof RuleSchema>;
+export type NodeRule = z.infer<typeof NodeRuleSchema>;
+export type EdgeRule = z.infer<typeof EdgeRuleSchema>;
+export {};
+//# sourceMappingURL=_schema.d.ts.map

package/dist/parsers/rules/_schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_schema.d.ts","sourceRoot":"","sources":["../../../src/parsers/rules/_schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,eAAO,MAAM,UAAU,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAQzC,CAAC;AAIF,QAAA,MAAM,cAAc;;;;IAKhB,oEAAoE;;IAEpE,2EAA2E;;;;;;;;;;;;;;EAGpE,CAAC;AAEZ,QAAA,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;EAST,CAAC;AAEZ,eAAO,MAAM,UAAU;;;;IAKnB,gFAAgF;;;;;;;QAvBhF,oEAAoE;;QAEpE,2EAA2E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA2BpE,CAAC;AAEZ,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAC9C,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AACtD,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC"}

package/dist/parsers/rules/_schema.js

@@ -0,0 +1,44 @@
+import { z } from "zod";
+// Recursive `applies_when` predicate.
+export const WhenSchema = z.lazy(() => z.union([
+    z.object({ always: z.literal(true) }).strict(),
+    z.object({ capability: z.string() }).strict(),
+    z.object({ not: WhenSchema }).strict(),
+    z.object({ any_of: z.array(WhenSchema) }).strict(),
+    z.object({ all_of: z.array(WhenSchema) }).strict(),
+]));
+const PropValueSchema = z.union([z.string(), z.boolean(), z.number(), z.null()]);
+const NodeRuleSchema = z
+    .object({
+    label: z.string(),
+    qname: z.string(),
+    props: z.record(PropValueSchema).optional(),
+    /** When set, repeats the node per element of the iterated array. */
+    iterate: z.string().optional(),
+    /** Conditional emit; evaluated against ctx (item bound when iterating). */
+    when: z.string().optional(),
+})
+    .strict();
+const EdgeRuleSchema = z
+    .object({
+    relType: z.string(),
+    iterate: z.string().optional(),
+    when: z.string().optional(),
+    src: z.string(),
+    dst: z.string(),
+    props: z.record(PropValueSchema).optional(),
+})
+    .strict();
+export const RuleSchema = z
+    .object({
+    type: z.string(),
+    category: z.string(),
+    input: z.enum(["object", "json", "xml-string"]),
+    /** Optional dot-path to the root element after XML parsing (e.g. "Profile"). */
+    root: z.string().optional(),
+    applies_when: WhenSchema.default({ always: true }),
+    nodes: z.array(NodeRuleSchema).default([]),
+    edges: z.array(EdgeRuleSchema).default([]),
+})
+    .strict();
+//# sourceMappingURL=_schema.js.map

package/dist/parsers/rules/_schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_schema.js","sourceRoot":"","sources":["../../../src/parsers/rules/_schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,sCAAsC;AACtC,MAAM,CAAC,MAAM,UAAU,GAAuB,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CACxD,CAAC,CAAC,KAAK,CAAC;IACN,CAAC,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE;IAC9C,CAAC,CAAC,MAAM,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;IAC7C,CAAC,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;IACtC,CAAC,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE;IAClD,CAAC,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE;CACnD,CAAC,CACH,CAAC;AAEF,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;AAEjF,MAAM,cAAc,GAAG,CAAC;KACrB,MAAM,CAAC;IACN,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC,QAAQ,EAAE;IAC3C,oEAAoE;IACpE,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC9B,2EAA2E;IAC3E,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC5B,CAAC;KACD,MAAM,EAAE,CAAC;AAEZ,MAAM,cAAc,GAAG,CAAC;KACrB,MAAM,CAAC;IACN,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC9B,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC3B,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE;IACf,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE;IACf,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC,QAAQ,EAAE;CAC5C,CAAC;KACD,MAAM,EAAE,CAAC;AAEZ,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC;KACxB,MAAM,CAAC;IACN,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,CAAC,CAAC;IAC/C,gFAAgF;IAChF,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC3B,YAAY,EAAE,UAAU,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;IAClD,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;IAC1C,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;CAC3C,CAAC;KACD,MAAM,EAAE,CAAC"}

package/dist/parsers/rules/_schema.ts

@@ -0,0 +1,54 @@
+import { z } from "zod";
+
+// Recursive `applies_when` predicate.
+export const WhenSchema: z.ZodType<unknown> = z.lazy(() =>
+  z.union([
+    z.object({ always: z.literal(true) }).strict(),
+    z.object({ capability: z.string() }).strict(),
+    z.object({ not: WhenSchema }).strict(),
+    z.object({ any_of: z.array(WhenSchema) }).strict(),
+    z.object({ all_of: z.array(WhenSchema) }).strict(),
+  ]),
+);
+
+const PropValueSchema = z.union([z.string(), z.boolean(), z.number(), z.null()]);
+
+const NodeRuleSchema = z
+  .object({
+    label: z.string(),
+    qname: z.string(),
+    props: z.record(PropValueSchema).optional(),
+    /** When set, repeats the node per element of the iterated array. */
+    iterate: z.string().optional(),
+    /** Conditional emit; evaluated against ctx (item bound when iterating). */
+    when: z.string().optional(),
+  })
+  .strict();
+
+const EdgeRuleSchema = z
+  .object({
+    relType: z.string(),
+    iterate: z.string().optional(),
+    when: z.string().optional(),
+    src: z.string(),
+    dst: z.string(),
+    props: z.record(PropValueSchema).optional(),
+  })
+  .strict();
+
+export const RuleSchema = z
+  .object({
+    type: z.string(),
+    category: z.string(),
+    input: z.enum(["object", "json", "xml-string"]),
+    /** Optional dot-path to the root element after XML parsing (e.g. "Profile"). */
+    root: z.string().optional(),
+    applies_when: WhenSchema.default({ always: true }),
+    nodes: z.array(NodeRuleSchema).default([]),
+    edges: z.array(EdgeRuleSchema).default([]),
+  })
+  .strict();
+
+export type Rule = z.infer<typeof RuleSchema>;
+export type NodeRule = z.infer<typeof NodeRuleSchema>;
+export type EdgeRule = z.infer<typeof EdgeRuleSchema>;

package/dist/parsers/rules/_selectors.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Tiny selector evaluator for rule files.
+ *
+ * Supports:
+ *   ${path.to.field}                  — interpolation, namespace-stripped if ns is set
+ *   ${path.to.field | raw}            — interpolation without namespace strip
+ *   ${path.to.field || other.field}   — OR fallback
+ *   ${a == 'foo'} / ${a != 'foo'}     — equality with string literal
+ *   ${!a}                              — negation
+ *   ${stripNs(record.x)}               — explicit stripNs helper
+ *   ${split(record.x,'-')[0]}          — split + index helper
+ *
+ * Context binds:
+ *   record  — parsed input object
+ *   item    — current iteration element (or null)
+ *   ns      — namespace string or null
+ *   caps    — capability bag
+ *
+ * Undefined-safe: missing fields evaluate to '' in interpolations, false in conditionals.
+ * Pure non-string primitives flow through (so a boolean prop value stays boolean).
+ */
+export interface EvalCtx {
+    record: unknown;
+    item: unknown;
+    ns: string | null;
+    caps: Record<string, unknown>;
+}
+/** Evaluate a template string like "Profile:${record.fullName}".
+ * Returns a string when the template has any literal chars or multiple refs.
+ * Returns the raw underlying value when the template is a single bare `${...}`
+ * (so booleans / numbers / null flow through unmodified). */
+export declare function evaluateString(template: string, ctx: EvalCtx): unknown;
+/** Evaluate a predicate (boolean) expression. Used for `when`. */
+export declare function evaluatePredicate(expr: string, ctx: EvalCtx): boolean;
+/** Evaluate an expression, returning the raw value (for `iterate`). */
+export declare function evaluateRaw(expr: string, ctx: EvalCtx): unknown;
+//# sourceMappingURL=_selectors.d.ts.map