@markbrutx/promptbook-core 0.1.0

package/src/lint/rules/unused-fragment.ts

@@ -0,0 +1,38 @@
+import { iterateReferences } from "../references.js";
+import type { LintFinding, LintRule, Severity } from "../types.js";
+
+export interface UnusedFragmentOptions {
+  severity?: Severity;
+}
+
+/**
+ * `unused-fragment` (book): a fragment that no composition mentions — not in a
+ * base, order, or any rule (add/replace/forbid/order/after) — is dead weight
+ * and is flagged. Findings are sorted by id for deterministic output.
+ */
+export function unusedFragment(options: UnusedFragmentOptions = {}): LintRule {
+  const severity = options.severity ?? "warning";
+  return {
+    id: "unused-fragment",
+    description: "Every fragment should be referenced by at least one composition or rule.",
+    scope: "book",
+    check(input) {
+      const referenced = new Set<string>();
+      for (const reference of iterateReferences(input.book)) {
+        referenced.add(reference.id);
+      }
+      const findings: LintFinding[] = [];
+      for (const id of [...input.book.fragments.keys()].sort()) {
+        if (!referenced.has(id)) {
+          findings.push({
+            ruleId: "unused-fragment",
+            severity,
+            message: `fragment "${id}" is not referenced by any composition or rule`,
+            fragmentId: id,
+          });
+        }
+      }
+      return findings;
+    },
+  };
+}

package/src/lint/types.ts

@@ -0,0 +1,55 @@
+/**
+ * Public types for the lint engine.
+ *
+ * Lint is static and deterministic: it runs pluggable rules over an assembled
+ * `{ text, trace }` and/or the book structure. It never calls a model and adds
+ * no runtime dependencies.
+ */
+import type { PromptBook, ResolveResult } from "../types.js";
+
+/** How serious a finding is. `error` drives a non-zero CLI exit. */
+export type Severity = "error" | "warning" | "info";
+
+/** When a rule can run: over a resolved prompt, or over the book structure. */
+export type LintScope = "resolved" | "book";
+
+/** A single problem a rule reports. */
+export interface LintFinding {
+  /** Id of the rule that produced this finding. */
+  ruleId: string;
+  severity: Severity;
+  /** Human-readable, domain-agnostic description. */
+  message: string;
+  /** Fragment the finding points at, when applicable. */
+  fragmentId?: string;
+  /** Composition rule index the finding points at, when applicable. */
+  ruleIndex?: number;
+}
+
+/** What lint runs against. `result` is present only for resolved-scope rules. */
+export interface LintInput {
+  book: PromptBook;
+  result?: ResolveResult;
+}
+
+/**
+ * A pluggable rule. Created by a factory so thresholds are configurable, e.g.
+ * `tokenBudget({ maxTokens })`. `check` is pure: same input, same findings.
+ */
+export interface LintRule {
+  /** Stable id, e.g. "token-budget". */
+  id: string;
+  /** One-line explanation of what the rule enforces. */
+  description: string;
+  /** Scope decides whether the rule needs `input.result`. */
+  scope: LintScope;
+  /** Inspect the input and return zero or more findings. */
+  check(input: LintInput): LintFinding[];
+}
+
+/** The aggregated outcome of a lint run. */
+export interface LintReport {
+  findings: LintFinding[];
+  errorCount: number;
+  warningCount: number;
+}

package/src/load.ts

