@graphrefly/graphrefly 0.44.0 → 0.46.0

package/dist/{index-CS0LTlB8.d.cts → utils/graphspec/index.d.ts}

@@ -1,7 +1,7 @@
-import { D as DescribeNodeOutput } from './sugar-DQjFmVqb.cjs';
-import { N as Node } from './node-kK3CvTrR.cjs';
-import { G as Graph, b as GraphDescribeOutput } from './graph-CWvEUQAq.cjs';
-import { L as LLMAdapter } from './types-C0_yquda.cjs';
+import { Node, DescribeNodeOutput } from '@graphrefly/pure-ts/core';
+import { Graph, GraphDescribeOutput } from '@graphrefly/pure-ts/graph';
+import { L as LLMAdapter } from '../../types-BB5Lw-pB.js';
+import '@graphrefly/pure-ts/extra';
 
 /**
  * LLM graph composition (roadmap §8.3).
@@ -145,7 +145,7 @@ type CatalogSourceEntry = {
  *
  * Tier 1.5.3 Phase 2.5 (DG1=B, 2026-04-27).
  */
-type GraphFactory = (factoryArgs: unknown) => Graph;
+type GraphSpecFactory = (factoryArgs: unknown) => Graph;
 /**
  * Fn/source lookup table passed to compileSpec and llmCompose.
  *
@@ -160,7 +160,7 @@ type GraphFactory = (factoryArgs: unknown) => Graph;
 type GraphSpecCatalog = {
     fns?: Record<string, FnFactory | CatalogFnEntry>;
     sources?: Record<string, SourceFactory | CatalogSourceEntry>;
-    graphFactories?: Record<string, GraphFactory>;
+    graphFactories?: Record<string, GraphSpecFactory>;
 };
 /** Type guard: is this a rich catalog fn entry (vs bare factory)? */
 declare function isRichFnEntry(entry: FnFactory | CatalogFnEntry): entry is CatalogFnEntry;
