@markbrutx/promptbook-core 0.1.0 → 0.2.0

package/dist/edge/index.js

@@ -1,7 +1,9 @@
 // Generated by `npm run build:edge`; do not edit by hand.
 
-// dist/interpolate.js
+// dist/vars.js
 var VAR_RE = /(\\?)\$\{([^}]+)\}/g;
+
+// dist/interpolate.js
 function interpolate(body, context, onMissing) {
   return body.replace(VAR_RE, (_match, backslash, expr) => {
     if (backslash) {

package/dist/index.d.ts

@@ -16,7 +16,10 @@ export type { BannedTokensOptions, DanglingReferenceOptions, DeadRuleOptions, Ex
 export { bannedTokens, type DefaultRulesOptions, danglingReference, deadRule, defaultRules, estimateTokensByChars, exampleBalance, languageDirectivePosition, tokenBudget, unusedFragment, } from "./lint/rules/index.js";
 export type { LintFinding, LintInput, LintReport, LintRule, LintScope, Severity } from "./lint/types.js";
 export { loadPrompts } from "./load.js";
+export type { RequiredContext } from "./required-context.js";
+export { requiredContext } from "./required-context.js";
 export { resolve } from "./resolve.js";
 export { resolveBook } from "./resolve-book.js";
 export type { AddTrace, CodePrompt, CodePromptSample, Composition, Context, ContextValue, ForbidTrace, Fragment, FsAdapter, PromptBook, ReplaceTrace, ResolveInput, ResolveResult, Rule, RuleAction, RuleTrace, Trace, UnmatchedAxis, When, } from "./types.js";
+export { extractVariables } from "./vars.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,UAAU,EACV,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EACrB,UAAU,EACV,uBAAuB,EACvB,cAAc,GACf,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAAE,aAAa,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACxF,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,YAAY,EACV,SAAS,EACT,WAAW,EACX,iBAAiB,EACjB,eAAe,EACf,SAAS,EACT,UAAU,EACV,OAAO,EACP,aAAa,EACb,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,UAAU,GACX,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AACtC,YAAY,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD,YAAY,EACV,mBAAmB,EACnB,wBAAwB,EACxB,eAAe,EACf,qBAAqB,EACrB,gCAAgC,EAChC,kBAAkB,EAClB,qBAAqB,GACtB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,YAAY,EACZ,KAAK,mBAAmB,EACxB,iBAAiB,EACjB,QAAQ,EACR,YAAY,EACZ,qBAAqB,EACrB,cAAc,EACd,yBAAyB,EACzB,WAAW,EACX,cAAc,GACf,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AACzG,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EACV,QAAQ,EACR,UAAU,EACV,gBAAgB,EAChB,WAAW,EACX,OAAO,EACP,YAAY,EACZ,WAAW,EACX,QAAQ,EACR,SAAS,EACT,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,IAAI,EACJ,UAAU,EACV,SAAS,EACT,KAAK,EACL,aAAa,EACb,IAAI,GACL,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,UAAU,EACV,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EACrB,UAAU,EACV,uBAAuB,EACvB,cAAc,GACf,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAAE,aAAa,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACxF,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,YAAY,EACV,SAAS,EACT,WAAW,EACX,iBAAiB,EACjB,eAAe,EACf,SAAS,EACT,UAAU,EACV,OAAO,EACP,aAAa,EACb,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,UAAU,GACX,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AACtC,YAAY,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD,YAAY,EACV,mBAAmB,EACnB,wBAAwB,EACxB,eAAe,EACf,qBAAqB,EACrB,gCAAgC,EAChC,kBAAkB,EAClB,qBAAqB,GACtB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,YAAY,EACZ,KAAK,mBAAmB,EACxB,iBAAiB,EACjB,QAAQ,EACR,YAAY,EACZ,qBAAqB,EACrB,cAAc,EACd,yBAAyB,EACzB,WAAW,EACX,cAAc,GACf,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AACzG,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,YAAY,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EACV,QAAQ,EACR,UAAU,EACV,gBAAgB,EAChB,WAAW,EACX,OAAO,EACP,YAAY,EACZ,WAAW,EACX,QAAQ,EACR,SAAS,EACT,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,IAAI,EACJ,UAAU,EACV,SAAS,EACT,KAAK,EACL,aAAa,EACb,IAAI,GACL,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -10,6 +10,8 @@ export { lint } from "./lint/lint.js";
 export { iterateReferences } from "./lint/references.js";
 export { bannedTokens, danglingReference, deadRule, defaultRules, estimateTokensByChars, exampleBalance, languageDirectivePosition, tokenBudget, unusedFragment, } from "./lint/rules/index.js";
 export { loadPrompts } from "./load.js";
+export { requiredContext } from "./required-context.js";
 export { resolve } from "./resolve.js";
 export { resolveBook } from "./resolve-book.js";
+export { extractVariables } from "./vars.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EACrB,UAAU,EACV,uBAAuB,EACvB,cAAc,GACf,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,aAAa,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACxF,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAevD,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAEtC,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAUzD,OAAO,EACL,YAAY,EAEZ,iBAAiB,EACjB,QAAQ,EACR,YAAY,EACZ,qBAAqB,EACrB,cAAc,EACd,yBAAyB,EACzB,WAAW,EACX,cAAc,GACf,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EACrB,UAAU,EACV,uBAAuB,EACvB,cAAc,GACf,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,aAAa,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACxF,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAevD,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAEtC,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAUzD,OAAO,EACL,YAAY,EAEZ,iBAAiB,EACjB,QAAQ,EACR,YAAY,EACZ,qBAAqB,EACrB,cAAc,EACd,yBAAyB,EACzB,WAAW,EACX,cAAc,GACf,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAExC,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAsBhD,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC"}

package/dist/interpolate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"interpolate.d.ts","sourceRoot":"","sources":["../src/interpolate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAK1C;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,CAapG"}
+{"version":3,"file":"interpolate.d.ts","sourceRoot":"","sources":["../src/interpolate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAG1C;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,CAapG"}

package/dist/interpolate.js

@@ -1,5 +1,4 @@
-/** Matches `${path}` placeholders, capturing an optional leading `\` escape. */
-const VAR_RE = /(\\?)\$\{([^}]+)\}/g;
+import { VAR_RE } from "./vars.js";
 /**
  * Substitute `${path}` placeholders in `body` using `context`.
  *

package/dist/interpolate.js.map

@@ -1 +1 @@
-{"version":3,"file":"interpolate.js","sourceRoot":"","sources":["../src/interpolate.ts"],"names":[],"mappings":"AAEA,gFAAgF;AAChF,MAAM,MAAM,GAAG,qBAAqB,CAAC;AAErC;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAC,IAAY,EAAE,OAAgB,EAAE,SAAgC;IAC1F,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,SAAiB,EAAE,IAAY,EAAE,EAAE;QACtE,IAAI,SAAS,EAAE,CAAC;YACd,OAAO,MAAM,IAAI,GAAG,CAAC;QACvB,CAAC;QACD,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QACxB,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QAC3B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,SAAS,CAAC,GAAG,CAAC,CAAC;YACf,OAAO,EAAE,CAAC;QACZ,CAAC;QACD,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IACvB,CAAC,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"interpolate.js","sourceRoot":"","sources":["../src/interpolate.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAEnC;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAC,IAAY,EAAE,OAAgB,EAAE,SAAgC;IAC1F,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,SAAiB,EAAE,IAAY,EAAE,EAAE;QACtE,IAAI,SAAS,EAAE,CAAC;YACd,OAAO,MAAM,IAAI,GAAG,CAAC;QACvB,CAAC;QACD,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QACxB,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QAC3B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,SAAS,CAAC,GAAG,CAAC,CAAC;YACf,OAAO,EAAE,CAAC;QACZ,CAAC;QACD,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IACvB,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/required-context.d.ts

@@ -0,0 +1,27 @@
+import type { ContextValue, PromptBook } from "./types.js";
+/**
+ * The context a composition declares it needs, derived statically (no cascade
+ * run). Lets a consumer see the keys to supply instead of discovering holes one
+ * `Missing variable` at a time.
+ */
+export interface RequiredContext {
+    /** `${var}` keys across the composition's reachable fragments; sorted, unique. */
+    vars: string[];
+    /** `when`-axis key → sorted unique option values seen across its rules. */
+    axes: Record<string, ContextValue[]>;
+    /** Provenance: each var → the fragment ids that introduce it; sorted, unique. */
+    sources: Record<string, string[]>;
+}
+/**
+ * Statically report the context a composition needs: the `${var}` keys across
+ * every fragment it can reach (`base ∪ add-ids ∪ replace-targets`) and the
+ * `when`-axes its rules branch on.
+ *
+ * Directed over-approximation: it unions vars across *all* rules without running
+ * the cascade, so supplying every reported key never leaves a hole in any
+ * context (a never-firing `add` may over-report, never under-report). `forbid`
+ * and `order` introduce no new fragments, so they contribute no vars. Throws on
+ * an unknown composition, matching `resolveBook`.
+ */
+export declare function requiredContext(book: PromptBook, compName: string): RequiredContext;
+//# sourceMappingURL=required-context.d.ts.map

package/dist/required-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"required-context.d.ts","sourceRoot":"","sources":["../src/required-context.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAG3D;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,kFAAkF;IAClF,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,EAAE,CAAC,CAAC;IACrC,iFAAiF;IACjF,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CACnC;AAKD;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,GAAG,eAAe,CA2CnF"}

package/dist/required-context.js

@@ -0,0 +1,71 @@
+import { iterateReferences } from "./lint/references.js";
+import { extractVariables } from "./vars.js";
+/** Roles that can put a fragment into the assembled output (so its vars matter). */
+const REACHABLE_ROLES = new Set(["base", "add", "replace-to"]);
+/**
+ * Statically report the context a composition needs: the `${var}` keys across
+ * every fragment it can reach (`base ∪ add-ids ∪ replace-targets`) and the
+ * `when`-axes its rules branch on.
+ *
+ * Directed over-approximation: it unions vars across *all* rules without running
+ * the cascade, so supplying every reported key never leaves a hole in any
+ * context (a never-firing `add` may over-report, never under-report). `forbid`
+ * and `order` introduce no new fragments, so they contribute no vars. Throws on
+ * an unknown composition, matching `resolveBook`.
+ */
+export function requiredContext(book, compName) {
+    const composition = book.compositions.get(compName);
+    if (!composition) {
+        const available = [...book.compositions.keys()].sort().join(", ") || "(none)";
+        throw new Error(`Unknown prompt "${compName}". Available compositions: ${available}.`);
+    }
+    const reachable = new Set();
+    for (const ref of iterateReferences(book)) {
+        if (ref.composition === compName && REACHABLE_ROLES.has(ref.role)) {
+            reachable.add(ref.id);
+        }
+    }
+    const sourceSets = new Map();
+    for (const id of reachable) {
+        const fragment = book.fragments.get(id);
+        if (!fragment) {
+            continue;
+        }
+        for (const key of extractVariables(fragment.body)) {
+            addTo(sourceSets, key, id);
+        }
+    }
+    const axisSets = new Map();
+    for (const rule of composition.rules) {
+        for (const [key, value] of Object.entries(rule.when)) {
+            addTo(axisSets, key, value);
+        }
+    }
+    const vars = [...sourceSets.keys()].sort();
+    const sources = {};
+    for (const key of vars) {
+        sources[key] = [...(sourceSets.get(key) ?? [])].sort();
+    }
+    const axes = {};
+    for (const key of [...axisSets.keys()].sort()) {
+        axes[key] = [...(axisSets.get(key) ?? [])].sort(compareContextValues);
+    }
+    return { vars, axes, sources };
+}
+/** Append `value` to the set under `key`, creating the set on first use. */
+function addTo(map, key, value) {
+    let set = map.get(key);
+    if (set === undefined) {
+        set = new Set();
+        map.set(key, set);
+    }
+    set.add(value);
+}
+/** Stable order for axis options: numeric when both numbers, else by string. */
+function compareContextValues(a, b) {
+    if (typeof a === "number" && typeof b === "number") {
+        return a - b;
+    }
+    return String(a).localeCompare(String(b));
+}
+//# sourceMappingURL=required-context.js.map

package/dist/required-context.js.map

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

package/dist/vars.d.ts

@@ -0,0 +1,12 @@
+/** Matches `${path}` placeholders, capturing an optional leading `\` escape. */
+export declare const VAR_RE: RegExp;
+/**
+ * Extract the variable keys referenced by `${path}` placeholders in `body`.
+ *
+ * Shares its syntax with {@link interpolate} (both read {@link VAR_RE}), so the
+ * keys reported here are exactly the ones interpolation substitutes. Escaped
+ * `\${path}` placeholders are ignored (they render literally); keys are trimmed,
+ * sorted and de-duplicated.
+ */
+export declare function extractVariables(body: string): string[];
+//# sourceMappingURL=vars.d.ts.map

package/dist/vars.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vars.d.ts","sourceRoot":"","sources":["../src/vars.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,eAAO,MAAM,MAAM,QAAwB,CAAC;AAE5C;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAUvD"}

package/dist/vars.js

@@ -0,0 +1,22 @@
+/** Matches `${path}` placeholders, capturing an optional leading `\` escape. */
+export const VAR_RE = /(\\?)\$\{([^}]+)\}/g;
+/**
+ * Extract the variable keys referenced by `${path}` placeholders in `body`.
+ *
+ * Shares its syntax with {@link interpolate} (both read {@link VAR_RE}), so the
+ * keys reported here are exactly the ones interpolation substitutes. Escaped
+ * `\${path}` placeholders are ignored (they render literally); keys are trimmed,
+ * sorted and de-duplicated.
+ */
+export function extractVariables(body) {
+    const keys = new Set();
+    for (const match of body.matchAll(VAR_RE)) {
+        const [, backslash, expr] = match;
+        if (backslash || expr === undefined) {
+            continue;
+        }
+        keys.add(expr.trim());
+    }
+    return [...keys].sort();
+}
+//# sourceMappingURL=vars.js.map

package/dist/vars.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vars.js","sourceRoot":"","sources":["../src/vars.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,MAAM,CAAC,MAAM,MAAM,GAAG,qBAAqB,CAAC;AAE5C;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QAC1C,MAAM,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,KAAK,CAAC;QAClC,IAAI,SAAS,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACpC,SAAS;QACX,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IACxB,CAAC;IACD,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;AAC1B,CAAC"}

package/package.json

@@ -1,9 +1,26 @@
 {
   "name": "@markbrutx/promptbook-core",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Agnostic, deterministic core for composing prompts from reusable fragments via declarative rules.",
   "type": "module",
   "license": "MIT",
+  "keywords": [
+    "prompt",
+    "prompt-engineering",
+    "prompt-management",
+    "llm",
+    "ai",
+    "composition",
+    "deterministic",
+    "agnostic"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/markbrutx/promptbook.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/markbrutx/promptbook#readme",
+  "bugs": "https://github.com/markbrutx/promptbook/issues",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -37,8 +54,8 @@
   "devDependencies": {
     "@biomejs/biome": "latest",
     "@types/node": "^20.14.0",
-    "esbuild": "^0.21.5",
     "@typescript/native-preview": "latest",
+    "esbuild": "^0.21.5",
     "typescript": "^5.6.0",
     "vitest": "^2.1.0"
   },

package/src/index.ts

@@ -59,6 +59,8 @@ export {
 } from "./lint/rules/index.js";
 export type { LintFinding, LintInput, LintReport, LintRule, LintScope, Severity } from "./lint/types.js";
 export { loadPrompts } from "./load.js";
+export type { RequiredContext } from "./required-context.js";
+export { requiredContext } from "./required-context.js";
 export { resolve } from "./resolve.js";
 export { resolveBook } from "./resolve-book.js";
 export type {
@@ -82,3 +84,4 @@ export type {
   UnmatchedAxis,
   When,
 } from "./types.js";
+export { extractVariables } from "./vars.js";

package/src/interpolate.ts

@@ -1,7 +1,5 @@
 import type { Context } from "./types.js";
-
-/** Matches `${path}` placeholders, capturing an optional leading `\` escape. */
-const VAR_RE = /(\\?)\$\{([^}]+)\}/g;
+import { VAR_RE } from "./vars.js";
 
 /**
  * Substitute `${path}` placeholders in `body` using `context`.

package/src/required-context.ts

@@ -0,0 +1,95 @@
+import type { FragmentReference } from "./lint/references.js";
+import { iterateReferences } from "./lint/references.js";
+import type { ContextValue, PromptBook } from "./types.js";
+import { extractVariables } from "./vars.js";
+
+/**
+ * The context a composition declares it needs, derived statically (no cascade
+ * run). Lets a consumer see the keys to supply instead of discovering holes one
+ * `Missing variable` at a time.
+ */
+export interface RequiredContext {
+  /** `${var}` keys across the composition's reachable fragments; sorted, unique. */
+  vars: string[];
+  /** `when`-axis key → sorted unique option values seen across its rules. */
+  axes: Record<string, ContextValue[]>;
+  /** Provenance: each var → the fragment ids that introduce it; sorted, unique. */
+  sources: Record<string, string[]>;
+}
+
+/** Roles that can put a fragment into the assembled output (so its vars matter). */
+const REACHABLE_ROLES = new Set<FragmentReference["role"]>(["base", "add", "replace-to"]);
+
+/**
+ * Statically report the context a composition needs: the `${var}` keys across
+ * every fragment it can reach (`base ∪ add-ids ∪ replace-targets`) and the
+ * `when`-axes its rules branch on.
+ *
+ * Directed over-approximation: it unions vars across *all* rules without running
+ * the cascade, so supplying every reported key never leaves a hole in any
+ * context (a never-firing `add` may over-report, never under-report). `forbid`
+ * and `order` introduce no new fragments, so they contribute no vars. Throws on
+ * an unknown composition, matching `resolveBook`.
+ */
+export function requiredContext(book: PromptBook, compName: string): RequiredContext {
+  const composition = book.compositions.get(compName);
+  if (!composition) {
+    const available = [...book.compositions.keys()].sort().join(", ") || "(none)";
+    throw new Error(`Unknown prompt "${compName}". Available compositions: ${available}.`);
+  }
+
+  const reachable = new Set<string>();
+  for (const ref of iterateReferences(book)) {
+    if (ref.composition === compName && REACHABLE_ROLES.has(ref.role)) {
+      reachable.add(ref.id);
+    }
+  }
+
+  const sourceSets = new Map<string, Set<string>>();
+  for (const id of reachable) {
+    const fragment = book.fragments.get(id);
+    if (!fragment) {
+      continue;
+    }
+    for (const key of extractVariables(fragment.body)) {
+      addTo(sourceSets, key, id);
+    }
+  }
+
+  const axisSets = new Map<string, Set<ContextValue>>();
+  for (const rule of composition.rules) {
+    for (const [key, value] of Object.entries(rule.when)) {
+      addTo(axisSets, key, value);
+    }
+  }
+
+  const vars = [...sourceSets.keys()].sort();
+  const sources: Record<string, string[]> = {};
+  for (const key of vars) {
+    sources[key] = [...(sourceSets.get(key) ?? [])].sort();
+  }
+  const axes: Record<string, ContextValue[]> = {};
+  for (const key of [...axisSets.keys()].sort()) {
+    axes[key] = [...(axisSets.get(key) ?? [])].sort(compareContextValues);
+  }
+
+  return { vars, axes, sources };
+}
+
+/** Append `value` to the set under `key`, creating the set on first use. */
+function addTo<V>(map: Map<string, Set<V>>, key: string, value: V): void {
+  let set = map.get(key);
+  if (set === undefined) {
+    set = new Set();
+    map.set(key, set);
+  }
+  set.add(value);
+}
+
+/** Stable order for axis options: numeric when both numbers, else by string. */
+function compareContextValues(a: ContextValue, b: ContextValue): number {
+  if (typeof a === "number" && typeof b === "number") {
+    return a - b;
+  }
+  return String(a).localeCompare(String(b));
+}

package/src/vars.ts

@@ -0,0 +1,22 @@
+/** Matches `${path}` placeholders, capturing an optional leading `\` escape. */
+export const VAR_RE = /(\\?)\$\{([^}]+)\}/g;
+
+/**
+ * Extract the variable keys referenced by `${path}` placeholders in `body`.
+ *
+ * Shares its syntax with {@link interpolate} (both read {@link VAR_RE}), so the
+ * keys reported here are exactly the ones interpolation substitutes. Escaped
+ * `\${path}` placeholders are ignored (they render literally); keys are trimmed,
+ * sorted and de-duplicated.
+ */
+export function extractVariables(body: string): string[] {
+  const keys = new Set<string>();
+  for (const match of body.matchAll(VAR_RE)) {
+    const [, backslash, expr] = match;
+    if (backslash || expr === undefined) {
+      continue;
+    }
+    keys.add(expr.trim());
+  }
+  return [...keys].sort();
+}