@@ -0,0 +1,282 @@
+import { parse as parseYaml } from "yaml";
+import { parseFrontmatter } from "./frontmatter.js";
+import { nodeFs } from "./fs.js";
+import { isContextValue, isMapping } from "./guards.js";
+import { joinPath, listFiles, stripExt } from "./paths.js";
+import type {
+  CodePrompt,
+  CodePromptSample,
+  Composition,
+  Context,
+  ContextValue,
+  Fragment,
+  FsAdapter,
+  PromptBook,
+  Rule,
+  When,
+} from "./types.js";
+
+const ACTION_KEYS = ["add", "replace", "forbid", "order"] as const;
+
+function toStringArray(raw: unknown): string[] {
+  if (!Array.isArray(raw)) {
+    return [];
+  }
+  return raw.map((value) => String(value));
+}
+
+function toScalar(value: unknown): ContextValue {
+  return isContextValue(value) ? value : String(value);
+}
+
+function parseWhen(raw: unknown): When {
+  if (!isMapping(raw)) {
+    return {};
+  }
+  const when: When = {};
+  for (const [key, value] of Object.entries(raw)) {
+    when[key] = toScalar(value);
+  }
+  return when;
+}
+
+/** Parse a context bag, or `undefined` when absent/empty (keeps the field optional). */
+function parseContextBag(raw: unknown): Context | undefined {
+  const bag = parseWhen(raw);
+  return Object.keys(bag).length > 0 ? bag : undefined;
+}
+
+/**
+ * Load every `.yaml`/`.yml` file in `dir` into a name-keyed map. Owns the shared
+ * scaffold: parallel reads, skip-with-warning on a non-mapping doc, and the
+ * duplicate-name warning (later wins). The caller's `build` turns one parsed doc
+ * into a named value; `noun` labels the warnings ("Composition", "Code-prompt").
+ */
+async function loadYamlDir<T extends { name: string; sourceFile: string }>(
+  fs: FsAdapter,
+  dir: string,
+  noun: string,
+  warnings: string[],
+  build: (doc: Record<string, unknown>, file: string, full: string) => Promise<T> | T,
+): Promise<Map<string, T>> {
+  const map = new Map<string, T>();
+  const files = await listFiles(fs, dir, [".yaml", ".yml"]);
+  const loaded = await Promise.all(
+    files.map(async (file) => {
+      const full = joinPath(dir, file);
+      return { file, full, raw: await fs.readFile(full) };
+    }),
+  );
+  for (const { file, full, raw } of loaded) {
+    const doc = parseYaml(raw) as unknown;
+    if (!isMapping(doc)) {
+      warnings.push(`${noun} file "${full}" is empty or not a mapping; skipped.`);
+      continue;
+    }
+    const value = await build(doc, file, full);
+    const previous = map.get(value.name);
+    if (previous) {
+      warnings.push(
+        `Duplicate ${noun.toLowerCase()} name "${value.name}" in "${previous.sourceFile}" and "${full}"; using the latter.`,
+      );
+    }
+    map.set(value.name, value);
+  }
+  return map;
+}
+
+function parseReplaceMap(raw: unknown, index: number, file: string): Record<string, string> {
+  if (!isMapping(raw)) {
+    throw new Error(`Rule #${index} in "${file}" has a "replace" that is not a mapping.`);
+  }
+  const map: Record<string, string> = {};
+  for (const [from, to] of Object.entries(raw)) {
+    map[from] = String(to);
+  }
+  return map;
+}
+
+function parseRule(entry: unknown, index: number, file: string): Rule {
+  if (!isMapping(entry)) {
+    throw new Error(`Rule #${index} in "${file}" must be a mapping.`);
+  }
+  const obj = entry;
+  const present = ACTION_KEYS.filter((key) => obj[key] !== undefined);
+  if (present.length !== 1) {
+    throw new Error(
+      `Rule #${index} in "${file}" must declare exactly one action (${ACTION_KEYS.join(
+        " / ",
+      )}); found ${present.length}.`,
+    );
+  }
+  const action = present[0] as (typeof ACTION_KEYS)[number];
+  const rule: Rule = { index, when: parseWhen(obj.when), action };
+  switch (action) {
+    case "add":
+      rule.add = toStringArray(obj.add);
+      if (typeof obj.after === "string") {
+        rule.after = obj.after;
+      }
+      break;
+    case "replace":
+      rule.replace = parseReplaceMap(obj.replace, index, file);
+      break;
+    case "forbid":
+      rule.forbid = toStringArray(obj.forbid);
+      break;
+    case "order":
+      rule.order = toStringArray(obj.order);
+      break;
+  }
+  return rule;
+}
+
+function parseRules(raw: unknown, file: string): Rule[] {
+  if (raw === undefined || raw === null) {
+    return [];
+  }
+  if (!Array.isArray(raw)) {
+    throw new Error(`"rules" in "${file}" must be a list.`);
+  }
+  return raw.map((entry, index) => parseRule(entry, index, file));
+}
+
+async function loadFragments(fs: FsAdapter, dir: string): Promise<Map<string, Fragment>> {
+  const fragments = new Map<string, Fragment>();
+  const sourceById = new Map<string, string>();
+  const fragmentsDir = joinPath(dir, "fragments");
+  const files = await listFiles(fs, fragmentsDir, [".md", ".markdown"]);
+  // Reads run in parallel; the sorted file order still drives processing,
+  // so duplicate detection and output stay deterministic.
+  const loaded = await Promise.all(
+    files.map(async (file) => {
+      const full = joinPath(fragmentsDir, file);
+      return { full, raw: await fs.readFile(full) };
+    }),
+  );
+  for (const { full, raw } of loaded) {
+    const { data, body } = parseFrontmatter(raw);
+    const id = typeof data.id === "string" ? data.id : undefined;
+    if (!id) {
+      throw new Error(`Fragment "${full}" is missing a string "id" in its frontmatter.`);
+    }
+    const existing = sourceById.get(id);
+    if (existing) {
+      throw new Error(`Duplicate fragment id "${id}" in "${existing}" and "${full}".`);
+    }
+    sourceById.set(id, full);
+    const fragment: Fragment = { id, body: body.trim(), sourceFile: full };
+    if (typeof data.kind === "string") {
+      fragment.kind = data.kind;
+    }
+    if (Array.isArray(data.tags)) {
+      fragment.tags = data.tags.map((tag) => String(tag));
+    }
+    fragments.set(id, fragment);
+  }
+  return fragments;
+}
+
+function loadCompositions(fs: FsAdapter, dir: string, warnings: string[]): Promise<Map<string, Composition>> {
+  return loadYamlDir(fs, joinPath(dir, "rules"), "Composition", warnings, (obj, file, full) => {
+    const name = typeof obj.name === "string" ? obj.name : stripExt(file);
+    const composition: Composition = {
+      name,
+      base: toStringArray(obj.base),
+      rules: parseRules(obj.rules, full),
+      sourceFile: full,
+    };
+    if (obj.order !== undefined) {
+      composition.order = toStringArray(obj.order);
+    }
+    return composition;
+  });
+}
+
+/**
+ * Load the captured output samples of one code-prompt manifest. A sample's text
+ * comes inline (`output`) or from a sibling file (`file`). Malformed entries
+ * and missing files become warnings, never throws — the core never runs the
+ * builder, so a broken snapshot just drops out of the menu.
+ */
+async function loadCodePromptSamples(
+  fs: FsAdapter,
+  codeDir: string,
+  raw: unknown,
+  manifest: string,
+  warnings: string[],
+): Promise<CodePromptSample[]> {
+  if (raw === undefined || raw === null) {
+    return [];
+  }
+  if (!Array.isArray(raw)) {
+    warnings.push(`"samples" in "${manifest}" must be a list; ignored.`);
+    return [];
+  }
+  const samples: CodePromptSample[] = [];
+  for (let index = 0; index < raw.length; index++) {
+    const entry = raw[index];
+    if (!isMapping(entry)) {
+      warnings.push(`Sample #${index} in "${manifest}" must be a mapping; skipped.`);
+      continue;
+    }
+    const label = typeof entry.label === "string" ? entry.label : undefined;
+    if (!label) {
+      warnings.push(`Sample #${index} in "${manifest}" is missing a string "label"; skipped.`);
+      continue;
+    }
+    let output: string | undefined;
+    if (typeof entry.output === "string") {
+      output = entry.output;
+    } else if (typeof entry.file === "string") {
+      try {
+        output = await fs.readFile(joinPath(codeDir, entry.file));
+      } catch {
+        warnings.push(`Sample "${label}" in "${manifest}" references missing file "${entry.file}"; skipped.`);
+        continue;
+      }
+    } else {
+      warnings.push(`Sample "${label}" in "${manifest}" must set "output" or "file"; skipped.`);
+      continue;
+    }
+    const sample: CodePromptSample = { label, output };
+    const context = parseContextBag(entry.context);
+    if (context !== undefined) {
+      sample.context = context;
+    }
+    samples.push(sample);
+  }
+  return samples;
+}
+
+function loadCodePrompts(fs: FsAdapter, dir: string, warnings: string[]): Promise<Map<string, CodePrompt>> {
+  const codeDir = joinPath(dir, "code-prompts");
+  return loadYamlDir(fs, codeDir, "Code-prompt", warnings, async (obj, file, full) => {
+    const name = typeof obj.name === "string" ? obj.name : stripExt(file);
+    const samples = await loadCodePromptSamples(fs, codeDir, obj.samples, full, warnings);
+    const codePrompt: CodePrompt = { name, samples, sourceFile: full };
+    if (typeof obj.description === "string") {
+      codePrompt.description = obj.description;
+    }
+    return codePrompt;
+  });
+}
+
+/**
+ * Load a prompts folder (`fragments/` + `rules/` + optional `code-prompts/`)
+ * into a {@link PromptBook}.
+ *
+ * Throws only on structural errors (missing/duplicate fragment id, malformed
+ * rule). Soft issues (empty rules file, duplicate composition name, broken
+ * code-prompt manifest/sample) become warnings. Code-prompts hold snapshot text
+ * only — the builder is never executed. Reference checks happen in `resolve`.
+ */
+export async function loadPrompts(promptsDir: string, fs: FsAdapter = nodeFs()): Promise<PromptBook> {
+  const warnings: string[] = [];
+  const [fragments, compositions, codePrompts] = await Promise.all([
+    loadFragments(fs, promptsDir),
+    loadCompositions(fs, promptsDir, warnings),
+    loadCodePrompts(fs, promptsDir, warnings),
+  ]);
+  return { fragments, compositions, codePrompts, warnings };
+}