@@ -212,6 +212,104 @@ type GraphSpecValidation = {
  * (counter at 0 forever) without it.
  */
 declare function validateSpec(spec: unknown): GraphSpecValidation;
+/**
+ * The change-set fed to {@link validateOwnership}. Mirrors the minimal slice
+ * of a PR diff the lint needs: the set of factory identifiers whose
+ * implementation the diff touches, plus the PR author and (optionally) the
+ * raw commit-message text so the `Override-Owner:` trailer can be detected.
+ *
+ * **Why factory-keyed (not path-keyed) — locked decision (DS-14.5.A Q5
+ * sub-flag).** PR-diff → spec-node mapping resolves through `meta.factory`
+ * provenance, NOT a `meta.ownerPath` glob. A diff that edits the
+ * implementation of factory `"rateLimiter"` maps to *every* spec node whose
+ * `meta.factory === "rateLimiter"`. This reuses the existing
+ * `factoryTag` / `decompileSpec` round-trip (the same `meta.factory` field
+ * `compileSpec` consumes) — no parallel ownership-path indexing scheme.
+ */
+type OwnershipPrDiff = {
+    /**
+     * Factory identifiers (the `meta.factory` value) whose source the PR
+     * modifies. A spec node is "edited by this PR" iff its `meta.factory` is
+     * in this set. Nodes without `meta.factory` cannot be mapped from a code
+     * diff and are therefore never flagged (silent — consistent with the
+     * un-annotated rule).
+     */
+    readonly editedFactories: readonly string[];
+    /** PR author's `Actor.id`. Compared against each edited node's `meta.owner`. */
+    readonly author: string;
+    /**
+     * Raw commit message(s) text. If any line is an `Override-Owner: <reason>`
+     * trailer (case-insensitive key, non-empty reason) the lint hard-fail is
+     * bypassed and recorded as an audit-trail override (Q5 sub-lock i — any
+     * committer may use it; it is recorded, never silently granted).
+     */
+    readonly commitMessage?: string;
+};
+/** One cross-owner violation surfaced by {@link validateOwnership}. */
+type OwnershipViolation = {
+    /** Spec node path that carries `meta.owner` and was edited by a non-owner. */
+    readonly node: string;
+    /** The `meta.owner` value on that node. */
+    readonly owner: string;
+    /** The PR author who edited it. */
+    readonly author: string;
+    /** The `meta.factory` that mapped the diff onto this node. */
+    readonly factory: string;
+};
+/** Result of {@link validateOwnership}. */
+type OwnershipValidation = {
+    /**
+     * `true` when no hard-fail applies — either no cross-owner edit, or every
+     * cross-owner edit is bypassed by a valid `Override-Owner:` trailer.
+     */
+    readonly ok: boolean;
+    /** Cross-owner edits that hard-fail (empty when `ok`). */
+    readonly violations: readonly OwnershipViolation[];
+    /**
+     * Cross-owner edits that WOULD have failed but were bypassed by an
+     * `Override-Owner:` commit trailer. Pure audit trail — CI / reviewers
+     * grep this to surface override abuse. Present (possibly empty) so callers
+     * can read `.overridden.length` without a null check.
+     */
+    readonly overridden: readonly OwnershipViolation[];
+    /**
+     * The override reason parsed from the `Override-Owner:` trailer, when one
+     * was present and applied. `undefined` when no trailer was used.
+     */
+    readonly overrideReason?: string;
+};
+/**
+ * Multi-agent subgraph ownership PR lint (DS-14.5.A delta #5, L0 rung;
+ * spec §2.3a INV-OWNER-2).
+ *
+ * Hard-fails a pull request whose code diff edits a spec node carrying
+ * `meta.owner` when the PR author is not that owner. Nodes **without**
+ * `meta.owner` are silent (no advisory, no failure) — "shared infrastructure"
+ * is exactly the un-annotated case; no separate allow-list is maintained.
+ *
+ * **Rules (Q5 lock):**
+ * - Edited node has no `meta.owner` → silent.
+ * - Edited node has `meta.owner` AND `author === meta.owner` → OK.
+ * - Edited node has `meta.owner` AND `author !== meta.owner` → **violation**
+ *   (hard-fail) unless an `Override-Owner: <reason>` commit trailer is present,
+ *   in which case the violation is moved to `overridden` (audit trail) and
+ *   `ok` stays `true`.
+ *
+ * **PR-diff → spec-node mapping (Q5 sub-flag lock):** `meta.factory`
+ * resolution. A node is "edited" iff its `meta.factory` appears in
+ * `prDiff.editedFactories`. This reuses the `factoryTag` / `decompileSpec`
+ * round-trip rather than introducing a `meta.ownerPath` glob. Nodes without
+ * `meta.factory` can't be mapped from a code diff and are never flagged.
+ *
+ * Pure function — no `Node` / `Graph` returned, no side effects. Designed to
+ * be called from a `graphrefly check-spec`-adjacent CI step (delta #6, Phase
+ * 16) or any host PR gate.
+ *
+ * @param spec - The committed GraphSpec (or any `describe({ detail: "spec" })`
+ *   projection / structural superset).
+ * @param prDiff - The factory-keyed diff slice + author + commit text.
+ */
+declare function validateOwnership(spec: unknown, prDiff: OwnershipPrDiff): OwnershipValidation;
 /** Options for {@link compileSpec}. */
 type CompileSpecOptions = {
     /** Fn/source catalog for resolving named factories. */
@@ -219,7 +317,7 @@ type CompileSpecOptions = {
     /**
      * How to handle nodes whose `fn` / `source` is missing from the catalog.
      * - `"placeholder"` (default): silently substitute identity passthroughs
-     *   (`producer(() => {})` / `derived(deps, vals => vals[0])`). Backward-
+     *   (`node([], () => {})` / `node(deps, (bd, a, ctx) => a.emit(bd[0]?.at(-1)))`). Backward-
      *   compatible — preserves the historical "soft compile" behavior.
      * - `"warn"`: substitute placeholders AND log each missing entry via
      *   `console.warn`, or via the `onWarn` callback if supplied.
@@ -348,38 +446,4 @@ type LLMRefineOptions = LLMComposeOptions;
  */
 declare function llmRefine(currentSpec: GraphSpec, feedback: string, adapter: LLMAdapter, opts?: LLMRefineOptions): Promise<GraphSpec>;
 
-type index_CatalogFnEntry = CatalogFnEntry;
-type index_CatalogSourceEntry = CatalogSourceEntry;
-type index_CompileSpecOptions = CompileSpecOptions;
-type index_ConfigFieldSchema = ConfigFieldSchema;
-type index_FnFactory = FnFactory;
-type index_GraphFactory = GraphFactory;
-type index_GraphSpec = GraphSpec;
-type index_GraphSpecCatalog = GraphSpecCatalog;
-type index_GraphSpecFeedbackEdge = GraphSpecFeedbackEdge;
-type index_GraphSpecNode = GraphSpecNode;
-type index_GraphSpecTemplate = GraphSpecTemplate;
-type index_GraphSpecTemplateRef = GraphSpecTemplateRef;
-type index_GraphSpecValidation = GraphSpecValidation;
-type index_LLMComposeOptions = LLMComposeOptions;
-type index_LLMRefineOptions = LLMRefineOptions;
-type index_SourceFactory = SourceFactory;
-type index_SpecDiffEntry = SpecDiffEntry;
-type index_SpecDiffResult = SpecDiffResult;
-declare const index_compileSpec: typeof compileSpec;
-declare const index_decompileSpec: typeof decompileSpec;
-declare const index_extractFnFactory: typeof extractFnFactory;
-declare const index_extractSourceFactory: typeof extractSourceFactory;
-declare const index_generateCatalogPrompt: typeof generateCatalogPrompt;
-declare const index_isRichFnEntry: typeof isRichFnEntry;
-declare const index_isRichSourceEntry: typeof isRichSourceEntry;
-declare const index_llmCompose: typeof llmCompose;
-declare const index_llmRefine: typeof llmRefine;
-declare const index_specDiff: typeof specDiff;
-declare const index_validateSpec: typeof validateSpec;
-declare const index_validateSpecAgainstCatalog: typeof validateSpecAgainstCatalog;
-declare namespace index {
-  export { type index_CatalogFnEntry as CatalogFnEntry, type index_CatalogSourceEntry as CatalogSourceEntry, type index_CompileSpecOptions as CompileSpecOptions, type index_ConfigFieldSchema as ConfigFieldSchema, type index_FnFactory as FnFactory, type index_GraphFactory as GraphFactory, type index_GraphSpec as GraphSpec, type index_GraphSpecCatalog as GraphSpecCatalog, type index_GraphSpecFeedbackEdge as GraphSpecFeedbackEdge, type index_GraphSpecNode as GraphSpecNode, type index_GraphSpecTemplate as GraphSpecTemplate, type index_GraphSpecTemplateRef as GraphSpecTemplateRef, type index_GraphSpecValidation as GraphSpecValidation, type index_LLMComposeOptions as LLMComposeOptions, type index_LLMRefineOptions as LLMRefineOptions, type index_SourceFactory as SourceFactory, type index_SpecDiffEntry as SpecDiffEntry, type index_SpecDiffResult as SpecDiffResult, index_compileSpec as compileSpec, index_decompileSpec as decompileSpec, index_extractFnFactory as extractFnFactory, index_extractSourceFactory as extractSourceFactory, index_generateCatalogPrompt as generateCatalogPrompt, index_isRichFnEntry as isRichFnEntry, index_isRichSourceEntry as isRichSourceEntry, index_llmCompose as llmCompose, index_llmRefine as llmRefine, index_specDiff as specDiff, index_validateSpec as validateSpec, index_validateSpecAgainstCatalog as validateSpecAgainstCatalog };
-}
-
-export { type CatalogFnEntry as C, type FnFactory as F, type GraphSpec as G, type LLMComposeOptions as L, type SourceFactory as S, type CatalogSourceEntry as a, type ConfigFieldSchema as b, type GraphSpecCatalog as c, type GraphSpecFeedbackEdge as d, type GraphSpecNode as e, type GraphSpecTemplate as f, type GraphSpecTemplateRef as g, type GraphSpecValidation as h, index as i, type CompileSpecOptions as j, type GraphFactory as k, type LLMRefineOptions as l, type SpecDiffEntry as m, type SpecDiffResult as n, compileSpec as o, decompileSpec as p, extractFnFactory as q, extractSourceFactory as r, generateCatalogPrompt as s, isRichFnEntry as t, isRichSourceEntry as u, llmCompose as v, llmRefine as w, specDiff as x, validateSpec as y, validateSpecAgainstCatalog as z };
+export { type CatalogFnEntry, type CatalogSourceEntry, type CompileSpecOptions, type ConfigFieldSchema, type FnFactory, type GraphSpec, type GraphSpecCatalog, type GraphSpecFactory, type GraphSpecFeedbackEdge, type GraphSpecNode, type GraphSpecTemplate, type GraphSpecTemplateRef, type GraphSpecValidation, type LLMComposeOptions, type LLMRefineOptions, type OwnershipPrDiff, type OwnershipValidation, type OwnershipViolation, type SourceFactory, type SpecDiffEntry, type SpecDiffResult, compileSpec, decompileSpec, extractFnFactory, extractSourceFactory, generateCatalogPrompt, isRichFnEntry, isRichSourceEntry, llmCompose, llmRefine, specDiff, validateOwnership, validateSpec, validateSpecAgainstCatalog };

package/dist/utils/graphspec/index.js

@@ -0,0 +1,35 @@
+import {
+  compileSpec,
+  decompileSpec,
+  extractFnFactory,
+  extractSourceFactory,
+  generateCatalogPrompt,
+  isRichFnEntry,
+  isRichSourceEntry,
+  llmCompose,
+  llmRefine,
+  specDiff,
+  validateOwnership,
+  validateSpec,
+  validateSpecAgainstCatalog
+} from "../../chunk-2OB3CEJS.js";
+import "../../chunk-IHTWQEDR.js";
+import "../../chunk-FMPF42Q4.js";
+import "../../chunk-BXGZFGZ4.js";
+import "../../chunk-AZDQPQ3V.js";
+export {
+  compileSpec,
+  decompileSpec,
+  extractFnFactory,
+  extractSourceFactory,
+  generateCatalogPrompt,
+  isRichFnEntry,
+  isRichSourceEntry,
+  llmCompose,
+  llmRefine,
+  specDiff,
+  validateOwnership,
+  validateSpec,
+  validateSpecAgainstCatalog
+};
+//# sourceMappingURL=index.js.map

package/dist/utils/graphspec/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}