@refrakt-md/runes 0.9.8 → 0.10.0

package/dist/reference.d.ts

@@ -0,0 +1,220 @@
+/**
+ * Shared rune-reference infrastructure used by both the AI prompt builder
+ * and the editor/CLI for serializing rune metadata. Lives in @refrakt-md/runes
+ * so that callers (`refrakt write`, `refrakt edit`, `refrakt reference`) can
+ * use it without pulling in the AI or editor packages.
+ */
+import type { Schema } from '@markdoc/markdoc';
+import type { ContentModel } from '@refrakt-md/types';
+/**
+ * Information about an attribute preset inherited by a rune — the set of
+ * attribute names contributed by the preset, plus metadata for display.
+ */
+export interface RuneBasePresetInfo {
+    /** Short, human-readable preset name (matches `AttributePresetMetadata.name`). */
+    name: string;
+    /** One-sentence description of the preset. */
+    description: string;
+    /** Names of the attributes contributed by this preset. */
+    attributes: string[];
+}
+/**
+ * Rune metadata interface — structurally compatible with Rune from @refrakt-md/runes
+ * without requiring a runtime dependency on the full Rune class.
+ */
+export interface RuneInfo {
+    name: string;
+    aliases: string[];
+    description: string;
+    schema: {
+        attributes?: Record<string, {
+            type?: unknown;
+            required?: boolean;
+            matches?: unknown;
+            description?: string;
+        }>;
+    };
+    /**
+     * Authoring hints — a short note that reads naturally to both humans browsing
+     * the reference and LLMs generating content. Rendered as a dedicated section
+     * in `describeRune` output and included in `refrakt write` prompts.
+     */
+    authoringHints?: string;
+    /** Pre-serialized content model; rendered into the reference output by `describeRune`. */
+    contentModel?: SerializedContentModel;
+    /** Named preset this rune inherits attributes from, if any (via `base:` in createContentModelSchema). */
+    basePreset?: RuneBasePresetInfo;
+    /** Example Markdoc snippet, falling back to `RUNE_EXAMPLES[name]` when omitted. */
+    example?: string;
+    /** Short source identifier (e.g. `"core"`, `"@refrakt-md/marketing"`) for grouping output. */
+    package?: string;
+}
+/** Runes that are internal or child-only — excluded from generated reference docs */
+export declare const EXCLUDED_RUNES: Set<string>;
+/** Attributes hidden from generated reference docs (rune.attribute format) */
+export declare const HIDDEN_ATTRIBUTES: Set<string>;
+export interface SerializedContentField {
+    name: string;
+    match: string;
+    optional?: boolean;
+    greedy?: boolean;
+    template?: string;
+    description?: string;
+    emitTag?: string;
+}
+export interface SerializedSequenceModel {
+    type: 'sequence';
+    fields: SerializedContentField[];
+}
+export interface SerializedHeadingExtractField {
+    name: string;
+    /** Regex source, or the literal string `'remainder'`. */
+    pattern: string;
+    optional?: boolean;
+}
+export interface SerializedKnownSection {
+    alias?: string[];
+    /** Whether this section has a specific model override (the actual model is not serialized). */
+    hasModel: boolean;
+}
+export interface SerializedSectionsModel {
+    type: 'sections';
+    sectionHeading: string;
+    fields?: SerializedContentField[];
+    sectionModel?: SerializedContentModel;
+    emitTag?: string;
+    headingExtract?: {
+        fields: SerializedHeadingExtractField[];
+    };
+    knownSections?: Record<string, SerializedKnownSection>;
+    implicitSection?: {
+        attributes?: Record<string, string>;
+    };
+}
+export interface SerializedDelimitedZone {
+    name: string;
+    type: 'sequence';
+    fields: SerializedContentField[];
+}
+export interface SerializedDelimitedModel {
+    type: 'delimited';
+    delimiter: string;
+    zones?: SerializedDelimitedZone[];
+    dynamicZones?: boolean;
+    zoneModel?: SerializedSequenceModel;
+}
+export interface SerializedCustomModel {
+    type: 'custom';
+    description: string;
+}
+export type SerializedContentModel = SerializedSequenceModel | SerializedSectionsModel | SerializedDelimitedModel | SerializedCustomModel;
+/**
+ * Render a single rune's reference as a markdown block. Used by both the
+ * AI prompt builder and the `refrakt reference` CLI.
+ */
+export declare function describeRune(rune: RuneInfo): string;
+/**
+ * Serialize a content model for JSON transport.
+ * Strips non-serializable fields (functions in `custom` models, RegExp in headingExtract).
+ * For function-based conditional models, evaluates with empty attrs to get the default.
+ */
+export declare function serializeContentModel(model: ContentModel | ((attrs: Record<string, any>) => ContentModel)): SerializedContentModel | undefined;
+export declare function stripContentModel(model: ContentModel): SerializedContentModel | undefined;
+/**
+ * Render a serialized content model to agent-readable markdown. The output
+ * describes the rune's input shape so a coding agent can author content
+ * with the right children in the right order.
+ *
+ * Output is stable: rerunning on the same serialized model produces
+ * byte-identical output.
+ */
+export declare function renderContentModel(model: SerializedContentModel): string;
+/**
+ * Minimal structural shape of a Rune-like object that `hydrateRuneInfo` accepts.
+ * Matches both the `Rune` class and loose objects like the ones produced by
+ * `defineRune()`.
+ */
+export interface RuneLike {
+    name: string;
+    aliases: string[];
+    description: string;
+    schema: Schema;
+    authoringHints?: string;
+}
+export interface HydrateOptions {
+    /** Identifier for the source (e.g. `"core"`, `"@refrakt-md/marketing"`). */
+    packageName?: string;
+    /** Optional per-rune fixture string, overriding `RUNE_EXAMPLES[name]`. */
+    example?: string;
+}
+/**
+ * Hydrate a `Rune`-like object into a fully-populated `RuneInfo` for the
+ * reference surface. Resolves the content model via the shared
+ * `schemaContentModels` WeakMap and the base preset via
+ * `schemaBasePresets` + `lookupAttributePreset`.
+ */
+export declare function hydrateRuneInfo(rune: RuneLike, options?: HydrateOptions): RuneInfo;
+/** Minimal source view for reference rendering — the merged rune set + metadata. */
+export interface ReferenceContext {
+    /** All Rune-like objects keyed by primary name. */
+    runes: Record<string, RuneLike>;
+    /** Package fixtures (keyed by rune name). Falls back to `RUNE_EXAMPLES[name]`. */
+    fixtures: Record<string, string>;
+    /** Per-rune source identifier (e.g. `"core"` or `"@refrakt-md/marketing"`). */
+    source: Record<string, string>;
+}
+/** Hydrate every non-excluded rune in a context, sorted alphabetically by name. */
+export declare function hydrateAllRuneInfos(ctx: ReferenceContext): RuneInfo[];
+/** Hydrate a single rune by primary name or alias. Returns `undefined` if absent. */
+export declare function hydrateRuneByName(ctx: ReferenceContext, name: string): RuneInfo | undefined;
+export interface SerializedAttribute {
+    type: string;
+    required: boolean;
+    matches?: string[];
+    description?: string;
+}
+export interface SerializedRune {
+    name: string;
+    package: string;
+    aliases: string[];
+    description: string;
+    authoringHints?: string;
+    attributes: {
+        own: Record<string, SerializedAttribute>;
+        base?: {
+            name: string;
+            description: string;
+            attributes: Record<string, SerializedAttribute>;
+        };
+        universal: string[];
+    };
+    contentModel?: SerializedContentModel;
+    example?: string;
+}
+/** Serialize a hydrated RuneInfo into the stable JSON shape used by the reference command. */
+export declare function serializeRune(info: RuneInfo, packageName?: string): SerializedRune;
+export interface ReferenceGroup {
+    /** Package short identifier (`"core"`, `"@refrakt-md/marketing"`, …). */
+    packageName: string;
+    /** Human-readable label used as the group heading in rendered output. */
+    label: string;
+    /** Sorted list of rune summaries. */
+    runes: Array<{
+        name: string;
+        description: string;
+        aliases: string[];
+    }>;
+}
+/** Group hydrated rune infos by source package, core first then alphabetical. */
+export declare function groupReferenceInfos(infos: RuneInfo[]): ReferenceGroup[];
+export interface RenderReferenceOptions {
+    /** Optional preamble inserted between the `# Available Runes` heading and the TOC. */
+    preamble?: string;
+}
+/**
+ * Render the full reference document as markdown. Pure — rerunning on the same
+ * context produces byte-identical output, so callers can diff it against a
+ * checked-in AGENTS.md to detect drift.
+ */
+export declare function renderReferenceMarkdown(ctx: ReferenceContext, options?: RenderReferenceOptions): string;
+//# sourceMappingURL=reference.d.ts.map

package/dist/reference.d.ts.map

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