package/src/paths.ts

@@ -0,0 +1,27 @@
+import type { FsAdapter } from "./types.js";
+
+/** Join a directory and child with a single `/`, tolerating a trailing slash. */
+export function joinPath(dir: string, child: string): string {
+  return dir.endsWith("/") ? `${dir}${child}` : `${dir}/${child}`;
+}
+
+/** Drop a file extension, e.g. `assistant.yaml` -> `assistant`. */
+export function stripExt(name: string): string {
+  const dot = name.lastIndexOf(".");
+  return dot === -1 ? name : name.slice(0, dot);
+}
+
+/**
+ * List files in `dir` whose name ends with one of `exts`, sorted for
+ * deterministic processing. A missing/unreadable directory yields `[]` so
+ * callers can treat an absent folder as "no files".
+ */
+export async function listFiles(fs: FsAdapter, dir: string, exts: string[]): Promise<string[]> {
+  let entries: string[];
+  try {
+    entries = await fs.readDir(dir);
+  } catch {
+    return [];
+  }
+  return entries.filter((name) => exts.some((ext) => name.endsWith(ext))).sort();
+}

package/src/resolve-book.ts

@@ -0,0 +1,237 @@
+import { interpolate } from "./interpolate.js";
+import type {
+  AddTrace,
+  Composition,
+  Context,
+  ContextValue,
+  ForbidTrace,
+  PromptBook,
+  ReplaceTrace,
+  ResolveResult,
+  RuleTrace,
+  Trace,
+  UnmatchedAxis,
+  When,
+} from "./types.js";
+
+/**
+ * Pure resolver over an already-loaded {@link PromptBook}. No filesystem, no
+ * YAML, no Node builtins — the entire dependency footprint is {@link interpolate}
+ * and type-only imports. This is the determinism boundary: given the same book
+ * and context, the returned `text` is byte-for-byte stable, and the module
+ * bundles to a self-contained artifact for edge runtimes (see `edge.ts`).
+ *
+ * Conflict strategy: rules apply in declaration order, later wins (cascade).
+ * `forbid` is the one exception — it is applied as a final filter and always
+ * wins, so a forbidden id never reaches the output even if added earlier.
+ */
+export function resolveBook(book: PromptBook, prompt: string, context: Context): ResolveResult {
+  const composition = book.compositions.get(prompt);
+  if (!composition) {
+    const available = [...book.compositions.keys()].sort().join(", ") || "(none)";
+    throw new Error(`Unknown prompt "${prompt}". Available compositions: ${available}.`);
+  }
+
+  const warnings: string[] = [...book.warnings];
+  const ruleTraces: RuleTrace[] = [];
+  const replaced: ReplaceTrace[] = [];
+  const added: AddTrace[] = [];
+  const forbidden: ForbidTrace[] = [];
+  const forbiddenIds = new Set<string>();
+
+  const working: string[] = [...composition.base];
+  let orderOverride: string[] | undefined = composition.order ? [...composition.order] : undefined;
+
+  for (const rule of composition.rules) {
+    const match = matchWhen(rule.when, context);
+    const trace: RuleTrace = {
+      index: rule.index,
+      action: rule.action,
+      when: rule.when,
+      fired: match.fired,
+    };
+    if (!match.fired) {
+      trace.reason = match.reason;
+      ruleTraces.push(trace);
+      continue;
+    }
+
+    switch (rule.action) {
+      case "replace": {
+        const effects: string[] = [];
+        for (const [from, to] of Object.entries(rule.replace ?? {})) {
+          const at = working.indexOf(from);
+          if (at === -1) {
+            warnings.push(`Rule #${rule.index} cannot replace "${from}": it is not present in "${prompt}".`);
+            continue;
+          }
+          working[at] = to;
+          replaced.push({ from, to, ruleIndex: rule.index });
+          effects.push(`${from} -> ${to}`);
+        }
+        trace.effect = `replace ${effects.join(", ")}`;
+        break;
+      }
+      case "add": {
+        const ids = rule.add ?? [];
+        const after = rule.after;
+        const at = insertionPoint(working, after, rule.index, prompt, warnings);
+        working.splice(at, 0, ...ids);
+        for (const id of ids) {
+          added.push(
+            after !== undefined ? { id, after, ruleIndex: rule.index } : { id, ruleIndex: rule.index },
+          );
+        }
+        trace.effect = `add ${ids.join(", ")}${after !== undefined ? ` after ${after}` : ""}`;
+        break;
+      }
+      case "forbid": {
+        const ids = rule.forbid ?? [];
+        for (const id of ids) {
+          forbiddenIds.add(id);
+          forbidden.push({ id, ruleIndex: rule.index });
+        }
+        trace.effect = `forbid ${ids.join(", ")}`;
+        break;
+      }
+      case "order": {
+        orderOverride = [...(rule.order ?? [])];
+        trace.effect = `order ${orderOverride.join(", ")}`;
+        break;
+      }
+    }
+    ruleTraces.push(trace);
+  }
+
+  const ordered = applyOrder(working, orderOverride);
+  const selected = ordered.filter((id) => !forbiddenIds.has(id));
+
+  const parts: string[] = [];
+  const finalOrder: string[] = [];
+  for (const id of selected) {
+    const fragment = book.fragments.get(id);
+    if (!fragment) {
+      warnings.push(`Fragment "${id}" referenced by "${prompt}" was not found.`);
+      continue;
+    }
+    parts.push(
+      interpolate(fragment.body, context, (key) => {
+        warnings.push(`Missing variable "${key}" while rendering fragment "${id}".`);
+      }),
+    );
+    finalOrder.push(id);
+  }
+
+  const trace: Trace = {
+    prompt,
+    context,
+    rules: ruleTraces,
+    finalOrder,
+    replaced,
+    added,
+    forbidden,
+    unmatchedAxes: computeUnmatchedAxes(composition, context),
+    warnings,
+  };
+
+  return { text: parts.join("\n\n"), trace };
+}
+
+interface WhenMatch {
+  fired: boolean;
+  reason?: string;
+}
+
+function matchWhen(when: When, context: Context): WhenMatch {
+  for (const [key, expected] of Object.entries(when)) {
+    const actual = context[key];
+    if (actual === undefined) {
+      return { fired: false, reason: `context.${key} is unset, rule expects "${expected}"` };
+    }
+    if (!valuesEqual(expected, actual)) {
+      return { fired: false, reason: `context.${key}="${actual}" does not equal expected "${expected}"` };
+    }
+  }
+  return { fired: true };
+}
+
+export function valuesEqual(a: ContextValue, b: ContextValue): boolean {
+  return String(a) === String(b);
+}
+
+/**
+ * Decide where an `add` inserts. With `after`, just past that id; without it,
+ * before the last fragment (so trailing format/footer fragments stay last).
+ */
+function insertionPoint(
+  working: string[],
+  after: string | undefined,
+  ruleIndex: number,
+  prompt: string,
+  warnings: string[],
+): number {
+  if (after === undefined) {
+    return Math.max(working.length - 1, 0);
+  }
+  const at = working.indexOf(after);
+  if (at === -1) {
+    warnings.push(`Rule #${ruleIndex} add anchor "${after}" not found in "${prompt}"; appending at end.`);
+    return working.length;
+  }
+  return at + 1;
+}
+
+/**
+ * Produce the final id sequence. With an `order` override, listed ids come
+ * first (those that are present), then any remaining working ids in their
+ * existing order. Without an override, the working order is used as-is.
+ * Duplicates are collapsed to their first occurrence.
+ */
+function applyOrder(working: string[], orderOverride: string[] | undefined): string[] {
+  const seen = new Set<string>();
+  const result: string[] = [];
+  const push = (id: string) => {
+    if (!seen.has(id)) {
+      seen.add(id);
+      result.push(id);
+    }
+  };
+  if (orderOverride) {
+    const present = new Set(working);
+    for (const id of orderOverride) {
+      if (present.has(id)) {
+        push(id);
+      }
+    }
+  }
+  for (const id of working) {
+    push(id);
+  }
+  return result;
+}
+
+/**
+ * Find context axes that some rule referenced but matched none. This surfaces
+ * holes like `industry=zoo` where industry rules exist but none cover "zoo".
+ */
+function computeUnmatchedAxes(composition: Composition, context: Context): UnmatchedAxis[] {
+  const result: UnmatchedAxis[] = [];
+  for (const key of Object.keys(context)) {
+    let referenced = false;
+    let matched = false;
+    for (const rule of composition.rules) {
+      if (Object.hasOwn(rule.when, key)) {
+        referenced = true;
+        const expected = rule.when[key];
+        if (expected !== undefined && valuesEqual(expected, context[key] as ContextValue)) {
+          matched = true;
+          break;
+        }
+      }
+    }
+    if (referenced && !matched) {
+      result.push({ key, value: context[key] as ContextValue });
+    }
+  }
+  return result;
+}

package/src/resolve.ts

@@ -0,0 +1,18 @@
+import { loadPrompts } from "./load.js";
+import { resolveBook } from "./resolve-book.js";
+import type { ResolveInput, ResolveResult } from "./types.js";
+
+/**
+ * Assemble a prompt for a context and return the text plus an explain trace.
+ *
+ * Loads the prompts folder (the one IO step), then delegates to the pure
+ * {@link resolveBook}. Given the same folder contents and input, the returned
+ * `text` is byte-for-byte stable.
+ *
+ * Each call re-reads the folder. For many resolves against the same folder,
+ * call {@link loadPrompts} once and reuse {@link resolveBook}.
+ */
+export async function resolve(input: ResolveInput): Promise<ResolveResult> {
+  const book = await loadPrompts(input.promptsDir, input.fs);
+  return resolveBook(book, input.prompt, input.context ?? {});
+}